Class FinSecurityMediaSmartCard

Namespace
Subsembly.FinTS
Assembly
Subsembly.FinTS.SmartCard.dll

Abstract base class for sll smart card based IFinSecurityMedia interface implementations.

public abstract class FinSecurityMediaSmartCard : IFinSecurityMedia, IFinSecurityMediaSmartCard
Inheritance
FinSecurityMediaSmartCard
Implements
Derived
Inherited Members

Remarks

This class implements all methods of the IFinSecurityMedia interface, delegating card specific work to some abstract methods that must be overridden by the derived concrete class.

Constructors

FinSecurityMediaSmartCard() 

public FinSecurityMediaSmartCard()

Properties

Capabilities

Delegates to OnGetCapabilities()

public FinSecurityMediaCaps Capabilities { get; }

Property Value

FinSecurityMediaCaps

Card 

protected CardExpress Card { get; }

Property Value

CardExpress

CardEncoding

Text encoding that is used by the text fields of the smart card.

protected Encoding CardEncoding { get; set; }

Property Value

Encoding

Remarks

The default Encoding is Windows 1252 encoding.

CardID 

protected byte[] CardID { get; }

Property Value

byte[]

ContactCapacity

Delegates to OnGetContactCapacity()

public int ContactCapacity { get; }

Property Value

int

MaxKeyLength

Delegates to OnGetMaxKeyLength()

public int MaxKeyLength { get; }

Property Value

int

PassphraseFlags

Delegates to OnGetPassphraseFlags()

public FinSecurityMediaPassphraseFlags PassphraseFlags { get; }

Property Value

FinSecurityMediaPassphraseFlags

PassphraseMaxLength

Delegates to OnGetPassphraseMaxLength()

public int PassphraseMaxLength { get; }

Property Value

int

PassphraseMinLength

Delegates to OnGetPassphraseMinLength()

public int PassphraseMinLength { get; }

Property Value

int

SecurityMediaID

Provides the hex representation of the EF_ID or similar file of this smart card.

public string SecurityMediaID { get; }

Property Value

string

SecurityMediaType

This base class is meant solely for smart card based implementations, hence this property always returns SmartCard.

public FinSecurityMediaType SecurityMediaType { get; }

Property Value

FinSecurityMediaType

SecurityProfiles 

public FinSecurityProfile[] SecurityProfiles { get; }

Property Value

FinSecurityProfile[]

Remarks

The default implementation always returns an array with a single RDH-1 element.

State

Indicates the current state of this IFinSecurityMedia implementation instance.

public FinSecurityMediaState State { get; }

Property Value

FinSecurityMediaState

Methods

Authenticate(string, string) 

public FinAuthenticateResult Authenticate(string sUserName, string sPassphrase)

Parameters

sUserName string
sPassphrase string

Returns

FinAuthenticateResult

AuthenticateAdmin(string, string) 

public FinAuthenticateResult AuthenticateAdmin(string sUserName, string sAdminPassphrase)

Parameters

sUserName string
sAdminPassphrase string

Returns

FinAuthenticateResult

AuthenticateSecure() 

public FinAuthenticateResult AuthenticateSecure()

Returns

FinAuthenticateResult

CanAuthenticateSecure() 

public bool CanAuthenticateSecure()

Returns

bool

CanChangePassphraseSecure() 

public bool CanChangePassphraseSecure()

Returns

bool

Cancel() 

public void Cancel()

ChangePassphrase(string, string, string) 

public FinAuthenticateResult ChangePassphrase(string sUserName, string sOldPassphrase, string sNewPassphrase)

Parameters

sUserName string
sOldPassphrase string
sNewPassphrase string

Returns

FinAuthenticateResult

ChangePassphraseSecure() 

public FinAuthenticateResult ChangePassphraseSecure()

Returns

FinAuthenticateResult

ChangePin(CardPinControl, string, string) 

protected FinAuthenticateResult ChangePin(CardPinControl aPinControl, string sOldPin, string sNewPin)

Parameters

aPinControl CardPinControl
sOldPin string
sNewPin string

Returns

FinAuthenticateResult

ChangePinSecure(CardPinControl) 

protected FinAuthenticateResult ChangePinSecure(CardPinControl aPinControl)

Parameters

aPinControl CardPinControl

Returns

FinAuthenticateResult

Create(string, string, string)

Always throws a NotSupportedException.

public void Create(string sSecurityMediaID, string sUserName, string sPassphrase)

Parameters

sSecurityMediaID string
sUserName string
sPassphrase string

CreateContact() 

public FinContact CreateContact()

Returns

FinContact

