Windows NT
Security
Smart Card Cryptographic Server Provider Notes
scardcsp.doc
Windows NT Design Team—Doug Barlow
Version 1.4.2
February 17, 2016
Distribution: Microsoft Internal Distribution
© Copyright Microsoft Corporation, 1998 - 2000. All Rights Reserved
Printed on 2/17/16 at 10:42 AM
Note: This documentation is an early release of the final product documentation.
It is meant to accompany software that is still in development. Some of the
information in this documentation may be inaccurate or may not be an accurate
representation of the functionality of the final retail product. Microsoft assumes no
responsibility for any damages that might occur either directly or indirectly from
these inaccuracies.
Windows NT
Smart Card Cryptographic Server Provider Notes
Draft: Version 1.4.2; 2/17/2016
Contents
1
2
3
3.1
3.1.1
3.1.2
3.1.3
3.2
3.3
3.4
3.5
3.6
3.7
4
5
Introduction ................................................................................................................................. 1
Windows 2000 Smart Card Logon Overview ............................................................................. 1
Smart Card CSP Design and Implementation ............................................................................. 1
CryptAcquireContext .................................................................................................................. 1
The Flags Parameter .................................................................................................................... 1
Fully Qualified Container Names ................................................................................................ 2
Unidentified Key Reuse .............................................................................................................. 2
CryptGenKey .............................................................................................................................. 3
CryptExportKey .......................................................................................................................... 3
CryptGetProvParam .................................................................................................................... 3
CryptSetProvParam ..................................................................................................................... 3
CryptGetKeyParam ..................................................................................................................... 4
CryptSetKeyParam ...................................................................................................................... 4
Error Codes ................................................................................................................................. 4
Frequently Asked Questions ....................................................................................................... 5
 Microsoft Corporation, 1998 - 2000. All Rights Reserved. Contents - i
Windows NT
Smart Card Cryptographic Server Provider Notes
Draft: Version 1.4.2; 2/17/2016
Smart Card Cryptographic Server Provider Notes
This document provides notes on the implementation of a Smart Card Cryptographic Service Provider.
1
Introduction
Windows 2000 provides the capability to use a smart card to log on. This document provides an introductory
tutorial on how a vendor would go about making their smart card work with Windows 2000.
2
Windows 2000 Smart Card Logon Overview
Windows 2000 provides support for Kerberos Authentication within a Domain. To log on with a smart card,
Windows 2000 uses the public key extension to Kerberos to obtain a session key for use by the user to be logged on.
Therefore, to log onto Windows 2000 with a smart card, the following requirements must be met:

The smart card must support RSA key exchange and signature operations. Currently RSA is the only
algorithm defined for use by the Public Key Extension to Kerberos. Other algorithms may be added in the
future.

The smart card must store the RSA key, and a certificate for the key.

