Tuesday, November 10, 2015

Linux and O2 Micro, Inc. OZ711EC1 SmartCard, DoD CAC Support

Preface:  This is a long post, but I wanted to give a lot of detail.  

I used LMDE 1, 32bit, non-pae kernel 3.11.

I upgraded LMDE from 1 to 2; however, I was never able to get the pcsc_scan to recognize the scanner (amid other issues that combined led to just surrendering), so I reinstalled LMDE 1.  I may have other things going on with my system (it is over 10-years old), so give the instructions a try!

I hope you find it useful.  Leave me comments accordingly...  

POST:
Wow, this has been an adventure.  I have tried on multiple occasions to get the smartcard reader working; however, I have given up many times before.  Periodically, I will try it again because I hope that new Linux kernels include the appropriate drivers or others have prepared to required drivers.  Well, I almost waited too long, as since around 2012, Linux has changed pcmcia software which has impacted some drivers.  I am writing this in November 2015 for time reference.

I am currently using Linux Mint Debian Edition 1 (32-bit) on version 8 update package.  Kernel 3.11.  I ended up having to use this version because the this computer is old enough that all the newer distros have pae compiled in by default which doesn't work on this computer.  The LMDE version didn't and works wonderfully.  I recommend if you have older hardware such as I am using (Acer C300 Travelmate Tablet).

Ok, now on to the meat of the post.  What I had to do to get the built in O2 Micro, Inc. OZ711EC1 SmartCardBus Controller to work properly.  I hope this helps anyone still struggling and saves them the difficulty of many hours (for me about 24-hours) of googling and reading posts to find a solution.  See the bottom of this post for additional links that lead me to the right answers.

1.  Install from repository the following CAC/SmartCard packages (copy / paste into terminal)

sudo apt-get install pcscd libpcsclite-dev libpcsclite1 pcsc-tools coolkey pcmciautils

2.  Install the following to compile the drivers for the card reader (copy/paste into terminal)

sudo apt-get install build-essential

3.  Install the linux kernel headers for your distro.  I'm unsure of a command line for this, so go to your package manager (I use synaptic) and navigate to:

linux-headers-
[Note:  This should match the linux-image-]

4.  Confirm Hardware:  Restart your computer.  After a reboot and logging in we want to check a few things and also convey what you should see.  I referenced this page; however, the driver's he references no longer work:  http://ubuntuforums.org/showthread.php?t=1505742


4A.  Ensure hardware is the Same as this post.  The information here should be may not work if you have different hardware.  From command prompt/terminal (CLI) run:

lspci

You should see this in the list:
02:01.0 CardBus bridge: O2 Micro, Inc. OZ711EC1 SmartCardBus Controller (rev 20)
02:01.1 CardBus bridge: O2 Micro, Inc. OZ711EC1 SmartCardBus Controller (rev 20)


4B.  Check to see that 'pcscd' is running.  From  CLI run:
sudo service pcscd status

You should see this if all is ok:
[ ok ] pcscd is running.

IF: you are running "sysvint" instead of "systemd", recommend you follow the directions at the link for troubleshooting below now.  If you choose not to follow it now, and you later find that the pcmcia card driver is bound to the device and pcscd is running BUT pcsc_scan doesn't detect the card reader, then remember to come back to this section.

Troubleshooting:
- If it isn't running OR it is running and not recognizing your device, I recommend you follow the procedures at the following page:
- http://ludovicrousseau.blogspot.kr/2010/12/configuring-your-system-for-pcscd-auto.html

- If it is not starting automatically and you are running a systemd system, the the instructions at this link may be helpful:
- http://ludovicrousseau.blogspot.fr/2011/11/pcscd-auto-start-using-systemd.html

- This link may also provide some assistance about auto start for pcscd and the UDEV file (see 5D below):
- http://ludovicrousseau.blogspot.kr/2010/09/pcscd-auto-start.html

4C.  Check to see if 'PCMCIA' recognizes hardware.  From CLI run:
pccardctl info

Note, on my system, I had to run the following:
/sbin/pccardctl info

You should see this if all is ok:
PRODID_1=""
PRODID_2=""
PRODID_3=""
PRODID_4=""
MANFID=0000,0000
FUNCID=255
PRODID_1="O2Micro"
PRODID_2="SmartCardBus Reader"
PRODID_3="V1.0"
PRODID_4=""
MANFID=ffff,0001
FUNCID=255
  


