pyecsca.codegen.client module

Client script.

Use it to interact with the built implementations (and flash them if necessary).

Examples

The following examples use the generated implementation in pyecsca-codegen-HOST.elf for the host architecture, which is assumed to use the Short-Weierstrass curve model with projective coordinates.

The first example generates a keypair and exports it.

$ client --platform HOST --fw ./pyecsca-codegen-HOST.elf shortw projective gen secg/secp128r1
(162938999268550597445809790209592423458, Point([x=111810799217268384317536017529141796945, y=309320541414531923178173772704935971498] in shortw/affine))
0.01743340492248535

The following example does ECDH with the target, which first generates a keypair.

$ client --platform HOST --fw ./pyecsca-codegen-HOST.elf shortw projective ecdh secg/secp128r1 122835813094999453922649270086793500655,326514220558629293368386081113307347349
Keypair: 162938999268550597445809790209592423458, [x=111810799217268384317536017529141796945, y=309320541414531923178173772704935971498]
ECDH result: 30567033074c9169e9355a7b348aa7511c3ae605

The following example signs a message "something" using the target, which first generates a keypair.

$ client --platform HOST --fw ./pyecsca-codegen-HOST.elf shortw projective ecdsa-sign secg/secp128r1 something
Keypair: 162938999268550597445809790209592423458, [x=111810799217268384317536017529141796945, y=309320541414531923178173772704935971498]
Signature: 30250211009dc6d5b03cffe0cbd5e829838ecb59e4021023496ba97cf1d816619fe626de2d07b6

The following example verifies a signature on the message "something" using the target and the provided public key.

$ client --platform HOST --fw ./pyecsca-codegen-HOST.elf shortw projective ecdsa-verify secg/secp128r1 111810799217268384317536017529141796945,309320541414531923178173772704935971498 something_else 30250211009dc6d5b03cffe0cbd5e829838ecb59e40210171c895d2d4f27850ff5f2a375ea22b7
Result: True

Note

The implementation has a PRNG it uses to get randomness. This PRNG starts with a constant state. You can use the --seed option to set a custom state.

class Triggers(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

Actions that the implementation can trigger on.

Given that this is a bit-flag, multiple choices are allowed, in which case the trigger signal will toggle onn each action entry/exit.

add = 1[source]
dadd = 2[source]
dbl = 4[source]
ladd = 8[source]
neg = 16[source]
scl = 32[source]
tpl = 64[source]
mult = 128[source]
keygen = 256[source]
ecdh = 512[source]
ecdsa_sign = 1024[source]
ecdsa_verify = 2048[source]
coord_map = 4096[source]
random_mod = 8192[source]
conjugate()[source]

Returns self, the complex conjugate of any int.

bit_length()[source]

Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> (37).bit_length()
6
bit_count()[source]

Number of ones in the binary representation of the absolute value of self.

Also known as the population count.

>>> bin(13)
'0b1101'
>>> (13).bit_count()
3
to_bytes(length=1, byteorder='big', *, signed=False)[source]

Return an array of bytes representing an integer.

length

Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes. Default is length 1.

byteorder

The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value. Default is to use ‘big’.

signed

Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

from_bytes(byteorder='big', *, signed=False)[source]

Return the integer represented by the given array of bytes.

bytes

Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.

byteorder

The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value. Default is to use ‘big’.

signed

Indicates whether two’s complement is used to represent the integer.

as_integer_ratio()[source]

Return integer ratio.

Return a pair of integers, whose ratio is exactly equal to the original int and with a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)
real[source]

the real part of a complex number

imag[source]

the imaginary part of a complex number

numerator[source]

the numerator of a rational number in lowest terms

denominator[source]

the denominator of a rational number in lowest terms

cmd_init_prng(seed)[source]
Return type:

str

cmd_set_params(params)[source]
Return type:

str

cmd_generate()[source]
Return type:

str

cmd_set_privkey(privkey)[source]
Return type:

str

cmd_set_pubkey(pubkey)[source]
Return type:

str