Decrypt(FinContact, FinSecureKey, FinOperationMode, byte[]) 

public byte[] Decrypt(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, byte[] vbCrypt)

Parameters

aContact FinContact
aKey FinSecureKey
nOpMode FinOperationMode
vbCrypt byte[]

Returns

byte[]

ElevateKey(FinContact, FinSecureKey, FinSecureKeyState) 

public void ElevateKey(FinContact aContact, FinSecureKey aKey, FinSecureKeyState nNewKeyState)

Parameters

aContact FinContact
aKey FinSecureKey
nNewKeyState FinSecureKeyState

Encrypt(FinContact, FinSecureKey, FinOperationMode, byte[]) 

public byte[] Encrypt(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, byte[] vbData)

Parameters

aContact FinContact
aKey FinSecureKey
nOpMode FinOperationMode
vbData byte[]

Returns

byte[]

EraseContact(int) 

public void EraseContact(int nContactIndex)

Parameters

nContactIndex int

EraseKey(FinContact, FinSecureKey) 

public void EraseKey(FinContact aContact, FinSecureKey aKey)

Parameters

aContact FinContact
aKey FinSecureKey

ExtractField(byte[], int, int) 

protected string ExtractField(byte[] vbData, int nOffset, int nLength)

Parameters

vbData byte[]
nOffset int
nLength int

Returns

string

ExtractInteger(byte[], int, int) 

protected int ExtractInteger(byte[] vbData, int nOffset, int nLength)

Parameters

vbData byte[]
nOffset int
nLength int

Returns

int

GenerateKey(FinContact, FinSecureKeyType, int, int, int) 

public FinSecureKey GenerateKey(FinContact aContact, FinSecureKeyType nKeyType, int nKeyLength, int nKeyNumber, int nKeyVersion)

Parameters

aContact FinContact
nKeyType FinSecureKeyType
nKeyLength int
nKeyNumber int
nKeyVersion int

Returns

FinSecureKey

GetCardResourceManager() 

public static SCardResourceManager GetCardResourceManager()

Returns

SCardResourceManager

Returns an established SCardResourceManager instance or null. If a valid instance is returned, then the caller is responsible for finally releasing and disposing that instance.

GetContactIndex(FinContact)

Extract and validate the ContactIndex field from the given FinContact

protected int GetContactIndex(FinContact aContact)

Parameters

aContact FinContact

Returns

int

Exceptions

InvalidOperationException

The given FinContact does not have a ContactIndex field, or it is outside of the range supported by the card.

InitPassphrase(string, string) 

public FinAuthenticateResult InitPassphrase(string sUserName, string sPassphrase)

Parameters

sUserName string
sPassphrase string

Returns

FinAuthenticateResult

InsertField(byte[], int, int, string) 

protected void InsertField(byte[] vbData, int nOffset, int nLength, string sValue)

Parameters

vbData byte[]
nOffset int
nLength int
sValue string

InsertInteger(byte[], int, int, int) 

protected void InsertInteger(byte[] vbData, int nOffset, int nLength, int nValue)

Parameters

vbData byte[]
nOffset int
nLength int
nValue int

IsBlank(byte[])

Checks whether the given data is a blank record.

protected bool IsBlank(byte[] vbData)

Parameters

vbData byte[]

Returns

bool

Remarks

This method performs a special blank test. If the entire given byte array is filled with the very same byte value, then it is assumed that the array is fully blank.

ObtainContact(int) 

public FinContact ObtainContact(int nContactIndex)

Parameters

nContactIndex int

Returns

FinContact

ObtainKey(FinContact, FinSecureKeyType, int, int) 

public FinSecureKey ObtainKey(FinContact aContact, FinSecureKeyType nKeyType, int nKeyNumber, int nKeyVersion)

Parameters

aContact FinContact
nKeyType FinSecureKeyType
nKeyNumber int
nKeyVersion int

Returns

FinSecureKey

OnChangePin(string, string) 

protected virtual FinAuthenticateResult OnChangePin(string sOldPin, string sNewPin)

Parameters

sOldPin string
sNewPin string

Returns

FinAuthenticateResult

Remarks

Default implementation always throws a NotSupportedException.

OnChangePinSecure() 

protected virtual FinAuthenticateResult OnChangePinSecure()

Returns

FinAuthenticateResult

OnDecrypt(FinContact, FinSecureKey, FinOperationMode, byte[]) 

protected abstract byte[] OnDecrypt(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, byte[] vbCrypt)

Parameters

aContact FinContact
aKey FinSecureKey
nOpMode FinOperationMode
vbCrypt byte[]

Returns

byte[]

