Class FinSecurityMediaSmartCard

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

Inheritance
System.Object
FinSecurityMediaSmartCard
FinSecurityMediaGDM
FinSecurityMediaZKA
Implements
Inherited Members
System.Object.ToString()
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Subsembly.FinTS
Assembly: Subsembly.FinTS.SmartCard.dll
Syntax
public abstract class FinSecurityMediaSmartCard : IFinSecurityMedia, IFinSecurityMediaSmartCard
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()

Declaration
public FinSecurityMediaSmartCard()

Properties

Capabilities

Delegates to OnGetCapabilities()

Declaration
public FinSecurityMediaCaps Capabilities { get; }
Property Value
Type Description
FinSecurityMediaCaps

Card

Declaration
protected CardExpress Card { get; }
Property Value
Type Description
Subsembly.SmartCard.CardExpress

CardEncoding

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

Declaration
protected Encoding CardEncoding { get; set; }
Property Value
Type Description
System.Text.Encoding
Remarks

The default Encoding is Windows 1252 encoding.

CardID

Declaration
protected byte[] CardID { get; }
Property Value
Type Description
System.Byte[]

ContactCapacity

Delegates to OnGetContactCapacity()

Declaration
public int ContactCapacity { get; }
Property Value
Type Description
System.Int32

MaxKeyLength

Delegates to OnGetMaxKeyLength()

Declaration
public int MaxKeyLength { get; }
Property Value
Type Description
System.Int32

PassphraseFlags

Delegates to OnGetPassphraseFlags()

Declaration
public FinSecurityMediaPassphraseFlags PassphraseFlags { get; }
Property Value
Type Description
FinSecurityMediaPassphraseFlags

PassphraseMaxLength

Delegates to OnGetPassphraseMaxLength()

Declaration
public int PassphraseMaxLength { get; }
Property Value
Type Description
System.Int32

PassphraseMinLength

Delegates to OnGetPassphraseMinLength()

Declaration
public int PassphraseMinLength { get; }
Property Value
Type Description
System.Int32

SecurityMediaID

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

Declaration
public string SecurityMediaID { get; }
Property Value
Type Description
System.String

SecurityMediaType

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

Declaration
public FinSecurityMediaType SecurityMediaType { get; }
Property Value
Type Description
FinSecurityMediaType

SecurityProfiles

Declaration
public FinSecurityProfile[] SecurityProfiles { get; }
Property Value
Type Description
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.

Declaration
public FinSecurityMediaState State { get; }
Property Value
Type Description
FinSecurityMediaState

Methods

Authenticate(String, String)

Declaration
public FinAuthenticateResult Authenticate(string sUserName, string sPassphrase)
Parameters
Type Name Description
System.String sUserName
System.String sPassphrase
Returns
Type Description
FinAuthenticateResult

AuthenticateAdmin(String, String)

Declaration
public FinAuthenticateResult AuthenticateAdmin(string sUserName, string sAdminPassphrase)
Parameters
Type Name Description
System.String sUserName
System.String sAdminPassphrase
Returns
Type Description
FinAuthenticateResult

AuthenticateSecure()

Declaration
public FinAuthenticateResult AuthenticateSecure()
Returns
Type Description
FinAuthenticateResult

CanAuthenticateSecure()

Declaration
public bool CanAuthenticateSecure()
Returns
Type Description
System.Boolean

Cancel()

Declaration
public void Cancel()

CanChangePassphraseSecure()

Declaration
public bool CanChangePassphraseSecure()
Returns
Type Description
System.Boolean

ChangePassphrase(String, String, String)

Declaration
public FinAuthenticateResult ChangePassphrase(string sUserName, string sOldPassphrase, string sNewPassphrase)
Parameters
Type Name Description
System.String sUserName
System.String sOldPassphrase
System.String sNewPassphrase
Returns
Type Description
FinAuthenticateResult

ChangePassphraseSecure()

Declaration
public FinAuthenticateResult ChangePassphraseSecure()
Returns
Type Description
FinAuthenticateResult

ChangePin(CardPinControl, String, String)

Declaration
protected FinAuthenticateResult ChangePin(CardPinControl aPinControl, string sOldPin, string sNewPin)
Parameters
Type Name Description
Subsembly.SmartCard.CardPinControl aPinControl
System.String sOldPin
System.String sNewPin
Returns
Type Description
FinAuthenticateResult

ChangePinSecure(CardPinControl)

Declaration
protected FinAuthenticateResult ChangePinSecure(CardPinControl aPinControl)
Parameters
Type Name Description
Subsembly.SmartCard.CardPinControl aPinControl
Returns
Type Description
FinAuthenticateResult

