ox_bn.h

Back to the files list

Big Number syscalls. More...

Data Structures
struct	cx_bn_mont_ctx_t
	Montgomery context. More...

Macros
#define	CX_BN_WORD_ALIGNEMENT   16
	Minimal word size in bytes. More...

Typedefs
typedef uint32_t	cx_bn_t
	Index of a big number. More...

Functions
SYSCALL cx_err_t	cx_bn_lock (size_t word_nbytes, uint32_t flags)
	Locks the BN processor. More...
SYSCALL uint32_t	cx_bn_unlock (void)
	Releases the BN lock. More...
SYSCALL bool	cx_bn_is_locked (void)
	Checks whether the BN processor is currently locked. More...
cx_err_t	cx_bn_locked (void)
	Ascertains whether the BN processor is currently locked. More...
SYSCALL cx_err_t	cx_bn_alloc (cx_bn_t *x, size_t nbytes)
	Allocates memory for a new BN. More...
SYSCALL cx_err_t	cx_bn_alloc_init (cx_bn_t *x, size_t nbytes, const uint8_t *value, size_t value_nbytes)
	Allocates memory for a new BN and initializes it with the specified value. More...
SYSCALL cx_err_t	cx_bn_destroy (cx_bn_t *x)
	Releases a BN and gives back its attached memory to the system. More...
SYSCALL cx_err_t	cx_bn_nbytes (const cx_bn_t x, size_t *nbytes)
	Gets the size in bytes of a BN. More...
SYSCALL cx_err_t	cx_bn_init (cx_bn_t x, const uint8_t *value, size_t value_nbytes)
	Iinitializes a BN with an unsigned value. More...
SYSCALL cx_err_t	cx_bn_rand (cx_bn_t x)
	Generates a random number and stores it in the given index. More...
SYSCALL cx_err_t	cx_bn_copy (cx_bn_t a, const cx_bn_t b)
	Copies the BN value. More...
SYSCALL cx_err_t	cx_bn_set_u32 (cx_bn_t x, uint32_t n)
	Sets the value of a BN with a 32-bit unsigned value. More...
SYSCALL cx_err_t	cx_bn_get_u32 (const cx_bn_t x, uint32_t *n)
	Gets the 32-bit value corresponding to a BN. More...
SYSCALL cx_err_t	cx_bn_export (const cx_bn_t x, uint8_t *bytes, size_t nbytes)
	Stores (serializes) a BN value as unsigned raw bytes in big-endian order. More...
SYSCALL cx_err_t	cx_bn_cmp (const cx_bn_t a, const cx_bn_t b, int *diff)
	Compares two BN values. More...
SYSCALL cx_err_t	cx_bn_cmp_u32 (const cx_bn_t a, uint32_t b, int *diff)
	Compares a BN value with an unsigned integer. More...
SYSCALL cx_err_t	cx_bn_is_odd (const cx_bn_t n, bool *odd)
	Tests whether a BN value is odd. More...
SYSCALL cx_err_t	cx_bn_xor (cx_bn_t r, const cx_bn_t a, const cx_bn_t b)
	Performs the bitwise 'exclusive-OR' of two BN values. More...
SYSCALL cx_err_t	cx_bn_or (cx_bn_t r, const cx_bn_t a, const cx_bn_t b)
	Performs the bitwise 'OR' of two BN values. More...
SYSCALL cx_err_t	cx_bn_and (cx_bn_t r, const cx_bn_t a, const cx_bn_t b)
	Performs the bitwise 'AND' of two BN values. More...
SYSCALL cx_err_t	cx_bn_tst_bit (const cx_bn_t x, uint32_t pos, bool *set)
	Tests the bit value at the specified index. More...
SYSCALL cx_err_t	cx_bn_set_bit (cx_bn_t x, uint32_t pos)
	Sets the bit value at the specified index. More...
SYSCALL cx_err_t	cx_bn_clr_bit (cx_bn_t x, uint32_t pos)
	Clears the bit value at the specified index. More...
