Gcr.SecretExchange

Subclasses:

None

Methods

Inherited:

GObject.Object (37)

Structs:

GObject.ObjectClass (5)

class	new (protocol)
	begin ()
	get_protocol ()
	get_secret ()
	receive (exchange)
	send (secret, secret_len)

Virtual Methods

Inherited:

GObject.Object (7)

	do_derive_transport_key (peer, n_peer)
	do_generate_exchange_key (scheme, public_key, n_public_key)

Properties

Name	Type	Flags	Short Description
protocol	str	r/w/co	Exchange protocol

Signals

Inherited:

GObject.Object (1)

Fields

Inherited:

GObject.Object (1)

Name	Type	Access	Description
parent	GObject.Object	r

Class Details

class Gcr.SecretExchange(**kwargs)

Bases:

GObject.Object

Abstract:

No

Structure:

Gcr.SecretExchangeClass

Allows exchange of secrets between two processes on the same system without exposing those secrets to things like loggers, non-pageable memory etc.

This does not protect against active attacks like MITM attacks.

Each side creates a secret exchange object, and one of the sides calls [method`SecretExchange`.begin]. This creates a string, which should be passed to the other side. Each side passes the strings it receives into [method`SecretExchange`.receive].

In order to send a reply (either with or without a secret) use [method`SecretExchange`.send]. A side must have successfully called [method`SecretExchange`.receive] before it can use [method`SecretExchange`.send].

The secret exchange objects can be used for multiple iterations of the conversation, or for just one request/reply. The only limitation being that the initial request cannot contain a secret.

Caveat: Information about the approximate length (rounded up to the nearest 16 bytes) may be leaked. If this is considered inacceptable, do not use [class`SecretExchange`].

classmethod new(protocol)

Parameters:

protocol (str or None) – the exchange protocol to use

Returns:

A new Gcr.SecretExchange object

Return type:

Gcr.SecretExchange

Create a new secret exchange object.

Specify a protocol of None to allow any protocol. This is especially relevant on the side of the exchange that does not call [method`SecretExchange`.begin], that is the originator. Currently the only protocol supported is Gcr.SECRET_EXCHANGE_PROTOCOL_1.

begin()

Returns:

A newly allocated string to be sent to the other side of the secret exchange

Return type:

str

Begin the secret exchange. The resulting string should be sent to the other side of the exchange. The other side should use [method`SecretExchange`.receive] to process the string.

get_protocol()

Returns:

the protocol or None

Return type:

str

Will return None if no protocol was specified, and either [method`SecretExchange`.begin] or [method`SecretExchange`.receive] have not been called successfully.

get_secret()

Returns:

the last secret received

Return type:

[str]

Returns the last secret received. If no secret has yet been received this will return None. The string is owned by the Gcr.SecretExchange object and will be valid until the next time that Gcr.SecretExchange.receive() is called on this object, or the object is destroyed.

Depending on the secret passed into the other side of the secret exchange, the result may be a binary string. It does however have a null terminator, so if you’re certain that it is does not contain arbitrary binary data, it can be used as a string.

receive(exchange)

Parameters:

exchange (str) – the string received

Returns:

whether the string was successfully parsed and received

Return type:

bool

Receive a string from the other side of secret exchange. This string will have been created by [method`SecretExchange`.begin] or [method`SecretExchange`.send].

After this call completes successfully the value returned from Gcr.SecretExchange.get_secret() will have changed.

send(secret, secret_len)

Parameters:

• secret (str or None) – optionally, a secret to send to the other side

• secret_len (int) – length of secret, or -1 if null terminated

Returns:

a newly allocated string to be sent to the other side of the secret exchange

Return type:

str

Send a reply to the other side of the secret exchange, optionally sending a secret.

[method`SecretExchange`.receive] must have been successfully called at least once on this object. In other words this object must have received data from the other side of the secret exchange, before we can send a secret.

do_derive_transport_key(peer, n_peer) virtual

Parameters:

• peer (int) –

• n_peer (int) –

Return type:

bool

do_generate_exchange_key(scheme, public_key, n_public_key) virtual

Parameters:

• scheme (str) –

• public_key (int) –

• n_public_key (int) –

Return type:

bool

Property Details

Gcr.SecretExchange.props.protocol

Name:

protocol

Type:

str

Default Value:

'sx-aes-1'

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

The protocol being used for the exchange.

Will be None if no protocol was specified when creating this object, and either [method`SecretExchange`.begin] or [method`SecretExchange`.receive] have not been called successfully.