This is an old revision of the document!


Smart cards info

PKCS#11/PKCS#15 with JavaCard on Windows

  • Download Muscle applet via svn co svn:svn.debian.org/muscleplugins/trunk/MCardApplet or local copy of preconfigured NetBeans applet
  • Compile, Convert and upload applet to smart card - see HOWTO
  • IMPORTANT: Muscle applet needs to be installed with privilege 'default selected' (CARD_RESET in later specifications). OpenSC tools are NOT selecting Muscle applet, therefore preselected applet is necessity.
    • e.g. in GPShell, install -file cardedge.cap -nvDataLimit 2000 -instParam 00 -priv 4 (-priv 4 makes applet default selected)
  • Initialize applet with opensc-tool (two APDUs are send, first one select Muscle applet, second one initialize default pins, puks, etc)
opensc-tool -s 00:A4:04:00:06:A0:00:00:00:01:01 -s B0:2A:00:00:38:08:4D:75:73:63:6C:65:30:30:04:01:08:30:30:30:30:30:30:30:30:08:30:30:30:30:30:30:30:30:05:02:08:30:30:30:30:30:30:30:30:08:30:30:30:30:30:30:30:30:00:00:17:70:00:02:01
  • 08:4D:75:73:63:6C:65:30:30:04:01:(8 bytes, Muscle00)
  • 08:30:30:30:30:30:30:30:30: (8 bytes, )
  • 08:30:30:30:30:30:30:30:30:05:02: (pin_tries = 5, ublk_tries = 2)
  • 08:30:30:30:30:30:30:30:30:08:30:30:30:30:30:30:30:30:00:00:17:70:00:02:01
  • Try to obtain card ATR: opensc-tool -a (should always work, even with unsupported cards)
    • should return ATR, for example: 3b:7d:95:00:00:80:31:80:65:b0:83:11:d0:a9:83:00:90:00
  • Try to obtain applet name: opensc-tool -n
    • Should return “MuscleApplet”
    • if you get “unsupported card” response, force card driver 'muscle' for all subsequent commands: opensc-tool -c muscle -a
    • specific driver can be permanently forced via opensc.conf file. Uncomment and set value 'force_card_driver = muscle'. Some tools like pkcs11-tool cannot force the driver on command line and therefore it is necessary (and more convenient) to force driver in opensc.conf.
    • FIXME: Muscle java card profile can be created (see opensc.conf for details)
    • all supported card drivers (“card driver” is wrapper that converts card (possibly) proprietary interface into opensc interface) can be listed by: opensc-tool -D
  • Note: initialized applet is assumed (see previous section)
  • Note: forced card driver is assumed (see previous section)
  • List slots via: pkcs11-tool –module opensc-pkcs11.dll -L
    • FIXME: will stop responding, no debug info dispalyed even in -vvvvv mode
  • Note: initialized applet is assumed (see previous section)
  • Note: forced card driver is assumed (see previous section)
  • Clear your card: pkcs15-init -E
    • Unspecified PIN [reference 1] required. Type “00000000”
    • Possible error: Please enter Unspecified PIN [reference 1]: Failed to erase card: Unsupported CLA byte in APDU
      • Reason: applet is not default selected. Install with privilege -priv 4
  • Create PKCS#15 objects: pkcs15-init -C
    • Possible error: Please enter User PIN [User PIN]: Failed to create PKCS #15 meta structure: File not found
      • Reason: applet responds with SW_SEQUENCE_END (9C 12) error status - no more data objects available. However, pkcs15-init expects at least one object present.
  • adding -vvvvvv to any command will enable verbose debug info
  • Opensc tools use PC/SC subsystem via winscard.dll library. However, the winscard.dll library is loaded directly from Windows\System32 folder, not from actual folder where opensc tool is run from. To enable APDU interception, it is necessary to:
    • uncomment line 'provider_library = winscard2.dll' in opensc.conf in reader_driver pcsc {} section

Other useful info:

Generate self-signed X.509 certificates with OpenSSL

  • openssl genrsa -out my.key 2048
    • (unable to write 'random state' may appear - not important)
    • my.key file will be created in current directory
  • openssl req -new -x509 -days 365 -key my.key -out my.crt -sha512
    • fill in certificate parameters
    • you may prefill required info into file and 'openssl req -new -x509 -days 365 -key my.key -out my.crt -sha512 < certificate_info.txt'
  • openssl pkcs12 -export -out my.p12 -in my.crt -inkey my.key
    • export your private and public key into single my.p12 file
    • import later on target machine into certificate store
  • Tools→Options→Advanced→View certificates and tab Authorities
    • Button Import, select certificate in *.crt file (e.g., my.crt from OpenSSL generation)
  • For other people certificates:
    • Switch to 'People' tab, button Import, select target person certificate in *.crt, *.der or *.ber file
  • For your certificate:
    • Switch to 'Your certificates' tab, button Import, select your certificate in *.p12 file (e.g., my.p12 from OpenSSL generation)
    • Go to Tools→Account settings - select mail account
    • Go to Security settings - button Select… and select certificate imported previously
    • Do the same for encrypt&decrypt messages certificate

Truebleshooting

  • Remove and import again when your certificate is not recognized as trusted by Thunderbird (even when same certificate is imported in 'Authority' tab)
  • If message send fail when message encryption is enabled, key for receiver may not be trusted (check View on corresponding certificate). Certificate imported in Authority tab may be missing
  • (NOTE: certificate imported by previous steps is assumed)
  • Delete… your certificate from 'Your certificates' or 'People'
  • Find same certificate in Authorities and delete it as well
  • (If you try to import your certificate into authorities again then it should NOT cause 'This certificate is already installed as a certificate authority.' message
  • Internet Explorer→Internet Options→Content→Certificates
    • Button 'Import', Browser, change file filter to 'All files (*.😉', import file *.p12 (e.g., my.p12)
  • File→Options→Trust Center→Trust Center Settings→Email Security
  • Group Encrypted email→Settings→

PKCS#11 token in Windows Vista/7 and higher

  • Download Smart card minidriver specification: http://msdn.microsoft.com/en-us/windows/hardware/gg487500.aspx
  • Download Cryptographic Next Generation (CNG) SDK (US Export registration required): http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=1251
  • Create new MFC dll project (e.g., SCMD.dll)
  • Copy content of cardmod.h file from CNG SDK into SCMD.cpp
  • Create empty function body returning “UNSUPPORTED” value (-1) for every function prototype from cardmod.h
    • function prototypes looks like DWORD WINAPI function_name(function_arguments;)
    • add AFX_MANAGE_STATE(AfxGetStaticModuleState()); is used to protect MFC state of exported function
    • you may use Regular expression tool to speed up manual replacement a bit
Regular expression to match:
DWORD
WINAPI
([a-zA-Z0-9_]*?)\(
([. _a-zA-Z0-9*,()].*?)\);

Regular expression to replace:
DWORD
WINAPI
\1(
\2) {
  AFX_MANAGE_STATE(AfxGetStaticModuleState());
  return -1;
}  
  • Remove all structures/enums/constants definitions found in cardmod.h from SCMD.cpp (it will stay in cardmod.h)
  • Build the project to produce DLL
  • Create INF file containing minidriver description (see Smart card minidriver specification for example)