Troubleshooting: I am unsure how to trouble shoot this...  mine was just working.

4D.  Check to see if a driver is attached to hardware:  You can also check from CLI:
/sbin/pccardctl status

You will likely see (Bolded part means no driver for device in socket 1):
Socket 0:
no card
Socket 1:
5.0V 

16-bit 
PC Card
Subdevice 0 (function 0) [unbound]


If the last line looks like the following, you can skip step 5 - building drivers. Bolded part indicates the card reader is bound to a driver.
Subdevice 0 (function 0) bound to driver "ozscrlx_cs"

Troubleshooting:  If both socket 0 and socket 1 have no card, then you can try mounting the card/device with the following command:
examplesudo /sbin/pccardctl insert
sudo /sbin/pccardctl insert 1

Note:  The following command will disable (eject) the device from the bus:
sudo /sbin/pccardctl eject 1


4E.  Continuing after verifying hardware:  Now that we have verified the hardware is present and recognized by the system, we will transition to the 5th step to get and compile the driver.  If you haven't been able to confirm the hardware, the driver will no do you any good until you get the hardware resolved.

5.   Building and Installing the Drivers:  This is based upon my recollection of what I did to build and install the drivers.

5A.  Get the source files:  Download the latest driver from the following link.  Extract the files.

Version I utilized:
http://download.gna.org/o2scr/o2scr-1.0.8.tar.bz2

All versions:
http://download.gna.org/o2scr/

5B.  Build and Install:  Navigate to the extracted folder.  Commands that follow assume you are at a command line / terminal in the directory where you extracted the contents of the tar.bz2 file.

cd o2scr
sudo make install
Note:  The previous command should have made and installed the driver (o2scr.ko), but it fails to do this.  You need to manually enter the directory for the driver and build from there.

cd src/ozscrlx/make
sudo make install

Hopefully these all went smoothly and without error.  If so, lets do some verification.

Troubleshooting:  If there was a problem with compiling the drivers, then you will need to trouble shoot the issue.  One possible solution if you are certain you have the linux headers and build essentials installed could be copying the header files from pcsd-lite to /usr/lib/PCSD.  I did this when I was trying the other driver out (broken driver) and did not remove them when I found the driver from gna.org.

5C.  Check installation:

* Check to see that files were installed in the correct locations and that the source build actually completed without error.  First, the device driver.


sudo updatedb
sudo locate o2scr.ko

> You should see location similar to following which shows it was installed to the kernel modules section  (NOTE:  the bolded portion will likely be different based on your kernel):
/lib/modules/3.11-2-486/extra/o2scr.ko

* Check the static linked object file was compiled.

sudo locate lib_OZSCR.so

> You should see the following which shows it was installed to the kernel modules section:
/usr/local/o2micro/lib_OZSCR.so

>> If you don't find the .so file located as stated above, recompile and install from the source:
cd o2scr/src/ozctapi
make
sudo make install

* IMPORTANT:  Once confirmed modules are installed we need to make the kernel aware of it.  Use the following command:

sudo depmod -a
* Check to ensure the reader configuration file for the card reader was installed:

cat /etc/reader.conf.d/o2scr.conf
> output:
# Configuration file for pcsc-lite
#
# This file has to be configured for serial and PCMCIA readers only.
# normal USB readers shall _not_ be configured here!
#
# David Corcoran

FRIENDLYNAME            "O2Micro SmartCardBus Reader"
DEVICENAME              /dev/o2scr0
LIBPATH                 /usr/local/o2micro/lib_OZSCR.so
CHANNELID               0xF10000


# End of file


Troubleshooting:  If the cat didn't produce the output from above, then create the file and paste the output from above into the file with the following commands from CLI:

sudo touch /etc/reader.conf.d/o2scr.conf
sudo gedit /etc/reader.conf.d/o2scr.conf

* Paste the following into the o2scr.conf, save, and close:
# Configuration file for pcsc-lite
#
# This file has to be configured for serial and PCMCIA readers only.
# normal USB readers shall _not_ be configured here!
#
# David Corcoran

FRIENDLYNAME            "O2Micro SmartCardBus Reader"
DEVICENAME              /dev/o2scr0
LIBPATH                 /usr/local/o2micro/lib_OZSCR.so
CHANNELID               0xF10000

# End of file


5D.  Create UDEV rule.  I believe this is required.  From CLI:

