/share/man/man4/cmx.4

  1.\"
  2.\" Copyright (c) 2006-2007 Daniel Roethlisberger <daniel@roe.ch>
  3.\" All rights reserved.
  4.\" 
  5.\" Redistribution and use in source and binary forms, with or without
  6.\" modification, are permitted provided that the following conditions
  7.\" are met:
  8.\" 1. Redistributions of source code must retain the above copyright
  9.\"    notice unmodified, this list of conditions, and the following
 10.\"    disclaimer.
 11.\" 2. Redistributions in binary form must reproduce the above copyright
 12.\"    notice, this list of conditions and the following disclaimer in the
 13.\"    documentation and/or other materials provided with the distribution.
 14.\" 
 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 25.\" SUCH DAMAGE.
 26.\"
 27.\" $FreeBSD$
 28.\"
 29.Dd July 7, 2007
 30.Dt CMX 4
 31.Os
 32.Sh NAME
 33.Nm cmx
 34.Nd Omnikey CardMan 4040 smartcard reader device driver
 35.Sh SYNOPSIS
 36.Cd device cmx
 37.Sh DESCRIPTION
 38The
 39.Nm
 40driver provides support for the PCCARD based
 41.Em Omnikey CardMan 4040
 42smartcard reader.
 43The driver provides a character device special file based
 44.Em Chip/Smart Card Interface Devices (CCID)
 45interface.  The driver implements what the vendor calls the
 46.Em Synchronous API
 47onto the smartcard reader device.
 48.Pp
 49Reading and writing is synchronous, meaning that a call to
 50.Xr write 2
 51directly corresponds to a complete CCID command sent to the
 52device, while the following
 53.Xr read 2
 54will return the complete answer from the reader.  There is no
 55support for partial reads or writes.  There is no upper limit on
 56CCID request or response sizes, but the complete CCID request
 57must be sent to the driver in
 58.Xr write 2
 59and the complete CCID response must fit into the buffer
 60supplied to
 61.Xr read 2 .
 62.Pp
 63Non-blocking I/O,
 64.Xr select 2
 65and
 66.Xr poll 2
 67are supported and work as expected.  An open file descriptor
 68will always be ready for writing, but only ready for reading
 69if the device indicates that it has data available.
 70.Sh FILES
 71.Bl -tag -width /usr/ports/security/openct -compact
 72.It Pa /dev/cmx\fBn\fP
 73Character device special file.
 74.It Pa /usr/ports/security/openct
 75OpenCT, a userspace smartcard daemon containing a
 76.Em CCID
 77driver which directly supports
 78.Nm
 79devices.
 80.\".It Pa /usr/ports/devel/pcsc-lite
 81.\"PC/SC-Lite, a userspace smartcard daemon.
 82.\".It Pa /usr/ports/devel/libccid
 83.\"libccid, a generic
 84.\".Em CCID
 85.\"driver for use by PC/SC-Lite to interface to
 86.\".Nm
 87.\"devices.
 88.El
 89.Sh COMPATIBILITY
 90Userland smartcard code written for the vendor's Linux drivers
 91should work with the
 92.Nm
 93driver without modification.
 94.Sh SEE ALSO
 95.Xr pccard 4
 96.Sh HISTORY
 97The
 98.Nm cmx
 99driver first appeared in
100.Fx 7.1 .
101.Sh AUTHORS
102.An -nosplit
103The
104.Nm
105driver was written by
106.An Daniel Roethlisberger Aq daniel@roe.ch ,
107originally based on the Linux driver v1.1.0 by
108.An Omnikey GmbH Aq www.omnikey.com .
109Early testing and bug fixes by
110.An Marcin Cieslak Aq saper@system.pl .
111.Sh BUGS
112.An -nosplit
113The way the
114.Nm
115driver talks to the CardMan 4040 is a bit rough.  Due to the
116complete lack of hardware documentation other than vendor drivers
117for other operating systems, the gory details of the device's
118I/O registers are not understood very well.  There may be error
119conditions which can only be solved by physically reinserting the
120reader.