SYSCALL cx_err_t	cx_bn_shr (cx_bn_t x, uint32_t n)
	Performs a right shift. More...
SYSCALL cx_err_t	cx_bn_shl (cx_bn_t x, uint32_t n)
	Performs a left shift. More...
SYSCALL cx_err_t	cx_bn_cnt_bits (cx_bn_t n, uint32_t *nbits)
	Counts the number of bits set to 1 of the BN value. More...
SYSCALL cx_err_t	cx_bn_add (cx_bn_t r, const cx_bn_t a, const cx_bn_t b)
	Performs an addition r = a + b. More...
SYSCALL cx_err_t	cx_bn_sub (cx_bn_t r, const cx_bn_t a, const cx_bn_t b)
	Performs a subtraction r = a - b. More...
SYSCALL cx_err_t	cx_bn_mul (cx_bn_t r, const cx_bn_t a, const cx_bn_t b)
	Performs a multiplication r = a * b. More...
SYSCALL cx_err_t	cx_bn_mod_add (cx_bn_t r, const cx_bn_t a, const cx_bn_t b, const cx_bn_t n)
	Performs a modular addition r = a + b mod n. More...
SYSCALL cx_err_t	cx_bn_mod_sub (cx_bn_t r, const cx_bn_t a, const cx_bn_t b, const cx_bn_t n)
	Performs a modular subtraction r = a - b mod n. More...
SYSCALL cx_err_t	cx_bn_mod_mul (cx_bn_t r, const cx_bn_t a, const cx_bn_t b, const cx_bn_t n)
	Performs a modular multiplication r = a * b mod n. More...
SYSCALL cx_err_t	cx_bn_reduce (cx_bn_t r, const cx_bn_t d, const cx_bn_t n)
	Performs a reduction r = d mod n. More...
SYSCALL cx_err_t	cx_bn_mod_sqrt (cx_bn_t r, const cx_bn_t a, const cx_bn_t n, uint32_t sign)
	Computes r such that r² = a mod n if a is a quadratic residue. More...
SYSCALL cx_err_t	cx_bn_mod_pow_bn (cx_bn_t r, const cx_bn_t a, const cx_bn_t e, const cx_bn_t n)
	Performs a modular exponentiation r = a^e mod n. More...
SYSCALL cx_err_t	cx_bn_mod_pow (cx_bn_t r, const cx_bn_t a, const uint8_t *e, uint32_t e_len, const cx_bn_t n)
	Performs a modular exponentiation r = a^e mod n. More...
SYSCALL cx_err_t	cx_bn_mod_pow2 (cx_bn_t r, const cx_bn_t a, const uint8_t *e, uint32_t e_len, const cx_bn_t n)
	Performs a modular exponentiation r = a^e mod n. More...
SYSCALL cx_err_t	cx_bn_mod_invert_nprime (cx_bn_t r, const cx_bn_t a, const cx_bn_t n)
	Computes the modular inverse r = a^(-1) mod n, for a prime n. More...
SYSCALL cx_err_t	cx_bn_mod_u32_invert (cx_bn_t r, uint32_t a, cx_bn_t n)
	Computes the modular inverse r = a^(-1) mod n, of a 32-bit value. More...
SYSCALL cx_err_t	cx_mont_alloc (cx_bn_mont_ctx_t *ctx, size_t length)
	Allocates memory for the Montgomery context. More...
SYSCALL cx_err_t	cx_mont_init (cx_bn_mont_ctx_t *ctx, const cx_bn_t n)
	Initializes a Montgomery context with the modulus. More...
SYSCALL cx_err_t	cx_mont_init2 (cx_bn_mont_ctx_t *ctx, const cx_bn_t n, const cx_bn_t h)
	Initializes a Montgomery context with the modulus and the second Montgomery constant. More...
SYSCALL cx_err_t	cx_mont_to_montgomery (cx_bn_t x, const cx_bn_t z, const cx_bn_mont_ctx_t *ctx)
	Computes the Montgomery representation of a BN value. More...
