Module de.gematik.smartcards.pcsc

Package de.gematik.smartcards.pcsc.lib

Class WinscardLibraryImpl

java.lang.Object

de.gematik.smartcards.pcsc.lib.WinscardLibraryImpl

public final class WinscardLibraryImpl
extends Object

Class providing a wrapper for native library.

The main purpose for this class is to provide logging at level TRACE for methods in WinscardLibrary.

Author:

gematik

Method Summary

Modifier and Type	Method	Description
static List<String>	multiString(byte[] multiString)	Converts octet string into a list of strings.
static WinscardLibraryImpl	openLib()	Pseudo constructor.
int	scardConnect(ScardContext context, String szReader, int dwShareMode, int dwPreferredProtocols, ScardHandleByReference phCard, DwordByReference pdwActiveProtocol)	Method wrapping WinscardLibrary.SCardConnect(de.gematik.smartcards.pcsc.lib.ScardContext, java.lang.String, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardHandleByReference, de.gematik.smartcards.pcsc.lib.DwordByReference).
int	scardDisconnect(ScardHandle card, int dwPosition)	Method wrapping WinscardLibrary.SCardDisconnect(ScardHandle, Dword).
int	scardEstablishContext(Dword dwScope, com.sun.jna.Pointer pvReserved1, com.sun.jna.Pointer pvReserved2, ScardContextByReference phContext)	Method wrapping WinscardLibrary.SCardListReaders(ScardContext, ByteBuffer, ByteBuffer, DwordByReference).
int	scardGetStatusChange(ScardContext context, long dwTimeout, ScardReaderState... rgReaderStates)	Method wrapping WinscardLibrary.SCardGetStatusChange(ScardContext, Dword, ScardReaderState[], Dword).
int	scardListReaders(ScardContext context, String mszGroups, byte[] mszReaders, DwordByReference pcchReaders)	Method wrapping WinscardLibrary.SCardListReaders(ScardContext, ByteBuffer, ByteBuffer, DwordByReference).
int	scardReleaseContext(ScardContext context)	Method wrapping WinscardLibrary.SCardReleaseContext(ScardContext).
int	scardStatus(ScardHandle card, ByteBuffer mszReaderName, DwordByReference pcchReaderLen, DwordByReference pdwState, DwordByReference pdwProtocol, ByteBuffer pbAtr, DwordByReference pcbAtrLen)	Method wrapping WinscardLibrary.SCardStatus(de.gematik.smartcards.pcsc.lib.ScardHandle, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference).
byte[]	scardTransmit(ScardHandle card, byte[] sendBuffer, double... executionTime)	Method simplifying WinscardLibrary.SCardTransmit(de.gematik.smartcards.pcsc.lib.ScardHandle, de.gematik.smartcards.pcsc.lib.ScardIoRequest, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardIoRequest, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

openLib

public static WinscardLibraryImpl openLib()

Pseudo constructor.

Performs the following tasks:

1. loads the native platform specific PC/SC library
2. copies global PCI (protocol control information) structures for T=0, T=1 and raw out of native library into the corresponding ScardIoRequest.
3. constructs with this information the return value.

Returns:

WinscardLibraryImpl

multiString

public static List<String> multiString(byte[] multiString)

Converts octet string into a list of strings.

Assumes UTF-8 encoding. The octet string SHALL be encoded as follows:

1. Each string SHALL be zero-terminated, i.e. by an octet of value 0 = 0x00 = '00'.
2. An empty string SHALLterminates the list, i.e. two consecutive octets each with a value of 0 = 0x00 = '00'.

Parameters:

multiString - octet string containing a list of '0' terminated strings

Returns:

fixed size list of strings (see Arrays.asList(Object[]))

Throws:

IllegalArgumentException - if multi-string is not terminated with a null-terminated empty string

scardEstablishContext

public int scardEstablishContext(Dword dwScope,
 @Nullable
 com.sun.jna.Pointer pvReserved1,
 @Nullable
 com.sun.jna.Pointer pvReserved2,
 ScardContextByReference phContext)

Method wrapping WinscardLibrary.SCardListReaders(ScardContext, ByteBuffer, ByteBuffer, DwordByReference).

Observations:

1. If no resource manager is running then SCARD_E_NO_SERVICE is to be expected.
2. If a resource manager is running then SCARD_S_SUCCESS is to be expected.
3. Linux is able to use all scope-values defined in pcsc-lite.h.in, i.e. from set: [ SCARD_SCOPE_USER, SCARD_SCOPE_TERMINAL, SCARD_SCOPE_SYSTEM ].
4. Windows is unable to use scope SCARD_SCOPE_TERMINAL.

Implementation recommendations:

1. Make sure (or assume) that resource manager is running.
2. Use SCARD_SCOPE_SYSTEM in case TODO
3. Use SCARD_SCOPE_USER in case TODO

Parameters:

dwScope - see WinscardLibrary.SCardEstablishContext}

