Package org.identityconnectors.common.security

Class GuardedByteArray

  • public final class GuardedByteArray
extends java.lang.Object
    Secure byte array implementation that solves the problems associated with keeping confidential data as byte[]. That is, anything represented as a byte[] is kept in memory in clear text and stays in memory at least until it is garbage collected.

    The GuardedByteArray class alleviates this problem by storing the bytes in memory in an encrypted form. The encryption key will be a randomly-generated key.

    In their serialized form, GuardedByteArrays will be encrypted using a known default key. This is to provide a minimum level of protection regardless of the transport. For communications with the Remote Connector Framework it is recommended that deployments enable SSL for true encryption.

    Applications may also wish to persist GuardedByteArrays. In the case of Identity Manager, it should convert GuardedByteArrays to EncryptedData so that they can be stored and managed using the Manage Encryption features of Identity Manager. Other applications may wish to serialize APIConfiguration as a whole. These applications are responsible for encrypting the APIConfiguration blob for an additional layer of security (beyond the basic default key encryption provided by GuardedByteArray).

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static interface  GuardedByteArray.Accessor
      Callback interface for those times that it is necessary to access the clear text of the guarded bytes.

    • Constructor Summary

      Constructors 
      Constructor Description
      GuardedByteArray()
      Creates an empty secure byte array.
      GuardedByteArray​(byte[] clearBytes)
      Initializes the GuardedByteArray from the given clear text bytes.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void access​(GuardedByteArray.Accessor accessor)
      Provides access to the clear-text value of the byte array in a controlled fashion.
      void appendByte​(byte b)
      Appends a single clear-text byte to the secure byte array.
      GuardedByteArray copy()
      Create a copy of the byte array.
      void dispose()
      Clears the in-memory representation of the byte array.
      boolean equals​(java.lang.Object o)  
      int hashCode()  
      boolean isReadOnly()
      Returns true if this byte array has been marked read-only.
      void makeReadOnly()
      Mark this byte array as read-only.
      boolean verifyBase64SHA1Hash​(java.lang.String hash)
      Verifies that this base-64 encoded SHA1 hash of this byte array matches the given value.

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • GuardedByteArray

        public GuardedByteArray()
        Creates an empty secure byte array.

      • GuardedByteArray

        public GuardedByteArray​(byte[] clearBytes)
        Initializes the GuardedByteArray from the given clear text bytes. Caller is responsible for zeroing out the array of bytes after the call.
        Parameters:
        clearBytes - The clear-text bytes

    • Method Detail

      • access

        public void access​(GuardedByteArray.Accessor accessor)
        Provides access to the clear-text value of the byte array in a controlled fashion. The clear-text bytes will only be available for the duration of the call and automatically zeroed out following the call.

        NOTE: Callers are encouraged to use verifyBase64SHA1Hash(String) where possible if the intended use is merely to verify the contents of the byte array match an expected hash value.

        Parameters:
        accessor - Accessor callback.
        Throws:
        java.lang.IllegalStateException - If the byte array has been disposed

      • appendByte

        public void appendByte​(byte b)
        Appends a single clear-text byte to the secure byte array. The in-memory data will be decrypted, the byte will be appended, and then it will be re-encrypted.
        Parameters:
        b - The byte to append.
        Throws:
        java.lang.IllegalStateException - If the byte array is read-only
        java.lang.IllegalStateException - If the byte array has been disposed

      • dispose

        public void dispose()
        Clears the in-memory representation of the byte array.

      • isReadOnly

        public boolean isReadOnly()
        Returns true if this byte array has been marked read-only.
        Returns:
        true if this byte array has been marked read-only
        Throws:
        java.lang.IllegalStateException - If the byte array has been disposed

      • makeReadOnly

        public void makeReadOnly()
        Mark this byte array as read-only.
        Throws:
        java.lang.IllegalStateException - If the byte array has been disposed

      • copy

        public GuardedByteArray copy()
        Create a copy of the byte array. If this instance is read-only, the copy will not be read-only.
        Returns:
        A copy of the byte array.
        Throws:
        java.lang.IllegalStateException - If the byte array has been disposed

      • verifyBase64SHA1Hash

        public boolean verifyBase64SHA1Hash​(java.lang.String hash)
        Verifies that this base-64 encoded SHA1 hash of this byte array matches the given value.
        Parameters:
        hash - The hash to verify against.
        Returns:
        True if the hash matches the given parameter.
        Throws:
        java.lang.IllegalStateException - If the byte array has been disposed

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object