Spring/spring-vault
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Bundle Javadoc with Antora documentation site.

Browse Source 
Closes #872
This commit is contained in:
Mark Paluch
2024-07-31 15:46:40 +02:00
parent ba263e0df9
commit a162165a0f
15 changed files with 138 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -24,5 +24,4 @@ work/
node
node_modules
package.json
package-lock.json

27
pom.xml
View File

@@ -18,6 +18,7 @@
</modules>
<properties>
<maven.antora-version>1.0.0-alpha.4</maven.antora-version>
<antora.version>0.0.3</antora.version>
<assertj-core.version>3.25.1</assertj-core.version>
<aws-java-sdk.version>2.21.46</aws-java-sdk.version>
@@ -996,6 +997,32 @@
</build>
</profile>
<profile>
<id>antora</id>
<properties>
<maven.main.skip>true</maven.main.skip>
<maven.test.skip>true</maven.test.skip>
<aspectj.skip>true</aspectj.skip>
<maven.install.skip>true</maven.install.skip>
<skipTests>true</skipTests>
</properties>
<build>
<plugins>
<!-- force-skip -->
<plugin>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-plugin</artifactId>
<inherited>false</inherited>
<configuration>
<skip>true</skip>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>
<pluginRepositories>

10
spring-vault-distribution/package.json Normal file
View File

@@ -0,0 +1,10 @@
{
"dependencies": {
"antora": "3.2.0-alpha.6",
"@antora/atlas-extension": "1.0.0-alpha.2",
"@antora/collector-extension": "1.0.0-alpha.7",
"@asciidoctor/tabs": "1.0.0-beta.6",
"@springio/antora-extensions": "1.13.0",
"@springio/asciidoctor-extensions": "1.0.0-alpha.11"
}
}

27
spring-vault-distribution/pom.xml
View File

@@ -124,24 +124,17 @@
</configuration>
</plugin>
<plugin>
<groupId>io.spring.maven.antora</groupId>
<groupId>org.antora</groupId>
<artifactId>antora-maven-plugin</artifactId>
<version>${antora.version}</version>
<version>${maven.antora-version}</version>
<extensions>true</extensions>
<configuration>
<playbook>${project.basedir}/../src/main/antora/antora-playbook.yml</playbook>
<options>
<option>--to-dir=target/antora/site</option>
<option>--stacktrace</option>
<option>--fetch</option>
</options>
<playbook>${project.basedir}/../src/main/antora/antora-playbook.yml</playbook>
<packages>
<package>@antora/atlas-extension@1.0.0-alpha.1</package>
<package>@antora/collector-extension@1.0.0-alpha.3</package>
<package>@asciidoctor/tabs@1.0.0-beta.3</package>
<package>@springio/antora-extensions@1.8.0</package>
<package>@springio/asciidoctor-extensions@1.0.0-alpha.9</package>
</packages>
</configuration>
<executions>
<execution>
@@ -245,6 +238,20 @@
</goals>
</execution>
<execution>
<id>copy-javadoc</id>
<phase>package</phase>
<configuration>
<target>
<copy todir="${project.root}/target/antora/modules/ROOT/assets/attachments/api/java">
<fileset dir="${project.root}/target/site/apidocs" erroronmissingdir="true" />
</copy>
</target>
</configuration>
<goals>
<goal>run</goal>
</goals>
</execution>
</executions>
</plugin>

18
src/main/antora/antora-playbook.yml
View File

@@ -1,13 +1,7 @@
# The purpose of this Antora playbook is to build the docs in the current branch.
antora:
extensions:
- '@springio/antora-extensions/partial-build-extension'
- '@springio/antora-extensions/static-page-extension'
- require: '@springio/antora-extensions/latest-version-extension'
- require: '@springio/antora-extensions/inject-collector-cache-config-extension'
- '@antora/collector-extension'
- '@antora/atlas-extension'
- require: '@springio/antora-extensions/root-component-extension'
- require: '@springio/antora-extensions'
root_component_name: 'vault'
site:
title: Spring Vault
@@ -28,13 +22,15 @@ asciidoc:
extensions:
- '@asciidoctor/tabs'
- '@springio/asciidoctor-extensions'
- '@springio/asciidoctor-extensions/javadoc-extension'
sourcemap: true
urls:
latest_version_segment: ''
ui:
bundle:
url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.4.7/ui-bundle.zip
snapshot: true
runtime:
log:
failure_level: warn
format: pretty
ui:
bundle:
url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.4.16/ui-bundle.zip
snapshot: true

