vaultrs

Hashicorp Vault API的异步Rust客户端库

当前支持以下功能

• 身份验证
  • AppRole
  • AWS
  • JWT/OIDC
  • Kubernetes
  • 令牌
  • 证书
  • 用户密码
• 秘密
  • AWS
  • 数据库
  • KV v1
  • KV v2
  • PKI
  • SSH
  • 传输
• 系统
  • 健康
  • 策略
  • 密封
  • 包装

如果发现缺少功能，请提交问题。

安装

首先，选择两个TLS实现之一用于 vaultrs 连接到 Vault

• rustls（默认）使用 Rustls
• native-tls 使用 rust-native-tls，该工具基于您平台特定的TLS实现。

然后，将 vaultrs 添加到您的 cargo.toml 作为依赖项

1. 要使用 Rustls，按如下方式导入

[dependencies]
vaultrs = "0.7.1"

2. 要使用基于您平台特定TLS实现的 rust-native-tls，指定

[dependencies]
vaultrs = { version = "0.7.1", default-features = false, features = [ "native-tls" ] }

用法

基本

客户端用于配置与 Vault 的连接，并需要在执行所有API调用时传递。在幕后，它使用来自 Reqwest 的异步客户端与 Vault 进行通信。

use vaultrs::client::{VaultClient, VaultClientSettingsBuilder};

// Create a client
let client = VaultClient::new(
    VaultClientSettingsBuilder::default()
        .address("https://127.0.0.1:8200")
        .token("TOKEN")
        .build()
        .unwrap()
).unwrap();

秘密

AWS

该库目前支持 AWS 秘密引擎的所有可用操作。

有关更多示例，请参阅 tests/aws.rs。

use vaultrs::sys::mount;
use vaultrs::aws;
use vaultrs::api::aws::requests::{SetConfigurationRequest, CreateUpdateRoleRequest, GenerateCredentialsRequest};

// Mount AWS SE
mount::enable(&client, "aws_test", "aws", None).await?;

// Configure AWS SE
aws::config::set(&client, "aws_test", "access_key", "secret_key", Some(SetConfigurationRequest::builder()        
    .max_retries(3)
    .region("eu-central-1")
)).await?;

// Create HVault role
aws::roles::create_update(&client, "aws_test", "my_role", "assumed_role", Some(CreateUpdateRoleRequest::builder()
        .role_arns( vec!["arn:aws:iam::123456789012:role/test_role".to_string()] )
)).await?;

// Generate credentials
let res = aws::roles::credentials(&client, "aws_test", "my_role", Some(GenerateCredentialsRequest::builder()
    .ttl("3h")
)).await?;

let creds = res;
// creds.access_key
// creds.secret_key
// creds.security_token

键值对 v2

该库目前支持键值存储的第2版的所有可用操作。

use serde::{Deserialize, Serialize};
use vaultrs::kv2;

// Create and read secrets
#[derive(Debug, Deserialize, Serialize)]
struct MySecret {
    key: String,
    password: String,
}

let secret = MySecret {
    key: "super".to_string(),
    password: "secret".to_string(),
};
kv2::set(
    &client,
    "secret",
    "mysecret",
    &secret,
).await;

let secret: MySecret = kv2::read(&client, "secret", "mysecret").await.unwrap();
println!("{}", secret.password); // "secret"

键值对 v1

该库目前支持键值存储的第1版的所有可用操作。

use vaultrs::kv1;
use std::collections::HashMap;

let my_secrets = HashMap::from([
    ("key1".to_string(), "value1".to_string()),
    ("key2".to_string(), "value2".to_string())
]);

kv1::set(&client, "secret", "my/secrets", &my_secrets).await.unwrap();

let read_secrets: HashMap<String, String> = kv1::get(&client, "secret", "my/secrets").await.unwrap();

println!("{:}", read_secrets.get("key1").unwrap()); // value1

let list_secret = kv1::list(&client, "secret", "my").await.unwrap();

println!("{:?}", list_secret.data.keys); // [ "secrets" ]

kv1::delete(&client, "secret", "my/secrets").await.unwrap();

PKI

该库目前支持 PKI 秘密引擎的所有可用操作。

use vaultrs::api::pki::requests::GenerateCertificateRequest;
use vaultrs::pki::cert;

// Generate a certificate using the PKI backend
let cert = cert::generate(
    &client,
    "pki",
    "my_role",
    Some(GenerateCertificateRequest::builder().common_name("test.com")),
).await.unwrap();
println!("{}", cert.certificate) // "{PEM encoded certificate}"

传输

该库支持 Transit 秘密引擎的大部分操作，除了导入密钥或 batch_input 参数。

use vaultrs::api::transit::requests::CreateKeyRequest;
use vaultrs::api::transit::KeyType;
use vaultrs::transit::key;

// Create an encryption key using the /transit backend
key::create(
    &client,
    "transit",
    "my-transit-key",
    Some(CreateKeyRequest::builder()
       .derive(true)
       .key_type(KeyType::Aes256Gcm96)
       .auto_rotate_period("30d")),
).await.unwrap();

包装

所有请求都实现了可以被封装的能力。这些封装可以在您的应用程序内部传递，然后再解封装。

use vaultrs::api::ResponseWrapper;
use vaultrs::api::sys::requests::ListMountsRequest;

let endpoint = ListMountsRequest::builder().build().unwrap();
let wrap_resp = endpoint.wrap(&client).await; // Wrapped response
assert!(wrap_resp.is_ok());

let wrap_resp = wrap_resp.unwrap(); // Unwrap Result<>
let info = wrap_resp.lookup(&client).await; // Check status of this wrapped response
assert!(info.is_ok());

let unwrap_resp = wrap_resp.unwrap(&client).await; // Unwrap the response
assert!(unwrap_resp.is_ok());

let info = wrap_resp.lookup(&client).await; // Error: response already unwrapped
assert!(info.is_err());

错误处理和追踪

此crate产生的所有错误都封装在crate提供的ClientError枚举中。API警告通过tracing自动捕获，API错误则作为其自己的变体捕获并返回。与rustify相关的连接错误被封装并作为单个变体返回。

所有顶级API操作都通过tracing的#[instrument]属性进行了监控。

测试

请查看测试目录以获取测试用例。运行测试请使用cargo test。

注意：所有测试都依赖于使用Docker启动本地Vault开发服务器。为了运行测试，Docker必须在本地运行（Docker Desktop适用）。

贡献

查看问题以获取需要关注的项目，或者提交您自己的问题，然后

1. 在https://github.com/jmgilman/vaultrs/fork上创建仓库的分支
2. 创建您的功能分支（git checkout -b feature/fooBar）
3. 提交您的更改（git commit -am '添加一些fooBar'）
4. 将更改推送到分支（git push origin feature/fooBar）
5. 创建新的拉取请求

请参阅CONTRIBUTING以获取有关此库架构和如何向其添加额外功能的详细文档。