Lib.rs

Keyring-rs

一个跨平台库，用于在底层平台安全存储中管理密码（和其他机密）的存储和检索，并提供了一个完整的示例，该示例提供了一个命令行界面。

用法

要在项目中使用此crate，您必须在您的Cargo.toml中包含它，并指定您想使用的每个支持的凭证存储的feature。例如，如果您想在Mac和Win上使用平台凭证存储，并在Linux和*nix平台上使用Secret Service（同步），则您可以在[dependencies]部分添加如下片段：

keyring = { version = "3", features = ["apple-native", "windows-native", "sync-secret-service"] }

这将使您能够在代码中访问keyring crate。现在，您可以使用Entry::new函数创建一个新的密钥环条目。该new函数接受一个服务名称和一个用户名称，它们共同识别条目。

密码（字符串）或机密（二进制数据）可以通过其set_password或set_secret方法添加到条目中。（这些方法在底层凭证存储中创建条目。）然后可以使用get_password或get_secret方法读取密码或机密。然后可以使用delete_credential方法删除底层的凭证（及其密码/机密数据）。

use keyring::{Entry, Result};

fn main() -> Result<()> {
    let entry = Entry::new("my-service", "my-name")?;
    entry.set_password("topS3cr3tP4$$w0rd")?;
    let password = entry.get_password()?;
    println!("My password is '{}'", password);
    entry.delete_credential()?;
    Ok(())
}

错误

创建和操作条目可能会产生一个keyring::Error，它提供了一种平台无关的代码来分类错误，以及在相关的情况下，底层平台错误或更多有关错误原因的信息。

示例

keychain-rs项目包含一个示例应用程序（keyring-cli）和一个示例库（ios）。

《keyring-cli》应用程序是一个命令行界面，用于访问密钥环的全部功能。无需参数即可调用它以查看使用信息。它使用base64编码处理二进制数据的输入和输出。可以使用以下命令安装：cargo install，并用于测试库功能。当调试基于密钥环的应用程序时也可以使用，以便探测凭证存储的内容；只需确保使用与您的应用程序相同的特性/凭证存储构建它即可。

《ios》库是对iOS功能的全范围练习；它旨在加载到iOS测试框架中，例如此项目中找到的测试框架。虽然该库也可以在macOS上编译和链接，但这样做并不比直接使用crate提供任何优势。

客户端测试

该crate附带了一个模拟凭证存储，可以供希望在无需访问本地平台存储的情况下进行测试的客户端使用。模拟存储是跨平台的，允许模拟错误以及成功。

可扩展性

该crate允许客户端通过提供客户端可以实现的特性行为“自带凭证存储”。有关详细信息，请参阅开发者文档。

平台

该crate提供了以下特定平台凭证存储的内置实现

• Linux：基于DBus的Secret Service和内核keyutils。
• FreeBSD、OpenBSD：基于DBus的Secret Service。
• macOS、iOS：本地密钥链。
• Windows：Windows凭证管理器。

要启用您想要的存储，您可以使用特性：每个可能包含的凭证存储都有一个特性。如果您指定了特性（例如，dbus-secret-service）以及您的目标平台（例如，freebsd）支持该凭证存储，则它将作为该构建的默认凭证存储包含在内。这样，您可以为每个目标平台指定单个凭证存储的构建命令，并为所有目标使用相同的构建命令。

如果您未启用特定目标上支持的所有凭证存储，则该目标的默认存储将是模拟密钥存储。如果为特定目标启用了多个凭证存储，您将收到编译错误。有关哪些特性控制哪些凭证存储的包含（以及每个凭证存储针对哪些平台）的详细信息，请参阅开发者文档。

特定平台问题

由于维护者以及GitHub都没有在BSD变种上进行测试，我们依赖于贡献者来支持这些平台。感谢您的帮助！

如果您使用Secret Service作为凭证存储，请注意以下事项