Create(String, String, String)

Always throws a NotSupportedException.

Declaration
public void Create(string sSecurityMediaID, string sUserName, string sPassphrase)
Parameters
Type Name Description
System.String sSecurityMediaID
System.String sUserName
System.String sPassphrase

CreateContact()

Declaration
public FinContact CreateContact()
Returns
Type Description
FinContact

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

Declaration
public byte[] Decrypt(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, byte[] vbCrypt)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinOperationMode nOpMode
System.Byte[] vbCrypt
Returns
Type Description
System.Byte[]

ElevateKey(FinContact, FinSecureKey, FinSecureKeyState)

Declaration
public void ElevateKey(FinContact aContact, FinSecureKey aKey, FinSecureKeyState nNewKeyState)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinSecureKeyState nNewKeyState

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

Declaration
public byte[] Encrypt(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, byte[] vbData)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinOperationMode nOpMode
System.Byte[] vbData
Returns
Type Description
System.Byte[]

EraseContact(Int32)

Declaration
public void EraseContact(int nContactIndex)
Parameters
Type Name Description
System.Int32 nContactIndex

EraseKey(FinContact, FinSecureKey)

Declaration
public void EraseKey(FinContact aContact, FinSecureKey aKey)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey

ExtractField(Byte[], Int32, Int32)

Declaration
protected string ExtractField(byte[] vbData, int nOffset, int nLength)
Parameters
Type Name Description
System.Byte[] vbData
System.Int32 nOffset
System.Int32 nLength
Returns
Type Description
System.String

ExtractInteger(Byte[], Int32, Int32)

Declaration
protected int ExtractInteger(byte[] vbData, int nOffset, int nLength)
Parameters
Type Name Description
System.Byte[] vbData
System.Int32 nOffset
System.Int32 nLength
Returns
Type Description
System.Int32

GenerateKey(FinContact, FinSecureKeyType, Int32, Int32, Int32)

Declaration
public FinSecureKey GenerateKey(FinContact aContact, FinSecureKeyType nKeyType, int nKeyLength, int nKeyNumber, int nKeyVersion)
Parameters
Type Name Description
FinContact aContact
FinSecureKeyType nKeyType
System.Int32 nKeyLength
System.Int32 nKeyNumber
System.Int32 nKeyVersion
Returns
Type Description
FinSecureKey

GetCardResourceManager()

Declaration
public static SCardResourceManager GetCardResourceManager()
Returns
Type Description
Subsembly.SmartCard.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

Declaration
protected int GetContactIndex(FinContact aContact)
Parameters
Type Name Description
FinContact aContact
Returns
Type Description
System.Int32
Exceptions
Type Condition
System.InvalidOperationException

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

InitPassphrase(String, String)

Declaration
public FinAuthenticateResult InitPassphrase(string sUserName, string sPassphrase)
Parameters
Type Name Description
System.String sUserName
System.String sPassphrase
Returns
Type Description
FinAuthenticateResult

InsertField(Byte[], Int32, Int32, String)

Declaration
protected void InsertField(byte[] vbData, int nOffset, int nLength, string sValue)
Parameters
Type Name Description
System.Byte[] vbData
System.Int32 nOffset
System.Int32 nLength
System.String sValue

InsertInteger(Byte[], Int32, Int32, Int32)

Declaration
protected void InsertInteger(byte[] vbData, int nOffset, int nLength, int nValue)
Parameters
Type Name Description
System.Byte[] vbData
System.Int32 nOffset
System.Int32 nLength
System.Int32 nValue

IsBlank(Byte[])

Checks whether the given data is a blank record.

Declaration
protected bool IsBlank(byte[] vbData)
Parameters
Type Name Description
System.Byte[] vbData
Returns
Type Description
System.Boolean
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(Int32)

Declaration
public FinContact ObtainContact(int nContactIndex)
Parameters
Type Name Description
System.Int32 nContactIndex
Returns
Type Description
FinContact

ObtainKey(FinContact, FinSecureKeyType, Int32, Int32)

Declaration
public FinSecureKey ObtainKey(FinContact aContact, FinSecureKeyType nKeyType, int nKeyNumber, int nKeyVersion)
Parameters
Type Name Description
FinContact aContact
FinSecureKeyType nKeyType
System.Int32 nKeyNumber
System.Int32 nKeyVersion
Returns
Type Description
FinSecureKey

OnChangePin(String, String)

Declaration
protected virtual FinAuthenticateResult OnChangePin(string sOldPin, string sNewPin)
Parameters
Type Name Description
System.String sOldPin
System.String sNewPin
Returns
Type Description
FinAuthenticateResult
Remarks

Default implementation always throws a NotSupportedException.