SYSCALL cx_err_t	cx_mont_from_montgomery (cx_bn_t z, const cx_bn_t x, const cx_bn_mont_ctx_t *ctx)
	Computes the normal representation of a BN value given a Montgomery representation. More...
SYSCALL cx_err_t	cx_mont_mul (cx_bn_t r, const cx_bn_t a, const cx_bn_t b, const cx_bn_mont_ctx_t *ctx)
	Performs a Montgomery multiplication. More...
SYSCALL cx_err_t	cx_mont_pow (cx_bn_t r, const cx_bn_t a, const uint8_t *e, uint32_t e_len, const cx_bn_mont_ctx_t *ctx)
	Performs a modular exponentiation r = a^e mod n. More...
SYSCALL cx_err_t	cx_mont_pow_bn (cx_bn_t r, const cx_bn_t a, const cx_bn_t e, const cx_bn_mont_ctx_t *ctx)
	Performs a modular exponentiation r = a^e mod n. More...
SYSCALL cx_err_t	cx_mont_invert_nprime (cx_bn_t r, const cx_bn_t a, const cx_bn_mont_ctx_t *ctx)
	Computes the modular inverse r = a^(-1) mod n for a prime number n. More...
SYSCALL cx_err_t	cx_bn_is_prime (const cx_bn_t n, bool *prime)
	Tests whether a BN value is a probable prime. More...
SYSCALL cx_err_t	cx_bn_next_prime (cx_bn_t n)
	Gets the first prime number after a given BN value. More...
SYSCALL cx_err_t	cx_bn_rng (cx_bn_t r, const cx_bn_t n)
	Generates a random number r in the range ]0,n[. More...

Detailed Description

Big Number syscalls.

This file contains the big numbers definitions and functions:

• Lock the memory for further computations
• Unlock the memory at the end of the operations
• Arithmetic on big numbers

Macro Definition Documentation

CX_BN_WORD_ALIGNEMENT

#define CX_BN_WORD_ALIGNEMENT   16

Minimal word size in bytes.

A BN size shall be a multiple of this.

Typedef Documentation

cx_bn_t

typedef uint32_t cx_bn_t

Index of a big number.

Function Documentation

cx_bn_add()

SYSCALL cx_err_t cx_bn_add	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	b
)

Performs an addition r = a + b.

r, a and b shall have the same BN size.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the first operand.
[in]	b	BN index of the second operand.

Returns

Error code:

• CX_OK or CX_CARRY on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_alloc()

SYSCALL cx_err_t cx_bn_alloc	(	cx_bn_t *	x,
		size_t	nbytes
)

Allocates memory for a new BN.

The specified number of bytes is the minimal required bytes, the number of words allocated will be automatically a multiple of the configured word size. At this moment the BN value is set to 0.

Parameters

[in]	x	Pointer to a BN.
[in]	nbytes	Number of bytes of x.

Returns

Error code:

• CX_OK on success
• CX_BN_MEMORY_FULL
• CX_BN_INVALID_PARAMETER_SIZE

cx_bn_alloc_init()

SYSCALL cx_err_t cx_bn_alloc_init	(	cx_bn_t *	x,
		size_t	nbytes,
		const uint8_t *	value,
		size_t	value_nbytes
)

Allocates memory for a new BN and initializes it with the specified value.

The specified number of bytes is the minimal required bytes, the number of words allocated will be automatically a multiple of the configured word size.

Parameters

[in]	x	Pointer to a BN.
[in]	nbytes	Number of bytes of x.
[in]	value	Pointer to the value used to initialize the BN.
[in]	value_nbytes	Number of bytes of value.

Returns

Error code:

• CX_OK on success
• CX_BN_MEMORY_FULL
• CX_BN_INVALID_PARAMETER_SIZE

cx_bn_and()

SYSCALL cx_err_t cx_bn_and	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	b
)

Performs the bitwise 'AND' of two BN values.

