Smart Card Cryptographic Server Provider Notes

Windows NT

Security

Smart Card Cryptographic Server Provider Notes

scardcsp.doc

Windows NT Design Team—Doug Barlow

Version 1.4.2

March 17, 2000

Distribution: Microsoft Internal Distribution

Printed on 3/17/00 at 10:24 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; 3/17/2000

Contents

1 Introduction 1

2 Windows 2000 Smart Card Logon Overview 1

3 Smart Card CSP Design and Implementation 1

3.1 CryptAcquireContext 1

3.1.1 The Flags Parameter 1

3.1.2 Fully Qualified Container Names 2

3.1.3 Unidentified Key Reuse 2

3.2 CryptGenKey 3

3.3 CryptExportKey 3

3.4 CryptGetProvParam 3

3.5 CryptSetProvParam 3

3.6 CryptGetKeyParam 4

3.7 CryptSetKeyParam 4

4 Error Codes 4

5 Frequently Asked Questions 4

Windows NT Smart Card Cryptographic Server Provider Notes Draft: Version 1.4; 3/17/2000

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, Windows2000 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. (See http://www.pcscworkgroup.com.)

· 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.

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)

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.

The following parameter values of the CryptGetProvParam service look really interesting, and bear further investigation. It has not yet been decided what the action should be on these values.

PP_IMPTYPE

PP_CERTCHAIN

PP_KEY_TYPE_SUBTYPE

PP_PROVTYPE

PP_KEYSTORAGE

PP_APPLI_CERT

PP_ENUMMANDROOTS

PP_ENUMELECTROOTS

PP_KEYSET_TYPE

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.

The following parameter values of the CryptSetProvParam service look really interesting, and bear further investigation. It has not yet been decided what the action should be on these values.

PP_CHANGE_PASSWORD

PP_CERTCHAIN

PP_APPLI_CERT

PP_UI_PROMPT

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.

5 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.