Credential provider

The credential provider is a Microsoft Windows only extension and is not available on any other platform. The purpose is to allow end-users to select the credential to be used in different scenarios. Our credential provider will not introduce any new logon mechanism to Windows platform. Instead it extends the existing provider from Microsoft for better user experience and adds other private key tokens beside smart cards.

The most common misunderstanding about credential providers is that it has something to do with login. This is wrong, it does not. A credential provider only allows the end-user to select and enter information, and the purpose is unknown to the credential provider. It can be a Windows logon or something totally different.

A credential provider is not a logon provider.

Three types of credential providers supported:

  • Standard, select certificate and enter PIN.

  • Certificate, only select certificate.

  • PIN, only enter PIN.

The standard provider is the most commonly used, and it allows for selecting the certificate and enter PIN in the same dialog.

The other two providers are used when the application have decided to split the selecting of certificate and entering of PIN to two different dialogs. The most common scenario is a web browser that allows the end-user to select the certificate for client authentication and then let the CSP/KSP show the PIN dialog. The PIN provider is only used by Microsoft CSP/KSP.

Versions

Two different versions, or rather generations, of credential providers are available. The first generation was introduced in Windows 7 and the second in Windows 8.1. The second generation only introduced some extensions for Windows logon to allow grouping of logon tiles. The first generation will work without any problem with later versions of Windows, but there is no grouping of tiles.

Our credential provider support both generations via configuration, but by default the first generation is used. The reason for this is that grouping of tiles works bad with smart cards with multiple certificates (identities).

Full or Pass-through

The standard credential provider replaces the existing provider and there are two options:

  • wrap the existing provider (pass-through)

  • complete replacement (full).

The main reason for wrapping is that the existing provider can have other functionality than the pure credential provider. For eample Microsoft’s smart card credential provider is required for Microsoft Certificate Propagation (register certificate to CryptoAPI MY store).

The main reason for complete replacement is to guarantee that the existing provider is not accessing at all, since multiple access can cause conflicts.

The choice of pass-through or full will depend on your environment. Complete replacement, or full, is the default.

The certificate provider is always pass-through, since Microsoft "forgot" to document the format of the credential data blob that should be provided by the credential provider. Even the input data is not documented, but Net iD Client makes some intelligent guesses.

Filter

Here you find the filter mechanisms.

Block other providers

The credential provider architecture is pluggable, and as discussed above we can replace an existing credential provider. This is possible because of the filter mechanisms. Each provider can also tell which other providers that should be loaded or ignored. The most common scenario is to replace Microsoft Smartcard credential provider and Microsoft CertCredProvider. Or to replace others when used in the Citrix environment. It is possible to configure which credential providers to replace and also which be block.

The current filter configuration will be seen in trace:

[5688:9116] 11.21.31.472 CredentialProviderFilter - Allow {5BF56AD2-E297-416E-BC49-00B327C442AE} TRUE 'Net iD Credential Provider'
…
…
[5688:9116] 11.21.31.472 CredentialProviderFilter - Allow {8FD7E19C-3BF7-489B-A72C-846AB3678C96} FALSE 'Smartcard Credential Provider'

Update remote credential

The filter part of the credential provider also includes the possibility to update a remote credential. This means that the credential provider will get "something" that looks like a credential, and can return the same or another credential.

This part is not well documented, and there is no information about what happens if several credential providers starts acting on the data.

This behavior is used for terminal server sessions, such as pre-auth with Microsoft or any connection with Citrix. There are several configuration parameters available to try to translate the "something" data to real credential data, or to completely block the functionality. This area will need further investigation, and we hope we will get more information from Microsoft and Citrix in the future.

Presentation

A credential provider is generic, meaning it will not show any information to the end-user. It will only provide an image if any, some text strings, and some input fields to the application showing the real dialog. It will tell the size of the text strings, as large or small, but never in real pixel size. The application showing the real dialog decides the real text sizes, and the size of the image. The image will be resized by the application to whatever size the application decide it should have.

Limitation text size

A credential provider can tell large or small, nothing else.

Limitation image

