GuardedString (Oracle Fusion Middleware Java API Reference for Identity Connector Framework)

java.lang.Object
- org.identityconnectors.common.security.GuardedString

```
public final class GuardedString
extends java.lang.Object
```
Secure string implementation that solves the problems associated with keeping passwords as java.lang.String. That is, anything represented as a String is kept in memory as a clear text password and stays in memory at least until it is garbage collected.
The GuardedString class alleviates this problem by storing the characters in memory in an encrypted form. The encryption key will be a randomly-generated key.
In their serialized form, GuardedString 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 GuardedStrings. In the case of Identity Manager, it should convert GuardedStrings 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 GuardedString).

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`GuardedString.Accessor` Callback interface for those times that it is necessary to access the clear text of the secure string.

Constructor Summary

Constructors
Constructor and Description

GuardedString()
Creates an empty secure string

GuardedString(char[] clearChars)
Initialized the GuardedString from the given clear characters.

Constructors
Constructor and Description
`GuardedString()` Creates an empty secure string
`GuardedString(char[] clearChars)` Initialized the GuardedString from the given clear characters.

Method Summary

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

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - GuardedString
```
public GuardedString()
```
    Creates an empty secure string
  - GuardedString
```
public GuardedString(char[] clearChars)
```
    Initialized the GuardedString from the given clear characters. Caller is responsible for zeroing out the array of characters after the call.
    
    Parameters:
    
    clearChars - The clear-text characters
- Method Detail
  - access
```
public void access(GuardedString.Accessor accessor)
```
    Provides access to the clear-text value of the string in a controlled fashion. The clear-text characters 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 string match an expected hash value.
    
    Parameters:
    
    accessor - Accessor callback.
    
    Throws:
    
    java.lang.IllegalStateException - If the string has been disposed
  - appendChar
```
public void appendChar(char c)
```
    Appends a single clear-text character to the secure string. The in-memory data will be decrypted, the character will be appended, and then it will be re-encrypted.
    
    Parameters:
    
    c - The character to append.
    
    Throws:
    
    java.lang.IllegalStateException - If the string is read-only
    
    java.lang.IllegalStateException - If the string has been disposed
  - dispose
```
public void dispose()
```
    Clears the in-memory representation of the string.
  - isReadOnly
```
public boolean isReadOnly()
```
    Returns true iff this string has been marked read-only
    
    Returns:
    
    true iff this string has been marked read-only
    
    Throws:
    
    java.lang.IllegalStateException - If the string has been disposed
  - makeReadOnly
```
public void makeReadOnly()
```
    Mark this string as read-only.
    
    Throws:
    
    java.lang.IllegalStateException - If the string has been disposed
  - copy
```
public GuardedString copy()
```
    Create a copy of the string. If this instance is read-only, the copy will not be read-only.
    
    Returns:
    
    A copy of the string.
    
    Throws:
    
    java.lang.IllegalStateException - If the string has been disposed
  - verifyBase64SHA1Hash
```
public boolean verifyBase64SHA1Hash(java.lang.String hash)
```
    Verifies that this base-64 encoded SHA1 hash of this string 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 string 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

Class GuardedString

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

GuardedString

GuardedString

Method Detail

access

appendChar

dispose

isReadOnly

makeReadOnly

copy

verifyBase64SHA1Hash

equals

hashCode