{"id":20398489,"url":"https://github.com/keeper-security/linux-keyring-utility","last_synced_at":"2026-05-12T19:15:42.433Z","repository":{"id":255095587,"uuid":"802215269","full_name":"Keeper-Security/linux-keyring-utility","owner":"Keeper-Security","description":"A utility for natively interacting with the Linux Keyring","archived":false,"fork":false,"pushed_at":"2024-11-25T11:07:43.000Z","size":48,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-01-15T11:14:36.121Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Keeper-Security.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-17T18:42:55.000Z","updated_at":"2024-11-28T12:13:57.000Z","dependencies_parsed_at":"2024-09-10T01:24:20.188Z","dependency_job_id":"280d39f5-c57f-474d-b4b7-b80a39301931","html_url":"https://github.com/Keeper-Security/linux-keyring-utility","commit_stats":null,"previous_names":["keeper-security/linux-keyring-utility"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Keeper-Security%2Flinux-keyring-utility","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Keeper-Security%2Flinux-keyring-utility/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Keeper-Security%2Flinux-keyring-utility/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Keeper-Security%2Flinux-keyring-utility/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Keeper-Security","download_url":"https://codeload.github.com/Keeper-Security/linux-keyring-utility/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241945529,"owners_count":20046870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T04:22:17.626Z","updated_at":"2026-05-12T19:15:42.404Z","avatar_url":"https://github.com/Keeper-Security.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Linux Keyring Utility\n\nThis utility interacts with the native Linux APIs to store and retrieve secrets from the Keyring using [Secret Service](https://specifications.freedesktop.org/secret-service/latest/).\nIt can be used by any integration, plugin, or code base to store and retrieve credentials, secrets, and passwords in any Linux Keyring simply and natively.\n\nTo use this utility, you can deploy the pre-built binary from the releases page, or by importing it into your code base. Both use cases are covered below.\n\nFor Windows implementations, see the [Windows Credential Utility](https://github.com/Keeper-Security/windows-credential-utility).\n\n## Details\n\nThe Linux Keyring Utility gets and sets _secrets_ in a Linux\n[Keyring](http://man7.org/linux/man-pages/man7/keyrings.7.html) using the\n[D-Bus](https://dbus.freedesktop.org/doc/dbus-tutorial.html)\n[Secret Service](https://specifications.freedesktop.org/secret-service/latest/).\n\nIt has been tested with\n[GNOME Keyring](https://wiki.gnome.org/Projects/GnomeKeyring/) and\n[KDE Wallet Manager](https://userbase.kde.org/KDE_Wallet_Manager).\nIt _should_ work with any implementation of the D-Bus Secrets Service.\n\n### Interface\n\nThere are two packages, `dbus_secrets` and `secret_collection`.\nThe `secret_collection` object uses the functions in `dbus_secrets`.\nIt unifies the D-Bus _Connection_, _Session_ and _Collection Service_ objects to offer a simple get/set/delete interface that the CLI uses.\n\n## Usage\n\nThe Go Language API has offers `Get()`, `Set()` and `Delete()` methods.\nThe first two accept and return `string` data.\n\n### Example (get)\n\n```go\npackage main\n\nimport (\n    \"os\"\n    sc \"github.com/Keeper-Security/linux-keyring-utility/pkg/secret_collection\"\n)\n\nfunc doit() {\n    if collection, err := sc.DefaultCollection(); err == nil {\n        if err := collection.Unlock(); err == nil {\n            if secret, err := collection.Get(\"myapp\", \"mysecret\"); err == nil {\n                print(string(secret))\n                os.Exit(0)\n            }\n        }\n    }\n    os.Exit(1)\n}\n```\n\nThe `.DefaultCollection()` returns whatever collection the _default_ _alias_ refers to.\nIt will generate an error if the _default_ alias is not set.\nMost Linux Keyring interfaces allow the user to set it.\n\nThe `.NamedCollection(string)` method provides access to collections by name.\n\n### Example (set)\n\nSet takes the data as a parameter and only returns an error or `nil` on success.\nIt does not restrict the content or length of the secret data.\n\n```go\nif err := collection.Set(\"myapp\", \"mysecret\", \"mysecretdata\"); err == nil {\n    // success\n}\n```\n\n## Binary Interface (CLI)\n\nThe Linux binary supports three subcommands:\n\n1. `get`\n2. `set`\n3. `del`\n4. `version`\n\n_Get_ and _del_ require one parameter; name, which is the secret _Label_ in D-Bus API terms.\n\n_Del_ or _delete_ accepts one or more secret labels and deletes all of them.\nIt will stop on the first error condition it encounters.\n\n_Set_ requires the data as a _single_ string in the second parameter.\nFor example, `set foo bar baz` will generate an error but `set foo 'bar baz'` will work.\nIf the string is `-` then the string is read from standard input.\n\n_Version_ prints the version and exits with status 0.\n\n### Base64 encoding\n\n_Get_ and _set_ take a `-b` or `--base64` flag that handles base64 automatically.\nIf used, _Set_ will encode the input before storing it and/or _get_ will decode it before printing.\n\nNote that calling `get -b` on a secret that is _not_ base64 encoded secret will generate an error.\n\n### Examples\n\n```shell\n# set has no output\nlkru set root_cred '{\n    \"username\": \"root\"\n    \"password\": \"rand0m.\"\n}'\n# get prints (to stdout) whatever was set\nlku get root_cred\n{\n    \"username\": \"root\"\n    \"password\": \"rand0m.\"\n}\nlkru set -b root_cred2 '{\"username\": \"gollum\", \"password\": \"MyPrecious\"}'\nlkru get root_cred2\neyJ1c2VybmFtZSI6ICJnb2xsdW0iLCAicGFzc3dvcmQiOiAiTXlQcmVjaW91cyJ9\nlkru get -b root_cred2\n{\"username\": \"gollum\", \"password\": \"MyPrecious\"}\ncat ./good_cred.json | lkru set -b root_cred3 -\nlkru get root_cred3\newogICJ1c2VybmFtZSI6ICJhZGFtIiwKICAicGFzc3dvcmQiOiAicGFzc3dvcmQxMjMuIgp9\n```\n\n### Errors\n\nError output goes to `stderr` so adding `2\u003e/dev/null` to the end of a command will suppress it.\n\n#### No keyring\n\nThe default alias does not point to a collection.\nIt might not exist or there may not be a default.\nUse KDE Wallet Manager or GNOME Seahorse to create a collection and/or it as default.\n\n```shell\nUnable to get secret 'test_cred': Unable to retrieve secret 'test_cred' for application 'lkru' from collection '/org/freedesktop/secrets/aliases/default': Object does not exist at path “/org/freedesktop/secrets/aliases/default”\n```\n\n#### No matching secret\n\nA secret may not be returned even though a secret with the same label exists.\nIf the secret was not created with lkru, it may not have the same [attributes](/Keeper-Security/linux-keyring-utility/blob/main/pkg/dbus_secrets/dbus_secrets.go#L41). Namely 'Agent', 'Application', and 'Id'.\n\n```shell\nUnable to get secret 'test_cred': Unable to retrieve secret 'test_cred' for application 'lkru' from collection '/org/freedesktop/secrets/aliases/default': org.freedesktop.Secret.Collection.SearchItems returned nothing\n```\n\n#### No D-Bus Session Secret Service\n\nThere is no Secret Service registered on the D-Bus Session.\nThis happens when the user is not logged into the GUI.\n\n```shell\nUnable to get the default keyring: Unable to open a D-Bus session: The name org.freedesktop.secrets was not provided by any .service files\n```\n\n#### No D-Bus\n\nThe system is not running D-Bus.\nSeveral lightweight linux distributions ship without it by default.\n\n```shell\nUnable to get the default keyring: Unable to connect to the D-Bus Session Bus: exec: \"dbus-launch\": executable file not found in $PATH\n```\n\n## Contributing\n\nPlease read and refer to the contribution guide before making your first PR.\n\nFor bugs, feature requests, etc., please submit an issue!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeeper-security%2Flinux-keyring-utility","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeeper-security%2Flinux-keyring-utility","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeeper-security%2Flinux-keyring-utility/lists"}