bbs.h File Reference

The main libbbs header file. More...

#include <stdint.h>
#include <stdarg.h>

Go to the source code of this file.

Macros
#define	BBS_SK_LEN   32
	Octet string length of secret key.
#define	BBS_PK_LEN   96
	Octet string length of public key.
#define	BBS_SIG_LEN   80
	Octet string length of signature.
#define	BBS_PROOF_BASE_LEN   272
	Minimum octet string length of proof.
#define	BBS_PROOF_UD_ELEM_LEN   32
	Octet string length of UD element.
#define	BBS_PROOF_LEN(num_undisclosed)
	Macro that calculates the octet string length of proof with num_undisclosed number of undisclosed messages.
#define	BBS_OK   0
	return value on success
#define	BBS_ERROR   1
	return value on error
#define	bbs_sha256_keygen_full(...)   bbs_keygen_full(bbs_sha256_cipher_suite,__VA_ARGS__)
#define	bbs_sha256_keygen(...)   bbs_keygen(bbs_sha256_cipher_suite,__VA_ARGS__)
#define	bbs_sha256_sk_to_pk(...)   bbs_sk_to_pk(bbs_sha256_cipher_suite,__VA_ARGS__)
#define	bbs_sha256_sign(...)   bbs_sign(bbs_sha256_cipher_suite,__VA_ARGS__)
#define	bbs_sha256_verify(...)   bbs_verify(bbs_sha256_cipher_suite,__VA_ARGS__)
#define	bbs_sha256_proof_gen(...)   bbs_proof_gen(bbs_sha256_cipher_suite,__VA_ARGS__)
#define	bbs_sha256_proof_verify(...)   bbs_proof_verify(bbs_sha256_cipher_suite,__VA_ARGS__)
#define	bbs_shake256_keygen_full(...)   bbs_keygen_full(bbs_shake256_cipher_suite,__VA_ARGS__)
#define	bbs_shake256_keygen(...)   bbs_keygen(bbs_shake256_cipher_suite,__VA_ARGS__)
#define	bbs_shake256_sk_to_pk(...)   bbs_sk_to_pk(bbs_shake256_cipher_suite,__VA_ARGS__)
#define	bbs_shake256_sign(...)   bbs_sign(bbs_shake256_cipher_suite,__VA_ARGS__)
#define	bbs_shake256_verify(...)   bbs_verify(bbs_shake256_cipher_suite,__VA_ARGS__)
#define	bbs_shake256_proof_gen(...)   bbs_proof_gen(bbs_shake256_cipher_suite,__VA_ARGS__)
#define	bbs_shake256_proof_verify(...)   bbs_proof_verify(bbs_shake256_cipher_suite,__VA_ARGS__)

Typedefs
typedef uint8_t	bbs_secret_key[BBS_SK_LEN]
	BBS secret key.
typedef uint8_t	bbs_public_key[BBS_PK_LEN]
	BBS public key.
typedef uint8_t	bbs_signature[BBS_SIG_LEN]
	BBS signature.
typedef struct bbs_cipher_suite	bbs_cipher_suite_t
	BBS cipher suite.

Functions
int	bbs_init (void)
int	bbs_deinit (void)
int	bbs_keygen_full (bbs_cipher_suite_t *cipher_suite, bbs_secret_key sk, bbs_public_key pk)
int	bbs_keygen (bbs_cipher_suite_t *cipher_suite, bbs_secret_key sk, const uint8_t *key_material, uint16_t key_material_len, const uint8_t *key_info, uint16_t key_info_len, const uint8_t *key_dst, uint8_t key_dst_len)
int	bbs_sk_to_pk (bbs_cipher_suite_t *cipher_suite, const bbs_secret_key sk, bbs_public_key pk)
int	bbs_sign (bbs_cipher_suite_t *cipher_suite, const bbs_secret_key sk, const bbs_public_key pk, bbs_signature signature, const uint8_t *header, uint64_t header_len, uint64_t num_messages,...)
	Create a signature.
int	bbs_verify (bbs_cipher_suite_t *cipher_suite, const bbs_public_key pk, const bbs_signature signature, const uint8_t *header, uint64_t header_len, uint64_t num_messages,...)
	Verify a signature.
