Module vault.java.driver
Package io.github.jopenlibs.vault.api.sys

Class Wrapping

java.lang.Object
io.github.jopenlibs.vault.api.OperationsBase
io.github.jopenlibs.vault.api.sys.Wrapping
public class Wrapping extends OperationsBase

The implementing class for /v1/sys/wrapping/* REST endpoints

This class is not intended to be constructed directly. Rather, it is meant to used by way of Vault in a DSL-style builder pattern. See the Javadoc comments of each public method for usage examples.

See Also:

  • Constructor Details

  • Method Details

    • lookupWrap

      public LogicalResponse lookupWrap() throws VaultException

      Returns information about the current client token for a wrapped token, for which the lookup endpoint is at "sys/wrapping/lookup". Example usage:

      
 final String wrappingToken = "...";
 final VaultConfig config = new VaultConfig().address(...).token(wrappingToken).build();
 final Vault vault = new Vault(config);
 final LogicalResponse response = vault.sys().wrapping().lookupWarp();
 // Then you can validate "path" for example ...
 final String path = response.getData().get("path");
      Returns:
      The response information returned from Vault
      Throws:
      VaultException - If any error occurs, or unexpected response received from Vault

    • lookupWrap

      public LogicalResponse lookupWrap(String wrappedToken) throws VaultException

      Returns information about the a wrapped token when authorization is needed for lookup, for which the lookup endpoint is at "sys/wrapping/lookup". Example usage:

      
 final VaultConfig config = new VaultConfig().address(...).token(authToken).build();
 final Vault vault = new Vault(config);
 ...
 final String wrappingToken = "...";
 final LogicalResponse response = vault.sys().wrapping().lookupWarp(wrappingToken);
 // Then you can validate "path" for example ...
 final String path = response.getData().get("path");
      Parameters:
      wrappedToken - Wrapped token.
      Returns:
      The response information returned from Vault
      Throws:
      VaultException - If any error occurs, or unexpected response received from Vault

    • lookupWrap

      public LogicalResponse lookupWrap(String wrappedToken, boolean inBody) throws VaultException

      Returns information about the a wrapped token, for which the lookup endpoint is at "sys/wrapping/lookup". Example usage:

      
 final VaultConfig config = new VaultConfig().address(...).token(authToken).build();
 final Vault vault = new Vault(config);
 ...
 final String wrappingToken = "...";
 final LogicalResponse response = vault.sys().wrapping().lookupWarp(wrappingToken);
 // Then you can validate "path" for example ...
 final String path = response.getData().get("path");
      Parameters:
      wrappedToken - Wrapped token.
      inBody - When true the token value placed in the body request: {"token": "$wrappedToken"}, otherwise, set the token into header: "X-Vault-Token: $wrappedToken".
      Returns:
      The response information returned from Vault
      Throws:
      VaultException - If any error occurs, or unexpected response received from Vault

    • wrap

      public WrapResponse wrap(JsonObject jsonObject, int ttlInSec) throws VaultException

      Provide access to the /sys/wrapping/wrap endpoint.

      This provides a powerful mechanism for information sharing in many environments. In the types of scenarios, often the best practical option is to provide cover for the secret information, be able to detect malfeasance (interception, tampering), and limit lifetime of the secret's exposure. Response wrapping performs all three of these duties:

      • It provides cover by ensuring that the value being transmitted across the wire is not the actual secret but a reference to such a secret, namely the response-wrapping token. Information stored in logs or captured along the way do not directly see the sensitive information.
      • It provides malfeasance detection by ensuring that only a single party can ever unwrap the token and see what's inside. A client receiving a token that cannot be unwrapped can trigger an immediate security incident. In addition, a client can inspect a given token before unwrapping to ensure that its origin is from the expected location in Vault.
      • It limits the lifetime of secret exposure because the response-wrapping token has a lifetime that is separate from the wrapped secret (and often can be much shorter), so if a client fails to come up and unwrap the token, the token can expire very quickly. 
      
 final String authToken = "...";
 final String wrappingToken = "...";
 final VaultConfig config = new VaultConfig().address(...).token(authToken).build();
 final Vault vault = new Vault(config);

 final WrapResponse wrapResponse = vault.sys().wrapping().wrap(
                 // Data to wrap
                 new JsonObject()
                         .add("foo", "bar")
                         .add("zoo", "zar"),

                 // TTL of the response-wrapping token
                 60
         );

 final UnwrapResponse unwrapResponse = vault.sys().wrapping().unwrap(wrapResponse.getToken());
 final JsonObject unwrappedData = response.getData(); // original data
      Parameters:
      jsonObject - User data to wrap.
      ttlInSec - Wrap TTL in seconds
      Returns:
      The response information returned from Vault
      Throws:
      VaultException - If any error occurs, or unexpected response received from Vault
      See Also:

    • unwrap

      public UnwrapResponse unwrap() throws VaultException

      Returns the original response inside the wrapped auth token. This method is useful if you need to unwrap a token without being authenticated. See unwrap(String) if you need to do that authenticated.

      In the example below, you cannot use twice the VaultConfig, since after the first usage of the wrappingToken, it is not usable anymore. You need to use the unwrappedToken in a new vault configuration to continue. Example usage:

      
 final String wrappingToken = "...";
 final VaultConfig config = new VaultConfig().address(...).token(wrappingToken).build();
 final Vault vault = new Vault(config);
 final AuthResponse response = vault.sys().wrapping().unwrap();
 final String unwrappedToken = response.getAuthClientToken();
      Returns:
      The response information returned from Vault
      Throws:
      VaultException - If any error occurs, or unexpected response received from Vault
      See Also:

    • unwrap

      public UnwrapResponse unwrap(String wrappedToken) throws VaultException

      Provide access to the /sys/wrapping/unwrap endpoint.

      Returns the original response inside the given wrapping token. Unlike simply reading cubbyhole/response (which is deprecated), this endpoint provides additional validation checks on the token, returns the original value on the wire rather than a JSON string representation of it, and ensures that the response is properly audit-logged.

      This endpoint can be used by using a wrapping token as the client token in the API call, in which case the token parameter is not required; or, a different token with permissions to access this endpoint can make the call and pass in the wrapping token in the token parameter. Do not use the wrapping token in both locations; this will cause the wrapping token to be revoked but the value to be unable to be looked up, as it will basically be a double-use of the token!

      In the example below, authToken is NOT your wrapped token, and should have unwrapping permissions. The unwrapped data in UnwrapResponse.getData(). Example usage:

      
 final String authToken = "...";
 final String wrappingToken = "...";
 final VaultConfig config = new VaultConfig().address(...).token(authToken).build();
 final Vault vault = new Vault(config);

 final WrapResponse wrapResponse = vault.sys().wrapping().wrap(
                 // Data to wrap
                 new JsonObject()
                         .add("foo", "bar")
                         .add("zoo", "zar"),

                 // TTL of the response-wrapping token
                 60
         );

 final UnwrapResponse unwrapResponse = vault.sys().wrapping().unwrap(wrapResponse.getToken());
 final JsonObject unwrappedData = response.getData(); // original data
      Parameters:
      wrappedToken - Specifies the wrapping token ID, do NOT also put this in your VaultConfig.getToken(), if token is null, this method will unwrap the auth token in VaultConfig.getToken()
      Returns:
      The response information returned from Vault
      Throws:
      VaultException - If any error occurs, or unexpected response received from Vault
      See Also:

    • unwrap

      public UnwrapResponse unwrap(String wrappedToken, boolean inBody) throws VaultException

      Provide access to the /sys/wrapping/unwrap endpoint.

      Returns the original response inside the given wrapping token. Unlike simply reading cubbyhole/response (which is deprecated), this endpoint provides additional validation checks on the token, returns the original value on the wire rather than a JSON string representation of it, and ensures that the response is properly audit-logged.

      This endpoint can be used by using a wrapping token as the client token in the API call, in which case the token parameter is not required; or, a different token with permissions to access this endpoint can make the call and pass in the wrapping token in the token parameter. Do not use the wrapping token in both locations; this will cause the wrapping token to be revoked but the value to be unable to be looked up, as it will basically be a double-use of the token!

      In the example below, authToken is NOT your wrapped token, and should have unwrapping permissions. The unwrapped data in UnwrapResponse.getData(). Example usage:

      
 final String authToken = "...";
 final String wrappingToken = "...";
 final VaultConfig config = new VaultConfig().address(...).token(authToken).build();
 final Vault vault = new Vault(config);

 final WrapResponse wrapResponse = vault.sys().wrapping().wrap(
                 // Data to wrap
                 new JsonObject()
                         .add("foo", "bar")
                         .add("zoo", "zar"),

                 // TTL of the response-wrapping token
                 60
         );

 final UnwrapResponse unwrapResponse = vault.sys().wrapping().unwrap(wrapResponse.getToken(), true);
 final JsonObject unwrappedData = response.getData(); // original data
      Parameters:
      wrappedToken - Specifies the wrapping token ID, do NOT also put this in your VaultConfig.getToken(), if token is null, this method will unwrap the auth token in VaultConfig.getToken()
      inBody - When true the token value placed in the body request: {"token": "$wrappedToken"}, otherwise, set the token into header: "X-Vault-Token: $wrappedToken".
      Returns:
      The response information returned from Vault
      Throws:
      VaultException - If any error occurs, or unexpected response received from Vault
      See Also:

    • rewrap

      public WrapResponse rewrap(String wrappedToken) throws VaultException

      Provide access to the /sys/wrapping/rewrap endpoint. This endpoint rewraps a response-wrapped token. The new token will use the same creation TTL as the original token and contain the same response. The old token will be invalidated. This can be used for long-term storage of a secret in a response-wrapped token when rotation is a requirement.

      
 final String authToken = "...";
 final String wrappingToken = "...";
 final VaultConfig config = new VaultConfig().address(...).token(authToken).build();
 final Vault vault = new Vault(config);

 final WrapResponse wrapResponse = vault.auth().wrap(
                 // Data to wrap
                 new JsonObject()
                         .add("foo", "bar")
                         .add("zoo", "zar"),

                 // TTL of the response-wrapping token
                 60
         );
 ...
 final WrapResponse wrapResponse2 = vault.auth().rewrap(wrapResponse.getToken());

 final UnwrapResponse unwrapResponse = vault.auth().unwrap(wrapResponse2.getToken());
 final JsonObject unwrappedData = response.getData(); // original data
      Parameters:
      wrappedToken - Wrapped token ID to re-wrap.
      Returns:
      The response information returned from Vault
      Throws:
      VaultException - If any error occurs, or unexpected response received from Vault
      See Also: