Package de.espirit.firstspirit.agency

Interface PasswordAgent

public interface PasswordAgent

The PasswordAgent provides access to the internal mechanisms of FirstSpirit which allow to encrypt and decrypt password strings.
Although the FirstSpirit internal mechanisms are used, the encryption is not compatible to the password property encryption used by the FirstSpirit server.

There are three possible ways to provide an encryption key. If more than one key is available, the key with the highest priority is used. The ordering from lowest to highest priority is as follows:

  1. Internal obfuscation key, always available
  2. Key file configured in fs-server.conf
  3. Key environment variable configured in fs-server.conf

Password string encryption is always available, even when it is not activated for internal password property handling of the FirstSpirit server.
Reminder: If keys are removed or unavailable, all passwords encrypted with such a key are not decryptable.

A password namespace string is part of the encryption process. This namespace can be a constant, for instance a class or module name or a random token. The namespace used for decrypting a password must be the same used for encrypting the password or decryption will not be successful. It is the responsibility of the API user to provide a namespace. Using a constant namespace is a viable option and not a security drawback.

Since:
5.2.1904

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final SpecialistType<PasswordAgent>
    TYPE
    The agent's technical type to be used to request the agent from a SpecialistsBroker.

  • Method Summary

    Modifier and Type
    Method
    Description
    @NotNull String
    decryptPassword(@NotNull String namespace, @NotNull String password)
    Decrypts a password.
    This method uses the FirstSpirit internal password encryption mechanisms to perform the encryption.
    @NotNull String
    encryptPassword(@NotNull String namespace, @NotNull String password)
    Encrypts a password.
    This method uses the FirstSpirit internal password encryption mechanisms to perform the encryption.
    boolean
    isEncryptedPassword(@Nullable String password)
    Indicates if the given string is an encrypted password.
    The password string may be null, in this case false is returned.
    boolean
    isHigherPriorityKeyAvailableForPassword(@NotNull String password)
    Tests whether the encrypted password has been encrypted with a low priority key while a higher priority key is available on the FirstSpirit server in the meantime.
    boolean
    isPasswordEncryptionEnabled()
    Indicates if the password encryption is enabled for the FirstSpirit server.
    Even if the password encryption for the FirstSpirit server is disabled (i.e. when this method returns false), it is possible to use the encryptPassword(String, String) and decryptPassword(String, String) methods.
    To enable the internal password encryption of the FirstSpirit server, please use the password.encryption.active setting in the fs-server.conf file.

  • Field Details

  • Method Details

    • isPasswordEncryptionEnabled

      boolean isPasswordEncryptionEnabled()
      Indicates if the password encryption is enabled for the FirstSpirit server.
      Even if the password encryption for the FirstSpirit server is disabled (i.e. when this method returns false), it is possible to use the encryptPassword(String, String) and decryptPassword(String, String) methods.
      To enable the internal password encryption of the FirstSpirit server, please use the password.encryption.active setting in the fs-server.conf file.
      Returns:
      true if the password encryption is enabled for the FirstSpirit server, false otherwise.
      Since:
      5.2.1904

    • isEncryptedPassword

      boolean isEncryptedPassword(@Nullable @Nullable String password)
      Indicates if the given string is an encrypted password.
      The password string may be null, in this case false is returned. If the password string is identified as an encrypted password, it can be decrypted by calling the decryptPassword(String, String) method.
      Note: This method does not decrypt or validate the encrypted password, only the string prefix is examined.
      Parameters:
      password - The encrypted password or null.
      Returns:
      true if the password string was identified as an encrypted password, false otherwise.
      Since:
      5.2.1904

    • isHigherPriorityKeyAvailableForPassword

      boolean isHigherPriorityKeyAvailableForPassword(@NotNull @NotNull String password)
      Tests whether the encrypted password has been encrypted with a low priority key while a higher priority key is available on the FirstSpirit server in the meantime. Returns true if a higher priority key is available and re-encrypting the encrypted password by calling the encryptPassword(String, String) method as well as updating the stored password string should be performed.
      Note: This method does not decrypt or validate the encrypted password, only the used key is examined.
      Parameters:
      password - The encrypted password, must not be null.
      Returns:
      true if the encrypted password should be re-encrypted and updated because a higher priority key is available, false otherwise.
      Throws:
      NullPointerException - If the password is null.
      IllegalArgumentException - If the password is not an encrypted password.
      Since:
      5.2.1904

    • encryptPassword

      @NotNull @NotNull String encryptPassword(@NotNull @NotNull String namespace, @NotNull @NotNull String password)
      Encrypts a password.
      This method uses the FirstSpirit internal password encryption mechanisms to perform the encryption. It always returns an encrypted password even if the password encryption is disabled for the FirstSpirit server. If no other key is available on the FirstSpirit server, an internal obfuscation key is used.
      Parameters:
      namespace - Choosable password namespace. The namespace is part of the encryption process, only passwords with the same namespace are compatible and decryptable. Must not be null.
      password - The clear text password, must not be null.
      Returns:
      The encrypted password.
      Throws:
      NullPointerException - If one of the parameters is null.
      Since:
      5.2.1904

    • decryptPassword

      @NotNull @NotNull String decryptPassword(@NotNull @NotNull String namespace, @NotNull @NotNull String password)
      Decrypts a password.
      This method uses the FirstSpirit internal password encryption mechanisms to perform the encryption. This method always returns a decrypted password even if the password encryption is disabled for the FirstSpirit server. If no other key is available on the FirstSpirit server, an internal obfuscation key is used.
      Parameters:
      namespace - Choosable password namespace string. The namespace is part of the encryption process, only passwords with the same namespace are compatible and decryptable. Must not be null.
      password - The encrypted password, must not be null.
      Returns:
      The decrypted clear text password.
      Throws:
      SecurityException - If the encryption key is not (longer) available, the encrypted password was tampered with or the namespace is wrong.
      NullPointerException - If one of the parameters is null.
      IllegalArgumentException - If the password is not an encrypted password.
      Since:
      5.2.1904