Package com.atlassian.secrets.api

Interface SecretServiceBackend

public interface SecretServiceBackend
An API for securely managing sensitive String data.

Depending on the implementation, seal(String, String) could store the secret using a 3rd party secrets service such as, HashiCorp Vault or AWS SecretsManager. Similarly, an alternate implementation could be used for simply AES encrypting the secret.

Inversely, unseal(SealedSecret) can be used to retrieve a secret stored in a 3rd party secrets service, or it could be used to AES decrypt it.

Since:
5.0.0
Author:
Adam Brokes, Byron Conroy, Dylan Rathbone, Jun Jeong see com.atlassian.secrets.service.RoutingSecretService see com.atlassian.secrets.service.aes.AESSecretService see com.atlassian.secrets.service.aws.AWSSecretService see com.atlassian.secrets.service.vault.VaultSecretService

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    delete(String identifier)
    Deletes the secret associated with the given identifier.
    SecretServiceType
    getType()
    Returns the type of the backend (to be used by analytics).
    SealedSecret
    seal(String identifier, String plainTextToSecure)
    Securely seal a plain text string.
    String
    unseal(SealedSecret sealedSecret)
    Unseal the secret returning its plaintext value

  • Method Details

    • seal

      SealedSecret seal(String identifier, String plainTextToSecure) throws SecretServiceException
      Securely seal a plain text string. In this case 'seal' is used as a general term to represent any appropriate approach for securing the plain text string, be that; encryption or storing in an external secret manager
      Parameters:
      identifier - An application-wide unique String id for a secret. It serves two main purposes:
      • Determines which backend to use for sealing and unsealing the secret. If the identifier matches one of the secret mappings, the mapped backend is used instead of the default backend. Read 'Secret Mappings' in README.md for more details.
      • Constructs a key in a Key-Value store. For an example of how it is used, see SecretDao."
      It's important to ensure that the identifier is unique for each secret. If the same identifier string is provided for different secrets, the secret values will effectively overwrite each other in the Key-Value store.
      • You can make an identifier application-wide unique by providing structured prefixes followed by a sensible name.

        For example: "atl-secrets/confluence/database/hibernate.connection.password"
      • If multiple secrets share the same prefixes and names, random integers or ids can be suffixed to provide uniqueness.

        For example: "atl-secrets/confluence/ldap/password-68134", "atl-secrets/confluence/ldap/password-51361"
      plainTextToSecure - the plaintext string that needs to be securely sealed. Maximum text size that can be sealed is 64KB.
      Returns:
      a SealedSecret to be used by unseal(SealedSecret) when a plaintext version of the secret is required.
      Throws:
      IllegalArgumentException - If the identifier doesn't contain any non-whitespace text
      SecretServiceException - If the plaintext is not successfully sealed

    • unseal

      String unseal(SealedSecret sealedSecret) throws SecretServiceException
      Unseal the secret returning its plaintext value
      Parameters:
      sealedSecret - a SealedSecret from a prior call to seal(String, String)
      Returns:
      a plaintext String for the secret
      Throws:
      SecretServiceException - If the secret cannot be unsealed

    • delete

      void delete(String identifier) throws SecretServiceException
      Deletes the secret associated with the given identifier.

      This method has no effect on SecretService implementations whose seal method returns an EncryptionBasedSecret, as they do not store secret data.
      Parameters:
      identifier - An application-wide unique String id for the secret. See seal(String, String) for more details about the identifier.
      Throws:
      SecretServiceException - if there is an error during the deletion process.

    • getType

      SecretServiceType getType()
      Returns the type of the backend (to be used by analytics).
      Returns:
      The SecretServiceType of this SecretServiceBackend