pvReserved1 - see WinscardLibrary.SCardEstablishContext}

pvReserved2 - see WinscardLibrary.SCardEstablishContext}

phContext - see WinscardLibrary.SCardEstablishContext}

Returns:

see WinscardLibrary.SCardEstablishContext}

scardListReaders

public int scardListReaders(@Nullable
 ScardContext context,
 @Nullable
 String mszGroups,
 @Nullable
 byte[] mszReaders,
 DwordByReference pcchReaders)

Method wrapping WinscardLibrary.SCardListReaders(ScardContext, ByteBuffer, ByteBuffer, DwordByReference).

Observations:

1. It does not matter how a ScardContext is established.
2. Linux does not support hContext = null.
3. Windows: hContext = null returns a list of all readers ever attached to the computer (obviously since OS-installation).
4. The observed behavior doesn't depend on the value of mszGroups. Thus, mszGroups could be any of NULL, SCARD_ALL_READERS, SCARD_DEFAULT_READERS or a concatenation of SCARD_ALL_READERS and SCARD_DEFAULT_READERS.
5. The array backing mszReaders can be larger than necessary.
6. If the size indicated by pcchReaders is smaller than the size of the to be returned mszReaders then SCARD_E_INSUFFICIENT_BUFFER is returned.
7. Neither Windows nor Linux support SCARD_AUTOALLOCATE.

Implementation recommendations: In order to get a list of readers actually connected:

1. For hContext use a real context established with either with SCARD_SCOPE_SYSTEM or with SCARD_SCOPE_USER (presently no differences are known between these two values).
2. Set mszGroups to NULL.
3. Call the method in a do .. while()-loop. Within that loop first call this method with mszReaders set to NULL and pcchReaders containing 0 in order to retrieve the required buffer size. Then allocate an appropriate buffer for mszReaders and call the method again. Loop as long as the second call returns SCARD_E_INSUFFICIENT_BUFFER. This return value occurs in case another reader is connected between the first and second call and because of the name of that reader a larger buffer is needed.

Parameters:

context - see WinscardLibrary.SCardListReaders}

mszGroups - see WinscardLibrary.SCardListReaders}

mszReaders - see WinscardLibrary.SCardListReaders}

pcchReaders - see WinscardLibrary.SCardListReaders}

Returns:

see WinscardLibrary.SCardListReaders}

scardGetStatusChange

public int scardGetStatusChange(ScardContext context,
 long dwTimeout,
 ScardReaderState... rgReaderStates)

Method wrapping WinscardLibrary.SCardGetStatusChange(ScardContext, Dword, ScardReaderState[], Dword).

Note: Compared to WinscardLibrary.SCardGetStatusChange(ScardContext, Dword, ScardReaderState[], Dword) this method has no parameter cReaders, because this method calculates that value from parameter rgReaderStates.

Parameters:

context - see WinscardLibrary.SCardGetStatusChange(de.gematik.smartcards.pcsc.lib.ScardContext, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardReaderState[], de.gematik.smartcards.pcsc.lib.Dword)}

dwTimeout - see WinscardLibrary.SCardGetStatusChange(de.gematik.smartcards.pcsc.lib.ScardContext, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardReaderState[], de.gematik.smartcards.pcsc.lib.Dword)}

rgReaderStates - see WinscardLibrary.SCardGetStatusChange(de.gematik.smartcards.pcsc.lib.ScardContext, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardReaderState[], de.gematik.smartcards.pcsc.lib.Dword)}

Returns:

see WinscardLibrary.SCardGetStatusChange(de.gematik.smartcards.pcsc.lib.ScardContext, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardReaderState[], de.gematik.smartcards.pcsc.lib.Dword)}

Throws:

IllegalArgumentException - if readerStates has zero length

NullPointerException - if rgReaderStates is null

scardConnect

public int scardConnect(ScardContext context,
 String szReader,
 int dwShareMode,
 int dwPreferredProtocols,
 ScardHandleByReference phCard,
 DwordByReference pdwActiveProtocol)

Method wrapping WinscardLibrary.SCardConnect(de.gematik.smartcards.pcsc.lib.ScardContext, java.lang.String, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardHandleByReference, de.gematik.smartcards.pcsc.lib.DwordByReference).

Parameters:

context - see WinscardLibrary.SCardConnect(de.gematik.smartcards.pcsc.lib.ScardContext, java.lang.String, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardHandleByReference, de.gematik.smartcards.pcsc.lib.DwordByReference)}

szReader - see WinscardLibrary.SCardConnect(de.gematik.smartcards.pcsc.lib.ScardContext, java.lang.String, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardHandleByReference, de.gematik.smartcards.pcsc.lib.DwordByReference)}

dwShareMode - see WinscardLibrary.SCardConnect(de.gematik.smartcards.pcsc.lib.ScardContext, java.lang.String, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardHandleByReference, de.gematik.smartcards.pcsc.lib.DwordByReference)}