5
src/main/antora/antora.yml
View File

@@ -10,3 +10,8 @@ ext:
local: true
scan:
dir: spring-vault-distribution/target/classes/
- run:
command: ./mvnw package -Pdistribute
local: true
scan:
dir: target/antora

3
src/main/antora/modules/ROOT/nav.adoc
View File

@@ -12,3 +12,6 @@
** xref:vault/client-support.adoc[]
** xref:vault/authentication.adoc[]
** xref:vault/spring-security.adoc[]
* xref:attachment$api/java/index.html[Javadoc,role=link-external,window=_blank]

8
src/main/antora/modules/ROOT/pages/vault/authentication.adoc
View File

@@ -939,14 +939,14 @@ VaultToken token = executor.login();
Vault's tokens can be associated with a time to live. Tokens obtained by an authentication method
are intended to be used as long as the session is active and should not expire while the application is active.
Spring Vault provides with {self-docs-root}api/org/springframework/vault/authentication/LifecycleAwareSessionManager.html[`LifecycleAwareSessionManager`] a session manager that can renew the token until it reaches its terminal TTL to then perform another login to obtain the next token which is associated with the session.
Spring Vault provides with javadoc:org.springframework.vault.authentication.LifecycleAwareSessionManager[] a session manager that can renew the token until it reaches its terminal TTL to then perform another login to obtain the next token which is associated with the session.
Depending on the authentication method, a login can create two kinds of tokens:
* {self-docs-root}api/org/springframework/vault/support/VaultToken.html[`VaultToken`]: Generic token encapsulating the actual token.
* {self-docs-root}api/org/springframework/vault/authentication/LoginToken.html[`LoginToken`]: Token associated with renewability/TTL.
* javadoc:org.springframework.vault.support.VaultToken[]: Generic token encapsulating the actual token.
* javadoc:org.springframework.vault.authentication.LoginToken[]: Token associated with renewability/TTL.
Authentication methods such as {self-docs-root}api/org/springframework/vault/authentication/TokenAuthentication.html[`TokenAuthentication`] just create a `VaultToken` which does not carry any renewability/TTL details. `LifecycleAwareSessionManager` will run a self-lookup on the token to retrieve renewability and TTL from Vault.
Authentication methods such as javadoc:org.springframework.vault.authentication.TokenAuthentication[] just create a `VaultToken` which does not carry any renewability/TTL details. javadoc:org.springframework.vault.authentication.LifecycleAwareSessionManager[] will run a self-lookup on the token to retrieve renewability and TTL from Vault.
`VaultToken` are renewed periodically if self-lookup is enabled. Note that `VaultToken` are never revoked, only `LoginToken` are revoked.
Authentication methods creating `LoginToken` directly (all login-based authentication methods) already provide all necessary details to setup token renewal. Tokens obtained from a login are revoked by `LifecycleAwareSessionManager` if the session manager is shut down.

4
src/main/antora/modules/ROOT/pages/vault/client-support.adoc
View File