The smart card must be capable of working with the Microsoft PC/SC implementation.
http://www.pcscworkgroup.com.)
(See

There must be a Cryptographic Service Provider (CSP) to map between the Microsoft Cryptographic API
and the specific functions of the card.
Documentation on writing a CSP is provided through MSDN. This document expands on that information with
specifics necessary to tie the smart card CSP in with the Windows 2000 logon program.
3
Smart Card CSP Design and Implementation
A Smart Card CSP must conform to the specifications of the Microsoft CryptoAPI Service Provider. There are a
few special cases of how a Smart Card CSP should deal with the standard Microsoft CryptoAPI Service Provider
interfaces that need explicit documentation. These are noted below.
3.1 CryptAcquireContext
Several special actions must be taken by a Smart Card CSP during context acquisition. They are documented here.
3.1.1 The Flags Parameter
A Smart Card CSP must support all defined flags for CryptAcquireContext. Of special note are the following:
CRYPT_SILENT – This flag is taken literally, so that absolutely no UI will be placed in front of
the user when this flag is in effect. If UI is necessary to continue an operation, the operation
fails.
CRYPT_MACHINE_KEYSET – This flag is taken to mean that no cached information should be
used, that all information must come from the card itself. This provides the same
functionality as the typical meaning of the flag, but makes it more meaningful in the context
of removable hardware tokens.
 Microsoft Corporation, 1998 - 2000. All Rights Reserved.
1
Windows NT
Smart Card Cryptographic Server Provider Notes
Draft: Version 1.4.2; 2/17/2016
CRYPT_VERIFYCONTEXT – This flag has a dual meaning, depending on the name of the
container to be accessed. If the container name is NULL or blank, this flag implies that no
access to any keys is required, and that no UI should be presented to the user. This form is
used to connect to the CSP to query it’s capabilities, but not to actually use its keys.
If the container name is non-NULL and non-blank, then this flag implies that access to only
the publicly available information within the specified container is required. The CSP should
not ask for a PIN. Attempts to access private information (for example, a CryptSignHash
command) should be rejected with an appropriate error code.
3.1.2 Fully Qualified Container Names
In some instances, the calling application is already aware of which smart card it wishes to talk to, based on the
reader it is in. A Smart Card CSP will recognize Fully Qualified Container Names, whereby the specific reader
containing the smart card can be specified in addition to the container name. A Fully Qualified Container Name has
the following format:
\\.\<readerName>[\[<containerName>]]
Where <readerName> represents the Friendly Name of the smart card reader, and <containerName>
represents the name of the desired container. If the container name is not specified, or has zero length, the default
container for the card is implied. This also implies that backslashes are not allowed in reader names or container
names.
Examples of container names supported by a Smart Card CSP are:
Blank or NULL – Use the default container from the a card supporting cryptographic services
chosen by the user through the common smart card dialog. If the CRYPT_SILENT flag is in
effect, and there is more than one default container available (e.g., more than one card), then
the call should fail.
“MyLogin” – Search for a card supporting cryptographic services with a container name of
“MyLogin”. If a certificate for this container is cached, then the card search will be restricted
to cards with the same ATR as the card from which the certificate was contained. If such a
card is found immediately, no UI is displayed. If no such card is available, or if multiple
cards are available, and the CRYPT_SILENT flag is not in effect, then the common smart
card dialog is displayed.
“\\.\My USB Reader 0” or “\\.\My USB Reader 0\” – Use the default container from the card in the
reader with the friendly name of “My USB Reader 0”. If no card is there, or if it does not
support cryptographic services, or if it does not have a default container, an error is returned.
No UI is displayed.
“\\.\My USB Reader 0 \MyLogin” – Use the container named, “MyLogin” from the card in the
reader with the friendly name of “My USB Reader 0”. If no card is there, or if it does not
support cryptographic services, or if it does not have a container named, “MyLogin”, an error
is returned. No UI is displayed.
If a Smart Card CSP is asked to return the container name via the CryptGetProvParam service, either through the
PP_CONTAINER or PP_ENUMCONTAINERS parameter identifiers, only the container name will be returned, not
the Fully Qualified Container Name.
3.1.3 Unidentified Key Reuse
The current implementation of the certificate generation utility attempts to minimize user interaction in order to limit
UI questions that are incomprehensible to the average user. To make this work, it is necessary for CSPs which don’t
have full and immediate access to their entire collection of containers to enter into a bit of negotiation with this
utility. This section details the exact behavior expected of smart card CSPs.
When activated with CryptAcquireContext(pszContainer = <GUID>, dwFlags = CRYPT_NEWKEYSET), the
smart card CSP should do the following:
1) Allow the user to select any card supported by this CSP, whether or not a container exists on the card.
2) If the user selects a card with no existing container, proceed to create the container. (Go to step 5)
 Microsoft Corporation, 1998 - 2000. All Rights Reserved.
2
Windows NT
Smart Card Cryptographic Server Provider Notes
Draft: Version 1.4.2; 2/17/2016
3) At this point, the user has selected a card which already has an existing container. If your CSP supports
multiple containers on a card and there is room for a new container, proceed to create the container. (Go to step
5)
4) At this point, the user has selected a card which does not have room for an additional container. Return an error
condition with the specific error code NTE_TOKEN_KEYSET_STORAGE_FULL.
5) Done
The certificate generation utility will recognize this error code, and respond with CryptAcquireContext(pszContainer
= NULL, dwFlags = 0) to allow the user to reselect a card for reuse.
For this to operate smoothly, if the CSP utilizes the Smart Card Common Selection Dialog, it should be called with
the SC_DLG_MINIMAL_UI flag.
ISSUE:
If there is more than one card that matches, then the Smart Card Selection Dialog will appear twice. How
do we avoid making the user select the card twice?
3.2 CryptGenKey
The following flag values of the CryptGenKey service are of special note:
CRYPT_EXPORTABLE – Since this flag exists to allow portability of the private key, and by
definition, keys created within smart cards are portable, this flag is simply ignored. Note that
requests to export the private key out of the smart card will be rejected.
3.3 CryptExportKey
A blob type of PRIVATEKEYBLOB is not supported.
3.4 CryptGetProvParam
The following parameter values of the CryptGetProvParam service are of special note:
PP_ENUMCONTAINERS only returns container names, not Fully Qualified Container Names.
PP_CONTAINER only returns the container name, not the Fully Qualified Container Name.
PP_UNIQUE_CONTAINER is synonymous to PP_CONTAINER for smart cards. Just return the
current container name.
3.5 CryptSetProvParam
The following parameter values of the CryptSetProvParam are of special note:
PP_ADMIN_PIN – This allows the administrator PIN of the card to be preset by the application,
to avoid having UI requesting the PIN being displayed. If the supplied value is NULL, then
any cached administrator PIN for this container should be forgotten.
PP_KEYEXCHANGE_PIN – This allows the access PIN for the Key Exchange Key of the
container to be preset by the application, to avoid having UI requesting the PIN being
displayed. If the supplied value is NULL, then any cached key exchange PIN for this
container should be forgotten.
PP_SIGNATURE_PIN – This allows the access PIN for the Signature Key of the container to be
preset by the application, to avoid having UI requesting the PIN being displayed. If the
supplied value is NULL, then any cached signature PIN for this container should be forgotten.
In all cases, all PINs cached for the card should be forgotten if the card is removed.
 Microsoft Corporation, 1998 - 2000. All Rights Reserved.
