diff --git a/spring-vault-core/src/test/java/org/springframework/vault/documentation/KeyValueV1.java b/spring-vault-core/src/test/java/org/springframework/vault/documentation/KeyValueV1.java new file mode 100644 index 00000000..74557cc4 --- /dev/null +++ b/spring-vault-core/src/test/java/org/springframework/vault/documentation/KeyValueV1.java @@ -0,0 +1,59 @@ +/* + * Copyright 2020 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.vault.documentation; + +import java.util.Collections; + +import org.springframework.vault.client.VaultEndpoint; +import org.springframework.vault.core.VaultKeyValueOperations; +import org.springframework.vault.core.VaultKeyValueOperationsSupport; +import org.springframework.vault.core.VaultOperations; +import org.springframework.vault.core.VaultTemplate; +import org.springframework.vault.support.VaultResponse; + +/** + * @author Mark Paluch + */ +//@formatter:off +public class KeyValueV1 { + + void vaultOperations() { + + // tag::vaultOperations[] + VaultOperations operations = new VaultTemplate(new VaultEndpoint()); + + operations.write("secret/elvis", Collections.singletonMap("social-security-number", "409-52-2002")); + + VaultResponse read = operations.read("secret/elvis"); + read.getRequiredData().get("social-security-number"); + // end::vaultOperations[] + } + + void keyValueApi() { + + // tag::keyValueApi[] + VaultOperations operations = new VaultTemplate(new VaultEndpoint()); + VaultKeyValueOperations keyValueOperations = operations.opsForKeyValue("secret", + VaultKeyValueOperationsSupport.KeyValueBackend.KV_1); + + keyValueOperations.put("elvis", Collections.singletonMap("password", "409-52-2002")); + + VaultResponse read = keyValueOperations.get("elvis"); + read.getRequiredData().get("social-security-number"); + // end::keyValueApi[] + } + +} diff --git a/spring-vault-core/src/test/java/org/springframework/vault/documentation/KeyValueV2.java b/spring-vault-core/src/test/java/org/springframework/vault/documentation/KeyValueV2.java new file mode 100644 index 00000000..a695d1ac --- /dev/null +++ b/spring-vault-core/src/test/java/org/springframework/vault/documentation/KeyValueV2.java @@ -0,0 +1,97 @@ +/* + * Copyright 2020 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.vault.documentation; + +import java.util.Collections; +import java.util.Map; + +import com.fasterxml.jackson.annotation.JsonProperty; + +import org.springframework.vault.client.VaultEndpoint; +import org.springframework.vault.core.VaultKeyValueOperations; +import org.springframework.vault.core.VaultKeyValueOperationsSupport; +import org.springframework.vault.core.VaultOperations; +import org.springframework.vault.core.VaultTemplate; +import org.springframework.vault.core.VaultVersionedKeyValueOperations; +import org.springframework.vault.support.VaultResponse; +import org.springframework.vault.support.Versioned; +import org.springframework.vault.support.Versioned.Version; + +/** + * @author Mark Paluch + */ +//@formatter:off +public class KeyValueV2 { + + void vaultOperations() { + + // tag::vaultOperations[] + VaultOperations operations = new VaultTemplate(new VaultEndpoint()); + + operations.write("secret/data/elvis", Collections.singletonMap("data", + Collections.singletonMap("social-security-number", "409-52-2002"))); + + VaultResponse read = operations.read("secret/data/ykey"); + Map data = (Map) read.getRequiredData().get("data"); + data.get("social-security-number"); + // end::vaultOperations[] + } + + void keyValueApi() { + + // tag::keyValueApi[] + VaultOperations operations = new VaultTemplate(new VaultEndpoint()); + VaultKeyValueOperations keyValueOperations = operations.opsForKeyValue("secret", + VaultKeyValueOperationsSupport.KeyValueBackend.KV_2); + + keyValueOperations.put("elvis", Collections.singletonMap("social-security-number", "409-52-2002")); + + VaultResponse read = keyValueOperations.get("elvis"); + read.getRequiredData().get("social-security-number"); + // end::keyValueApi[] + } + + void versionedApi() { + + // tag::versionedApi[] + VaultOperations operations = new VaultTemplate(new VaultEndpoint()); + VaultVersionedKeyValueOperations versionedOperations = operations.opsForVersionedKeyValue("secret"); + + Versioned.Metadata metadata = versionedOperations.put("elvis", // <1> + Collections.singletonMap("social-security-number", "409-52-2002")); + + Version version = metadata.getVersion(); // <2> + + Versioned ssn = versionedOperations.get("elvis", Version.from(42)); // <3> + + Versioned mappedSsn = versionedOperations.get("elvis", // <4> + Version.from(42), SocialSecurityNumber.class); + + Versioned> versioned = Versioned.create(Collections // <5> + .singletonMap("social-security-number", "409-52-2002"), + Version.from(42)); + + versionedOperations.put("elvis", version); + // end::versionedApi[] + } + + static class SocialSecurityNumber{ + + @JsonProperty("social-security-number") + String ssn; + } + +} diff --git a/spring-vault-core/src/test/java/org/springframework/vault/documentation/PKI.java b/spring-vault-core/src/test/java/org/springframework/vault/documentation/PKI.java new file mode 100644 index 00000000..a7fc767a --- /dev/null +++ b/spring-vault-core/src/test/java/org/springframework/vault/documentation/PKI.java @@ -0,0 +1,64 @@ +/* + * Copyright 2020 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.vault.documentation; + +import java.security.KeyStore; +import java.security.cert.X509Certificate; +import java.security.spec.KeySpec; +import java.time.Duration; +import java.util.Arrays; + +import org.springframework.vault.client.VaultEndpoint; +import org.springframework.vault.core.VaultOperations; +import org.springframework.vault.core.VaultPkiOperations; +import org.springframework.vault.core.VaultTemplate; +import org.springframework.vault.support.CertificateBundle; +import org.springframework.vault.support.VaultCertificateRequest; +import org.springframework.vault.support.VaultCertificateResponse; + +/** + * @author Mark Paluch + */ +//@formatter:off +public class PKI { + + void pkiApi() { + + // tag::pkiApi[] + VaultOperations operations = new VaultTemplate(new VaultEndpoint()); + VaultPkiOperations pkiOperations = operations.opsForPki("pki"); + + VaultCertificateRequest request = VaultCertificateRequest.builder() // <1> + .ttl(Duration.ofHours(48)) + .altNames(Arrays.asList("prod.dc-1.example.com", "prod.dc-2.example.com")) + .withIpSubjectAltName("1.2.3.4") + .commonName("hello.example.com") + .build(); + + VaultCertificateResponse response = pkiOperations.issueCertificate("production", request); // <2> + CertificateBundle certificateBundle = response.getRequiredData(); + + KeyStore keyStore = certificateBundle.createKeyStore("my-keystore"); // <3> + + KeySpec privateKey = certificateBundle.getPrivateKeySpec(); // <4> + X509Certificate certificate = certificateBundle.getX509Certificate(); + X509Certificate caCertificate = certificateBundle.getX509IssuerCertificate(); + + pkiOperations.revoke(certificateBundle.getSerialNumber()); // <5> + // end::pkiApi[] + } + +} diff --git a/spring-vault-core/src/test/java/org/springframework/vault/documentation/Token.java b/spring-vault-core/src/test/java/org/springframework/vault/documentation/Token.java new file mode 100644 index 00000000..a2841bf2 --- /dev/null +++ b/spring-vault-core/src/test/java/org/springframework/vault/documentation/Token.java @@ -0,0 +1,64 @@ +/* + * Copyright 2020 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.vault.documentation; + +import java.security.KeyStore; +import java.security.cert.X509Certificate; +import java.security.spec.KeySpec; +import java.time.Duration; + +import org.springframework.vault.client.VaultEndpoint; +import org.springframework.vault.core.VaultOperations; +import org.springframework.vault.core.VaultTemplate; +import org.springframework.vault.core.VaultTokenOperations; +import org.springframework.vault.support.CertificateBundle; +import org.springframework.vault.support.VaultCertificateResponse; +import org.springframework.vault.support.VaultToken; +import org.springframework.vault.support.VaultTokenRequest; +import org.springframework.vault.support.VaultTokenResponse; + +/** + * @author Mark Paluch + */ +//@formatter:off +public class Token { + + void tokenApi() { + + // tag::tokenApi[] + VaultOperations operations = new VaultTemplate(new VaultEndpoint()); + VaultTokenOperations tokenOperations = operations.opsForToken(); + + VaultTokenResponse tokenResponse = tokenOperations.create(); // <1> + VaultToken justAToken = tokenResponse.getToken(); + + VaultTokenRequest tokenRequest = VaultTokenRequest.builder().withPolicy("policy-for-myapp") + .displayName("Access tokens for myapp") + .renewable() + .ttl(Duration.ofHours(1)) + .build(); + + VaultTokenResponse appTokenResponse = tokenOperations.create(tokenRequest); // <2> + VaultToken appToken = appTokenResponse.getToken(); + + tokenOperations.renew(appToken); // <3> + + tokenOperations.revoke(appToken); // <4> + + // end::tokenApi[] + } + +} diff --git a/spring-vault-core/src/test/java/org/springframework/vault/documentation/Transit.java b/spring-vault-core/src/test/java/org/springframework/vault/documentation/Transit.java new file mode 100644 index 00000000..7db5513a --- /dev/null +++ b/spring-vault-core/src/test/java/org/springframework/vault/documentation/Transit.java @@ -0,0 +1,74 @@ +/* + * Copyright 2020 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.vault.documentation; + +import org.springframework.vault.client.VaultEndpoint; +import org.springframework.vault.core.VaultOperations; +import org.springframework.vault.core.VaultTemplate; +import org.springframework.vault.core.VaultTransitOperations; +import org.springframework.vault.support.Ciphertext; +import org.springframework.vault.support.Plaintext; +import org.springframework.vault.support.Signature; +import org.springframework.vault.support.VaultTransitKeyCreationRequest; + +/** + * @author Mark Paluch + */ +//@formatter:off +public class Transit { + + void encryptSimple() { + + // tag::encryptSimple[] + VaultOperations operations = new VaultTemplate(new VaultEndpoint()); + VaultTransitOperations transitOperations = operations.opsForTransit("transit"); + + transitOperations.createKey("my-aes-key", VaultTransitKeyCreationRequest.ofKeyType("aes128-gcm96")); // <1> + + String ciphertext = transitOperations.encrypt("my-aes-key", "plaintext to encrypt"); // <2> + + String plaintext = transitOperations.decrypt("my-aes-key", ciphertext); // <3> + + // end::encryptSimple[] + } + + void encryptPlaintext(VaultTransitOperations transitOperations) { + + // tag::encryptPlaintext[] + byte [] plaintext = "plaintext to encrypt".getBytes(); + + Ciphertext ciphertext = transitOperations.encrypt("my-aes-key", Plaintext.of(plaintext)); // <1> + + Plaintext decrypttedPlaintext = transitOperations.decrypt("my-aes-key", ciphertext); // <2> + + // end::encryptPlaintext[] + } + + void signVerify(VaultTransitOperations transitOperations) { + + // tag::signVerify[] + byte [] plaintext = "plaintext to sign".getBytes(); + + transitOperations.createKey("my-ed25519-key", VaultTransitKeyCreationRequest.ofKeyType("ed25519")); // <1> + + Signature signature = transitOperations.sign("my-ed25519-key", Plaintext.of(plaintext)); // <2> + + boolean valid = transitOperations.verify("my-ed25519-key", Plaintext.of(plaintext), signature); // <3> + + // end::signVerify[] + } + +} diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index 559df316..5139eac1 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -4,6 +4,7 @@ Mark Paluch; :revdate: {localdate} :spring-framework-docs: https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/ :self-docs-root: https://docs.spring.io/spring-vault/docs/{version}/ +:example-root: ../../../../spring-vault-core/src/test/java/org/springframework/vault/documentation (C) 2016-2020 The original authors. diff --git a/src/main/asciidoc/reference/vault-secret-engines.adoc b/src/main/asciidoc/reference/vault-secret-engines.adoc new file mode 100644 index 00000000..32605882 --- /dev/null +++ b/src/main/asciidoc/reference/vault-secret-engines.adoc @@ -0,0 +1,252 @@ +[[vault.core.secret-engines]] += Supporting for Vault's Secret Engines + +Spring Vault ships with several extensions to support Vault's various secret engines. + +Specifically, Spring Vault ships with extensions for: + +* <> +* <> +* <> +* <> +* Transform (Enterprise Feature) +* <> +* System Backend + +All other backends can be used through methods on `VaultTemplate` directly (`VaultTemplate.read(…)`, `VaultTemplate.write(…)`). + +[[vault.core.backends.kv1]] +== Key-Value Version 1 ("unversioned secrets") + +The `kv` secrets engine is used to store arbitrary secrets within the configured physical storage for Vault. + +When running the `kv` secrets engine non-versioned only the most recently written value for a key will be preserved. +The benefits of non-versioned kv is a reduced storage size for each key since no additional metadata or history is stored. +Additionally, requests going to a backend configured this way will be more performant because there will be 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. +That's the primary command line tool for Vault providing commands such as `vault kv get`, `vault kv put` and so on. + +This API can be used with both Key-Value engine versions by specifying the version and mount path. +The following example uses the Key-Value version 1: + +==== +[source,java,indent=0] +---- +include::../{example-root}/KeyValueV1.java[tags=keyValueApi] +---- +==== + +`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. +The following example illustrates writing and reading a secret at `mykey`. +The `kv` secrets engine is mounted at `secret`: + +==== +[source,java,indent=0] +---- +include::../{example-root}/KeyValueV1.java[tags=vaultOperations] +---- +==== + +You can find more details about the https://www.vaultproject.io/api-docs/secret/kv/kv-v1[Vault Key-Value version 1 API] in the Vault reference documentation. + +[[vault.core.backends.kv2]] +== Key-Value Version 2 ("versioned secrets") + +The `kv` secrets engine can be run in one of two versions. +This section explains using version 2. When running v2 of the `kv` backend a key can retain a configurable number of versions. +The older versions' metadata and data can be retrieved. +Additionally, Check-and-Set operations can be used to avoid overwriting data unintentionally. + +Similar to <>, Spring Vault ships with a dedicated Key-Value API to encapsulate differences between the individual Key-Value API implementations. +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. +That's the primary command line tool for Vault providing commands such as `vault kv get`, `vault kv put` and so on. + +This API can be used with both Key-Value engine versions by specifying the version and mount path. +The following example uses the Key-Value version 2: + +==== +[source,java,indent=0] +---- +include::../{example-root}/KeyValueV2.java[tags=keyValueApi] +---- +==== + +`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. + +==== +[source,java,indent=0] +---- +include::../{example-root}/KeyValueV2.java[tags=versionedApi] +---- +<1> Store secrets at `elvis` in that is available under the `secret/` mount. +<2> Storing data in the versioned backend returns metadata such as the version number. +<3> The versioned Key-Value API allows retrieval of specific versions identified by the version number. +<4> Versioned key-value secrets can be mapped into value objects. +<5> When updating versioned secrets using CAS, the input must refer to the previously obtained version. +==== + +While using the `kv` v2 secrets engine through `VaultTemplate` is possible. +It’s not the most convenient approach since the API offers a different approach to context paths and how input/output is represented. +Specifically, interaction with the actual secrets requires wrapping/unwrapping of the data section and introducing a `data/` path segment between the mount and the secrets key. + +==== +[source,java,indent=0] +---- +include::../{example-root}/KeyValueV2.java[tags=vaultOperations] +---- +==== + +You can find more details about the https://www.vaultproject.io/api-docs/secret/kv/kv-v2[Vault Key-Value version 2 API] in the Vault reference documentation. + +[[vault.core.backends.pki]] +== PKI (Public Key Infrastructure) + +The `pki` secrets engine represents a backend for certificates by implementing certificate authority operations. + +The PKI secrets engine generates dynamic X.509 certificates. +With this secrets engine, services can get certificates without going through the usual manual process of generating a private key and CSR, submitting to a CA, and waiting for a verification and signing process to complete. +Vault's built-in authentication and authorization mechanisms provide the verification functionality. + +Spring Vault supports issuing, signing, revoking certificates, and CRL retrieval through `VaultPkiOperations`. +All other PKI functionality can be used through `VaultOperations`. + +The following examples explain briefly the use of how to issue and revoke certificates: + +==== +[source,java,indent=0] +---- +include::../{example-root}/PKI.java[tags=pkiApi] +---- +<1> Construct a certificate request using the `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`. +<3> Generated certificates can be loaded directly into a Java `KeyStore` containing 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 a SSL-secured HTTP server. +<4> `CertificateBundle` allows accessing the private key, public and issuer certificate directly through the Java Cryptography Extension API. +<5> Once a certificate is no longer in use, it can be revokey through its serial number. +Vault will include the revoked certificate in its CRL. +==== + +You can find more details about the https://www.vaultproject.io/api-docs/secret/pki[Vault PKI secrets API] in the Vault reference documentation. + +[[vault.core.backends.token]] +== Token Authentication Backend + +This backend is an authentication backend that doesn't interact with actual secrets. +Rather, it gives access to access token management. +You can read more about <> in the <>. + +The `token` authentication method is built-in and automatically available at `/auth/token`. +It allows users to authenticate using a token, as well to create new tokens, revoke secrets by token, and more. + +When any other auth method returns an identity, Vault core invokes the token method to create a new unique token for that identity. + +The token store can also be used to bypass any other auth method: you can create tokens directly, as well as perform a variety of other operations on tokens such as renewal and revocation. + +Spring Vault uses this backend to renew and revoke session tokens supplied by the configured <>. + +The following examples shows how to request, renew and revoke a Vault token from within your application: + +==== +[source,java,indent=0] +---- +include::../{example-root}/Token.java[tags=tokenApi] +---- +<1> Create an token applying role defaults. +<2> Using the builder API, you can define fine-grained settings for the token to request. +Requesting a token returns a `VaultToken` which is used as value object for Vault tokens. +<3> Tokens can be renewed through the Token API. Typically, that is done by `SessionManager` to keep track of the Vault session token. +<5> Tokens can be revoked if needed through the Token API. Typically, that is done by `SessionManager` to keep track of the Vault session token. +==== + +You can find more details about the https://www.vaultproject.io/api-docs/auth/token[Vault Token Auth Method API] in the Vault reference documentation. + +[[vault.core.backends.transit]] +== Transit Backend + +The transit secrets engine handles cryptographic functions on data in-transit. +Vault doesn't store the data sent to this secrets engine. +It can also be seen as "cryptography as a service" or "encryption as a service". +The transit secrets engine can also sign and verify data; generate hashes and HMACs of data; and act as a random bytes source. + +The primary use case for transit is to encrypt data from applications while still storing that encrypted data in some primary data store. +This relieves the burden of proper encryption/decryption from application developers and pushes the burden onto the operators of Vault. + +Spring Vault supports a wide range of Transit operations: + +* Key creation +* Key reconfiguration +* Encryption/Decryption/Rewrapping +* HMAC computation +* Signing and signature verification + +All operations within `transit` are centered around keys. +The Transit engine supports the versioning of keys allowing you to pick a key type https://www.vaultproject.io/docs/secrets/transit[from a variety of key types]. +Note that depending on the key type may impose a limitation on which operations can used. + +Let's take a look at encryption and decryption. +The following examples shows how to create a key and how to encrypt and decrypt data: + +==== +[source,java,indent=0] +---- +include::../{example-root}/Transit.java[tags=encryptSimple] +---- +<1> First, we need a key to begin with. +Each key requires the type to be specified. `aes128-gcm96` supports encryption, decryption, key derivation, and convergent encryption of which we need encryption and decryption for this example. +<2> Next, we encrypt a `String` containing the plaintext that should be encrypted. +The input `String` uses the default `Charset` to encode the string into its binary representation. +Requesting a token returns a `VaultToken` which is used as value object for Vault tokens. +The `encrypt` method returns Base64-encoded ciphertext, typically starting with `vault:`. +<3> To decrypt ciphertext into plaintext, call the `decrypt` method. +It decrypts the ciphertext and returns a `String` that is decoded using the default charset. +==== + +The preceeding example uses simple strings for cryptographic operations. +While it's a simple approach, it bears the risk of charset misconfiguration and it is not binary-safe. +Binary safety is required when the plaintext uses a binary representation for data such as images, compressed data or binary datastructures. + +To encrypt and decrypt binary data, use the `Plaintext` and `Ciphertext` value objects that can hold binary values: + +==== +[source,java,indent=0] +---- +include::../{example-root}/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. +==== + +`Plaintext` and `Ciphertext` come with a contextual object `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 plaintext and verifying the signature for a given plaintext. +Sign operations require an asymmetric key, typically using Elliptic Curve Cryptography or RSA. + +TIP: This tip explains how signatures work internally. + + + +Signatures make use of the public/private key split to ensure authenticity. + +The signer uses its private key to create a signature (as otherwise anybody would be able to sign messages in your name!). +The verifier uses the public key part to verify the signature. The actual signature is typically a hash value. + + + +Internally, the hash gets computed and encrypted using the private key to create the final signature. The verification decrypts the signature message, computes their own hash for the plaintext and compares both hash values to check whether the signature is valid or not. + +==== +[source,java,indent=0] +---- +include::../{example-root}/Transit.java[tags=signVerify] +---- +<1> Signing requires an asymmetric key. Any Elliptic Curve Cryptography or RSA key type can be used. Once the key is created, we have all pre-requisites in place to create a signature. +<2> The signature gets created for a plaintext 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 plaintext message. As return 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. diff --git a/src/main/asciidoc/reference/vault.adoc b/src/main/asciidoc/reference/vault.adoc index 397c13ce..07de18f5 100644 --- a/src/main/asciidoc/reference/vault.adoc +++ b/src/main/asciidoc/reference/vault.adoc @@ -21,6 +21,8 @@ include::getting-started.adoc[] include::imperative-template.adoc[] +include::vault-secret-engines.adoc[] + include::reactive-template.adoc[] include::propertysource.adoc[]