CREDENTIALA structure (wincred.h)
The CREDENTIAL structure contains an individual credential.
Syntax
typedef struct _CREDENTIALA {
DWORD Flags;
DWORD Type;
LPSTR TargetName;
LPSTR Comment;
FILETIME LastWritten;
DWORD CredentialBlobSize;
LPBYTE CredentialBlob;
DWORD Persist;
DWORD AttributeCount;
PCREDENTIAL_ATTRIBUTEA Attributes;
LPSTR TargetAlias;
LPSTR UserName;
} CREDENTIALA, *PCREDENTIALA;
Members
Flags
A bit member that identifies characteristics of the credential. Undefined bits should be initialized as zero and not otherwise altered to permit future enhancement.
| Value | Meaning |
|---|---|
|
Bit set if the credential does not persist the CredentialBlob and the credential has not been written during this logon session. This bit is ignored on input and is set automatically when queried.
If Type is CRED_TYPE_DOMAIN_CERTIFICATE, the CredentialBlob is not persisted across logon sessions because the PIN of a certificate is very sensitive information. Indeed, when the credential is written to credential manager, the PIN is passed to the CSP associated with the certificate. The CSP will enforce a PIN retention policy appropriate to the certificate. If Type is CRED_TYPE_DOMAIN_PASSWORD or CRED_TYPE_DOMAIN_CERTIFICATE, an authentication package always fails an authentication attempt when using credentials marked as CRED_FLAGS_PROMPT_NOW. The application (typically through the key ring UI) prompts the user for the password. The application saves the credential and retries the authentication. Because the credential has been recently written, the authentication package now gets a credential that is not marked as CRED_FLAGS_PROMPT_NOW. |
|
Bit is set if this credential has a TargetName member set to the same value as the UserName member. Such a credential is one designed to store the CredentialBlob for a specific user. For more information, see the CredMarshalCredential function.
This bit can only be specified if Type is CRED_TYPE_DOMAIN_PASSWORD or CRED_TYPE_DOMAIN_CERTIFICATE. |
Type
The type of the credential. This member cannot be changed after the credential is created. The following values are valid.
TargetName
The name of the credential. The TargetName and Type members uniquely identify the credential. This member cannot be changed after the credential is created. Instead, the credential with the old name should be deleted and the credential with the new name created.
If Type is CRED_TYPE_DOMAIN_PASSWORD or CRED_TYPE_DOMAIN_CERTIFICATE, this member identifies the server or servers that the credential is to be used for. The member is either a NetBIOS or DNS server name, a DNS host name suffix that contains a wildcard character, a NetBIOS or DNS domain name that contains a wildcard character sequence, or an asterisk.
If TargetName is a DNS host name, the TargetAlias member can be the NetBIOS name of the host.
If the TargetName is a DNS host name suffix that contains a wildcard character, the leftmost label of the DNS host name is an asterisk (*), which denotes that the target name is any server whose name ends in the specified name, for example, *.microsoft.com.
If the TargetName is a domain name that contains a wildcard character sequence, the syntax is the domain name followed by a backslash and asterisk (*), which denotes that the target name is any server that is a member of the named domain (or realm).
If TargetName is a DNS domain name that contains a wildcard character sequence, the TargetAlias member can be a NetBIOS domain name that uses a wildcard sequence for the same domain.
If TargetName specifies a DFS share, for example, DfsRoot\DfsShare, then this credential matches the specific DFS share and any servers reached through that DFS share.
If TargetName is a single asterisk (*), this credential matches any server name.
If TargetName is CRED_SESSION_WILDCARD_NAME, this credential matches any server name. This credential matches before a single asterisk and is only valid if Persist is CRED_PERSIST_SESSION. The credential can be set by applications that want to temporarily override the default credential.
This member cannot be longer than CRED_MAX_DOMAIN_TARGET_NAME_LENGTH (337) characters.
If the Type is CRED_TYPE_GENERIC, this member should identify the service that uses the credential in addition to the actual target. Microsoft suggests the name be prefixed by the name of the company implementing the service. Microsoft will use the prefix "Microsoft". Services written by Microsoft should append their service name, for example Microsoft_RAS_TargetName. This member cannot be longer than CRED_MAX_GENERIC_TARGET_NAME_LENGTH (32767) characters.
This member is case-insensitive.
Comment
A string comment from the user that describes this credential. This member cannot be longer than CRED_MAX_STRING_LENGTH (256) characters.
LastWritten
The time, in Coordinated Universal Time (Greenwich Mean Time), of the last modification of the credential. For write operations, the value of this member is ignored.
CredentialBlobSize
The size, in bytes, of the CredentialBlob member. This member cannot be larger than CRED_MAX_CREDENTIAL_BLOB_SIZE (5*512) bytes.
CredentialBlob
Secret data for the credential. The CredentialBlob member can be both read and written.
If the Type member is CRED_TYPE_DOMAIN_PASSWORD, this member contains the plaintext Unicode password for UserName. The CredentialBlob and CredentialBlobSize members do not include a trailing zero character. Also, for CRED_TYPE_DOMAIN_PASSWORD, this member can only be read by the authentication packages.
If the Type member is CRED_TYPE_DOMAIN_CERTIFICATE, this member contains the clear test Unicode PIN for UserName. The CredentialBlob and CredentialBlobSize members do not include a trailing zero character. Also, this member can only be read by the authentication packages.
If the Type member is CRED_TYPE_GENERIC, this member is defined by the application.
Credentials are expected to be portable. Applications should ensure that the data in CredentialBlob is portable. The application defines the byte-endian and alignment of the data in CredentialBlob.
Persist
Defines the persistence of this credential. This member can be read and written.
AttributeCount
The number of application-defined attributes to be associated with the credential. This member can be read and written. Its value cannot be greater than CRED_MAX_ATTRIBUTES (64).
Attributes
Application-defined attributes that are associated with the credential. This member can be read and written.
TargetAlias
Alias for the TargetName member. This member can be read and written. It cannot be longer than CRED_MAX_STRING_LENGTH (256) characters.
If the credential Type is CRED_TYPE_GENERIC, this member can be non-NULL, but the credential manager ignores the member.
UserName
The user name of the account used to connect to TargetName.
If the credential Type is CRED_TYPE_DOMAIN_PASSWORD, this member can be either a DomainNameUserName or a UPN.
If the credential Type is CRED_TYPE_DOMAIN_CERTIFICATE, this member must be a marshaled certificate reference created by calling CredMarshalCredential with a CertCredential.
If the credential Type is CRED_TYPE_GENERIC, this member can be non-NULL, but the credential manager ignores the member.
This member cannot be longer than CRED_MAX_USERNAME_LENGTH (513) characters.
Remarks
Note
The wincred.h header defines CREDENTIAL as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Header | wincred.h |