OnEncrypt(FinContact, FinSecureKey, FinOperationMode, byte[]) 

protected virtual byte[] OnEncrypt(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, byte[] vbData)

Parameters

aContact FinContact
aKey FinSecureKey
nOpMode FinOperationMode
vbData byte[]

Returns

byte[]

Remarks

Override this method in order to encrypt the given data with the smart card. The default implementation of this method just invokes Encrypt(FinOperationMode, byte[]).

OnEraseContact(int) 

protected virtual void OnEraseContact(int nContactIndex)

Parameters

nContactIndex int

OnEraseKey(FinContact, FinSecureKey) 

protected virtual void OnEraseKey(FinContact aContact, FinSecureKey aKey)

Parameters

aContact FinContact
aKey FinSecureKey

OnGenerateKey(FinContact, FinSecureKeyType, int, int, int) 

protected virtual FinSecureKey OnGenerateKey(FinContact aContact, FinSecureKeyType nKeyType, int nKeyLength, int nKeyNumber, int nKeyVersion)

Parameters

aContact FinContact
nKeyType FinSecureKeyType
nKeyLength int
nKeyNumber int
nKeyVersion int

Returns

FinSecureKey

OnGetCapabilities() 

protected abstract FinSecurityMediaCaps OnGetCapabilities()

Returns

FinSecurityMediaCaps

OnGetContactCapacity() 

protected abstract int OnGetContactCapacity()

Returns

int

OnGetMaxKeyLength() 

protected virtual int OnGetMaxKeyLength()

Returns

int

The default implementation always returns 96, the standard length for RDH-1 keys.

OnGetPassphraseFlags() 

protected abstract FinSecurityMediaPassphraseFlags OnGetPassphraseFlags()

Returns

FinSecurityMediaPassphraseFlags

OnGetPassphraseMaxLength() 

protected abstract int OnGetPassphraseMaxLength()

Returns

int

OnGetPassphraseMinLength() 

protected virtual int OnGetPassphraseMinLength()

Returns

int

Remarks

The default implementation always returns zero.

OnGetSecurityProfiles() 

protected virtual FinSecurityProfile[] OnGetSecurityProfiles()

Returns

FinSecurityProfile[]

OnInitContact(FinContact)

Override this method in order to provide additional initialisation for a new FinContact instance.

protected virtual void OnInitContact(FinContact aContact)

Parameters

aContact FinContact

Remarks

This method is invoked by the implementation of the CreateContact() after setting up appropriate default values for all required fields. The default implementation of OnInitContact does nothing.

OnInitPin(string) 

protected virtual FinAuthenticateResult OnInitPin(string sPin)

Parameters

sPin string

Returns

FinAuthenticateResult

Remarks

Default implementation always throws a NotSupportedException.

OnReadContact(FinContact, int) 

protected abstract void OnReadContact(FinContact aContact, int nContactIndex)

Parameters

aContact FinContact
nContactIndex int

OnReadKey(FinContact, FinSecureKeyType, int, int) 

protected abstract FinSecureKey OnReadKey(FinContact aContact, FinSecureKeyType nKeyType, int nKeyNumber, int nKeyVersion)

Parameters

aContact FinContact
nKeyType FinSecureKeyType
nKeyNumber int
nKeyVersion int

Returns

FinSecureKey

OnReleaseCard(CardExpress)

Must be overriden in order to clean up any context information that may have been collected since OnSelectCard(CardExpress) was called.

protected abstract void OnReleaseCard(CardExpress aCard)

Parameters

aCard CardExpress

OnSelectCard(CardExpress)

Must be override in order to implement selection of the card application.

protected abstract byte[] OnSelectCard(CardExpress aCard)

Parameters

aCard CardExpress

Handle to successfully connected card. The overriding method must use this handle in order to access the card.

Returns

byte[]

If successfull, then the unique card id (EF_ID or similar) must be returned. If the connected card does not appear to be supported, then null must be returned.

OnSignHash(FinContact, FinSecureKey, FinOperationMode, FinHash, byte[]) 

protected abstract byte[] OnSignHash(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, FinHash nHash, byte[] vbHash)

Parameters

aContact FinContact
aKey FinSecureKey
nOpMode FinOperationMode
nHash FinHash
vbHash byte[]

Returns

byte[]

OnUpdateKeyState(FinContact, FinSecureKey) 

protected virtual void OnUpdateKeyState(FinContact aContact, FinSecureKey aKey)

Parameters

aContact FinContact
aKey FinSecureKey

OnVerify(FinContact, FinSecureKey, FinOperationMode, FinHash, byte[], byte[]) 