@@ -98,7 +98,7 @@ NOTE: Apache HttpClient's https://hc.apache.org/httpcomponents-client-5.2.x/logg
[[vault.client-ssl]]
== Vault Client SSL configuration
SSL can be configured using `SslConfiguration` by setting various properties.
SSL can be configured using javadoc:org.springframework.vault.support.SslConfiguration[] by setting various properties.
You can set either `javax.net.ssl.trustStore` to configure
JVM-wide SSL settings or configure `SslConfiguration`
to set SSL settings only for Spring Vault.
@@ -128,7 +128,7 @@ SslConfiguration.forKeyStore(new FileSystemResource("keystore.jks"), <4>
<4> Configuring only key store settings with providing a key-configuration.
====
Please note that providing `SslConfiguration` can be only applied when either Apache Http Components or the OkHttp client is on your class-path.
Please note that providing javadoc:org.springframework.vault.support.SslConfiguration[] can be only applied when either Apache Http Components or the OkHttp client is on your class-path.
The SSL configuration supports also PEM-encoded certificates as alternative to a Java Key Store.

42
src/main/antora/modules/ROOT/pages/vault/imperative-template.adoc
View File

@@ -1,19 +1,20 @@
[[vault.core.template]]
= Introduction to VaultTemplate
The class `VaultTemplate`, located in the package `org.springframework.vault.core`,
The class javadoc:org.springframework.vault.core.VaultTemplate[], located in the package `org.springframework.vault.core`,
is the central class of the Spring's Vault support providing a rich feature set to
interact with Vault. The template offers convenience operations to read, write and
delete data in Vault and provides a mapping between your domain objects and Vault data.
NOTE: Once configured, `VaultTemplate` is thread-safe and can be reused across
NOTE: Once configured, javadoc:org.springframework.vault.core.VaultTemplate[] is thread-safe and can be reused across
multiple instances.
The mapping between Vault documents and domain classes is done by delegating to
`RestTemplate`. Spring Web support provides the mapping infrastructure.
The `VaultTemplate` class implements the interface `VaultOperations`.
In as much as possible, the methods on `VaultOperations` are named after methods
The javadoc:org.springframework.vault.core.VaultTemplate[] class implements the interface
javadoc:org.springframework.vault.core.VaultOperations[].
In as much as possible, the methods on javadoc:org.springframework.vault.core.VaultOperations[] are named after methods
available on the Vault API to make the API familiar to existing Vault developers
who are used to the API and CLI. For example, you will find methods such as
"write", "delete", "read", and "revoke".
@@ -22,8 +23,8 @@ the use of the Vault API and `VaultOperations`. A major difference in between
the two APIs is that `VaultOperations` can be passed domain objects instead of
JSON Key-Value pairs.
NOTE: The preferred way to reference the operations on `VaultTemplate` instance
is via its interface `VaultOperations`.
NOTE: The preferred way to reference the operations on javadoc:org.springframework.vault.core.VaultTemplate[] instance
is via its interface javadoc:org.springframework.vault.core.VaultOperations[].
While there are many convenience methods on `VaultTemplate` to help you easily
perform common tasks if you should need to access the Vault API directly to access
@@ -37,7 +38,8 @@ Now let's look at a examples of how to work with Vault in the context of the Spr
[[vault.core.template.beans]]
== Registering and configuring Spring Vault beans
Using Spring Vault does not require a Spring Context. However, instances of `VaultTemplate` and `SessionManager` registered inside a managed context will participate
Using Spring Vault does not require a Spring Context. However, instances of `VaultTemplate` and
javadoc:org.springframework.vault.authentication.SessionManager[] registered inside a managed context will participate
in {spring-framework-docs}core.html#beans-factory-nature[lifecycle events]
provided by the Spring IoC container. This is useful to dispose active Vault sessions upon
application shutdown. You also benefit from reusing the same `VaultTemplate`
@@ -45,11 +47,11 @@ instance across your application.
Spring Vault comes with a supporting configuration class that provides bean definitions
for use inside a Spring context. Application configuration
classes typically extend from `AbstractVaultConfiguration` and are required to
classes typically extend from javadoc:org.springframework.vault.config.AbstractVaultConfiguration[] and are required to
provide additional details that are environment specific.
Extending from `AbstractVaultConfiguration` requires to implement
` VaultEndpoint vaultEndpoint()` and `ClientAuthentication clientAuthentication()`
Extending from javadoc:org.springframework.vault.config.AbstractVaultConfiguration[] requires to implement
`VaultEndpoint vaultEndpoint()` and `ClientAuthentication clientAuthentication()`
methods.
.Registering Spring Vault objects using Java based bean metadata
@@ -78,8 +80,8 @@ public class AppConfig extends AbstractVaultConfiguration {
}
}
----
<1> Create a new `VaultEndpoint` that points by default to `\https://localhost:8200`.
<2> This sample uses `TokenAuthentication` to get started quickly.
<1> Create a new javadoc:org.springframework.vault.client.VaultEndpoint[] that points by default to `\https://localhost:8200`.
<2> This sample uses javadoc:org.springframework.vault.authentication.TokenAuthentication[] to get started quickly.
See <<vault.core.authentication>> for details on supported authentication methods.
====
@@ -111,14 +113,14 @@ public class AppConfig extends AbstractVaultConfiguration {
}
}
----
<1> `VaultEndpoint` can be constructed using various factory methods such as
<1> javadoc:org.springframework.vault.client.VaultEndpoint[] can be constructed using various factory methods such as
`from(URI uri)` or `VaultEndpoint.create(String host, int port)`.
<2> Dependencies for `ClientAuthentication` methods can be obtained either from
`AbstractVaultConfiguration` or provided by your configuration.
====
NOTE: Creating a custom configuration class might be cumbersome in some cases.
Take a look at `EnvironmentVaultConfiguration` that allows configuration by using
Take a look at javadoc:org.springframework.vault.config.EnvironmentVaultConfiguration[] that allows configuration by using
properties from existing property sources and Spring's `Environment`. Read more
in <<vault.core.environment-vault-configuration>>.
@@ -132,9 +134,9 @@ must be reused throughout a session. This aspect is handled by a
`SessionManager` implementation. A `SessionManager` decides how often it
obtains a token, about revocation and renewal. Spring Vault comes with two implementations:
* `SimpleSessionManager`: Just obtains tokens from the supplied
* javadoc:org.springframework.vault.authentication.SimpleSessionManager[]: Just obtains tokens from the supplied
`ClientAuthentication` without refresh and revocation
* `LifecycleAwareSessionManager`: This `SessionManager` schedules token
* javadoc:org.springframework.vault.authentication.LifecycleAwareSessionManager[]: This `SessionManager` schedules token
renewal if a token is renewable and revoke a login token on disposal.
Renewal is scheduled with an `AsyncTaskExecutor`. `LifecycleAwareSessionManager`
is configured by default if using `AbstractVaultConfiguration`.
@@ -142,8 +144,10 @@ is configured by default if using `AbstractVaultConfiguration`.
[[vault.core.environment-vault-configuration]]
== Using `EnvironmentVaultConfiguration`
Spring Vault includes `EnvironmentVaultConfiguration` configure the Vault client from Spring's `Environment` and a set of predefined
property keys. `EnvironmentVaultConfiguration` supports frequently applied configurations. Other configurations are supported by deriving from the most appropriate configuration class. Include `EnvironmentVaultConfiguration` with `@Import(EnvironmentVaultConfiguration.class)` to existing
Spring Vault includes javadoc:org.springframework.vault.config.EnvironmentVaultConfiguration[] configure the Vault client from Spring's `Environment` and a set of predefined
property keys.
javadoc:org.springframework.vault.config.EnvironmentVaultConfiguration[] supports frequently applied configurations. Other configurations are supported by deriving from the most appropriate configuration class.
Include javadoc:org.springframework.vault.config.EnvironmentVaultConfiguration[] with `@Import(EnvironmentVaultConfiguration.class)` to existing
Java-based configuration classes and supply configuration properties through any of Spring's ``PropertySource``s.
.Using EnvironmentVaultConfiguration with a property file
@@ -238,7 +242,7 @@ One common design feature of all Spring template classes is that all functionali
This helps ensure that exceptions and any resource management that maybe required are performed consistency.
While this was of much greater need in the case of JDBC and JMS than with Vault, it still offers a single spot for access and logging to occur.
As such, using the execute callback is the preferred way to access the Vault API
to perform uncommon operations that we've not exposed as methods on `VaultTemplate`.
to perform uncommon operations that we've not exposed as methods on javadoc:org.springframework.vault.core.VaultTemplate[].
Here is a list of execute callback methods.