sudo touch /etc/udev/rules.d/99-pcscd.rules
sudo gedit /etc/udev/rules.d/99-pcscd.rules

* Paste the following into the 99-pcscd.rules, save, and close (Note: if you are running pcscd as root for group instead of 'group', you may need to change the "GROUP="pcscd" to "root"):

ACTION!="add", GOTO="pcscd_rules_end"
KERNEL=="o2scr0", SUBSYSTEM=="ozscrlx", GROUP="pcscd"
LABEL="pcscd_rules_end"

# End of File

6.  Reboot and Check for Hardware/Driver Recognition:

6A.  Reboot! :)

6B.  Repeat steps above in step 4:

* 4B:  verify that pcscd is still running.

Troubleshooting:  If it is not running.  You can try stopping the daemon and running from the CLI with the following commands.  You may want to leave it open and running as we do other steps in a separate window.

sudo service pcscd stop
sudo /usr/sbin/pcscd --foreground --debug

*4D.  Check to see if a driver is attached to hardware:  You can also check from CLI:
/sbin/pccardctl status

You should see (Bolded part) that the driver is attached to the hardware (bound):
Socket 0:
no card
Socket 1:
5.0V 

16-bit 
PC Card
Subdevice 0 (function 0) bound to driver "ozscrlx_cs"


Troubleshooting:  If not bound, you should try ejecting and inserting the card.

* Eject Card
sudo /sbin/pccardctl eject 1
sudo /sbin/pccardctl status
* Validate Ejected

* Insert Card 
sudo /sbin/pccardctl insert 1
sudo /sbin/pccardctl status 
 * Validate inserted and hopefully, that it is now bound.

* If not bound at this point, I'm unsure what further to troubleshoot besides restarting and validating the steps to this point.  Could be an issue with the compilation, but our previous steps should have identified this issue alread.  Resort to google.  Good luck. :(