cmd_scalar_mult(scalar, point)[source]
Return type:

str

cmd_ecdh(pubkey)[source]
Return type:

str

cmd_ecdsa_sign(data)[source]
Return type:

str

cmd_ecdsa_verify(data, sig)[source]
Return type:

str

cmd_set_trigger(actions)[source]
Return type:

str

cmd_debug()[source]
Return type:

str

class EmulatorTarget(model, coords, print_config=<Print: 0>, trace_config=<rainbow.rainbow.TraceConfig object>, allow_breakpoints=False)[source]

Bases: Target

emulator: rainbow_stm32f215[source]
result: list[source]
trace: list[source]
model: CurveModel[source]
coords: CoordinateModel[source]
seed: Optional[bytes][source]
params: Optional[DomainParameters][source]
privkey: Optional[int][source]
pubkey: Optional[Point][source]
connect(**kwargs)[source]

Connect to the target device.

Return type:

None

set_params(params)[source]
Return type:

None

scalar_mult(scalar, point)[source]
Return type:

Point

init_prng(seed)[source]
Return type:

None

generate()[source]
Return type:

Tuple[int, Point]

set_privkey(privkey)[source]
Return type:

None

set_pubkey(pubkey)[source]
Return type:

None

ecdh(other_pubkey)[source]
Return type:

bytes

ecdsa_sign(data)[source]
Return type:

bytes

ecdsa_verify(data, signature)[source]
Return type:

bool

transform_trace(filter_malloc=True, save_instructions=False)[source]
Return type:

Trace

set_trigger()[source]
debug()[source]
Return type:

Tuple[str, str]

quit()[source]
disconnect()[source]

Disconnect from the target device.

class ImplTarget(model, coords, **kwargs)[source]

Bases: SimpleSerialTarget

A target that is based on an implementation built by pyecsca-codegen.

``

This is an abstract class that uses the send_cmd method on the pyecsca.sca.target.simpleserial.SimpleSerialTarget class to send commands to the target. That class in turn requires one to implement the read/write/connect/disconnect methods that communicate with the target somehow. See DeviceTarget that uses pyecsca.sca.target.chipwhisperer.ChipWhispererTarget for thar purpose, or HostTarget that uses pyecsca.sca.target.binary.BinaryTarget.

timeout: int[source]
model: CurveModel[source]
coords: CoordinateModel[source]
seed: Optional[bytes][source]
params: Optional[DomainParameters][source]
privkey: Optional[int][source]
pubkey: Optional[Point][source]
trigger: Optional[Triggers][source]
init_prng(seed)[source]

Init the PRNG using the seed.

Return type:

None

set_params(params)[source]

Set the domain parameters on the target.

Return type:

None

generate()[source]

Generate a keypair on the target and set it (and export it).

Requires that domain parameters are set up.

Return type:

Tuple[int, Point]

set_privkey(privkey)[source]

Set the private key on the target.

Return type:

None

set_pubkey(pubkey)[source]

Set the public key on the target.

Return type:

None

scalar_mult(scalar, point)[source]

Run scalar multiplication on the target and export the result.

Requires that domain parameters are set up.

Return type:

Point

abstract connect()[source]

Connect to the target device.

ecdh(other_pubkey)[source]

Do ECDH with the target.

Requires that domain parameters are set up, as well as a private key.

Return type:

bytes

abstract read(num=0, timeout=0)[source]

Read upto num bytes or until timeout milliseconds from the target’s serial output.

Parameters:

  • num (int) – The number of bytes to read, 0 for all available.

  • timeout (int) – The timeout in milliseconds.

Return type:

bytes

Returns:

The bytes read.

recv_msgs(timeout)[source]

Receive SimpleSerialMessage messages, while waiting upto timeout seconds.

Parameters:

timeout (int) – How long to wait.

Return type:

Mapping[str, SimpleSerialMessage]

Returns:

The received messages with their char.

send_cmd(cmd, timeout)[source]

Send a SimpleSerialMessage and receive the response messages that the command produces, within a timeout.

