CredMan

Reads and write credentials to the Windows Credential Manger.

Syntax:

CredMan(command [, target [, user_type [, secret_def]]])

Parameters:

(s) command: "domain", "generic", "read", "delete", or "enum" (see below).

(s) target: (optional) A name that along with the type provide a unique identifier.

(s) user_type: (optional) User name or credential type depending on the command.

(s) secret_def: (optional) User's password or default text depending the command.

Returns:

(i) @True, @False, rank 1 array, or rank 2 array. The return value depends on the command.

The CredMan function provides scripts access to the secure Windows Credential Manager. Credentials added with this function are machine persistent but can only be created, read or modified for the user account used to execute the function in a WIL script.

The function enables you to read credentials using the "Read" command but the credential's secret is usually returned as an empty string in the output array. This is because the secret is passed to a register cryptographic services provider for encryption and storage. The provider used is determined but the credential type and the application name or server name in the target parameter. For example, if you create a "Domain" credential with a NetBIOS or DNS domain name of the network host as the target, the secret can only be read by authentication packages like NTML or Kerberos.

Note: Generally, you can read generic credential passwords you create with this function that are not associated with a cryptographic service provider or other service by using a specific target.

Command

Explanation of function commands alone with parameter requirements and output.

Command	Purpose	Parameters	Function Return Values
"Domain"	Creates or modifies a domain credential.	target, user (user_type), and secret_def*	@True on success; otherwise, @False
"Generic"	Creates or modifies a generic credential.	target, user (user_type), and secret_def*	@True on success; otherwise, @False
"Read"	Returns a single credential from the current user's credential set.	target and type (user_type). "Domain" or "Generic" are the supported as the type parameter. The secret parameter can optionally be used to customize the array element text returned when the target is not found. Otherwise, the text "<not found>" is use when target is not in the credential set.	One dimension array of 4 elements. From array index 0 to 3, the elements are target, type, user, and secret.
"Enum"	Returns the current user's entire credential set.	N/A	Two dimension array with one row for each credential in the current user's credential set. The return arrays columns contain each credentials decorated target name, type, and user name. Passwords are not included in the return array. The function returns an array with no elements when the credential cache is empty.
"Delete"	Removes a credential from the current user's credential set.	target and type (user_type). The "Domain" or "Generic" types are supported in the type parameter.	@True on success; otherwise, @False

* The function will not error when the secret parameter is not present. If the secret_def parameter is passed as a WIL variable, the variable's string contents will be removed from process memory and the variable will contain an empty string on the functions return.

Target

This is the name of the credential. The name is used to uniquely identify a credential along with the type reading and deleting. It is also used to associate a credential with an application, service, or network host.

User_type

Use this parameter to provide a credential user name when creating a new or modifying an existing credential. The parameter holds the credential type "Generic" or "Domain" when using the "Read" or "Delete" options. Together the target name and type uniquely identify a credential.

Secret_def

When using the "Generic" or "Domain" command the secret parameter holds the password or pin of the credential. It can be an empty string. When using the "Read" command, the parameter can be used to indicate alternative text to use in each element of the return array when the target is not found.

Examples 1:

  ; Create a generic credential
  Target = 'SpiffyScript'
  User = 'ScriptUser'
  Pswd = '*topsecret*'
  
  ; CredMan changes the contents of the Pswd variable
  ; to an empty string. This removes the password
  ; from string memory. 
  ret = CredMan('Generic', Target, User, Pswd) 
  If ret Then Text = ' added'
  Else Text = ' not added'
  Message('Add Generic Example', Target:Text)

Examples 2:

  ; Read a generic credential
  Target = 'SpiffyScript'
  Type = 'Generic'
  Nf = 'Not Found'
  
  ret = CredMan('Read', Target, Type, Nf)
  If ret[0] == Nf Then Text = Target:' ':Nf
  Else Text = ArrayItemize(ret, @lf)
  Message('Read Generic Example', Text)

Examples 3:

  ; Remove a generic credential
  Target = 'SpiffyScript'
  Type = 'Generic'
  
  ret = CredMan('Delete', Target, Type)
  If ret  Then Text = Target:' deleted'
  Else Text = Target:'' not found fo
  Message('Remove Generic Example', Text)

Examples 4:

  ; List most credentials in the 
  ; credential manager store
  Ret = CredMan('Enum' )
  Creds = ''
  iMax = ArrInfo(Ret, 1) - 1
  For i = 0 To iMax
     Creds := Ret[i, 0]:@lf:Ret[i, 1]:@lf:Ret[i, 2]:@lf:@lf
  Next
  If iMax < 0  Then Text = 'No credentials found'
  Else Text = Creds
  ; Enum command does not return passwords/secrets
  Message('Enum Credentials Example', Text)