Creating a Credential Type Provider (Windows Embedded CE 6.0)

1/6/2010

Credential manager type providers handle the semantics of various credential types. Windows Embedded CE has default set of credential type providers, as shown in Credential Type Providers. OEMs or IHVs can add support for additional type providers or provide custom handling for pre-defined credential types.

To create a custom type provider, you must implement the functions or entry points that are called by credential manager. A type provider can implement multiple types, and therefore all entry points will have the type identifier for the entry point that is being called.

The following functions or entry points are typically implemented in a type provider.

• Load
  This function or entry point is called once per type implemented in the type provider. This function is called by credential manager at startup and loads the various type providers. Any global state should be initialized in this function, either per provider or per type. Note that this entry point may be called multiple times if the type provider supports multiple types. Therefore care should be taken to ensure that any global state for a provider is initialized only once.
• Unload
  This function or entry point is called when credential manager is shut down and when all the type providers are being unloaded. Release any global resources per type in this function. This function may be called multiple times if the type provider supports multiple types. If Unload has been called for all loaded types, then the provider can release any global resources per provider at that point.
• MatchTarget
  This function or entry point is called when credential manager has to determine if two targets are semantically equivalent. The type provider should define the semantic rules to determine if the targets match. For example, you may choose to implement the type provider to do a case sensitive comparison instead of the default case in-sensitive comparision done by credential manager. Note that if the type provider implements multiple types then the semantic rules may be different for each type. Use the dwType parameter to identify the type for which this entry point was called.
• MatchUser
  This function or entry point is called when credential manager has to determine if two users are semantically equivalent. The type provider should define the semantic rules to determine if the users match. For example, you may choose to implement the type provider to do a case sensitive comparison instead of the default case in-sensitive comparison done by credential manager. Note that if the type provider implements multiple types then the semantic rules may be different for each type. Use the dwType parameter to identify the type for which this entry point was called.
• HandleBlob
  This function or entry point is called by credential manager to identify the information that must be cached for a given credential type. Credential manager obtains raw credential information from the user. In some cases, the type provider may choose to modify the raw data before it is cached by credential manager. For example, the type provider may choose to save a hash of the password instead of saving a plain text password obtained from the user, or the type provider may add additional information to the user credential. In some cases the type provider may choose to not cache any credential information based on policy settings.

You must always implement Load and Unload for any type provider that you implement. Credential manager has default rules for the other operations, so type providers can defer some of the other functionality to credential manager. The Flags value in the HKEY_LOCAL_MACHINE\CredMan\Types\Primitive\ID registry key can be used to specify operations for which credential manager will call the type provider. For more informaton about this registry key, see Credential Manager Registry Settings.

Defining credential types and associating them with a custom type provider

After you create a type provider DLL, the next step is to define and associate credential types with the type provider DLL. You may choose to define primitive or virtual credential types and associate them with your custom type provider. You can also modify existing primitive credential types so that they map to your custom type provider.

Depending on your requirements, you can implement one or more of the following options for associating credential types with your custom type provider.

Add a new primitive credential type

1. Define the type identifier.
   Credential types are identified by a DWORD. Primitive type identifiers have the LSB bit set to zero. User defined types should be in the range [0x00000000 – 0x0000ffff]. For example,

   #define OEM_CUSTOM_PRIMITIVE_TYPE 0x2
   

2. The information about credential types and type providers is stored in the registry. Add credential type configuration information to registry. For example,

   [HKEY_LOCAL_MACHINE\Comm\Security\CredMan\Types\Primitive\2]
               "Dll"="oem.dll"
               "Flags"=dword:0
   

   The Dll value points to the type provider DLL that implements this type. The Flags value controls the various capabilities of the type provider. For more information, see Credential Manager Registry Settings.

Add a new virtual credential type

1. Define the type identifier.
   Virtual types map to one or more primitive types. Virtual types are identified by a DWORD. Virtual type identifiers have the LSB bit set to 1. User defined types should be in the range [0x00000000 – 0x0000ffff]. For example,

   #define OEM_CUSTOM_VIRTUAL_TYPE 0x1
   

2. The information about credential types and type providers is stored in the registry. To specify the primitive types that the virtual type maps to, you must configure the registry. For example,

   [HKEY_LOCAL_MACHINE\Comm\Security\CredMan\Types\Virtual\1]
               "Ids"="2,4"
   

   In this example, virtual type 1 maps to primitive types 2 and 4.
   Virtual types do not have type provider DLLs associated directly with them. Type provider DLLs are required only for primitive types. For each virtual type operation credential manager will call the type providers for the constituent primitive types.
   For more information about registry settings, see Credential Manager Registry Settings.

Customize an existing primitive or virtual credential type

Credential manager supports pre-defined primitive and virtual credential types. The configuration information related to these supported types is stored in the registry. To customize the handling of a specific pre-defined credential type, the registry must be modified.

For example, if the default credential type CRED_TYPE_PLAINTEXT_PASSWORD has to be mapped to a custom type provider, the following changes should be made in the registry.

The following registry key syntax shows the original mapping. Note that the DLL is Credprov. This is the default credential type provider.

[HKEY_LOCAL_MACHINE\comm\security\CredMan\Types\Primitive\65542]
            "dll"="credprov.dll"
            "flags"=dword:e

The following registry key shows the modified mapping. Note that the DLL value points to a custom type provider called CustomTypeProvider.

[HKEY_LOCAL_MACHINE\comm\security\CredMan\Types\Primitive\65542]
            "dll"="CustomTypeProvider.dll"
            "flags"=dword:0

Similar customizations can be done for virtual types and their mappings.

See Also

Concepts

Credential Manager Security

Other Resources

Credential Manager OS Design Development
Credential Manager Application Development
Credential Manager