dwPreferredProtocols - see WinscardLibrary.SCardConnect(de.gematik.smartcards.pcsc.lib.ScardContext, java.lang.String, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardHandleByReference, de.gematik.smartcards.pcsc.lib.DwordByReference)}

phCard - see WinscardLibrary.SCardConnect(de.gematik.smartcards.pcsc.lib.ScardContext, java.lang.String, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardHandleByReference, de.gematik.smartcards.pcsc.lib.DwordByReference)}

pdwActiveProtocol - see WinscardLibrary.SCardConnect(de.gematik.smartcards.pcsc.lib.ScardContext, java.lang.String, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardHandleByReference, de.gematik.smartcards.pcsc.lib.DwordByReference)}

Returns:

see WinscardLibrary.SCardConnect(de.gematik.smartcards.pcsc.lib.ScardContext, java.lang.String, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardHandleByReference, de.gematik.smartcards.pcsc.lib.DwordByReference)}

scardStatus

public int scardStatus(ScardHandle card,
 @Nullable
 ByteBuffer mszReaderName,
 DwordByReference pcchReaderLen,
 DwordByReference pdwState,
 DwordByReference pdwProtocol,
 ByteBuffer pbAtr,
 DwordByReference pcbAtrLen)

Method wrapping WinscardLibrary.SCardStatus(de.gematik.smartcards.pcsc.lib.ScardHandle, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference).

Parameters:

card - see WinscardLibrary.SCardStatus(de.gematik.smartcards.pcsc.lib.ScardHandle, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference)

mszReaderName - see WinscardLibrary.SCardStatus(de.gematik.smartcards.pcsc.lib.ScardHandle, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference)

pcchReaderLen - see WinscardLibrary.SCardStatus(de.gematik.smartcards.pcsc.lib.ScardHandle, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference)

pdwState - see WinscardLibrary.SCardStatus(de.gematik.smartcards.pcsc.lib.ScardHandle, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference)

pdwProtocol - see WinscardLibrary.SCardStatus(de.gematik.smartcards.pcsc.lib.ScardHandle, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference)

pbAtr - see WinscardLibrary.SCardStatus(de.gematik.smartcards.pcsc.lib.ScardHandle, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference)

pcbAtrLen - see WinscardLibrary.SCardStatus(de.gematik.smartcards.pcsc.lib.ScardHandle, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference)

Returns:

see WinscardLibrary.SCardStatus(de.gematik.smartcards.pcsc.lib.ScardHandle, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, de.gematik.smartcards.pcsc.lib.DwordByReference, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference)

scardTransmit

public byte[] scardTransmit(ScardHandle card,
 byte[] sendBuffer,
 double... executionTime)
                     throws PcscException

Method simplifying WinscardLibrary.SCardTransmit(de.gematik.smartcards.pcsc.lib.ScardHandle, de.gematik.smartcards.pcsc.lib.ScardIoRequest, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardIoRequest, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference).

Parameters:

card - see WinscardLibrary.SCardTransmit(de.gematik.smartcards.pcsc.lib.ScardHandle, de.gematik.smartcards.pcsc.lib.ScardIoRequest, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.Dword, de.gematik.smartcards.pcsc.lib.ScardIoRequest, java.nio.ByteBuffer, de.gematik.smartcards.pcsc.lib.DwordByReference)}

sendBuffer - command message to be transmitted

executionTime - [OUT] parameter with at least one element which receives the execution time of the underlying library call in seconds

Returns:

corresponding response message

Throws:

PcscException - if the card operation fails

scardDisconnect

public int scardDisconnect(ScardHandle card,
 int dwPosition)

Method wrapping WinscardLibrary.SCardDisconnect(ScardHandle, Dword).

Parameters:

card - see WinscardLibrary.SCardDisconnect(de.gematik.smartcards.pcsc.lib.ScardHandle, de.gematik.smartcards.pcsc.lib.Dword)}

dwPosition - see WinscardLibrary.SCardDisconnect(de.gematik.smartcards.pcsc.lib.ScardHandle, de.gematik.smartcards.pcsc.lib.Dword)}

Returns:

see WinscardLibrary.SCardDisconnect(de.gematik.smartcards.pcsc.lib.ScardHandle, de.gematik.smartcards.pcsc.lib.Dword)}

scardReleaseContext

public int scardReleaseContext(ScardContext context)

Method wrapping WinscardLibrary.SCardReleaseContext(ScardContext).

Observations:

1. It does not matter if SCardEstablishContext was not successful. The context can be released successfully anyway.
2. A context can be released only once. Another call of SCardReleaseContext produces SCARD_E_INVALID_HANDLE.

Implementation recommendations:

1. Either assume that the used ScardContext is valid, or
2. check validity with TODO #SCardIsValidContext(ScardContext).

Parameters:

context - see WinscardLibrary.SCardReleaseContext}

Returns:

see WinscardLibrary.SCardReleaseContext}