6C.  If bound, lets ensure a device was created.  Make note of the ownership and group.  root root may be ok as long as it is created. Note, my example shows a group of pcscd, which i did by following steps to ensure the pcscd daemon ran at startup (my issue was the driver (.ko file) was not compiled or installed and without that file AND with the reader.conf file created, pcscd will not start.  If issues persist after all instructions, come back here and follow this link referenced:  http://ludovicrousseau.blogspot.kr/2010/12/configuring-your-system-for-pcscd-auto.html

* from CLI:
ls -l /dev/o2scr0

* Expected output:
crw------- 1 root root 248, 0 Nov 15 20:39 /dev/o2scr0 

OR you may see the following if you have taken the course of creating a group for pcscd. 

crw-rw---- 1 root pcscd 248, 0 Nov 10 20:25 o2scr0

6D.  Check that smartcard and reader is recognized.  From CLI, run the following command.  It should indicated the reader is found and show when a card is inserted and removed.

pcsc_scan

You should see similar output:

* Started (without card inserted):
 PC/SC device scanner
V 1.4.21 (c) 2001-2011, Ludovic Rousseau
Compiled with PC/SC lite version: 1.8.7
Using reader plug'n play mechanism
Scanning present readers...
0: O2Micro SmartCardBus Reader 00 00

Tue Nov 10 22:55:06 2015
Reader 0: O2Micro SmartCardBus Reader 00 00
  Card state: Card removed,


* Card Inserted:
 Tue Nov 10 22:56:29 2015
Reader 0: O2Micro SmartCardBus Reader 00 00
  Card state: Card inserted, Shared Mode,
  ATR: 3B DB 96 00 80 1F 03 00 31 C0 64 B0 F3 10 00 07 90 00 80

ATR: 3B DB 96 00 80 1F 03 00 31 C0 64 B0 F3 10 00 07 90 00 80
+ TS = 3B --> Direct Convention
+ T0 = DB, Y(1): 1101, K: 11 (historical bytes)
  TA(1) = 96 --> Fi=512, Di=32, 16 cycles/ETU
    250000 bits/s at 4 MHz, fMax for Fi = 5 MHz => 312500 bits/s
  TC(1) = 00 --> Extra guard time: 0
  TD(1) = 80 --> Y(i+1) = 1000, Protocol T = 0
-----
  TD(2) = 1F --> Y(i+1) = 0001, Protocol T = 15 - Global interface bytes following
-----
  TA(3) = 03 --> Clock stop: not supported - Class accepted by the card: (3G) A 5V B 3V
+ Historical bytes: 00 31 C0 64 B0 F3 10 00 07 90 00
  Category indicator byte: 00 (compact TLV data object)
    Tag: 3, len: 1 (card service data byte)
      Card service data byte: C0
        - Application selection: by full DF name
        - Application selection: by partial DF name
        - EF.DIR and EF.ATR access services: by GET RECORD(s) command
        - Card with MF
    Tag: 6, len: 4 (pre-issuing data)
      Data: B0 F3 10 00
    Mandatory status indicator (3 last bytes)
      LCS (life card cycle): 07 (Operational state (activated))
      SW: 9000 (Normal processing.)
+ TCK = 80 (correct checksum)

Possibly identified card (using /usr/share/pcsc/smartcard_list.txt):
3B DB 96 00 80 1F 03 00 31 C0 64 B0 F3 10 00 07 90 00 80
    DoD CAC, Oberthur ID One 128 v5.5 Dual


* Card Removed:
 Tue Nov 10 22:57:53 2015
Reader 0: O2Micro SmartCardBus Reader 00 00
  Card state: Card removed,


I hope at this point you have seen the above feedback.  If you have... success so far and skip down to configuring firefox for use with your cac card.
(Note: Using exactly the same instructions, I was unable to get the pcsc_scan to see my reader despite the driver being bound to the card reader and pcscd running.... I dropped back to LMDE 1)

Troubleshooting:  At this step, you should see all of the above, but if you don't, then you have a problem.

* First try rebooting.

* Second if you find that the pcmcia card driver is bound to the device and pcscd is running but pcsc_scan doesn't detect the card reader, then try the trouble shooting is 4B (above).  It may be a problem with groups for the device driver (pcscd should be in group pcscd as well as several other locations).

* Finally you may also, try adding the following to the GRUB boot arguments before the 'quiet' argument (press e from grub menu):

pci=assign-busses,routeirq
or
pci=assign-busses

I tried these when my card was not immediately recognized.  My driver started working properly during a time I had booted with the first option added.  HOWEVER, from not re-adding it, I was able to reboot and still have my reader working properly without the additional argument.

7.  Configuring Firefox to work with a CAC Reader.

7A.  Configure:  This link provides instructions for getting and installing DOD Root Certificates and configuring firefox to use the CAC Card cardreader hardware. If you are not a DOD user and using another service, then install what you need for your required certificates.

Note that you will need to browse to the location for the PKCI device at the following location: /usr/lib/pkcs11/libcoolkeypk11.so.  What is depicted in the instructions is a different location than it was on my system.  If you don't find it at the location specified, run the following command:
sudo locate libcoolkeypk11.so

Link to instructions:
http://iase.disa.mil/pki-pke/getting_started/Pages/linux-firefox.aspx


7B.  Test.  Test your CAC configuration.  You may need to restart firefox for good measure before testing.  Also, if you are overseas, you may need to use a VPN to establish a secure connection due to certain IP addresses being blocked.  I successfully tested with AKO and my enterprise web mail.

If you are in need of a good VPN, then please consider getting it from TorGuard and using my affiliate referral link for good measure:  https://torguard.net/aff.php?aff=582


7C.  Congratulations.  You should be all set now.  I hope you found this guide useful and with enough detail to be successful in a fraction of the time it took me to research it.  Leave me some comments below... thanks... corrections... and issues.

8.  Key Reference Links (with a lot of useless links omitted):

Base thread of information that got me going this time:
> http://ubuntuforums.org/showthread.php?t=1505742

Another page with troubleshooting information and links:
> https://bugs.launchpad.net/ubuntu/+source/pcsc-lite/+bug/1061947

One of the PCSCD authors pages talking about configuration:
> http://ludovicrousseau.blogspot.fr/2011/11/pcscd-auto-start-using-systemd.html
> http://ludovicrousseau.blogspot.kr/2010/12/configuring-your-system-for-pcscd-auto.html

Launchpad Error Discussion for o2micro card:
> https://bugs.launchpad.net/ubuntu/+source/pcsc-lite/+bug/74724

DRIVER source code:
> http://download.gna.org/o2scr/

9.  Edit notes:
2015-11-15:
-  Added step to run depmod -a to update the list of modules.  I believe this is an important part that I forgot to capture.  Regardless, running the command will do no harm to your system.

No comments:

Post a Comment