r must be distinct from a and b.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the first operand.
[in]	b	BN index of the second operand.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_clr_bit()

SYSCALL cx_err_t cx_bn_clr_bit	(	cx_bn_t	x,
		uint32_t	pos
)

Clears the bit value at the specified index.

The BN value is in big endian order, thus the position 0 corresponds to the least significant bit.

Parameters

[in]	x	BN index.
[in]	pos	Position of the bit.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_cmp()

SYSCALL cx_err_t cx_bn_cmp	(	const cx_bn_t	a,
		const cx_bn_t	b,
		int *	diff
)

Compares two BN values.

Parameters

[in]	a	BN index to the first value to be compared.
[in]	b	BN index to the second value to be compared.
[out]	diff	Result of the comparison: 0 if the numbers are equal. > 0 if the first number is greater than the second < 0 if the first number is smaller than the second

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_cmp_u32()

SYSCALL cx_err_t cx_bn_cmp_u32	(	const cx_bn_t	a,
		uint32_t	b,
		int *	diff
)

Compares a BN value with an unsigned integer.

Parameters

[in]	a	BN index to the value to be compared.
[in]	b	Integer to be compared.
[out]	diff	Result of the comparison: 0 if the numbers are equal. > 0 if the BN value is greater < 0 if the BN value is smaller

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_cnt_bits()

SYSCALL cx_err_t cx_bn_cnt_bits	(	cx_bn_t	n,
		uint32_t *	nbits
)

Counts the number of bits set to 1 of the BN value.

Parameters

[in]	n	BN index.
[out]	nbits	Number of bits set.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_copy()

SYSCALL cx_err_t cx_bn_copy	(	cx_bn_t	a,
		const cx_bn_t	b
)

Copies the BN value.

Parameters

[out]	a	BN destination index.
[in]	b	BN source index.

Returns

Error code:

• CX_OK on success
• CX_BN_INVALID_PARAMETER_SIZE
• CX_BN_INVALID_PARAMETER_VALUE

cx_bn_destroy()

SYSCALL cx_err_t cx_bn_destroy

(

cx_bn_t *

x

)

Releases a BN and gives back its attached memory to the system.

Parameters

[in]

x

BN to release. If NULL, nothing is done.

Returns

Error code:

• CX_OK on success
• CX_BN_INVALID_PARAMETER_SIZE
• CX_BN_INVALID_PARAMETER_VALUE

cx_bn_export()

SYSCALL cx_err_t cx_bn_export	(	const cx_bn_t	x,
		uint8_t *	bytes,
		size_t	nbytes
)

Stores (serializes) a BN value as unsigned raw bytes in big-endian order.

Only the least significant nbytes bytes of the BN are serialized If nbytes is greater than the BN size, x is serialized right aligned and zero left-padded.

Parameters

[in]	x	BN index.
[out]	bytes	Buffer where to store the serialized number.
[in]	nbytes	Number of bytes to store into the buffer.

Returns

Error code:

• CX_OK on success
• CX_BN_INVALID_PARAMETER_SIZE
• CX_BN_INVALID_PARAMETER_VALUE

cx_bn_get_u32()

SYSCALL cx_err_t cx_bn_get_u32	(	const cx_bn_t	x,
		uint32_t *	n
)

Gets the 32-bit value corresponding to a BN.

Parameters

[in]	x	BN index.
[out]	n	Stored 32-bit unsigned value.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_init()

SYSCALL cx_err_t cx_bn_init	(	cx_bn_t	x,
		const uint8_t *	value,
		size_t	value_nbytes
)

Iinitializes a BN with an unsigned value.

Parameters

[in]	x	BN index.
[in]	value	Pointer to the value in big-endian order.
[in]	value_nbytes	Number of bytes of the value.

Returns

Error code:

• CX_OK on success
• CX_BN_INVALID_PARAMETER_SIZE
• CX_BN_INVALID_PARAMETER_VALUE

cx_bn_is_locked()

SYSCALL bool cx_bn_is_locked

