How to use the command 'secret-tool' (with examples)

The secret-tool command is a utility used for storing, retrieving, and managing secrets like passwords in a secure manner. It is a part of the libsecret package which provides a unified API for working with password managers such as GNOME Keyring. This command allows users to securely store and access sensitive information by communicating with any Freedesktop secret service implementation, which makes managing passwords both efficient and safe.

Use case 1: Store a secret with an optional label

Code:

secret-tool store --label=MyEmailPassword email myemail@example.com

Motivation:

Storing a secret with an optional label is crucial when you want to save confidential information like passwords or API keys securely. Using a label helps in identifying the stored secret easily without having to remember the associated key-value details. This is particularly useful in environments where multiple secrets are managed, and a quick reference point is required to fetch the correct secret effortlessly.

Explanation:

• store: This command argument specifies that you want to store a new secret.
• --label=MyEmailPassword: The --label option is used to assign a human-readable name to the stored secret. In this case, MyEmailPassword identifies the secret relating to an email password.
• email: This is the key part of the key-value pair that helps in identifying the secret.
• myemail@example.com: This is the value part of the key-value pair which usually contains the sensitive information you want to store securely.

Example Output:

When you execute this command, the secret tool will prompt you to enter and confirm a password. Once entered, it will be securely stored with the label “MyEmailPassword”, but no typical output is displayed for confirmation on the terminal.

Use case 2: Retrieve a secret

Code:

secret-tool lookup email myemail@example.com

Motivation:

There will be times when you need to retrieve stored secrets to use them in your applications or when logging into services. This functionality ensures that you do not have to remember all your passwords or keys, as you can easily fetch them securely when needed. This is particularly useful for developers managing multiple API keys or for users with numerous credential needs.

Explanation:

• lookup: This argument is used when you want to retrieve a stored secret.
• email: This specifies the key part of the key-value pair that identifies which secret you need to retrieve.
• myemail@example.com: The value part here is used to further narrow down the search for the exact secret that was stored.

Example Output:

Upon executing, you might see output similar to this:

EmailPassword123

This is the stored secret; however, the actual output would depend on what value was stored previously.

Use case 3: Get more information about a secret

Code:

secret-tool search email myemail@example.com

Motivation:

In some situations, you might need to gather extra details about a secret you’ve stored. This could include understanding the properties associated with the secret, or confirming the existence of a secret within the secret service. For admins or developers, getting such meta-data can be critical for audit trails or debugging purposes.

Explanation:

• search: This command allows you to find more details or search for a secret stored.
• email: The key we use here helps pinpoint which secret’s information we are interested in.
• myemail@example.com: Like before, this value further clarifies which specific secret from the key-value pairs you are looking to gather information about.

Example Output:

The output will provide detailed information about the secret, such as its creation date or labels, but this depends on the system’s setup. There may be no direct terminal output unless the system is configured to provide additional information.

Use case 4: Delete a stored secret

Code:

secret-tool clear email myemail@example.com

Motivation:

There might be times where it becomes necessary to delete a secret after it is no longer needed or if it has been compromised. Clearing a stored secret ensures that outdated or unsecured credentials do not pose any risk. This command is essential in maintaining a clean and secure environment by ensuring that only relevant and active credentials are stored.

Explanation:

• clear: This command argument indicates that you intend to delete a particular secret.
• email: Specifies the part of the key-value pair needed to identify the secret for deletion.
• myemail@example.com: This value further ensures that the correct secret is targeted for removal.

Example Output:

Upon execution, there typically won’t be any output to the terminal, as the deletion happens quietly. The secret would be removed from the stored secrets database, but no visual confirmation is displayed unless additional verbose flags or logging is enabled in the system.

Conclusion

The secret-tool command provides a powerful facility for securely managing sensitive information. Whether you need to store, retrieve, examine, or delete secrets, secret-tool offers the flexibility and security necessary for effective secret management. Its ability to integrate with systems like GNOME Keyring makes it versatile for various environments and needs.