lakers – An implementation of EDHOC (RFC 9528) in Rust

This is the documentation of the Python bindings for Lakers, called lakers-python. Documentation on the underlying Rust library is found on docs.rs.

See the project README file for installation, maintenance and license information.

The EdhocInitiator and EdhocResponder are entry points to this module. Both provided classes that represent one side of the EDHOC exchange, and are updated with and produce messages and information through a series of method calls on the object.

Operations in this module produce logging entries on the lakers.initiator and lakers.responder logger names. Due to implementation details of pyo3_log, Python’s log levels are cached in the Rust implementation. It is recommended that the full logging is configured before creating Lakers objects. A setup with logging.basicConfig(loglevel=5) will also show Lakers’ trace level log messages, which have no equivalent Python level.

These are the two main entry points:

class lakers.EdhocInitiator

An implementation of the EDHOC protocol for the initiator side.

prepare_message_1(c_i=None, ead_1=Ellipsis)

Generates message 1.

At this point, a C_I (connection identifier) may be provided, as well as additonal EAD data.

parse_message_2(message_2)

Process message 2.

This produces both the C_R and the ID_CRED_R, and maybe additional EAD data sent by the responder, but does not verify them yet: They are only verified when the application provides the expanded credential CRED_R (typically based on the information in ID_CRED_R) in verify_message_2().

verify_message_2(i, cred_i, valid_cred_r)

Verifies the previously inserted message 2.

At this point, the initiator’s private key I as well as the initiator’s identity CRED_I needs to be provided, as well as the peer’s credential CRED_R (as looked up by its ID_CRED_R from the preceeding parse_message_2() output).

prepare_message_3(cred_transfer, ead_3=Ellipsis)

Generates a message 3.

Input influences whether the credential previously provided in verify_message_2() is sent by value or reference, and whether any additional EAD data is to be sent.

completed_without_message_4()

Declares the protocol to have completed without the need of a message 4.

Key material can be extracted after this point, but some properties of the protocol only hold when non-EDHOC messages protected with the extracted key material are received from the peer.

process_message_4(message_4)

Processes and verifies message 4.

This produces EAD data if the peer sent any.

compute_ephemeral_secret(g_a)

edhoc_exporter(label, context, length)

Exports key material.

edhoc_key_update(context)

Performs the key update procedure, enabling the production of new key material.

get_h_message_1()

selected_cipher_suite()

The cipher suite that is agreed on by the exchange.

class lakers.EdhocResponder(r, cred_r)

An implementation of the EDHOC protocol for the responder side.

process_message_1(message_1)

Processes an incoming message 1.

It produces the C_I and any additional EAD data.

prepare_message_2(cred_transfer, c_r=None, ead_2=Ellipsis)

Generates message 2.

Input influences whether the credential is sent by value or reference, which credential is sent, and whether any optional EAD data is to be sent.

parse_message_3(message_3)

Processes message 3.

This produces the initiator’s ID_CRED_I and maybe additional EAD data sent by the initiator, but does not verify them yet: They are only verified when the application provides the expanded credential CRED_I (typically based on the information in ID_CRED_I) in verify_message_3().

verify_message_3(valid_cred_i)

Verifies the previously inserted message 3.

Verification is based on the CRED_I (as looked up by its ID_CRED_I from the preceeding parse_message_3() output).

completed_without_message_4()

Declares the protocol to have completed without any message 4.

Key material may be exported from this point, and is used to confirm key agreement to the initiator by using it to protect any next protocol.

prepare_message_4(ead_4=Ellipsis)

Generates a message 4.

This may contain additional EAD data.

After generating this message, the protocol has completed.

edhoc_exporter(label, context, length)

Exports key material.

edhoc_key_update(context)

Performs the key update procedure, enabling the production of new key material.

Several tool classes augment the operation of those classes:

class lakers.AuthzAutenticator

prepare_ead_2(voucher_response)

process_ead_1(ead_1, message_1)

class lakers.AuthzDevice(id_u, g_w, loc_w)

get_g_w()

prepare_ead_1(secret, ss)

process_ead_2(ead_2, cred_v)

set_h_message_1(h_message_1)

class lakers.AuthzEnrollmentServer(w, cred_v, acl=None)

handle_voucher_request(vreq)

class lakers.AuthzServerUserAcl(w, cred_v)

decode_voucher_request(vreq)

prepare_voucher(vreq)

class lakers.Credential(value, *, kid=None, public_key=None)

A credential for use in EDHOC.

For now supports CCS credentials only. Experimental support for CCS_PSK credentials is also available.

kid()

public_key()

value()

class lakers.CredentialTransfer

An enum describing options how to send credentials.

ByReference = CredentialTransfer.ByReference

ByValue = CredentialTransfer.ByValue

class lakers.EADItem(label, is_critical, value=None)

An owned EAD item.

is_critical()

label()

value()

lakers.credential_check_or_fetch(id_cred_received, cred_expected=None)

lakers.p256_generate_key_pair()

this function is useful to test the python bindings