(

void

)

Checks whether the BN processor is currently locked.

The memory can be used only if the BN processor is locked.

Returns

1 if locked, 0 otherwise.

cx_bn_is_odd()

SYSCALL cx_err_t cx_bn_is_odd	(	const cx_bn_t	n,
		bool *	odd
)

Tests whether a BN value is odd.

Parameters

[in]	n	BN index.
[out]	odd	Boolean which indicates the parity of the BN value: 1 if odd 0 if even

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_is_prime()

SYSCALL cx_err_t cx_bn_is_prime	(	const cx_bn_t	n,
		bool *	prime
)

Tests whether a BN value is a probable prime.

Parameters

[in]	n	BN index of the value.
[out]	prime	Boolean which indicates whether the number is a prime: 1 if it is a prime 0 otherwise

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_bn_lock()

SYSCALL cx_err_t cx_bn_lock	(	size_t	word_nbytes,
		uint32_t	flags
)

Locks the BN processor.

The memory is reset then the word size is set. Once locked the memory can be used.

Parameters

[in]	word_nbytes	Word size in byte, the size of the parameters will be a multiple of word_nbytes. This size must be a multiple of CX_BN_WORD_ALIGNEMENT.
[in]	flags	Flags.

Returns

Error code:

• CX_OK on success
• CX_BN_LOCKED if already locked.

cx_bn_locked()

cx_err_t cx_bn_locked

(

void

)

Ascertains whether the BN processor is currently locked.

If the BN processor is not locked the memory cannot be used.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED

cx_bn_mod_add()

SYSCALL cx_err_t cx_bn_mod_add	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	b,
		const cx_bn_t	n
)

Performs a modular addition r = a + b mod n.

r, a, b and n shall have the same BN size. The values of a and b must be strictly smaller than modulus value.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the first operand.
[in]	b	BN index of the second operand.
[in]	n	BN index of the modulus.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_bn_mod_invert_nprime()

SYSCALL cx_err_t cx_bn_mod_invert_nprime	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	n
)

Computes the modular inverse r = a^(-1) mod n, for a prime n.

r, a and n shall have the same BN size. n must be prime.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the value to be inverted.
[in]	n	BN index of the modulus.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_bn_mod_mul()

SYSCALL cx_err_t cx_bn_mod_mul	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	b,
		const cx_bn_t	n
)

Performs a modular multiplication r = a * b mod n.

r, a, b and n shall have the same BN size. The value of b must be strictly smaller than modulus value.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the first operand.
[in]	b	BN index of the second operand.
[in]	n	BN index of the modulus.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_INVALID_PARAMETER_VALUE
• CX_MEMORY_FULL

cx_bn_mod_pow()

SYSCALL cx_err_t cx_bn_mod_pow	(	cx_bn_t	r,
		const cx_bn_t	a,
		const uint8_t *	e,
		uint32_t	e_len,
		const cx_bn_t	n
)

Performs a modular exponentiation r = a^e mod n.

r, a and n shall have the same BN size. r, a and n must be different.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the base of the exponentiation.
[in]	e	Pointer to the exponent.
[in]	e_len	Length of the exponent buffer.
[in]	n	BN index of the modulus.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_bn_mod_pow2()

SYSCALL cx_err_t cx_bn_mod_pow2	(	cx_bn_t	r,
		const cx_bn_t	a,
		const uint8_t *	e,
		uint32_t	e_len,
		const cx_bn_t	n
)

Performs a modular exponentiation r = a^e mod n.

This fonction reuses the parameter a for intermediate computations, hence requires less memory. r, a and n shall have the same BN size. r, a and n must be different.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the base of the exponentiation. The BN value is modified during the computations.
[in]	e	Pointer to the exponent.
[in]	e_len	Length of the exponent buffer.
[in]	n	BN index of the modulus.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_bn_mod_pow_bn()

SYSCALL cx_err_t cx_bn_mod_pow_bn	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	e,
		const cx_bn_t	n
)