int	bbs_proof_gen (bbs_cipher_suite_t *cipher_suite, const bbs_public_key pk, const bbs_signature signature, uint8_t *proof, const uint8_t *header, uint64_t header_len, const uint8_t *presentation_header, uint64_t presentation_header_len, const uint64_t *disclosed_indexes, uint64_t disclosed_indexes_len, uint64_t num_messages,...)
	Create a proof over a signature.
int	bbs_proof_verify (bbs_cipher_suite_t *cipher_suite, const bbs_public_key pk, const uint8_t *proof, uint64_t proof_len, const uint8_t *header, uint64_t header_len, const uint8_t *presentation_header, uint64_t presentation_header_len, const uint64_t *disclosed_indexes, uint64_t disclosed_indexes_len, uint64_t num_messages,...)
	Verify a proof over a signature.

Variables
bbs_cipher_suite_t *	bbs_sha256_cipher_suite
bbs_cipher_suite_t *	bbs_shake256_cipher_suite

Detailed Description

The main libbbs header file.

(C) 2025 Fraunhofer AISEC

Author

Thomas Bellebaum

Sebastian Schmiedmayer

Martin Schanzenbach

Date

2 Jun 2025

Macro Definition Documentation

BBS_PROOF_LEN

#define BBS_PROOF_LEN

(

num_undisclosed

)

Value:

                    (BBS_PROOF_BASE_LEN + num_undisclosed * BBS_PROOF_UD_ELEM_LEN \
                    )

Macro that calculates the octet string length of proof with num_undisclosed number of undisclosed messages.

bbs_sha256_keygen

#define bbs_sha256_keygen

(

...

)

bbs_keygen(bbs_sha256_cipher_suite,__VA_ARGS__)

Helper for SHA256 suite

See also

bbs_keygen

bbs_sha256_keygen_full

#define bbs_sha256_keygen_full

(

...

)

bbs_keygen_full(bbs_sha256_cipher_suite,__VA_ARGS__)

Helper for SHA256 suite

See also

bbs_keygen_full

bbs_sha256_proof_gen

#define bbs_sha256_proof_gen

(

...

)

bbs_proof_gen(bbs_sha256_cipher_suite,__VA_ARGS__)

Helper for SHA256 suite

See also

bbs_proof_gen

bbs_sha256_proof_verify

#define bbs_sha256_proof_verify

(

...

)

bbs_proof_verify(bbs_sha256_cipher_suite,__VA_ARGS__)

Helper for SHA256 suite

See also

bbs_proof_verify

bbs_sha256_sign

#define bbs_sha256_sign

(

...

)

bbs_sign(bbs_sha256_cipher_suite,__VA_ARGS__)

Helper for SHA256 suite

See also

bbs_sign

bbs_sha256_sk_to_pk

#define bbs_sha256_sk_to_pk

(

...

)

bbs_sk_to_pk(bbs_sha256_cipher_suite,__VA_ARGS__)

Helper for SHA256 suite

See also

bbs_sk_to_pk

bbs_sha256_verify

#define bbs_sha256_verify

(

...

)

bbs_verify(bbs_sha256_cipher_suite,__VA_ARGS__)

Helper for SHA256 suite

See also

bbs_verify

bbs_shake256_keygen

#define bbs_shake256_keygen

(

...

)

bbs_keygen(bbs_shake256_cipher_suite,__VA_ARGS__)

Helper for SHAKE256 suite

See also

bbs_keygen

bbs_shake256_keygen_full

#define bbs_shake256_keygen_full

(

...

)

bbs_keygen_full(bbs_shake256_cipher_suite,__VA_ARGS__)

Helper for SHAKE256 suite

See also

bbs_keygen_full

bbs_shake256_proof_gen

#define bbs_shake256_proof_gen

(

...

)

bbs_proof_gen(bbs_shake256_cipher_suite,__VA_ARGS__)

Helper for SHAKE256 suite

See also

bbs_proof_gen

bbs_shake256_proof_verify

#define bbs_shake256_proof_verify

(

...

)

bbs_proof_verify(bbs_shake256_cipher_suite,__VA_ARGS__)

Helper for SHAKE256 suite

See also

bbs_proof_verify

bbs_shake256_sign

#define bbs_shake256_sign

(

...

)

bbs_sign(bbs_shake256_cipher_suite,__VA_ARGS__)

Helper for SHAKE256 suite

See also