protected virtual bool OnVerify(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, FinHash nHash, byte[] vbHash, byte[] vbSignature)

Parameters

aContact FinContact
aKey FinSecureKey
nOpMode FinOperationMode
nHash FinHash
vbHash byte[]
vbSignature byte[]

Returns

bool

Remarks

Override this method in order to verify the given signature with the smart card. The default implementation of this method just invokes Verify(FinOperationMode, FinHash, byte[], byte[]).

OnVerifyPin(string) 

protected abstract FinAuthenticateResult OnVerifyPin(string sPin)

Parameters

sPin string

PIN to verify. This is never null.

Returns

FinAuthenticateResult

OnVerifyPinOK()

Invoked whenever the PIN was successfully verified and the object switches into the Authenticated state.

protected virtual void OnVerifyPinOK()

OnVerifyPinSecure() 

protected abstract FinAuthenticateResult OnVerifyPinSecure()

Returns

FinAuthenticateResult

OnWriteContact(FinContact, int) 

protected virtual void OnWriteContact(FinContact aContact, int nContactIndex)

Parameters

aContact FinContact
nContactIndex int

Remarks

The default implementation does nothing. It is perfectly legal for an implementation to not store contact information and simply ignore the StoreContact call.

OnWriteKey(FinContact, FinSecureKey) 

protected virtual void OnWriteKey(FinContact aContact, FinSecureKey aKey)

Parameters

aContact FinContact
aKey FinSecureKey

ReadBinary(int, int) 

protected byte[] ReadBinary(int nOffset, int nLength)

Parameters

nOffset int
nLength int

Returns

byte[]

ReadByte(int) 

protected byte ReadByte(int nOffset)

Parameters

nOffset int

Returns

byte

ReadRecord(int, int) 

protected byte[] ReadRecord(int nRecNo, int nLength)

Parameters

nRecNo int
nLength int

Returns

byte[]

Release() 

public void Release()

ResetKey(FinContact, FinSecureKey) 

public void ResetKey(FinContact aContact, FinSecureKey aKey)

Parameters

aContact FinContact
aKey FinSecureKey

Select(string) 

public FinAuthenticateResult Select(string sSecurityMediaID)

Parameters

sSecurityMediaID string

Returns

FinAuthenticateResult

SelectCard(string) 

public string SelectCard(string sReaderName)

Parameters

sReaderName string

Returns

string

SelectFile(int) 

protected void SelectFile(int nFileID)

Parameters

nFileID int

SendCommand(CardCommandAPDU) 

protected CardResponseAPDU SendCommand(CardCommandAPDU aCmdAPDU)

Parameters

aCmdAPDU CardCommandAPDU

Returns

CardResponseAPDU

SignHash(FinContact, FinSecureKey, FinOperationMode, FinHash, byte[]) 

public byte[] SignHash(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, FinHash nHash, byte[] vbHash)

Parameters

aContact FinContact
aKey FinSecureKey
nOpMode FinOperationMode
nHash FinHash
vbHash byte[]

Returns

byte[]

StoreContact(int, FinContact) 

public void StoreContact(int nContactIndex, FinContact aContact)

Parameters

nContactIndex int
aContact FinContact

StoreKey(FinContact, FinSecureKey) 

public void StoreKey(FinContact aContact, FinSecureKey aKey)

Parameters

aContact FinContact
aKey FinSecureKey

UpdateBinary(int, byte[]) 

protected void UpdateBinary(int nOffset, byte[] vbData)

Parameters

nOffset int
vbData byte[]

UpdateByte(int, byte) 

protected void UpdateByte(int nOffset, byte nByte)

Parameters

nOffset int
nByte byte

UpdateRecord(int, byte[]) 

protected void UpdateRecord(int nRecNo, byte[] vbData)

Parameters

nRecNo int
vbData byte[]

Verify(FinContact, FinSecureKey, FinOperationMode, FinHash, byte[], byte[]) 

public bool Verify(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, FinHash nHash, byte[] vbHash, byte[] vbSignature)

Parameters

aContact FinContact
aKey FinSecureKey
nOpMode FinOperationMode
nHash FinHash
vbHash byte[]
vbSignature byte[]

Returns

bool

VerifyPin(CardPinControl, string) 

protected FinAuthenticateResult VerifyPin(CardPinControl aPinControl, string sPin)

Parameters

aPinControl CardPinControl
sPin string

Returns

FinAuthenticateResult

VerifyPinSecure(CardPinControl) 

protected FinAuthenticateResult VerifyPinSecure(CardPinControl aPinControl)

Parameters

aPinControl CardPinControl

Returns

FinAuthenticateResult