Performs a modular exponentiation r = a^e mod n.

r, a and n shall have the same BN size. r, a and n must be different.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the base of the exponentiation.
[in]	e	BN index of the exponent.
[in]	n	BN index of the modulus.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_bn_mod_sqrt()

SYSCALL cx_err_t cx_bn_mod_sqrt	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	n,
		uint32_t	sign
)

Computes r such that r² = a mod n if a is a quadratic residue.

This returns an error if the given number is not a quadratic residue. r, a and n shall have the same BN size.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the quadratic residue or quadratic non residue.
[in]	n	BN index of the modulus.
[in]	sign	Sign of the result.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL
• CX_NO_RESIDUE

cx_bn_mod_sub()

SYSCALL cx_err_t cx_bn_mod_sub	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	b,
		const cx_bn_t	n
)

Performs a modular subtraction r = a - b mod n.

r, a, b and n shall have the same BN size. The values of a and b must be strictly smaller than modulus value.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the first operand.
[in]	b	BN index of the second operand.
[in]	n	BN index of the modulus.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_bn_mod_u32_invert()

SYSCALL cx_err_t cx_bn_mod_u32_invert	(	cx_bn_t	r,
		uint32_t	a,
		cx_bn_t	n
)

Computes the modular inverse r = a^(-1) mod n, of a 32-bit value.

r and n shall have the same BN size. The parameter n is detroyed and contains zero after the function returns.

Parameters

[out]	r	BN index for the result.
[in]	a	32-bit value to be inverted.
[in]	n	BN index of the modulus.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL
• CX_INTERNAL_ERROR
• CX_NOT_INVERTIBLE

cx_bn_mul()

SYSCALL cx_err_t cx_bn_mul	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	b
)

Performs a multiplication r = a * b.

a and b shall have the same BN size. The size of r must be the size of a

• the size of b.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the first operand.
[in]	b	BN index of the second operand.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_nbytes()

SYSCALL cx_err_t cx_bn_nbytes	(	const cx_bn_t	x,
		size_t *	nbytes
)

Gets the size in bytes of a BN.

Parameters

[in]	x	BN index.
[out]	nbytes	Returned number of bytes.

Returns

Error code:

• CX_OK on success
• CX_BN_INVALID_PARAMETER

cx_bn_next_prime()

SYSCALL cx_err_t cx_bn_next_prime

(

cx_bn_t

n

)

Gets the first prime number after a given BN value.

Parameters

[in,out]

n

BN index of the value and the result.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL
• CX_OVERFLOW

cx_bn_or()

SYSCALL cx_err_t cx_bn_or	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	b
)

Performs the bitwise 'OR' of two BN values.

r must be distinct from a and b.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the first operand.
[in]	b	BN index of the second operand.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_rand()

SYSCALL cx_err_t cx_bn_rand

(

cx_bn_t

x

)

Generates a random number and stores it in the given index.

Parameters

[in]

x

BN index.

Returns

Error code:

• CX_OK on success
• CX_BN_INVALID_PARAMETER_VALUE

cx_bn_reduce()

SYSCALL cx_err_t cx_bn_reduce	(	cx_bn_t	r,
		const cx_bn_t	d,
		const cx_bn_t	n
)

Performs a reduction r = d mod n.

r and n shall have the same BN size.

Parameters

[out]	r	BN index for the result.
[in]	d	BN index of the value to be reduced.
[in]	n	BN index of the modulus.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_bn_rng()

SYSCALL cx_err_t cx_bn_rng	(	cx_bn_t	r,
		const cx_bn_t	n
)