6
src/main/antora/modules/ROOT/pages/vault/propertysource.adoc
View File

@@ -5,14 +5,14 @@ Vault can be used in many different ways. One specific use-case is using
Vault to store encrypted properties. Spring Vault supports Vault as property
source to obtain configuration properties using Spring's {spring-framework-docs}core.html#beans-property-source-abstraction[PropertySource abstraction].
NOTE: You can reference properties stored inside Vault in other property sources or use value injection with `@Value(…)`. Special attention is required when bootstrapping beans that require data stored inside of Vault. A `VaultPropertySource` must be initialized at that time to retrieve properties from Vault.
NOTE: You can reference properties stored inside Vault in other property sources or use value injection with `@Value(…)`. Special attention is required when bootstrapping beans that require data stored inside of Vault. A javadoc:org.springframework.vault.core.env.VaultPropertySource[] must be initialized at that time to retrieve properties from Vault.
NOTE: Spring Boot/Spring Cloud users can benefit from https://github.com/spring-cloud/spring-cloud-vault-config[Spring Cloud Vault]'s
configuration integration that initializes various property sources during application startup.
== Registering `VaultPropertySource`
Spring Vault provides a `VaultPropertySource` to be used with Vault to obtain
Spring Vault provides a javadoc:org.springframework.vault.core.env.VaultPropertySource[] to be used with Vault to obtain
properties. It uses the nested `data` element to expose properties stored and
encrypted in Vault.
@@ -25,7 +25,7 @@ sources.addFirst(new VaultPropertySource(vaultTemplate, "secret/my-application")
----
====
In the code above, `VaultPropertySource` has been added with highest precedence
In the code above, javadoc:org.springframework.vault.core.env.VaultPropertySource[] has been added with highest precedence
in the search. If it contains a ´foo` property, it will be detected and returned
ahead of any `foo` property in any other `PropertySource`.
`MutablePropertySources` exposes a number of methods that allow for precise

43
src/main/antora/modules/ROOT/pages/vault/reactive-template.adoc
View File

@@ -20,58 +20,59 @@ too slow the data repository can also slow down or stop completely until network
Spring Vault's reactive client support is built on top of <<vault.authentication.steps,composable authentication steps>> and Spring's functional `WebClient` via Reactor Netty or Jetty, which feature both a fully non-blocking, event-driven HTTP client.
It exposes `VaultTokenSupplier` as supplier of `VaultToken` to authenticate HTTP requests
and `ReactiveVaultOperations` as the primary entry point. The core configuration of
It exposes javadoc:org.springframework.vault.authentication.VaultTokenSupplier[] as supplier of javadoc:org.springframework.vault.support.VaultToken[] to authenticate HTTP requests
and javadoc:org.springframework.vault.core.ReactiveVaultOperations[] as the primary entry point.
The core configuration of
`VaultEndpoint`, `ClientOptions` and <<vault.client-ssl,SSL>> are reused across the
various client implementation.
The class `ReactiveVaultTemplate`, located in the package `org.springframework.vault.core`,
The class javadoc:org.springframework.vault.core.ReactiveVaultTemplate[], located in the package `org.springframework.vault.core`,
is the central class of the Spring's reactive Vault support providing a rich feature set to
interact with Vault. The template offers convenience operations to read, write and
delete data in Vault and provides a mapping between your domain objects and Vault data.
NOTE: Once configured, `ReactiveVaultTemplate` is thread-safe and can be reused across
NOTE: Once configured, javadoc:org.springframework.vault.core.ReactiveVaultTemplate[] is thread-safe and can be reused across
multiple instances.
The mapping between Vault documents and domain classes is done by delegating to
`WebClient` and its codecs.
The `ReactiveVaultTemplate` class implements the interface `ReactiveVaultOperations`.
In as much as possible, the methods on `ReactiveVaultOperations` are named after methods
The javadoc:org.springframework.vault.core.ReactiveVaultTemplate[] class implements the interface javadoc:org.springframework.vault.core.ReactiveVaultOperations[].
In as much as possible, the methods on javadoc:org.springframework.vault.core.ReactiveVaultOperations[] are named after methods
available on the Vault API to make the API familiar to existing Vault developers
who are used to the API and CLI. For example, you will find methods such as
"write", "delete", and "read".
The design goal was to make it as easy as possible to transition between
the use of the Vault API and `ReactiveVaultOperations`. A major difference in between
the two APIs is that `ReactiveVaultOperations` can be passed domain objects instead of
the use of the Vault API and javadoc:org.springframework.vault.core.ReactiveVaultOperations[]. A major difference in between
the two APIs is that javadoc:org.springframework.vault.core.ReactiveVaultOperations[] can be passed domain objects instead of
JSON Key-Value pairs.
NOTE: The preferred way to reference the operations on `ReactiveVaultTemplate` instance
is via its interface `ReactiveVaultOperations`.
NOTE: The preferred way to reference the operations on javadoc:org.springframework.vault.core.ReactiveVaultTemplate[] instance
is via its interface javadoc:org.springframework.vault.core.ReactiveVaultOperations[].
Functionality not explicitly exposed by the `ReactiveVaultTemplate` you can use one of
Functionality not explicitly exposed by the javadoc:org.springframework.vault.core.ReactiveVaultTemplate[] you can use one of
several execute callback methods to access underlying APIs. The execute callbacks
will give you a reference to a `WebClient` object.
Please see the section <<vault.core.reactive.executioncallback,Execution Callbacks>> for more information.
Now let's look at a examples of how to work with Vault in the context of the Spring container.
Now let's look at examples of how to work with Vault in the context of the Spring container.
[[vault.core.reactive.template.beans]]
== Registering and configuring Spring Vault beans
Using Spring Vault does not require a Spring Context. However, instances of
`ReactiveVaultTemplate` and `VaultTokenSupplier` registered inside a managed context will participate
javadoc:org.springframework.vault.core.ReactiveVaultTemplate[] and `VaultTokenSupplier` registered inside a managed context will participate
in {spring-framework-docs}core.html#beans-factory-nature[lifecycle events]
provided by the Spring IoC container. This is useful to dispose active Vault sessions upon
application shutdown. You also benefit from reusing the same `ReactiveVaultTemplate`
application shutdown. You also benefit from reusing the same javadoc:org.springframework.vault.core.ReactiveVaultTemplate[]
instance across your application.
Spring Vault comes with a supporting configuration class that provides bean definitions
for use inside a Spring context. Application configuration
classes typically extend from `AbstractVaultConfiguration` and are required to
classes typically extend from javadoc:org.springframework.vault.config.AbstractVaultConfiguration[] and are required to
provide additional details that are environment specific.
Extending from `AbstractVaultConfiguration` requires to implement
Extending from javadoc:org.springframework.vault.config.AbstractVaultConfiguration[] requires to implement
` VaultEndpoint vaultEndpoint()` and `ClientAuthentication clientAuthentication()`
methods.
@@ -101,8 +102,8 @@ public class AppConfig extends AbstractReactiveVaultConfiguration {
}
}
----
<1> Create a new `VaultEndpoint` that points by default to `\https://localhost:8200`.
<2> This sample uses `TokenAuthentication` to get started quickly.
<1> Create a new javadoc:org.springframework.vault.client.VaultEndpoint[] that points by default to `\https://localhost:8200`.
<2> This sample uses javadoc:org.springframework.vault.authentication.TokenAuthentication[] to get started quickly.
See <<vault.core.authentication>> for details on supported authentication methods.
====
@@ -115,8 +116,8 @@ The reactive client requires a non-blocking token supplier whose contract is def
in `VaultTokenSupplier`. Tokens can be static or obtained through a
<<vault.authentication.steps,declared authentication flow>>.
Vault login should not occur on each authenticated Vault interaction but
the session token should be kept across a session. This aspect is handled by a
session manager implementing `ReactiveSessionManager`, such as `ReactiveLifecycleAwareSessionManager`.
the session token should be kept across a session.
This aspect is handled by a session manager implementing javadoc:org.springframework.vault.authentication.ReactiveSessionManager[], such as javadoc:org.springframework.vault.authentication.ReactiveLifecycleAwareSessionManager[].
[[vault.core.reactive.executioncallback]]
== Execution callbacks
@@ -127,7 +128,7 @@ that exceptions and any resource management that maybe required are performed
consistency. While this was of much greater need in the case of JDBC and JMS
than with Vault, it still offers a single spot for access and logging to occur.
As such, using the execute callback is the preferred way to access the Vault API
to perform uncommon operations that we've not exposed as methods on `ReactiveVaultTemplate`.
to perform uncommon operations that we've not exposed as methods on javadoc:org.springframework.vault.core.ReactiveVaultTemplate[].
Here is a list of execute callback methods.

2
src/main/antora/modules/ROOT/pages/vault/vault-repositories.adoc
View File

@@ -1,7 +1,7 @@
[[vault.repositories]]
= Vault Repositories
Working with `VaultTemplate` and responses mapped to Java classes allows basic data operations like read, write and delete.
Working with javadoc:org.springframework.vault.core.VaultTemplate[] and responses mapped to Java classes allows basic data operations like read, write and delete.
Vault repositories apply Spring Data's repository concept on top of Vault.
A Vault repository exposes basic CRUD functionality and supports query derivation with predicates constraining the identifier property, paging and sorting.
Vault repositories use the key/value secrets engine functionality to persist and query data.

28
src/main/antora/modules/ROOT/pages/vault/vault-secret-engines.adoc
View File

@@ -25,7 +25,7 @@ The benefits of non-versioned kv is a reduced storage size for each key, since n
Additionally, requests going to a backend configured this way are more performant because there are fewer storage calls and no locking for any given request.
Spring Vault ships with a dedicated Key-Value API to encapsulate differences between the individual Key-Value API implementations.
`VaultKeyValueOperations` follows the Vault CLI design.
javadoc:org.springframework.vault.core.VaultKeyValueOperations[] follows the Vault CLI design.
That's the primary command line tool for Vault providing commands such as `vault kv get`, `vault kv put` and so on.
You can use this API with both Key-Value engine versions by specifying the version and mount path.
@@ -38,9 +38,9 @@ include::example$KeyValueV1.java[tags=keyValueApi]
----
====
`VaultKeyValueOperations` supports all Key-Value operations such as `put`, `get`, `delete`, `list`.
javadoc:org.springframework.vault.core.VaultKeyValueOperations[] supports all Key-Value operations such as `put`, `get`, `delete`, `list`.
Alternatively, the API can be used through `VaultTemplate` because of its direct mapping and simple use, as keys and responses map directly to input and output keys.
Alternatively, the API can be used through javadoc:org.springframework.vault.core.VaultTemplate[] because of its direct mapping and simple use, as keys and responses map directly to input and output keys.
The following example illustrates writing and reading a secret at `mykey`.
The `kv` secrets engine is mounted at `secret`:
@@ -76,7 +76,7 @@ include::example$KeyValueV2.java[tags=keyValueApi]
----
====
`VaultKeyValueOperations` supports all Key-Value operations, such as `put`, `get`, `delete`, `list`.
javadoc:org.springframework.vault.core.VaultKeyValueOperations[] supports all Key-Value operations, such as `put`, `get`, `delete`, `list`.
You can also interact with the specifics of the versioned key-value API. This is useful if you want to obtain a specific secret or you need access to the metadata.
@@ -124,12 +124,12 @@ The following examples explain briefly the use of how to issue and revoke certif
----
include::example$PKI.java[tags=pkiApi]
----
<1> Construct a certificate request by using the `VaultCertificateRequest` builder.
<1> Construct a certificate request by using the javadoc:org.springframework.vault.support.VaultCertificateRequest[] builder.
<2> Request a certificate from Vault.
Vault acts as certificate authority and responds with a signed X.509 certificate.
The actual response is a `CertificateBundle`.
The actual response is a javadoc:org.springframework.vault.support.CertificateBundle[].
<3> You can obtain generated certificates directly as Java KeyStore that contains public and private keys as well as the issuer certificate. KeyStore has a wide range of uses, which makes this format suitable to configure (for example a HTTP client, a database driver, or an SSL-secured HTTP server).
<4> `CertificateBundle` allows accessing the private key and the public and issuer certificates directly through the Java Cryptography Extension API.
<4> javadoc:org.springframework.vault.support.CertificateBundle[] allows accessing the private key and the public and issuer certificates directly through the Java Cryptography Extension API.
<5> Once a certificate is no longer in use (or it was compromised), you can revoke it through its serial number.
Vault includes the revoked certificate in its CRL.
====
@@ -212,19 +212,19 @@ The preceeding example uses simple strings for cryptographic operations.
While it is a simple approach, it bears the risk of charset misconfiguration and is not binary-safe.
Binary safety is required when the plain text uses a binary representation for data such as images, compressed data, or binary data structures.
To encrypt and decrypt binary data, use the `Plaintext` and `Ciphertext` value objects that can hold binary values:
To encrypt and decrypt binary data, use the javadoc:org.springframework.vault.support.Plaintext[] and javadoc:org.springframework.vault.support.Ciphertext[] value objects that can hold binary values:
====
[source,java,indent=0]
----
include::example$Transit.java[tags=encryptPlaintext]
----
<1> Assuming a key `my-aes-key` is already in place, we're encrypting the `Plaintext` object.
In return, the `encrypt` method returns a `Ciphertext` object.
<2> The `Ciphertext` object can be used directly for decryption and returns a `Plaintext` object.
<1> Assuming a key `my-aes-key` is already in place, we're encrypting the javadoc:org.springframework.vault.support.Plaintext[] object.
In return, the `encrypt` method returns a javadoc:org.springframework.vault.support.Ciphertext[] object.
<2> The javadoc:org.springframework.vault.support.Ciphertext[] object can be used directly for decryption and returns a javadoc:org.springframework.vault.support.Plaintext[] object.
====
`Plaintext` and `Ciphertext` come with a contextual object, `VaultTransitContext`.
javadoc:org.springframework.vault.support.Plaintext[] and javadoc:org.springframework.vault.support.Ciphertext[] come with a contextual object, javadoc:org.springframework.vault.support.VaultTransitContext[].
It is used to supply a nonce value for https://www.vaultproject.io/docs/secrets/transit#convergent-encryption[convergent encryption] and for a context value to make use of key derivation.
Transit allows for signing plain text and verifying the signature for a given plain text.
@@ -242,8 +242,8 @@ Internally, the hash gets computed and encrypted using the private key to create
include::example$Transit.java[tags=signVerify]
----
<1> Signing requires an asymmetric key. You can use any Elliptic Curve Cryptography or RSA key type. Once the key is created, you have all the prerequisites in place to create a signature.
<2> The signature gets created for a plain text message. The returned `Signature` contains an ASCII-safe string that uses Base64 characters.
<3> To verify the signature, the verification requires a Signature object and the plain text message. As the return value, you get whether the signature was valid or not.
<2> The signature gets created for a plain text message. The returned javadoc:org.springframework.vault.support.Signature[] contains an ASCII-safe string that uses Base64 characters.
<3> To verify the signature, the verification requires a javadoc:org.springframework.vault.support.Signature[] object and the plain text message. As the return value, you get whether the signature was valid or not.
====
You can find more details about the https://www.vaultproject.io/api/secret/transit[Vault Transit Backend] in the Vault reference documentation.

1
src/main/antora/resources/antora-resources/antora.yml
View File

@@ -8,7 +8,6 @@ asciidoc:
springversion: ${spring.version}
attribute-missing: 'warn'
include-xml-namespaces: false
self-docs-root: https://docs.spring.io/spring-vault/reference/
spring-data-commons-docs-url: https://docs.spring.io/spring-data/commons/reference
spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/commons/docs/current/api/
spring-framework-docs: https://docs.spring.io/spring-framework/reference/{springversionshort}