stringphone package¶

This is the autogenerated API documentation. Use it as a reference to the public API of the project.

stringphone.crypto module¶

Symmetric and asymmetric cryptography- and signing-related classes and methods.

class stringphone.crypto.AsymmetricCrypto[source]¶

Bases: object

decrypt(ciphertext, public_key)[source]¶

Asymmetrically decrypt and verify the ciphertext.

Parameters:	plaintext (bytes) – The ciphertext to decrypt. public_key (bytes) – The sender’s public encryption key.
Returns:	The plaintext.
Return type:	bytes

encrypt(plaintext, public_key)[source]¶

Asymmetrically encrypt and sign the plaintext to the given public key.

Parameters:	plaintext (bytes) – The plaintext to encrypt. public_key (bytes) – The recipient’s public encryption key.
Returns:	The ciphertext.
Return type:	bytes

public_key¶

The public encryption key of the AsymmetricCrypto object.

Return type:	bytes

class stringphone.crypto.Signer(private_key)[source]¶

Bases: object

Instantiate a new Signer.

Parameters:	private_key (bytes) – The private signing key to use. Use `generate_signing_key_seed` to generate this.

public_key¶

The public key of this Signer object.

Return type:	bytes

sign(plaintext)[source]¶

Sign the given plaintext.

Parameters:	plaintext (bytes) – The plaintext to sign.
Returns:	The signed plaintext.
Return type:	bytes

class stringphone.crypto.SymmetricCrypto(key)[source]¶

Bases: object

Instantiate a new SymmetricCrypto object.

SymmetricCrypto performs symmetric encryption and decryption of byte arrays.

Parameters:	key (bytes) – The key to use for encryption and decryption. Use `generate_topic_key` to generate this.

decrypt(ciphertext)[source]¶

Decrypt the ciphertext.

Parameters:	ciphertext (bytes) – The ciphertext to decrypt.
Returns:	The ciphertext.
Return type:	bytes

encrypt(plaintext)[source]¶

Encrypt the plaintext.

Parameters:	plaintext (bytes) – The plaintext to encrypt.
Returns:	The ciphertext.
Return type:	bytes

class stringphone.crypto.Verifier(public_key)[source]¶

Bases: object

Instantiate a new Verifier.

Parameters:	public_key (bytes) – The public signing key to use.

verify(signed)[source]¶

Verify the signature of a signed bytestring.

Raises BadSignatureError:
Returns:	The plaintext that was signed with a valid signature.
Return type:	bytes
	The signature was invalid.

stringphone.crypto.generate_signing_key_seed()[source]¶

Generate and return a new signing key seed. The generated seed is cryptographically secure.

Returns:	A cryptographically secure random signing key seed.
Return type:	bytes

stringphone.crypto.generate_topic_key()[source]¶

Generate and return a new topic key. The generated key is cryptographically secure.

Returns:	A cryptographically secure random topic key.
Return type:	bytes

stringphone.exceptions module¶

exception stringphone.exceptions.BadSignatureError[source]¶

Bases: Exception

Raised when a signature did not verify.

exception stringphone.exceptions.IntroductionError[source]¶

Bases: Exception

Raised when a message is an introduction.

exception stringphone.exceptions.IntroductionReplyError[source]¶

Bases: Exception

Raised when a message is an introduction reply.

exception stringphone.exceptions.MalformedMessageError[source]¶

Bases: Exception

Raised when attempting to decode a malformed message.

exception stringphone.exceptions.MissingTopicKeyError[source]¶

Bases: Exception

Raised when trying to encode data without the topic key.

exception stringphone.exceptions.UntrustedKeyError[source]¶

Bases: Exception

Raised when the verification key for a signed message could not be found.

stringphone.topic module¶

lasses and methods relating to the topic and its participants.

class stringphone.topic.Message(message)[source]¶

Bases: bytes

ciphertext¶

The ciphertext.

Raises ValueError:
Return type:	bytes
	if the given message type does not have this property.

encrypted_topic_key¶

The encrypted topic key.

Raises ValueError:
Return type:	bytes
	if the given message type does not have this property.