Generates a random number r in the range ]0,n[.

r is such that: 0 < r < n.

Parameters

[out]	r	BN index for the result.
[in]	n	BN index of the upper bound.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_bn_set_bit()

SYSCALL cx_err_t cx_bn_set_bit	(	cx_bn_t	x,
		uint32_t	pos
)

Sets the bit value at the specified index.

The BN value is in big endian order, thus the position 0 corresponds to the least significant bit.

Parameters

[in]	x	BN index.
[in]	pos	Position of the bit.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_set_u32()

SYSCALL cx_err_t cx_bn_set_u32	(	cx_bn_t	x,
		uint32_t	n
)

Sets the value of a BN with a 32-bit unsigned value.

Parameters

[in]	x	BN index.
[in]	n	32-bit value to be assigned.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_shl()

SYSCALL cx_err_t cx_bn_shl	(	cx_bn_t	x,
		uint32_t	n
)

Performs a left shift.

Parameters

[in]	x	BN index.
[in]	n	Number of bits to shift.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_shr()

SYSCALL cx_err_t cx_bn_shr	(	cx_bn_t	x,
		uint32_t	n
)

Performs a right shift.

Parameters

[in]	x	BN index.
[in]	n	Number of bits to shift.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_sub()

SYSCALL cx_err_t cx_bn_sub	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	b
)

Performs a subtraction r = a - b.

r, a and b shall have the same BN size.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the first operand.
[in]	b	BN index of the second operand.

Returns

Error code:

• CX_OK or CX_CARRY on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_tst_bit()

SYSCALL cx_err_t cx_bn_tst_bit	(	const cx_bn_t	x,
		uint32_t	pos,
		bool *	set
)

Tests the bit value at the specified index.

The BN value is in big endian order, thus the position 0 corresponds to the least significant bit.

Parameters

[in]	x	BN index.
[in]	pos	Position of the bit.
[out]	set	Boolean which indicates the bit value 1 if the bit is set 0 otherwise

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_bn_unlock()

SYSCALL uint32_t cx_bn_unlock

(

void

)

Releases the BN lock.

It erases all content data. Once unlocked the memory cannot be used anymore.

Returns

Error code:

• CX_OK on success
• CX_BN_NOT_LOCKED if not locked

cx_bn_xor()

SYSCALL cx_err_t cx_bn_xor	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	b
)

Performs the bitwise 'exclusive-OR' of two BN values.

r must be distinct from a and b.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the first operand.
[in]	b	BN index of the second operand.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_mont_alloc()

SYSCALL cx_err_t cx_mont_alloc	(	cx_bn_mont_ctx_t *	ctx,
		size_t	length
)

Allocates memory for the Montgomery context.

Parameters

[in]	ctx	Pointer to the Montgomery context.
[in]	length	BN size for the context fields.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_MEMORY_FULL

cx_mont_from_montgomery()

SYSCALL cx_err_t cx_mont_from_montgomery	(	cx_bn_t	z,
		const cx_bn_t	x,
		const cx_bn_mont_ctx_t *	ctx
)

Computes the normal representation of a BN value given a Montgomery representation.

The context must be initialized.

Parameters

[out]	x	BN index for the result.
[in]	z	BN index of the value to be converted. The value should be in Montgomery representation.
[in]	ctx	Pointer to the Montgomery context, initialized with the modulus and the second Montgomery constant.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_mont_init()

SYSCALL cx_err_t cx_mont_init	(	cx_bn_mont_ctx_t *	ctx,
		const cx_bn_t	n
)

Initializes a Montgomery context with the modulus.

Calculate and set up the second Montgomery constant.

Parameters

[in]	ctx	Pointer to a Montgomery context.
[in]	n	BN index of the modulus.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_mont_init2()

SYSCALL cx_err_t cx_mont_init2	(	cx_bn_mont_ctx_t *	ctx,
		const cx_bn_t	n,
		const cx_bn_t	h
)

Initializes a Montgomery context with the modulus and the second Montgomery constant.

Set up the second Montgomery constant with the given parameter. The caller should make sure that the given second Montgomery constant is correct.

Parameters

[in]	ctx	Pointer to a Montgomery context.
[in]	n	BN index of the modulus.
[in]	h	BN index of the pre calculated second Montgomery constant.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_mont_invert_nprime()

SYSCALL cx_err_t cx_mont_invert_nprime	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_mont_ctx_t *	ctx
)

