This tutorial will guide you through the basic steps on how to use Freedesktop Secrets API using the python-sdbus binds.
Note
This tutorial will use blocking API for simplicity. Async API can be easily used instead.
To interact with the secrets API a process needs to acquire a new session.
Secrets API supports an in-transit encryption but its not required. Most of secrets implementations should support plain mode without encryption. This is the simplest way to use secrets API.
secrets_service = SecretService()
session_algorithm = 'plain' # Plain mode, no encryption
session_input = ('s', '') # Variant of an empty string
# With plain algorithm we only need session path
# output of algorithm negotiation can be ignored (assigned to _)
_, my_session_path = secrets_service.open_session(
session_algorithm,
session_input,
)
Session is identified by an object path. In this case the session path is stored in the my_session_path
variable.
Session can be closed manually using :pySecretSessionInterface.close
method or automatically when process that acquired session disconnects from the bus.
Unless you need to store multiple secrets it is better to find a default collection.
This collection should always be present.
default_collection_path = secrets_service.read_alias('default')
default_collection = SecretCollection(default_collection_path)
:pySecretCollectionInterface.create_item
should be used to create new items.
The secret can be created with properties to uniquely identify it. Each property name must be prefixed with org.freedesktop.Secret.Item.
string. For example, secret attributes would be org.freedesktop.Secret.Item.Attributes
. See example.
The secret data itself is a tuple of session path, encryption parameters bytes (empty in case of plain mode), bytes of value and content type string. (for example, text/plain; charset=utf8
)
Last argument is a boolean whether or not to replace existing secret with same attributes.
secret_properties_dict = {
'org.freedesktop.Secret.Item.Label': ('s', 'MyItem'),
'org.freedesktop.Secret.Item.Type': ('s', 'Test'),
'org.freedesktop.Secret.Item.Attributes': ('a{ss}', {
"Attribute1": "Value1",
"Attribute2": "Value2",
})
}
new_secret_path, prompt = default_collection.create_item(
secret_properties_dict,
(
my_session_path, # session path
b'', # encryption parameters, empty in plain mode
b'my secret', # secret value it self
'text/plain; charset=utf8', # content type
),
False, # do not replace secret with same attributes
)
After getting a collection you can either search the items using :pySecretCollectionInterface.search_items
or iterate over :pySecretCollectionInterface.items
property and examine each secret individually.
Each secret has a dictionary of attributes which can be used to uniquely identify a secret.
found_secrets_paths = default_collection.search_items(
{
"Attribute1": "Value1",
"Attribute2": "Value2",
}
)
After finding the secret path in order to get the secret you should use the :pySecretItemInterface.get_secret
method to get secret data.
Secret data contains tuple of session path, encryption parameters bytes (empty in case of plain mode), secret value bytes and content type string.
secret = SecretItem(new_secret_path)
session_path, params, value, content_type = secret.get_secret(my_session_path)
Note
See secrets specification for more in depth look.