----------------------------------------------------------------------
SUMMARY
----------------------------------------------------------------------

These set of functions allows for secure storage of credentials to a file.  The
intent is that these credentials can be used by other scripts to connect to 
remote hosts.  This is loosely patterned after the *-VICredentialStoreItem
cmdlets release by VMware in the VI Toolkit for Windows.  The MS DPAPI is 
used in this implementation and so the credential file is only usable by one 
user on a single computer.

The default location for the credential store is:
%appdata%\SecureCredStore\credentials.xml

----------------------------------------------------------------------
DETAILS
----------------------------------------------------------------------

Public functions:

New-SecureCredentialStoreItem
    Add a new host/user/password entry to the credential store.
    
    Parameters:
        hostname = Required: The hostname to be saved with this entry.
        username = Required: The username to be saved with this entry.
        password = Optional: A System.Security.SecureString form of the 
                             password.  If not provided the user will
                             be prompted.
        file =     Optional: Use this alternate credential file.

   
Get-SecureCredentialStoreItem
    Retrieve zero, one, or more items from the credential store.
    
    Parameters:
        hostname    Optional: Get credentials for this host.
        username    Optional: Get credentials for this username.  May be
                              combined with hostname.
        file        Optional: Use this alternate credential file.
        

Remove-SecureCredentialStoreItem
    Remove zero, one, or more items from the credential store.
    
    Parameters:
        hostname    Optional: Remove credentials for this host.
        username    Optional: Remove credentials for this username.  May be
                              combined with hostname.
        file        Optional: Use this alternate credential file.


Clear-SecureCredentialStoreItems
    Remove all items from teh credential store.
    
        file        Optional: Use this alternate credential file.

SecureCredentialStoreItem
    The credential storage object.
    
    Properties:
        hostname    The hostname stored in this item.
        username    The username stored in this item.
        password    The SecureString version of the password.
        credential  A pscredential object.
    
    Methods:
        passwordToPlainText     Returns the password in plain text.  This
                                violates the security protections of the
                                PSCredential, so use this only when 
                                necessary.
    

Private functions:

These are not needed for normal usage.  The public functions use them
transparently.

Load-SecureCredentialStoreFromFile
Save-SecureCredentialStoreToFile

----------------------------------------------------------------------
Examples
----------------------------------------------------------------------
# Source the file so the functions are available.
. .\SecureCredentialStoreItemFunctions

# Add some credentials
New-SecureCredentialStoreItem -hostname localhost -username root
New-SecureCredentialStoreItem -hostname localhost -username user
New-SecureCredentialStoreItem -hostname remotehost -username root

# List the credentials
Get-SecureCredentialStoreItem

# Get all credentials for a host
Get-SecureCredentialStoreItem -hostname localhost

# Get the credential for the user/host
$myCred = Get-SecureCredentialStoreItem -hostname localhost -username root

# Use portions of the credential
$myCred.hostname
$myCred.username
$myCred.password
$myCred.credential
$myCred.passwordToPlainText()

# Remove all credentials for a host
Remove-SecureCredentialStoreItem -hostname localhost

# Remove all credentials for a username
Remove-SecureCredentialStoreItem -username user

# Remove all credentials for a combination host/user
Remove-SecureCredentialStoreItem -hostname localhost -username root

# Clear all credentials
Clear-SecureCredentialStoreItems

----------------------------------------------------------------------
KNOWN LIMITATIONS
----------------------------------------------------------------------

I have not determined how I want to handle undecryptable passwords in the 
credential file.  So far it just displays a message and exits.


----------------------------------------------------------------------
BUGS
----------------------------------------------------------------------