bbs_sign

bbs_shake256_sk_to_pk

#define bbs_shake256_sk_to_pk

(

...

)

bbs_sk_to_pk(bbs_shake256_cipher_suite,__VA_ARGS__)

Helper for SHAKE256 suite

See also

bbs_sk_to_pk

bbs_shake256_verify

#define bbs_shake256_verify

(

...

)

bbs_verify(bbs_shake256_cipher_suite,__VA_ARGS__)

Helper for SHAKE256 suite

See also

bbs_verify

Typedef Documentation

bbs_cipher_suite_t

typedef struct bbs_cipher_suite bbs_cipher_suite_t

BBS cipher suite.

The cipher suite. Is one of bbs_sha256_cipher_suite or bbs_shake256_cipher_suite

bbs_public_key

typedef uint8_t bbs_public_key[BBS_PK_LEN]

BBS public key.

The public key is an octet string of length BBS_PK_LEN.

bbs_secret_key

typedef uint8_t bbs_secret_key[BBS_SK_LEN]

BBS secret key.

The secret key is an octet string of length BBS_SK_LEN.

bbs_signature

typedef uint8_t bbs_signature[BBS_SIG_LEN]

BBS signature.

The BBS signature is an octet string of length BBS_SIG_LEN.

Function Documentation

bbs_deinit()

int bbs_deinit

(

void

)

Subsystem cleanup Call this function on global scope exit.

Returns

BBS_OK on success.

bbs_init()

int bbs_init

(

void

)

Subsystem initialization Call this function before any other API. Make sure to call bbs_deinit when done.

Returns

BBS_OK on success.

bbs_keygen()

int bbs_keygen	(	bbs_cipher_suite_t *	cipher_suite,
		bbs_secret_key	sk,
		const uint8_t *	key_material,
		uint16_t	key_material_len,
		const uint8_t *	key_info,
		uint16_t	key_info_len,
		const uint8_t *	key_dst,
		uint8_t	key_dst_len
	)

Generate a public/private key pair

For security, key_material MUST be random and infeasible to guess, e.g. generated by a trusted source of randomness and with enough entropy. See [RFC4086] for suggestions on generating randomness. key_material MUST be at least 32 bytes long, but it MAY be longer.

Parameters

cipher_suite	the cipher suite to use. See bbs_cipher_suite_t.
sk	where to store the secret key
key_material	a secret octet string. See requirements above.
key_material_len	the length of key_material
key_info	used to derive distinct keys from the same key material. (may be NULL)
key_info_len	the length of key_info
key_dst	an octet string representing the domain separation tag. May be NULL in which case it to the octet string ciphersuite_id || "KEYGEN_DST_".
key_dst_len	the length of key_dst

Returns

0 on success.

bbs_keygen_full()

int bbs_keygen_full	(	bbs_cipher_suite_t *	cipher_suite,
		bbs_secret_key	sk,
		bbs_public_key	pk
	)

Generate a public/private key pair. This is a convienience function for bbs_keygen in which the key_dst and key_info parameters are the empty string.

Parameters

cipher_suite	the cipher suite to use. See bbs_cipher_suite_t.
sk	where to store the secret key
pk	where to store the public key

Returns

0 on success.

bbs_proof_gen()

int bbs_proof_gen	(	bbs_cipher_suite_t *	cipher_suite,
		const bbs_public_key	pk,
		const bbs_signature	signature,
		uint8_t *	proof,
		const uint8_t *	header,
		uint64_t	header_len,
		const uint8_t *	presentation_header,
		uint64_t	presentation_header_len,
		const uint64_t *	disclosed_indexes,
		uint64_t	disclosed_indexes_len,
		uint64_t	num_messages,
			...
	)

Create a proof over a signature.

The num_messages is followed by this amount of varargs that consist of a tuple of uint8_t* pointers to octet strings followed by a uint32_t length indicator.

Parameters

cipher_suite	the cipher suite to use. See bbs_cipher_suite_t.
pk	public key.
signature	the signature to use.
proof	pointer to the proof. Must be allocated by caller as octet string with size BBS_PROOF_LEN(N) where N = (num_messages - disclosed_indexes_len).
header	an octet string containing context and application specific information. If not supplied, it defaults to the empty octet string ("").
header_len	the length of the message header.
presentation_header	an octet string containing the presentation header. If not supplied, it defaults to the empty octet string ("").
presentation_header_len	the length of the proof presentation header.
disclosed_indexes	a vector of unsigned integers in ascending order. Indexes of disclosed messages. If not supplied, it defaults to the empty array ("()").
disclosed_indexes_len	the length of disclosed_indexes array.
num_messages	the number of messages followed by in varargs.

