bolos_endorsement.h File Reference

Endorsement API used to prove code execution on a secure device. More...

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

Go to the source code of this file.

Typedefs
typedef enum bls_endorsement_key_e	bls_endorsement_key_t

Enumerations
enum	bls_endorsement_key_e { BLS_ENDORSEMENT_KEY1, BLS_ENDORSEMENT_KEY2 }
	Describe the endorsement key to use. More...

Functions
int	bls_endorsement_supported (bls_endorsement_key_t key)
	Check if endorsement is supported for the given key. More...
int	bls_endorsement_get_authentication_public_key (uint8_t *out, size_t outLength)
	Get the per device unique uncompressed public key signing the endorsement initialization request. More...
int	bls_endorsement_init (bls_endorsement_key_t key, uint8_t *out, size_t outLength)
	Initialize an endorsement key provisioning for the given key. More...
int	bls_endorsement_commit (bls_endorsement_key_t key, uint8_t *response, size_t responseLength)
	Finalize an endorsement key provisioning process by providing the associated certificate. More...
int	bls_endorsement_get_code_hash (uint8_t *out, size_t outLength)
	Get the currently running code hash. More...
int	bls_endorsement_key1_get_app_secret (uint8_t *out, size_t outLength)
	Get the application secret for endorsement key 1. More...
int	bls_endorsement_key1_sign_data (const uint8_t WIDE *in, size_t length, uint8_t *out, size_t outLength)
	Sign a message using endorsement key 1. More...
int	bls_endorsement_key2_derive_sign_data (const uint8_t WIDE *in, size_t length, uint8_t *out, size_t outLength)
	Sign a message using a key derived from endorsement key 2. More...
int	bls_endorsement_get_public_key (bls_endorsement_key_t endorsementKey, uint8_t *out, size_t outLength)
	Get the public component of an endorsement key. More...
int	bls_endorsement_get_certificate (bls_endorsement_key_t endorsementKey, uint8_t *out, size_t outLength)
	Get the certificate associated to an endorsement key. More...

Detailed Description

Endorsement API used to prove code execution on a secure device.

Author

Ledger Firmware Team hello.nosp@m.@led.nosp@m.ger.f.nosp@m.r

Version

1.0

Date

29th of February 2016

The endorsement API let developers verify cryptographic proofs that the code is running on a trusted device initialized by the issuer

Two set of algorithms are available :

• Algorithm 1 provides a secret to the running code, and let the running code sign a message. Both elements are bound to the running code and the unique per device private key A1.
• Algorithm 2 let the running code sign a message using a key derived from the unique per device private key A2

The provisioning of both keys can be done by the developer or the issuer

Enumeration Type Documentation

enum bls_endorsement_key_e

Describe the endorsement key to use.

Enumerator
BLS_ENDORSEMENT_KEY1	use endorsement key 1
BLS_ENDORSEMENT_KEY2	use endorsement key 2

Function Documentation

int bls_endorsement_commit	(	bls_endorsement_key_t	key,
		uint8_t *	response,
		size_t	responseLength
	)

Finalize an endorsement key provisioning process by providing the associated certificate.

No check is performed on the certificate format

Parameters

[in]	key	Endorsement key to provision
[in]	response	Buffer containing the certificate
[in]	responseLength	Size of the buffer containing the certificate

Returns

1 if success, 0 if error

int bls_endorsement_get_authentication_public_key	(	uint8_t *	out,
		size_t	outLength
	)

Get the per device unique uncompressed public key signing the endorsement initialization request.

Parameters

[out]	out	Buffer to contain the key
[in]	outLength	Size of the buffer to contain the key

Returns

size of the uncompressed public key if success, 0 if error

int bls_endorsement_get_certificate	(	bls_endorsement_key_t	endorsementKey,
		uint8_t *	out,
		size_t	outLength
	)

Get the certificate associated to an endorsement key.

Parameters

[in]	endorsementKey	Endorsement certificate to retrieve
[out]	out	Buffer to contain the certificate
[in]	outLength	Size of the buffer to contain the certificate

Returns

size of the certificate if success, 0 if error

int bls_endorsement_get_code_hash	(	uint8_t *	out,
		size_t	outLength
	)

Get the currently running code hash.

The hashed data is implementation dependant

Parameters

[out]	out	Buffer to contain the hash
[in]	outLength	Size of the buffer to contain the hash

Returns

size of the code hash if success, 0 if error

int bls_endorsement_get_public_key	(	bls_endorsement_key_t	endorsementKey,
		uint8_t *	out,
		size_t	outLength
	)

Get the public component of an endorsement key.

Parameters

[in]	endorsementKey	Endorsement public key to retrieve
[out]	out	Buffer to contain the uncompressed public key
[in]	outLength	Size of the buffer to contain the uncompressed public key

Returns

size of the uncompressed public key if success, 0 if error

int bls_endorsement_init	(	bls_endorsement_key_t	key,
		uint8_t *	out,
		size_t	outLength
	)

Initialize an endorsement key provisioning for the given key.

When called, the device generates a secp256k1 new key pair for the given endorsement key then returns the uncompressed public key and a signature of the uncompressed public key by the device unique endorsement authentication key.

Parameters

[in]	key	Endorsement key to provision
[out]	out	Buffer to contain the endorsement provisioning request
[in]	outLength	Size of the buffer to contain the endorsement provisioning request

Returns

size of the endorsement provisioning request if success, 0 if error

int bls_endorsement_key1_get_app_secret	(	uint8_t *	out,
		size_t	outLength
	)

Get the application secret for endorsement key 1.

The application secret is defined as a HMAC-SHA512 of the currently running code hash using the endorsement key 1 as key

Parameters

[out]	out	Buffer to contain the application secret
[in]	outLength	Size of the buffer to contain the application secret

Returns

size of the application secret if success, 0 if error

int bls_endorsement_key1_sign_data	(	const uint8_t WIDE *	in,
		size_t	length,
		uint8_t *	out,
		size_t	outLength
	)

Sign a message using endorsement key 1.

This call returns the ECDSA signature of a SHA-256 hash of (currently running code hash || message) by endorsement key 1

Parameters

[in]	in	Buffer containing the message to sign
[in]	length	Size of the message to sign
[out]	out	Buffer to contain the signature
[in]	outLength	Size of the buffer to contain the signature

Returns

size of the signature if success, 0 if error

int bls_endorsement_key2_derive_sign_data	(	const uint8_t WIDE *	in,
		size_t	length,
		uint8_t *	out,
		size_t	outLength
	)

Sign a message using a key derived from endorsement key 2.

This call returns the ECDSA signature of a SHA-256 hash of the message by a private key computed by adding mod n the HMAC-SHA256 of the endorsement key 2 public key using the currently running code hash as key to the endorsement key 2 private key.

Parameters

[in]	in	Buffer containing the message to sign
[in]	length	Size of the message to sign
[out]	out	Buffer to contain the signature
[in]	outLength	Size of the buffer to contain the signature

Returns

size of the signature if success, 0 if error

int bls_endorsement_supported

(

bls_endorsement_key_t

key

)

Check if endorsement is supported for the given key.

Parameters

[in]

key

Endorsement key to check

Returns

1 if supported, 0 if not supported