3
Windows NT
Smart Card Cryptographic Server Provider Notes
Draft: Version 1.4.2; 2/17/2016
3.6 CryptGetKeyParam
The following parameter values of the CryptGetKeyParam service are of special note:
KP_CERTIFICATE returns the certificate associated with the key.
3.7 CryptSetKeyParam
The following parameter values of the CryptSetProvParam are of special note:
KP_CERTIFICATE sets the certificate associated with the key. The public key of the certificate
must match the public key of the key. Any error return should use the SCARD_* error
facility codes to ensure that XEnroll.dll properly reports errors to the user.
KP_ADMIN_PIN – This allows the administrator PIN of the card to be preset by the application,
to avoid having UI requesting the PIN being displayed. If the supplied value is NULL, then
any cached PIN for this key should be forgotten.
KP_KEYEXCHANGE_PIN – This allows the access PIN for this key to be preset by the
application, to avoid having UI requesting the PIN being displayed. If the supplied value is
NULL, then any cached PIN for this key should be forgotten. The referenced key must be the
Key Exchange Key.
KP_SIGNATURE_PIN – This allows the access PIN for this key to be preset by the application,
to avoid having UI requesting the PIN being displayed. If the supplied value is NULL, then
any cached PIN for this key should be forgotten. The referenced key must be the Signature
Key.
4
Error Codes
In order to standardize operation across all Smart Card CSPs, the following error codes should be returned to
represent the specified conditions. This does not attempt to be a complete list of error conditions.
Error Code
Condition
SCARD_W_CANCELLED_BY_USER
The user pressed ‘Cancel’ on a Smart Card Selection Dialog.
(GetOpenCardName returned SCARD_E_CANCELED.)
SCARD_W_CANCELLED_BY_USER
The user pressed ‘Cancel’ on a Smart Card PIN prompt Dialog.
SCARD_E_NO_SUCH_CERTIFICATE
A Certificate for the key has not been written to the card.
SCARD_E_CERTIFICATE_UNAVAILABLE
The Certificate for the key could not be read from the card.
CARD_E_INVALID_CHV
The supplied PIN is not in the proper format for the card. For
example, it is the wrong length, or contains invalid characters.
SCARD_W_WRONG_CHV
PIN validation failed. Either the user entered an incorrect PIN,
or the PIN supplied through a SetProvParam was incorrect.
SCARD_W_CHV_BLOCKED
PIN validation has been blocked by the card due to excessive
invalid PIN entries.
NTE_TOKEN_KEYSET_STORAGE_FULL
No room exists on the smart card for additional containers. This
should not be used for anything except containers.
 Microsoft Corporation, 1998 - 2000. All Rights Reserved.
4
Windows NT
5
Smart Card Cryptographic Server Provider Notes
Draft: Version 1.4.2; 2/17/2016
Frequently Asked Questions
My card doesn’t support RSA. Can I still make it log on?
Yes, there are several options, although they all result in much weaker security. You could use the card to store an
RSA key as a file, and have your CSP actually do the RSA operations on the PC. Alternatively, you could store the
user’s password on the card, and write your own GINA replacement to pull the password from the card instead of
prompting the user.
Do I have to write all that crypto stuff?
Your CSP may call the Microsoft CryptoAPI to perform cryptographic operations not specific to your card; simply
use one of the Microsoft supplied providers, instead of your own, to be sure you don’t just recurse. Then the
specific operations done by your smart card may be intercepted by your CSP, and everything else handled by the
existing providers.
 Microsoft Corporation, 1998 - 2000. All Rights Reserved.
5