Parameters:

  • cmd (SimpleSerialMessage) – The command message to send.

  • timeout (int) – The timeout value to wait for the responses.

Return type:

Mapping[str, SimpleSerialMessage]

Returns:

A mapping of the starting character of the message to the message.

abstract write(data)[source]

Write the data bytes to the target’s serial input.

Parameters:

data (bytes) – The data to write.

Return type:

None

ecdsa_sign(data)[source]

Sign a message on the target.

Requires that domain parameters are set up, as well as a private key.

Return type:

bytes

ecdsa_verify(data, signature)[source]

Verify a signature on the target.

Requires that domain parameters are set up, as well as a public key.

Return type:

bool

debug()[source]

Run the debug command on the target.

Returns the curve model and coordinate model names.

Return type:

Tuple[str, str]

set_trigger(actions)[source]

Setup the trigger on the target. :rtype: None

Note

The triggers are not exclusive, and you can set to trigger on multiple actions. However, note that they toggle the trigger signal. For example, if you set up triggers on scalar multiplication and addition (Triggers.mult | Triggers.add) the trigger signal will go high once scalar multiplication starts, then go low during each addition operation and finally go low for good after scalar multiplication ends.

quit()[source]

Turn off the target.

disconnect()[source]

Disconnect from the target device.

class DeviceTarget(model, coords, platform, **kwargs)[source]

Bases: ImplTarget, ChipWhispererTarget

A ChipWhisperer-based device target.

connect()[source]

Connect to the target device.

debug()[source]

Run the debug command on the target.

Returns the curve model and coordinate model names.

Return type:

Tuple[str, str]

disconnect()[source]

Disconnect from the target device.

ecdh(other_pubkey)[source]

Do ECDH with the target.

Requires that domain parameters are set up, as well as a private key.

Return type:

bytes

ecdsa_sign(data)[source]

Sign a message on the target.

Requires that domain parameters are set up, as well as a private key.

Return type:

bytes

ecdsa_verify(data, signature)[source]

Verify a signature on the target.

Requires that domain parameters are set up, as well as a public key.

Return type:

bool

flash(fw_path)[source]

Flash the firmware at fw_path to the target.

Parameters:

fw_path (str) – The path to the firmware blob.

Return type:

bool

Returns:

Whether the flashing was successful.

generate()[source]

Generate a keypair on the target and set it (and export it).

Requires that domain parameters are set up.

Return type:

Tuple[int, Point]

init_prng(seed)[source]

Init the PRNG using the seed.

Return type:

None

quit()[source]

Turn off the target.

read(num=0, timeout=0)[source]

Read upto num bytes or until timeout milliseconds from the target’s serial output.

Parameters:

  • num (int) – The number of bytes to read, 0 for all available.

  • timeout (int) – The timeout in milliseconds.

Return type:

bytes

Returns:

The bytes read.

recv_msgs(timeout)[source]

Receive SimpleSerialMessage messages, while waiting upto timeout seconds.

Parameters:

timeout (int) – How long to wait.

Return type:

Mapping[str, SimpleSerialMessage]

Returns:

The received messages with their char.

reset()[source]
scalar_mult(scalar, point)[source]

Run scalar multiplication on the target and export the result.

Requires that domain parameters are set up.

Return type:

Point

send_cmd(cmd, timeout)[source]

Send a SimpleSerialMessage and receive the response messages that the command produces, within a timeout.

Parameters:

  • cmd (SimpleSerialMessage) – The command message to send.

  • timeout (int) – The timeout value to wait for the responses.

Return type:

Mapping[str, SimpleSerialMessage]

Returns:

A mapping of the starting character of the message to the message.

set_params(params)[source]

Set the domain parameters on the target.

Return type:

None

set_privkey(privkey)[source]

Set the private key on the target.

Return type:

None

set_pubkey(pubkey)[source]

Set the public key on the target.

Return type:

None

set_trigger(actions)[source]

Setup the trigger on the target. :rtype: None

Note