• 通过此crate访问凭证存储始终是同步的；也就是说，它阻塞了调用它的线程。即使您的特性集指定了使用基于Zbus的secret-service crate（它提供了异步接口），这也同样适用，因为此crate始终使用阻塞接口。如果您的应用程序已经在使用异步运行时，并且您在此crate中使用async-secret-service特性构建，您应该（1）为此crate指定您正在使用的相同的异步运行时作为特性，并且（2）确保有一个单独的线程用于所有访问凭证存储的keyring调用。未使用单独的线程可能导致死锁。
• 因为这个存储库的凭证存储访问总是同步的，所以即使您的代码已经使用了一个异步运行时，也没有理由不使用这个存储库的sync-secret-service功能（而不是async-secret-service）。是的，这个功能要求在您的用户机器上安装libdbus，但在所有包含秘密服务实现的桌面操作系统安装中默认都有（例如Gnome密钥圈或KWallet）。如果您想格外小心，可以使用这个存储库的附加vendored功能将dbus库与您的应用程序静态链接，这样就不需要在用户机器上安装了。但请记住，如果更新了libdbus，使用vendored功能将需要重建您的应用程序，以便将libdbus更新发送给用户。
• 每次调用秘密服务都是通过进程间调用完成的，这需要时间（通常是几十毫秒，甚至几百毫秒）。如果由于某种原因，您的代码像数据库一样猛击秘密服务，您将希望实现一个写入透过的交易后缓存来保护您的用户免受减速。mock凭证存储可以用于这个目的。

如果您使用的是Windows原生凭证存储，请小心多线程访问，因为Windows凭证存储不能保证您的调用将按照它们制作的顺序进行序列化。一次只从一个线程访问任何单个凭证，如果您正在对多个凭证执行需要特定序列化顺序的操作，请从同一线程执行所有这些操作。

macOS和iOS凭证存储不允许服务或用户名为空，因为空字段在查找时被视为通配符。请使用一些默认的非空值。

从v2升级

v2和v3之间主要的功性变化是通过dbus-secret-service crate添加了对秘密服务的同步支持。这意味着秘密服务的密钥圈用户不再需要链接到异步运行时。（还有其他优点；有关详细信息，请参阅上面）。

v2和v3之间主要的API变化是添加了对非字符串（即二进制）"密码"数据的支持。为此，进行了两项更改

1. 在Entry对象上有两个新方法：set_secret和get_secret。这些是set_password和get_password的类似物，但它们接受或返回二进制数据（字节数组/向量）而不是字符串。

2. v2方法delete_password已被重命名为delete_credential，旨在明确要删除的内容，并强调它是否是"密码"或"秘密"无关紧要。

v2和v3之间的另一个API变化是默认功能集的概念已经消失：您现在必须明确指定您想要包含哪些存储库支持的关键存储（除了始终存在的mock密钥存储）。因此，所有密钥圈客户端开发人员都需要更新他们的Cargo.toml文件以正确使用新功能。

所有v2数据与v3数据完全向前兼容；在这方面没有任何变化。但是，与v2不同，秘密服务凭证存储的v3实现不会读取由v1密钥圈编写的凭证。（有关为什么做出此决定的详细信息，请参阅此问题）。使用秘密服务并且仍在使用旧v1凭证的密钥圈客户端应将这些凭证替换为v2/v3凭证。CLI已扩展，允许读取和删除v1凭证（因此提供了如何执行此操作的示例代码）。

MSRV 已升级到 1.75，所有直接依赖项均处于最新稳定版本。

许可协议

根据以下任一协议进行许可：

• Apache 许可协议 2.0（LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0）
• MIT 许可协议（LICENSE-MIT 或 http://opensource.org/licenses/MIT）

任由您选择。

贡献者

感谢以下人员为使此库更完善所做出的贡献，无论是通过贡献代码、讨论还是错误报告！

• @Alexei-Barnes
• @benwr
• @bhkaminski
• @Brooooooklyn
• @brotskydotcom
• @complexspaces
• @connor4312
• @dario23
• @dten
• @gondolyr
• @hwchen
• @jankatins
• @jasikpark
• @jkhsjdhjs
• @jonathanmorley
• @jyuch
• @klemensn
• @landhb
• @lexxvir
• @MaikKlein
• @Phrohdoh
• @phlip9
• @ReactorScram
• @Rukenshia
• @russellbanks
• @ryanavella
• @samuela
• @stankec
• @steveatinfincia
• @Sytten
• @thewh1teagle
• @tmpfs
• @VorpalBlade
• @zschreur

如果您应该在这个名单上，但没找到自己，请联系 @brotskydotcom。

贡献

除非您明确表示否则，根据 Apache-2.0 许可协议，您有意提交以包含在作品中的任何贡献，将按上述方式双许可，不附加任何额外条款或条件。