encryption_key¶

The encryption key that encrypts the topic key.

Raises ValueError:
Return type:	bytes
	if the given message type does not have this property.

recipient_id¶

The ID of the recipient.

Raises ValueError:
Return type:	bytes
	if the given message type does not have this property.

sender_id¶

The ID of the sender.

Raises ValueError:
Return type:	bytes
	if the given message type does not have this property.

sender_key¶

The public key of the sender.

Raises ValueError:
Return type:	bytes
	if the given message type does not have this property.

signed_encryption_key¶

The signed encryption key.

Raises ValueError:
Return type:	bytes
	if the given message type does not have this property.

signed_payload¶

The signed payload (signature + ciphertext).

Raises ValueError:
Return type:	bytes
	if the given message type does not have this property.

type¶

The type of the message.

Return type:	int

class stringphone.topic.Topic(signing_key_seed=None, topic_key=None, participants=None)[source]¶

Bases: object

A topic is the main avenue of communication. It can be any one-to-many channel, such as an MQTT topic, an IRC chat room, or even a TCP socket (one-to-one is a subset of one-to-many communication).

Various amounts of state can be passed to initialize according to each use case.

Parameters:

signing_key_seed (bytes) –
The optional seed for our signing key. If you require identity persistence of this participant across restarts, save and provide this. A participant’s public and private key and ID are generated from this seed, so passing the same seed will result in the same keys and ID. Keep this completely secret from everyone.

If this is not provided, one will be generated. You will not be able to retrieve the generated seed, so only do this if you don’t care about persistent identities.
topic_key (bytes) –
The optional symmetric encryption key this topic uses. If this is known when instantiating, we can start sending and receiving messages immediately, and discovery will only be useful to get other participants to trust us.

If this is not provided, encryption and decryption will fail.
participants (dict) – The optional dictionary of trusted participants. This should have the form {b”participant_id”: b”participant_key”}. Participant keys in this dictionary will be trusted when verifying messages signed with them.

add_participant(public_key)[source]¶

Add a participant to the list of trusted participants.

Parameters:	public_key (bytes) – The public key of the participant to add.

construct_intro()[source]¶

Generate an introduction of ourselves to send to other devices.

Returns:	The message to broadcast.
Return type:	bytes

construct_reply(message)[source]¶

Generate a reply to an introduction. This gives the party that was just introduced FULL ACCESS to the topic key and all decrypted messages.

Raises BadSignatureError:
Parameters:	message (bytes) – The raw introduction message from the channel.
Returns:	The reply message to broadcast.
Return type:	bytes
	if the signature of the encryption key is invalid.

decode(message, naive=False, ignore_untrusted=False)[source]¶

Decode a message.

If naive is True, signature verification will not be performed. Use at your own risk.

Parameters:	message (bytes) – The plaintext to encode. naive (bool) – If `True`, signature verification IS NOT PERFORMED. Use at your own risk. ignore_untrusted (bool) – If `True`, messages from unknown participants will be silently ignored. This does not include introductions or introduction replies, as those are special and will still raise an exception.
Returns:	The decrypted and (optionally) verified plaintext.
Return type:	bytes

encode(message)[source]¶

Encode a message from transmission.

Parameters:	message (bytes) – The plaintext to encode.
Returns:	The encrypted ciphertext to broadcast.
Return type:	bytes

id¶

Our ID.

Return type:	bytes

parse_reply(message)[source]¶

Decode the reply to an introduction. If the reply contains a valid encrypted topic key that is addressed to us, add it to the topic. If we already know the topic key, ignore this message.

Parameters:	message (bytes) – The raw reply message from the channel.
Returns:	Whether the retrieval of the topic key was successful.
Return type:	bool

participants()[source]¶

Return all trusted participants.

Return type:	dict

public_key¶

Our public key.

Return type:	bytes

remove_participant(participant_id)[source]¶

Remove a participant from the list of trusted participants.

Parameters:	participant_id (bytes) – The ID of the participant to remove.

topic_key¶

Return the topic encryption key.

Return type:	bytes