+
Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,20 @@ jobs:
components: clippy
- name: cargo clippy
run: cargo clippy --all-targets --all-features --workspace -- -D warnings
doc:
# run docs generation on nightly rather than stable. This enables features like
# https://doc.rust-lang.org/beta/unstable-book/language-features/doc-cfg.html which allows an
# API be documented as only available in some specific platforms.
runs-on: ubuntu-latest
name: nightly / doc
steps:
- uses: actions/checkout@v4
- name: Install nightly
uses: dtolnay/rust-toolchain@nightly
- name: Install cargo-docs-rs
uses: dtolnay/install@cargo-docs-rs
- name: cargo docs-rs
run: cargo docs-rs
test:
runs-on: ubuntu-latest
name: stable / test
Expand All @@ -46,7 +60,7 @@ jobs:
- name: Install stable
uses: dtolnay/rust-toolchain@stable
- name: cargo test
run: cargo test --all-targets --all-features --workspace
run: cargo test --all-targets --all-features --workspace -- --include-ignored
# https://github.com/rust-lang/cargo/issues/6669
- name: cargo test --doc
run: cargo test --all-features --workspace --doc
Expand Down
7 changes: 6 additions & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,9 @@ repository = "https://github.com/jmgilman/vaultrs"
keywords = ["Vault", "API", "Client", "Hashicorp"]
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

[workspace]
members = [
Expand Down Expand Up @@ -38,3 +40,6 @@ thiserror = "1.0.40"
url = "2.3.1"
tracing = { version = "0.1.37", features = ["log"] }

[dev-dependencies]
tokio = { version = "1", default-features = false, features = ["macros", "rt-multi-thread"]}

178 changes: 11 additions & 167 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ vaultrs = { version = "0.7.3", default-features = false, features = [ "native-tl

## Usage

### Basic
### Setup the client

The client is used to configure the connection to Vault and is required to be
passed to all API calls for execution. Behind the scenes it uses an asynchronous
Expand All @@ -92,169 +92,7 @@ let client = VaultClient::new(
).unwrap();
```

### Secrets

#### AWS

The library currently supports all operations available for the
AWS Secret Engine.

See [tests/aws.rs][4] for more examples.

```rust,ignore
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
```

#### Key Value v2

The library currently supports all operations available for version 2 of the
key/value store.

```rust,ignore
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"
```

#### Key Value v1

The library currently supports all operations available for version 1 of the
key/value store.

```rust,ignore
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

The library currently supports all operations available for the PKI secrets
engine.

```rust,ignore
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

The library supports most operations for the
[Transit](https://developer.hashicorp.com/vault/api-docs/secret/transit) secrets engine,
other than importing keys or `batch_input` parameters.

```rust,ignore
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();
```

### Wrapping

All requests implement the ability to be
[wrapped](https://developer.hashicorp.com/vault/docs/concepts/response-wrapping). These
can be passed in your application internally before being unwrapped.

```rust,ignore
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());
```
For more usages, take a look at [the documentation][6]

## Error Handling and Tracing

Expand All @@ -272,7 +110,13 @@ See the the [tests][3] directory for tests. Run tests with `cargo test`.

**Note**: All tests rely on bringing up a local Vault development server using
Docker. In order to run tests Docker must be running locally (Docker Desktop
works).
works). The first run will be longer than other because it will fetch images.

Some long-running tests are ignored by default locally. To run them do:

```sh
cargo test -- --include-ignored
```

## Contributing

Expand All @@ -290,6 +134,6 @@ architecture of this library and how to add additional functionality to it.

[1]: https://developer.hashicorp.com/vault/
[2]: https://github.com/jmgilman/vaultrs/issues
[3]: https://github.com/jmgilman/vaultrs/tree/master/tests
[4]: https://github.com/jmgilman/vaultrs/tree/master/tests/aws.rs
[3]: https://github.com/jmgilman/vaultrs/tree/master/vaultrs-tests/tests/api_tests
[5]: https://github.com/jmgilman/vaultrs/tree/master/CONTRIBUTING.md
[6]: https://docs.rs/vaultrs
2 changes: 1 addition & 1 deletion src/api.rs
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ use self::sys::responses::WrappingLookupResponse;
/// details about any contained leases. The actual response content is contained
/// in the `data` field.
///
/// Most endpoints are configured to pass their responses through [strip] in
/// Most endpoints are configured to pass their responses through `strip` in
/// order to strip the result and return the enclosed response. Any warnings
/// are automatically logged accordingly.
#[derive(Deserialize, Debug)]
Expand Down
2 changes: 1 addition & 1 deletion src/api/sys/requests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ pub struct ReadHealthRequest {}
/// * Path: /sys/init
/// * Method: POST
/// * Response: [StartInitializationResponse]
/// * Reference: https://developer.hashicorp.com/vault/api-docs/system/init#start-initialization
/// * Reference: <https://developer.hashicorp.com/vault/api-docs/system/init#start-initialization>
#[derive(Builder, Default, Endpoint)]
#[endpoint(
path = "/sys/init",
Expand Down
2 changes: 1 addition & 1 deletion src/kv1.rs
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ use std::collections::HashMap;
/// Sets the value of the secret at the given path
///
/// A key called ttl will trigger some special behavior. See the [Vault KV secrets engine documentation][<https://developer.hashicorp.com/vault/docs/secrets/kv>] for details.
/// See [SetSecretRequest][crate::api::kv1::requests::SetSecretRequest]
/// See [SetSecretRequest]
pub async fn set<T: Serialize>(
client: &impl Client,
mount: &str,
Expand Down
Loading
Loading
点击 这是indexloc提供的php浏览器服务,不要输入任何密码和下载