A credential provider can only provide a single image. The image can be resized to fit.

The limitations above are according to specification. There is also a limitation added by Windows logon application: it will not support transparent images.

Transparent images are not supported.

The most important role for our credential provider is to modify the text and image presented to the end-user. The standard credential provider does not allow any modification. Our credential provider can show information from most parts of the certificate, and also change depending on different scenarios. For example type of token, type of issuer, or calling application.

Strings

Most field configuration is shared between credential provider and normal dialogs, but input labels are handled differently, so need to be configured separately.

[Dialog Field]
Edit=<PIN>;<Current PIN>;<New PIN>;<Confirm PIN>;<PUK>;<Challenge>;<Response>;<username>;<domain>;<Username Hint>
Example 1. Using strings in string table

Each field is a string and can be placed in the string table.

[Dialog Field]
Edit={string1150};{string1151};{string1152};{string1153};{string1154};{string1155};{string1156};-;-;{string1187}

It is possible to specify four fields for each credential:

  • title

  • subtitle

  • text-above

  • text-below

The two examples below shows how they are shown:

Login dialog
Login dialog

The important part is that our credential provider only tells the text and recommend the text size. The example above have same the size for all text fields, but our credential provider recommend something different according to trace:

[10428:10880] 13.09.19.995 CredentialProvider - Field 1 'Title' (LARGE_TEXT)
[10428:10880] 13.09.19.995 CredentialProvider - Field 2 'Subtitle' (SMALL_TEXT)

The actual text strings are taken from the configuration. The configuration is a bit generic to allow sharing of configuration between normal dialog and credentials without requiring it.

The identifier for each type of credential:

cp-pin

Standard credential provider and PIN provider

cp-crt

Certificate provider

Standard credential provider may change mode to enrollment of new credential or unlocking of locked credential:

cp-enroll

Enroll of new credential

cp-unlock

Unlock of locked credential

It is also possible to have different texts when credential is loading, missing, or empty:

cp-load

Credential is loading

cp-missing

Credential is missing, for example a smart card reader without a smart card

cp-empty

Credential is empty, for example a smart card reader with an empty smart card

Example 2. A small example
[Dialog Field]
Text=cp-pin:{PIN};cp-crt:{CRT};cp-load:{LOAD}
01={PIN}:{string:2000},{string:2001},{string:2002},{string:2003},{string:1150}
02={CRT}:{string:2000},{string:2001},{string:2004},{string:2005}
03={LOAD}:{string:2014}

Each string can be customized with the built-in string expansion that is available for all strings. For more information see Variables.

Images

Each credential can have an image. And even though it is not possible to tell the size of the image, our credential provider does some guessing depending on the calling application, the usage scenario, and Windows display scaling. The image is resized if the application wants a different size than the one provided, but provide the correct size for best result. It is not easy to get the correct size because the application does not give the size needed.

Many image formats are supported, but image/ico files are recommended. This because several images with different sizes can be stored in the same file. Basically, an image/ico file is a single file containing multiple image/png files.

The image shown will be based on the credential state and/or the content of the credential. That is, you can have different images for different certificate issuers.

The matching between image and credential, that is certificate and token, is using the built-in matching available for all matching scenarios. See Match. In addition to normal matching, you can also specify loading when the credential is loading, or default to tell that this image is the default image.

[Dialog Image]
01=load.ico -loading
02=xxx.ico -match {XXX}
03=default.ico -default

As mentioned above, the image format image/ico is used to handle multiple files, but you can also specify this with the option size:

[Dialog Image]
01=load64.png -loading -size 64
02=load128.png -loading -size 128

The configuration is shared with normal dialogs, but it is possible to show a specific image by using the options credential or dialog.

[Dialog Image]
01=logo_cp.ico -default -credential
02=logo_dlg.ico -default -dialog

The image, for example logo.ico, can be stored in different places depending on platform. See section Dialog Image for more information.

Configuration

The most common customization of the credential provider is to change the presentation such as text fields and image. For other available options, see CredentialProvider.

To test the credential provider dialogs, see the cp CLI command.