Module _scard'

SCARD_CTL_CODE(long code) -> long

Parameters:
    code: long



This function returns the value of a control code

from smartcard.scard import *
...
CM_IOCTL_GET_FEATURE_REQUEST = SCARD_CTL_CODE(3400)
...

Parameters:
    hcard: card handle return from SCardConnect()



This function establishes a temporary exclusive access mode for doing a
series of commands or transaction.  You might want to use this when you
are selecting a few files and then writing a large file so you can make
sure that another application will not change the current file.  If
another application has a lock on this reader or this application is in
SCARD_SHARE_EXCLUSIVE there will be no action taken.

from smartcard.scard import *
... establish context ...
hresult, hcard, dwActiveProtocol = SCardConnect(
    hcontext, 'SchlumbergerSema Reflex USB v.2 0', SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
if hresult!=SCARD_S_SUCCESS:
    raise error, 'unable to connect: ' + SCardGetErrorMessage(hresult)
hresult = SCardBeginTransaction(hcard)
if hresult != SCARD_S_SUCCESS:
    raise error, 'failed to begin transaction: ' + SCardGetErrorMessage(hresult)
...

Returns: SCARDRETCODE

Parameters:
    hcontext: context handle return from SCardEstablishContext()



This function cancels all pending blocking requests on the
ScardGetStatusChange() function.

from smartcard.scard import *
... establish context ...
hresult = SCardCancel(hcard)
if hresult != SCARD_S_SUCCESS:
    raise error, 'failed to cancel pending actions: ' + SCardGetErrorMessage(hresult)
...

Returns: SCARDRETCODE

Parameters:
    hcontext: context handle return from SCardEstablishContext()
    readername: card reader name
    dwShareMode: share mode
    dwPreferredProtocols: preferred protocols



This function establishes a connection to the friendly name of the reader
specified in szReader.  The first connection will power up and perform a
reset on the card.

Value of dwShareMode    Meaning
SCARD_SHARE_SHARED      This application will allow others to share the reader
SCARD_SHARE_EXCLUSIVE   This application will NOT allow others to share the reader
SCARD_SHARE_DIRECT      Direct control of the reader, even without a card

SCARD_SHARE_DIRECT can be used before using SCardControl() to send control
commands to the reader even if a card is not present in the reader.

Value of dwPreferredProtocols   Meaning
SCARD_PROTOCOL_T0               Use the T=0 protocol
SCARD_PROTOCOL_T1               Use the T=1 protocol
SCARD_PROTOCOL_RAW              Use with memory type cards

from smartcard.scard import *
... establish context ...
hresult, readers = SCardListReaders(hcontext, 'NULL')
if hresult != SCARD_S_SUCCESS:
    raise error, 'Failed to list readers:: ' + SCardGetErrorMessage(hresult)
hresult, hcard, dwActiveProtocol = SCardConnect(
    hcontext, readers[0], SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
if hresult != SCARD_S_SUCCESS:
    raise error, 'unable to connect: ' + SCardGetErrorMessage(hresult)
...

Returns: SCARDRETCODE

SCardControl( hcard,  dwControlCode, byte[] inbuffer) -> SCARDRETCODE

Parameters:
    hcard: card handle return from SCardConnect()
    dwControlCode: the control code to send
    inbuffer: list of bytes to send with the control code



This function sends a control command to the reader connected to by
SCardConnect().  It returns a result and the control response.


from smartcard.scard import *
hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
hresult, hcard, dwActiveProtocol = SCardConnect(
     hcontext, 'SchlumbergerSema Reflex USB v.2 0', SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
CMD = [0x12, 0x34]
hresult, response = SCardControl(hcard, 42, CMD)
if hresult != SCARD_S_SUCCESS:
    raise error, 'Failed to control: ' + SCardGetErrorMessage(hresult)

Parameters:
    hcard: card handle return from SCardConnect()
    dwDisposition: card disposition on return



This function terminates a connection to the connection made through
SCardConnect.  disposition can have the following values:

Value of disposition    Meaning
SCARD_LEAVE_CARD        Do nothing
SCARD_RESET_CARD        Reset the card (warm reset)
SCARD_UNPOWER_CARD      Unpower the card (cold reset)
SCARD_EJECT_CARD        Eject the card

from smartcard.scard import *
... establish context and connect to card ...
hresult = SCardDisconnect(hcard, SCARD_UNPOWER_CARD)
if hresult != SCARD_S_SUCCESS:
    raise error, 'failed to disconnect: ' + SCardGetErrorMessage(hresult)
...

Returns: SCARDRETCODE

Parameters:
    hcard: card handle return from SCardConnect()
    dwDisposition: card disposition on return




This function ends a previously begun transaction.  The calling
application must be the owner of the previously begun transaction or an
error will occur.  disposition can have the following values: The
disposition action is not currently used in this release.

Value of disposition    Meaning
SCARD_LEAVE_CARD        Do nothing
SCARD_RESET_CARD        Reset the card
SCARD_UNPOWER_CARD      Unpower the card
SCARD_EJECT_CARD        Eject the card

from smartcard.scard import *
... establish context, connect to card, begin transaction ...
hresult = SCardEndTransaction(hcard, SCARD_LEAVE_CARD)
if hresult != SCARD_S_SUCCESS:
    raise error, 'failed to end transaction: ' + SCardGetErrorMessage(hresult)

Returns: SCARDRETCODE

Parameters:
    dwScope: context scope



This function creates a communication context to the PC/SC Resource
Manager.  This must be the first function called in a PC/SC application.

Value of dwScope        Meaning
SCARD_SCOPE_USER        Operations performed within the scope of the User
SCARD_SCOPE_TERMINAL    Not used
SCARD_SCOPE_GLOBAL      Not used
SCARD_SCOPE_SYSTEM      Operations performed within the scope of the system


from smartcard.scard import *
hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
if hresult != SCARD_S_SUCCESS:
    raise error, 'Failed to establish context: ' + SCardGetErrorMessage(hresult)

Returns: SCARDRETCODE

Parameters:
    hcard: card handle return from SCardConnect()
    dwAttrId: value of attribute to get




This function get an attribute from the IFD Handler.

The possible attributes are:

======================================== ======= =======
Attribute                                Windows  PSCS  
                                                  lite
======================================== ======= =======
SCARD_ATTR_ASYNC_PROTOCOL_TYPES                     Y   
SCARD_ATTR_ATR_STRING                       Y       Y   
SCARD_ATTR_CHANNEL_ID                       Y       Y   
SCARD_ATTR_CHARACTERISTICS                  Y       Y   
SCARD_ATTR_CURRENT_BWT                      Y       Y   
SCARD_ATTR_CURRENT_CLK                      Y       Y   
SCARD_ATTR_CURRENT_CWT                      Y       Y   
SCARD_ATTR_CURRENT_D                        Y       Y   
SCARD_ATTR_CURRENT_EBC_ENCODING             Y       Y   
SCARD_ATTR_CURRENT_F                        Y       Y   
SCARD_ATTR_CURRENT_IFSC                     Y       Y   
SCARD_ATTR_CURRENT_IFSD                     Y       Y   
SCARD_ATTR_CURRENT_IO_STATE                 Y       Y   
SCARD_ATTR_CURRENT_N                        Y       Y   
SCARD_ATTR_CURRENT_PROTOCOL_TYPE            Y       Y   
SCARD_ATTR_CURRENT_W                        Y       Y   
SCARD_ATTR_DEFAULT_CLK                      Y       Y   
SCARD_ATTR_DEFAULT_DATA_RATE                Y       Y   
SCARD_ATTR_DEVICE_FRIENDLY_NAME_A           Y       Y   
SCARD_ATTR_DEVICE_FRIENDLY_NAME_W           Y       Y   
SCARD_ATTR_DEVICE_IN_USE                    Y       Y   
SCARD_ATTR_DEVICE_SYSTEM_NAME_A             Y       Y   
SCARD_ATTR_DEVICE_SYSTEM_NAME_W             Y       Y   
SCARD_ATTR_DEVICE_UNIT                      Y       Y   
SCARD_ATTR_ESC_AUTHREQUEST                  Y       Y   
SCARD_ATTR_ESC_CANCEL                       Y       Y   
SCARD_ATTR_ESC_RESET                        Y       Y   
SCARD_ATTR_EXTENDED_BWT                     Y       Y   
SCARD_ATTR_ICC_INTERFACE_STATUS             Y       Y   
SCARD_ATTR_ICC_PRESENCE                     Y       Y   
SCARD_ATTR_ICC_TYPE_PER_ATR                 Y       Y   
SCARD_ATTR_MAXINPUT                         Y       Y   
SCARD_ATTR_MAX_CLK                          Y       Y   
SCARD_ATTR_MAX_DATA_RATE                    Y       Y   
SCARD_ATTR_MAX_IFSD                         Y       Y   
SCARD_ATTR_POWER_MGMT_SUPPORT               Y       Y   
SCARD_ATTR_SUPRESS_T1_IFS_REQUEST           Y       Y   
SCARD_ATTR_SYNC_PROTOCOL_TYPES                      Y   
SCARD_ATTR_USER_AUTH_INPUT_DEVICE           Y       Y   
SCARD_ATTR_USER_TO_CARD_AUTH_DEVICE         Y       Y   
SCARD_ATTR_VENDOR_IFD_SERIAL_NO             Y       Y   
SCARD_ATTR_VENDOR_IFD_TYPE                  Y       Y   
SCARD_ATTR_VENDOR_IFD_VERSION               Y       Y   
SCARD_ATTR_VENDOR_NAME                      Y       Y   
======================================== ======= =======

Not all the dwAttrId values listed above may be implemented in the IFD
Handler you are using.  And some dwAttrId values not listed here may be
implemented.


from smartcard.scard import *
... establish context and connect to card ...
hresult, attrib = SCardGetAttrib(hcard, SCARD_ATTR_ATR_STRING)
if hresult == SCARD_S_SUCCESS:
    for j in attrib:
         print '0x%.2X' % attrib,
...

Returns: SCARDRETCODE

SCardGetErrorMessage(long lErrCode) -> ERRORSTRING *

Parameters:
    lErrCode: long



This function return a human readable text for the given PC/SC error code.

from smartcard.scard import *
...
hresult, response = SCardTransmit(hcard, SCARD_PCI_T0, SELECT + DF_TELECOM)
if hresult != SCARD_S_SUCCESS:
    raise error, 'Failed to transmit: ' + SCardGetErrorMessage(hresult)
...

SCardGetStatusChange( hcontext,  dwTimeout, tuple[] readerstatelist) -> SCARDRETCODE

Parameters:
    hcontext: context handle return from SCardEstablishContext()
    dwTimeout: timeout value, INFINITE for infinite time-out
    readerstatelist: in input/output, a list of reader state tuple (readername, state, atr)




This function receives a structure or list of tuples containing reader
states. A READERSTATE hast three fields (readername, state, atr).
It then blocks for a change in state to occur on any of the OR'd
values contained in the current state for a maximum blocking time of
dwTimeout or forever if INFINITE is used.  The new event state will be
contained in state.  A status change might be a card insertion or
removal event, a change in ATR, etc.

Value of state              Meaning
SCARD_STATE_UNAWARE         The application is unaware of the current state, and would like to know. The use of this value results in an immediate return from state transition monitoring services. This is represented by all bits set to zero
SCARD_STATE_IGNORE          This reader should be ignored
SCARD_STATE_CHANGED         There is a difference between the state believed by the application, and the state known by the resource manager. When this bit is set, the application may assume a significant state change has occurred on this reader
SCARD_STATE_UNKNOWN         The given reader name is not recognized by the resource manager. If this bit is set, then SCARD_STATE_CHANGED and SCARD_STATE_IGNORE will also be set
SCARD_STATE_UNAVAILABLE     The actual state of this reader is not available. If this bit is set, then all the following bits are clear
SCARD_STATE_EMPTY           There is no card in the reader. If this bit is set, all the following bits will be clear
SCARD_STATE_PRESENT         There is a card in the reader
SCARD_STATE_ATRMATCH        There is a card in the reader with an ATR matching one of the target cards. If this bit is set, SCARD_STATE_PRESENT will also be set. This bit is only returned on the SCardLocateCards function
SCARD_STATE_EXCLUSIVE       The card in the reader is allocated for exclusive use by another application. If this bit is set, SCARD_STATE_PRESENT will also be set
SCARD_STATE_INUSE           The card in the reader is in use by one or more other applications, but may be connected to in shared mode. If this bit is set, SCARD_STATE_PRESENT will also be set
SCARD_STATE_MUTE            There is an unresponsive card in the reader


from smartcard.scard import *
hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
hresult, readers = SCardListReaders(hcontext, [])
readerstates = []
cards = [ 'Schlumberger Cryptoflex 4k', 'Schlumberger Cryptoflex 8k', 'Schlumberger Cryptoflex 8k v2' ]
for i in xrange(len(readers)):
    readerstates += [ (readers[i], SCARD_STATE_UNAWARE) ]
hresult, newstates = SCardLocateCards(hcontext, cards, readerstates)
print '----- Please insert or remove a card ------------'
hresult, newstates = SCardGetStatusChange(hcontext, INFINITE, newstates)
for i in newstates
     reader, eventstate, atr = i
    if eventstate & SCARD_STATE_ATRMATCH:
        print ' Card found'
    if eventstate & SCARD_STATE_EMPTY:
        print ' Reader empty'

Parameters:
    hcontext: context handle return from SCardEstablishContext()



This function determines whether a smart card context handle is still
valid.  After a smart card context handle has been set by
SCardEstablishContext(), it may become not valid if the resource manager
service has been shut down.

from smartcard.scard import *
hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
hresult = SCardIsValidContext(hcontext)
if hresult != SCARD_S_SUCCESS:
    raise error, 'Invalid context: ' + SCardGetErrorMessage(hresult)
...

Returns: SCARDRETCODE

Parameters:
    hcontext: context handle return from SCardEstablishContext()



This function returns a list of currently available reader groups on the
system.

from smartcard.scard import *
hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
hresult, readerGroups = SCardListReaderGroups(hcontext)
if hresult != SCARD_S_SUCCESS:
    raise error, 'Unable to list reader groups: ' + SCardGetErrorMessage(hresult)
print 'PCSC Reader groups: ', readerGroups

Returns: SCARDRETCODE

SCardListReaders( hcontext, [] readergroups) -> SCARDRETCODE

Parameters:
    hcontext: context handle return from SCardEstablishContext()
    readergroups: a list of reader groups to search for readers



This function returns a list of currently available readers on the system.
A list of group can be provided in input to list readers in a given
group only.

from smartcard.scard import *
hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
hresult, readers = SCardListReaders(hcontext, [])
if hresult != SCARD_S_SUCCESS:
    raise error, 'Failed to list readers: ' + SCardGetErrorMessage(hresult)
print 'PCSC Readers: ', readers
hresult, readers = SCardListReaders(hcontext, ['SCard$T1ProtocolReaders', 'SCard$MyOwnGroup']
...

Parameters:
    hcard: card handle return from SCardConnect()
    dwShareMode: share mode
    dwPreferredProtocols: preferred protocols
    dwInitialization: the type of initialization that should be performed on the card




This function reestablishes a connection to a reader that was previously
connected to using SCardConnect().  In a multi application environment it
is possible for an application to reset the card in shared mode.  When
this occurs any other application trying to access certain commands will
be returned the value SCARD_W_RESET_CARD.  When this occurs
SCardReconnect() must be called in order to acknowledge that the card was
reset and allow it to change it's state accordingly.

Value of dwShareMode    Meaning
SCARD_SHARE_SHARED      This application will allow others to share the reader
SCARD_SHARE_EXCLUSIVE   This application will NOT allow others to share the reader

Value of dwPreferredProtocols   Meaning
SCARD_PROTOCOL_T0               Use the T=0 protocol
SCARD_PROTOCOL_T1               Use the T=1 protocol
SCARD_PROTOCOL_RAW              Use with memory type cards

dwPreferredProtocols is a bit mask of acceptable protocols for the connection. You can use (SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1) if you do not have a preferred protocol.

Value of dwInitialization   Meaning
SCARD_LEAVE_CARD            Do nothing
SCARD_RESET_CARD            Reset the card (warm reset)
SCARD_UNPOWER_CARD          Unpower the card (cold reset)
SCARD_EJECT_CARD            Eject the card


from smartcard.scard import *
hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
hresult, hcard, dwActiveProtocol = SCardConnect(
    hcontext, 'SchlumbergerSema Reflex USB v.2 0', SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
hresult, activeProtocol = SCardReconnect(hcard, SCARD_SHARE_EXCLUSIVE,
    SCARD_PROTOCOL_T0, SCARD_RESET_CARD)
...

Returns: SCARDRETCODE

Parameters:
    hcontext: context handle return from SCardEstablishContext()

Returns: SCARDRETCODE

SCardSetAttrib( hcard,  dwAttrId, BYTELIST * ATTRIBUTESIN) -> SCARDRETCODE

Parameters:
    hcard: card handle return from SCardConnect()
    dwAttrId: value of attribute to get
    ATTRIBUTESIN: BYTELIST *




This function sets an attribute from the IFD Handler. Not all
attributes are supported by all readers nor can they be set at all
times.

The possible attributes are:

======================================== ======= =======
Attribute                                Windows  PSCS  
                                                  lite
======================================== ======= =======
SCARD_ATTR_ASYNC_PROTOCOL_TYPES                     Y   
SCARD_ATTR_ATR_STRING                       Y       Y   
SCARD_ATTR_CHANNEL_ID                       Y       Y   
SCARD_ATTR_CHARACTERISTICS                  Y       Y   
SCARD_ATTR_CURRENT_BWT                      Y       Y   
SCARD_ATTR_CURRENT_CLK                      Y       Y   
SCARD_ATTR_CURRENT_CWT                      Y       Y   
SCARD_ATTR_CURRENT_D                        Y       Y   
SCARD_ATTR_CURRENT_EBC_ENCODING             Y       Y   
SCARD_ATTR_CURRENT_F                        Y       Y   
SCARD_ATTR_CURRENT_IFSC                     Y       Y   
SCARD_ATTR_CURRENT_IFSD                     Y       Y   
SCARD_ATTR_CURRENT_IO_STATE                 Y       Y   
SCARD_ATTR_CURRENT_N                        Y       Y   
SCARD_ATTR_CURRENT_PROTOCOL_TYPE            Y       Y   
SCARD_ATTR_CURRENT_W                        Y       Y   
SCARD_ATTR_DEFAULT_CLK                      Y       Y   
SCARD_ATTR_DEFAULT_DATA_RATE                Y       Y   
SCARD_ATTR_DEVICE_FRIENDLY_NAME_A           Y       Y   
SCARD_ATTR_DEVICE_FRIENDLY_NAME_W           Y       Y   
SCARD_ATTR_DEVICE_IN_USE                    Y       Y   
SCARD_ATTR_DEVICE_SYSTEM_NAME_A             Y       Y   
SCARD_ATTR_DEVICE_SYSTEM_NAME_W             Y       Y   
SCARD_ATTR_DEVICE_UNIT                      Y       Y   
SCARD_ATTR_ESC_AUTHREQUEST                  Y       Y   
SCARD_ATTR_ESC_CANCEL                       Y       Y   
SCARD_ATTR_ESC_RESET                        Y       Y   
SCARD_ATTR_EXTENDED_BWT                     Y       Y   
SCARD_ATTR_ICC_INTERFACE_STATUS             Y       Y   
SCARD_ATTR_ICC_PRESENCE                     Y       Y   
SCARD_ATTR_ICC_TYPE_PER_ATR                 Y       Y   
SCARD_ATTR_MAXINPUT                         Y       Y   
SCARD_ATTR_MAX_CLK                          Y       Y   
SCARD_ATTR_MAX_DATA_RATE                    Y       Y   
SCARD_ATTR_MAX_IFSD                         Y       Y   
SCARD_ATTR_POWER_MGMT_SUPPORT               Y       Y   
SCARD_ATTR_SUPRESS_T1_IFS_REQUEST           Y       Y   
SCARD_ATTR_SYNC_PROTOCOL_TYPES                      Y   
SCARD_ATTR_USER_AUTH_INPUT_DEVICE           Y       Y   
SCARD_ATTR_USER_TO_CARD_AUTH_DEVICE         Y       Y   
SCARD_ATTR_VENDOR_IFD_SERIAL_NO             Y       Y   
SCARD_ATTR_VENDOR_IFD_TYPE                  Y       Y   
SCARD_ATTR_VENDOR_IFD_VERSION               Y       Y   
SCARD_ATTR_VENDOR_NAME                      Y       Y   
======================================== ======= =======

Not all the dwAttrId values listed above may be implemented in the IFD
Handler you are using.  And some dwAttrId values not listed here may be
implemented.


from smartcard.scard import *
... establish context and connect to card ...
hresult, attrib = SCardSetAttrib(hcard, SCARD_ATTR_VENDOR_NAME, ['G', 'e', 'm', 'a', 'l', 't', 'o'])
if hresult != SCARD_S_SUCCESS:
     print 'Failed to set attribute'
...

Parameters:
    hcard: card handle return from SCardConnect()



This function returns the current status of the reader connected to by
hcard.  The reader friendly name is returned, as well as the state,
protocol and ATR.  The state is a DWORD possibly OR'd with the following
values:

Value of pdwState   Meaning
SCARD_ABSENT        There is no card in the reader
SCARD_PRESENT       There is a card in the reader, but it has not been moved into position for use
SCARD_SWALLOWED     There is a card in the reader in position for use. The card is not powered
SCARD_POWERED       Power is being provided to the card, but the reader driver is unaware of the mode of the card
SCARD_NEGOTIABLE    The card has been reset and is awaiting PTS negotiation
SCARD_SPECIFIC      The card has been reset and specific communication protocols have been established

Value of pdwProtocol    Meaning
SCARD_PROTOCOL_T0       Use the T=0 protocol
SCARD_PROTOCOL_T1       Use the T=1 protocol


from smartcard.scard import *
hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
hresult, hcard, dwActiveProtocol = SCardConnect(
         hcontext, 'SchlumbergerSema Reflex USB v.2 0', SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
hresult, reader, state, protocol, atr = SCardStatus(hcard)
if hresult != SCARD_S_SUCCESS:
    raise error, 'failed to get status: ' + SCardGetErrorMessage(hresult)
print 'Reader: ', reader
print 'State: ', state
print 'Protocol: ', protocol
print 'ATR: ',
for i in xrange(len(atr)):
    print '0x%.2X' % i,
print 
...

Returns: SCARDRETCODE

SCardTransmit( hcard, unsigned long pioSendPci, byte[] apducommand) -> SCARDRETCODE

Parameters:
    hcard: card handle return from SCardConnect()
    pioSendPci: unsigned long
    apducommand: list of APDU bytes to transmit



This function sends an APDU to the smart card contained in the reader
connected to by SCardConnect().
It returns a result and the card APDU response.

Value of pioSendPci     Meaning
SCARD_PCI_T0            Pre-defined T=0 PCI structure
SCARD_PCI_T1            Pre-defined T=1 PCI structure


from smartcard.scard import *
hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
hresult, hcard, dwActiveProtocol = SCardConnect(
     hcontext, 'SchlumbergerSema Reflex USB v.2 0', SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
SELECT = [0xA0, 0xA4, 0x00, 0x00, 0x02]
DF_TELECOM = [0x7F, 0x10]
hresult, response = SCardTransmit(hcard, SCARD_PCI_T0, SELECT + DF_TELECOM)
if hresult != SCARD_S_SUCCESS:
    raise error, 'Failed to transmit: ' + SCardGetErrorMessage(hresult)