OnChangePinSecure()

Declaration
protected virtual FinAuthenticateResult OnChangePinSecure()
Returns
Type Description
FinAuthenticateResult

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

Declaration
protected abstract byte[] OnDecrypt(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, byte[] vbCrypt)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinOperationMode nOpMode
System.Byte[] vbCrypt
Returns
Type Description
System.Byte[]

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

Declaration
protected virtual byte[] OnEncrypt(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, byte[] vbData)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinOperationMode nOpMode
System.Byte[] vbData
Returns
Type Description
System.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(Int32)

Declaration
protected virtual void OnEraseContact(int nContactIndex)
Parameters
Type Name Description
System.Int32 nContactIndex

OnEraseKey(FinContact, FinSecureKey)

Declaration
protected virtual void OnEraseKey(FinContact aContact, FinSecureKey aKey)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey

OnGenerateKey(FinContact, FinSecureKeyType, Int32, Int32, Int32)

Declaration
protected virtual FinSecureKey OnGenerateKey(FinContact aContact, FinSecureKeyType nKeyType, int nKeyLength, int nKeyNumber, int nKeyVersion)
Parameters
Type Name Description
FinContact aContact
FinSecureKeyType nKeyType
System.Int32 nKeyLength
System.Int32 nKeyNumber
System.Int32 nKeyVersion
Returns
Type Description
FinSecureKey

OnGetCapabilities()

Declaration
protected abstract FinSecurityMediaCaps OnGetCapabilities()
Returns
Type Description
FinSecurityMediaCaps

OnGetContactCapacity()

Declaration
protected abstract int OnGetContactCapacity()
Returns
Type Description
System.Int32

OnGetMaxKeyLength()

Declaration
protected virtual int OnGetMaxKeyLength()
Returns
Type Description
System.Int32

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

OnGetPassphraseFlags()

Declaration
protected abstract FinSecurityMediaPassphraseFlags OnGetPassphraseFlags()
Returns
Type Description
FinSecurityMediaPassphraseFlags

OnGetPassphraseMaxLength()

Declaration
protected abstract int OnGetPassphraseMaxLength()
Returns
Type Description
System.Int32

OnGetPassphraseMinLength()

Declaration
protected virtual int OnGetPassphraseMinLength()
Returns
Type Description
System.Int32
Remarks

The default implementation always returns zero.

OnGetSecurityProfiles()

Declaration
protected virtual FinSecurityProfile[] OnGetSecurityProfiles()
Returns
Type Description
FinSecurityProfile[]

OnInitContact(FinContact)

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

Declaration
protected virtual void OnInitContact(FinContact aContact)
Parameters
Type Name Description
FinContact aContact
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)

Declaration
protected virtual FinAuthenticateResult OnInitPin(string sPin)
Parameters
Type Name Description
System.String sPin
Returns
Type Description
FinAuthenticateResult
Remarks

Default implementation always throws a NotSupportedException.

OnReadContact(FinContact, Int32)

Declaration
protected abstract void OnReadContact(FinContact aContact, int nContactIndex)
Parameters
Type Name Description
FinContact aContact
System.Int32 nContactIndex

OnReadKey(FinContact, FinSecureKeyType, Int32, Int32)

Declaration
protected abstract FinSecureKey OnReadKey(FinContact aContact, FinSecureKeyType nKeyType, int nKeyNumber, int nKeyVersion)
Parameters
Type Name Description
FinContact aContact
FinSecureKeyType nKeyType
System.Int32 nKeyNumber
System.Int32 nKeyVersion
Returns
Type Description
FinSecureKey

OnReleaseCard(CardExpress)

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

Declaration
protected abstract void OnReleaseCard(CardExpress aCard)
Parameters
Type Name Description
Subsembly.SmartCard.CardExpress aCard

OnSelectCard(CardExpress)

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

Declaration
protected abstract byte[] OnSelectCard(CardExpress aCard)
Parameters
Type Name Description
Subsembly.SmartCard.CardExpress aCard

Handle to successfully connected card. The overriding method must use this handle in order to access the card.
Returns
Type Description
System.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[])

Declaration
protected abstract byte[] OnSignHash(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, FinHash nHash, byte[] vbHash)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinOperationMode nOpMode
FinHash nHash
System.Byte[] vbHash
Returns
Type Description
System.Byte[]

OnUpdateKeyState(FinContact, FinSecureKey)

Declaration
protected virtual void OnUpdateKeyState(FinContact aContact, FinSecureKey aKey)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey

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

Declaration
protected virtual bool OnVerify(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, FinHash nHash, byte[] vbHash, byte[] vbSignature)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinOperationMode nOpMode
FinHash nHash
System.Byte[] vbHash
System.Byte[] vbSignature
Returns
Type Description
System.Boolean
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)