Returns

BBS_OK on success.

bbs_proof_verify()

int bbs_proof_verify	(	bbs_cipher_suite_t *	cipher_suite,
		const bbs_public_key	pk,
		const uint8_t *	proof,
		uint64_t	proof_len,
		const uint8_t *	header,
		uint64_t	header_len,
		const uint8_t *	presentation_header,
		uint64_t	presentation_header_len,
		const uint64_t *	disclosed_indexes,
		uint64_t	disclosed_indexes_len,
		uint64_t	num_messages,
			...
	)

Verify a proof over a signature.

The num_messages is followed by this amount of varargs that consist of a tuple of uint8_t* pointers to octet strings followed by a uint32_t length indicator.

Parameters

cipher_suite	the cipher suite to use. See bbs_cipher_suite_t.
pk	public key.
proof	an octet string of the form outputted by bbs_proof_gen.
proof_len	length of proof.
header	an octet string containing context and application specific information. If not supplied, it defaults to the empty octet string ("").
header_len	the length of the message header.
presentation_header	an octet string containing the presentation header. If not supplied, it defaults to the empty octet string ("").
presentation_header_len	the length of the proof presentation header.
disclosed_indexes	a vector of unsigned integers in ascending order. Indexes of disclosed messages. If not supplied, it defaults to the empty array ("()").
disclosed_indexes_len	the length of disclosed_indexes array.
num_messages	the number of messages followed by in varargs.

Returns

BBS_OK on success.

bbs_sign()

int bbs_sign	(	bbs_cipher_suite_t *	cipher_suite,
		const bbs_secret_key	sk,
		const bbs_public_key	pk,
		bbs_signature	signature,
		const uint8_t *	header,
		uint64_t	header_len,
		uint64_t	num_messages,
			...
	)

Create a signature.

The num_messages is followed by this amount of varargs that consist of a tuple of uint8_t* pointers to octet strings followed by a uint32_t length indicator.

Parameters

cipher_suite	the cipher suite to use. See bbs_cipher_suite_t.
sk	secret key.
pk	public key.
signature	where to store the signature.
header	an octet string containing context and application specific information. If not supplied, it defaults to the empty octet string ("").
header_len	the length of the message header.
num_messages	the number of messages as octet strings followed in varargs.

Returns

BBS_OK on success.

bbs_sk_to_pk()

int bbs_sk_to_pk	(	bbs_cipher_suite_t *	cipher_suite,
		const bbs_secret_key	sk,
		bbs_public_key	pk
	)

Generate public key from secret key. Internally generates randomness for key_material and calls bbs_keygen with default parameters.

Parameters

cipher_suite	the cipher suite to use. See bbs_cipher_suite_t.
sk	secret key.
pk	public key.

Returns

BBS_OK on success.

bbs_verify()

int bbs_verify	(	bbs_cipher_suite_t *	cipher_suite,
		const bbs_public_key	pk,
		const bbs_signature	signature,
		const uint8_t *	header,
		uint64_t	header_len,
		uint64_t	num_messages,
			...
	)

Verify a signature.

The num_messages is followed by this amount of varargs that consist of a tuple of uint8_t* pointers to octet strings followed by a uint32_t length indicator.

Parameters

cipher_suite	the cipher suite to use. See bbs_cipher_suite_t.
pk	public key.
signature	the signature to verify.
header	an octet string containing context and application specific information. If not supplied, it defaults to the empty octet string ("").
header_len	the length of the message header.
num_messages	the number of messages followed by in varargs.

Returns

BBS_OK on success.

Variable Documentation

bbs_sha256_cipher_suite

bbs_cipher_suite_t* bbs_sha256_cipher_suite

extern

The SHA256 cipher suite

See also

bbs_cipher_suite_t

bbs_shake256_cipher_suite

bbs_cipher_suite_t* bbs_shake256_cipher_suite

extern

The SHAKE256 cipher suite

See also

bbs_cipher_suite_t