Computes the modular inverse r = a^(-1) mod n for a prime number n.

The context must be initialized.

Parameters

[out]	r	BN index for the result. The result is in Montgomery representation.
[in]	a	BN index of the value to be inverted. The value is in Montgomery representation.
[in]	ctx	Pointer to the Montgomery context, initialized with the modulus and the second Montgomery constant

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_mont_mul()

SYSCALL cx_err_t cx_mont_mul	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	b,
		const cx_bn_mont_ctx_t *	ctx
)

Performs a Montgomery multiplication.

The context must be initialized.

Parameters

[out]	r	BN index for the result.
[in]	a	BN index of the first operand in Montgomery representation.
[in]	b	BN index of the second operand in Montgomery representation.
[in]	ctx	Pointer to the Montgomery context, initialized with the modulus and the second Montgomery constant.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER

cx_mont_pow()

SYSCALL cx_err_t cx_mont_pow	(	cx_bn_t	r,
		const cx_bn_t	a,
		const uint8_t *	e,
		uint32_t	e_len,
		const cx_bn_mont_ctx_t *	ctx
)

Performs a modular exponentiation r = a^e mod n.

The context must be initialized. The BN value a is in Montgomery representation.

Parameters

[out]	r	BN index for the result. The result is in Montgomery representation.
[in]	a	BN index of the exponentiation base in Montgomery representation.
[in]	e	Pointer to the exponent.
[in]	e_len	Length of the exponent in bytes.
[in]	ctx	Pointer to the Montgomery context, initialized with the modulus and the second Montgomery constant.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_mont_pow_bn()

SYSCALL cx_err_t cx_mont_pow_bn	(	cx_bn_t	r,
		const cx_bn_t	a,
		const cx_bn_t	e,
		const cx_bn_mont_ctx_t *	ctx
)

Performs a modular exponentiation r = a^e mod n.

The context must be initialized. The BN value a is in Montgomery representation.

Parameters

[out]	r	BN index for the result. The result is in Montgomery representation.
[in]	a	BN index of the exponentiation base in Montgomery representation.
[in]	e	BN index of the exponent.
[in]	ctx	Pointer to the Montgomery context, initialized with the modulus and the second Montgomery constant.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

cx_mont_to_montgomery()

SYSCALL cx_err_t cx_mont_to_montgomery	(	cx_bn_t	x,
		const cx_bn_t	z,
		const cx_bn_mont_ctx_t *	ctx
)

Computes the Montgomery representation of a BN value.

The context must be initialized.

Parameters

[out]	x	BN index for the result.
[in]	z	BN index of the value to convert into Montgomery representation.
[in]	ctx	Pointer to the Montgomery context, initialized with the modulus and the second Montgomery constant.

Returns

Error code:

• CX_OK on success
• CX_NOT_LOCKED
• CX_INVALID_PARAMETER
• CX_MEMORY_FULL

Back to the files list

---

Did you find this page helpful?

How would you improve this page for developers?

I am a developer.
Contributors will be chosen randomly to receive rewards. Check this box to send your email and participate.

Ledger collects your email address to send you rewards for your contribution to improve the Developer Portal documentation. Learn more about how we manage your data and your rights.

By providing your email address, you consent that Ledger may contact you for rewards delivery purposes. If you are part of the randomly selected contributors, we will send you an email to ask for your physical address and if necessary, ask you for additional information on the suggestion you made. Your information will only be available to Ledger and will be retained for no longer than 90 days. It may be transferred to non-European countries that ensure an adequate level of protection or under the standard contractual clauses adopted by the EU Commission.

Please note that you may withdraw your consent at any time, access your data and request their rectification or deletion. You may also request the limitation of the processing of your data. To exercise your rights or for any question on the processing of your data, please contact LEDGER’s Data Protection Officer here. If nevertheless you believe LEDGER did not adequately address your concerns and mishandled your data, you may lodge a complaint with the personal data protection authority of your country.