Package com.chilkatsoft.chilkat2

Class SecureString

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.SecureString
All Implemented Interfaces:
AutoCloseable
public class SecureString extends ChilkatObject
<section class="securestring-summary">

Store, append, compare, hash, verify, and securely access sensitive string values.

Chilkat.SecureString holds sensitive text in an encrypted in-memory form while still allowing controlled operations on the value. It can append clear-text strings, append text from a StringBuilder, append another SecureString, load text from a file, return the clear-text value when needed, compare secure strings, mark the value read-only, maintain a hash of the current value, and verify a supplied hash against that maintained value.

Encrypted in-memory value

Store sensitive text in a form that is decrypted only when needed for access, modification, comparison, or hashing.

Append safely

Append clear-text strings, StringBuilder content, or another SecureString; the value is then re-encrypted.

Read-only protection

Set ReadOnly to prevent later modification of the secure string.

Hash maintenance

Set MaintainHash to a supported hash algorithm such as sha256, sha512, sha1, or md5.

Hash output and verification

Retrieve the current hash value in an encoding such as hex or Base64, or verify a supplied encoded hash with VerifyHash.

Compare and access

Compare two secure strings with SecStrEquals, or call Access when the clear-text value is required.

Common pattern: Create a SecureString, load or append the sensitive text, set MaintainHash if later verification is needed, and optionally set ReadOnly after the final value is established. Use Access only at the point where the clear-text string is actually needed, and check LastErrorText if an append, file load, hash, or verification operation fails.

Hash note: VerifyHash depends on MaintainHash having already been set so the object maintains an internal hash for the current secure string value.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • SecureString

      public SecureString()
      Creates a new SecureString object.

  • Method Details

    • getMaintainHash

      public String getMaintainHash()
      If set to the name of a hash algorithm, then a hash of the current string value is maintained. This allows for the hash to be verified via the VerifyHash method. Possible hash algorithm names are sha1, sha256, sha384, sha512, md5, md2, ripemd160, ripemd128,ripemd256, and ripemd320.
      Returns:
      the value of the MaintainHash property

    • setMaintainHash

      public void setMaintainHash​(String value)
      Sets the MaintainHash property; see getMaintainHash().
      Parameters:
      value - the new value (not null)

    • getReadOnly

      public boolean getReadOnly()
      Can be set to true to make this secure string read-only (cannot be modified).
      Returns:
      the value of the ReadOnly property

    • setReadOnly

      public void setReadOnly​(boolean value)
      Sets the ReadOnly property; see getReadOnly().
      Parameters:
      value - the new value

    • access

      public String access()
      Returns the clear-text string value.
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • append

      public void append​(String str)
      Appends a clear-text string to this secure string. The in-memory data will be decrypted, the string will be appended, and then it will be re-encrypted. Can return false if the string has been marked as read-only via the ReadOnly property.
      Parameters:
      str - the str argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendSb

      public void appendSb​(StringBuilder sb)
      Appends a clear-text string contained in a StringBuilder to this secure string. The in-memory data will be decrypted, the string will be appended, and then it will be re-encrypted. Can return false if the string has been marked as read-only via the ReadOnly property.
      Parameters:
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendSecure

      public void appendSecure​(SecureString secStr)
      Appends the contents of a secure string to this secure string. The in-memory data will be decrypted, the secure string will be appended, and then it will be re-encrypted. Can return false if this string has been marked as read-only via the ReadOnly property.
      Parameters:
      secStr - the secStr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • hashVal

      public String hashVal​(String encoding)
      Returns the hash value for the current value of this secure string. The encoding specifies the encoding to be used. It can be any of the binary encoding algorithms, such as base64, hex, and many more listed at Chilkat Binary Encodings
      Parameters:
      encoding - the encoding argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadFile

      public void loadFile​(String path, String charset)
      Loads the contents of a file into this secure string. The current contents of this object are replaced with the new text from the file.
      Parameters:
      path - the path argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • secStrEquals

      public void secStrEquals​(SecureString secStr)
      Returns true if the secStr equals the contents of this secure string.
      Parameters:
      secStr - the secStr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • verifyHash

      public void verifyHash​(String hashVal, String encoding)
      Verifies the hashVal against the hash value stored for the current value of this secure string. The MaintainHash property must've previously been set for this secure string to maintain an internal hash. The encoding specifies the encoding of the hashVal. It can be any of the binary encoding algorithms, such as base64, hex, and many more listed at Chilkat Binary Encodings
      Parameters:
      hashVal - the hashVal argument (not null)
      encoding - the encoding argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why