The triggers are not exclusive, and you can set to trigger on multiple actions. However, note that they toggle the trigger signal. For example, if you set up triggers on scalar multiplication and addition (Triggers.mult | Triggers.add) the trigger signal will go high once scalar multiplication starts, then go low during each addition operation and finally go low for good after scalar multiplication ends.

write(data)[source]

Write the data bytes to the target’s serial input.

Parameters:

data (bytes) – The data to write.

Return type:

None

model: CurveModel[source]
coords: CoordinateModel[source]
seed: Optional[bytes][source]
params: Optional[DomainParameters][source]
privkey: Optional[int][source]
pubkey: Optional[Point][source]
trigger: Optional[Triggers][source]
timeout: int[source]
class HostTarget(model, coords, **kwargs)[source]

Bases: ImplTarget, BinaryTarget

A host-based target, will just run the binary on your machine and communicate with it via stdin/stdout.

connect()[source]

Connect to the target device.

debug()[source]

Run the debug command on the target.

Returns the curve model and coordinate model names.

Return type:

Tuple[str, str]

disconnect()[source]

Disconnect from the target device.

ecdh(other_pubkey)[source]

Do ECDH with the target.

Requires that domain parameters are set up, as well as a private key.

Return type:

bytes

ecdsa_sign(data)[source]

Sign a message on the target.

Requires that domain parameters are set up, as well as a private key.

Return type:

bytes

ecdsa_verify(data, signature)[source]

Verify a signature on the target.

Requires that domain parameters are set up, as well as a public key.

Return type:

bool

generate()[source]

Generate a keypair on the target and set it (and export it).

Requires that domain parameters are set up.

Return type:

Tuple[int, Point]

init_prng(seed)[source]

Init the PRNG using the seed.

Return type:

None

process: Optional[Popen] = None[source]
quit()[source]

Turn off the target.

read(num=0, timeout=0)[source]

Read upto num bytes or until timeout milliseconds from the target’s serial output.

Parameters:

  • num (int) – The number of bytes to read, 0 for all available.

  • timeout (int) – The timeout in milliseconds.

Return type:

bytes

Returns:

The bytes read.

recv_msgs(timeout)[source]

Receive SimpleSerialMessage messages, while waiting upto timeout seconds.

Parameters:

timeout (int) – How long to wait.

Return type:

Mapping[str, SimpleSerialMessage]

Returns:

The received messages with their char.

scalar_mult(scalar, point)[source]

Run scalar multiplication on the target and export the result.

Requires that domain parameters are set up.

Return type:

Point

send_cmd(cmd, timeout)[source]

Send a SimpleSerialMessage and receive the response messages that the command produces, within a timeout.

Parameters:

  • cmd (SimpleSerialMessage) – The command message to send.

  • timeout (int) – The timeout value to wait for the responses.

Return type:

Mapping[str, SimpleSerialMessage]

Returns:

A mapping of the starting character of the message to the message.

set_params(params)[source]

Set the domain parameters on the target.

Return type:

None

set_privkey(privkey)[source]

Set the private key on the target.

Return type:

None

set_pubkey(pubkey)[source]

Set the public key on the target.

Return type:

None

set_trigger(actions)[source]

Setup the trigger on the target. :rtype: None

Note

The triggers are not exclusive, and you can set to trigger on multiple actions. However, note that they toggle the trigger signal. For example, if you set up triggers on scalar multiplication and addition (Triggers.mult | Triggers.add) the trigger signal will go high once scalar multiplication starts, then go low during each addition operation and finally go low for good after scalar multiplication ends.

write(data)[source]

Write the data bytes to the target’s serial input.

Parameters:

data (bytes) – The data to write.

Return type:

None

model: CurveModel[source]
coords: CoordinateModel[source]
seed: Optional[bytes][source]
params: Optional[DomainParameters][source]
privkey: Optional[int][source]
pubkey: Optional[Point][source]
trigger: Optional[Triggers][source]
timeout: int[source]
binary: List[str][source]
debug_output: bool[source]