Declaration
protected abstract FinAuthenticateResult OnVerifyPin(string sPin)
Parameters
Type Name Description
System.String sPin

PIN to verify. This is never null.
Returns
Type Description
FinAuthenticateResult

OnVerifyPinOK()

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

Declaration
protected virtual void OnVerifyPinOK()

OnVerifyPinSecure()

Declaration
protected abstract FinAuthenticateResult OnVerifyPinSecure()
Returns
Type Description
FinAuthenticateResult

OnWriteContact(FinContact, Int32)

Declaration
protected virtual void OnWriteContact(FinContact aContact, int nContactIndex)
Parameters
Type Name Description
FinContact aContact
System.Int32 nContactIndex
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)

Declaration
protected virtual void OnWriteKey(FinContact aContact, FinSecureKey aKey)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey

ReadBinary(Int32, Int32)

Declaration
protected byte[] ReadBinary(int nOffset, int nLength)
Parameters
Type Name Description
System.Int32 nOffset
System.Int32 nLength
Returns
Type Description
System.Byte[]

ReadByte(Int32)

Declaration
protected byte ReadByte(int nOffset)
Parameters
Type Name Description
System.Int32 nOffset
Returns
Type Description
System.Byte

ReadRecord(Int32, Int32)

Declaration
protected byte[] ReadRecord(int nRecNo, int nLength)
Parameters
Type Name Description
System.Int32 nRecNo
System.Int32 nLength
Returns
Type Description
System.Byte[]

Release()

Declaration
public void Release()

ResetKey(FinContact, FinSecureKey)

Declaration
public void ResetKey(FinContact aContact, FinSecureKey aKey)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey

Select(String)

Declaration
public FinAuthenticateResult Select(string sSecurityMediaID)
Parameters
Type Name Description
System.String sSecurityMediaID
Returns
Type Description
FinAuthenticateResult

SelectCard(String)

Declaration
public string SelectCard(string sReaderName)
Parameters
Type Name Description
System.String sReaderName
Returns
Type Description
System.String

SelectFile(Int32)

Declaration
protected void SelectFile(int nFileID)
Parameters
Type Name Description
System.Int32 nFileID

SendCommand(CardCommandAPDU)

Declaration
protected CardResponseAPDU SendCommand(CardCommandAPDU aCmdAPDU)
Parameters
Type Name Description
Subsembly.SmartCard.CardCommandAPDU aCmdAPDU
Returns
Type Description
Subsembly.SmartCard.CardResponseAPDU

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

Declaration
public byte[] SignHash(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, FinHash nHash, byte[] vbHash)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinOperationMode nOpMode
FinHash nHash
System.Byte[] vbHash
Returns
Type Description
System.Byte[]

StoreContact(Int32, FinContact)

Declaration
public void StoreContact(int nContactIndex, FinContact aContact)
Parameters
Type Name Description
System.Int32 nContactIndex
FinContact aContact

StoreKey(FinContact, FinSecureKey)

Declaration
public void StoreKey(FinContact aContact, FinSecureKey aKey)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey

UpdateBinary(Int32, Byte[])

Declaration
protected void UpdateBinary(int nOffset, byte[] vbData)
Parameters
Type Name Description
System.Int32 nOffset
System.Byte[] vbData

UpdateByte(Int32, Byte)

Declaration
protected void UpdateByte(int nOffset, byte nByte)
Parameters
Type Name Description
System.Int32 nOffset
System.Byte nByte

UpdateRecord(Int32, Byte[])

Declaration
protected void UpdateRecord(int nRecNo, byte[] vbData)
Parameters
Type Name Description
System.Int32 nRecNo
System.Byte[] vbData

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

Declaration
public bool Verify(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, FinHash nHash, byte[] vbHash, byte[] vbSignature)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinOperationMode nOpMode
FinHash nHash
System.Byte[] vbHash
System.Byte[] vbSignature
Returns
Type Description
System.Boolean

VerifyPin(CardPinControl, String)

Declaration
protected FinAuthenticateResult VerifyPin(CardPinControl aPinControl, string sPin)
Parameters
Type Name Description
Subsembly.SmartCard.CardPinControl aPinControl
System.String sPin
Returns
Type Description
FinAuthenticateResult

VerifyPinSecure(CardPinControl)

Declaration
protected FinAuthenticateResult VerifyPinSecure(CardPinControl aPinControl)
Parameters
Type Name Description
Subsembly.SmartCard.CardPinControl aPinControl
Returns
Type Description
FinAuthenticateResult

Implements