Class FinSecureKey

Namespace: Subsembly.FinTS

Assembly: Subsembly.FinTS.Core.dll

Holds a RSA key pair and its attributes.

public class FinSecureKey

Inheritance: object

FinSecureKey

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Every instance of the FinSecureKey is owned by a particular security media, represented by its IFinSecurityMedia implementation. Usually an instance of a FinSecureKey is obtained through the ObtainKey(FinContact, FinSecureKeyType, int, int) method of an IFinSecurityMedia implementation.

A FinSecureKey instance can hold a public/private key pair or just the public key. In the latter case, the private key can either be completely unknown, or is securely stored on the security media that owns this FinSecureKey instance.

Constructors

FinSecureKey()

Constructs a FinSecureKey instance without any RSA keys.

public FinSecureKey()

FinSecureKey(byte[], byte[])

Creates a new FinSecureKey instance.

public FinSecureKey(byte[] vbModulus, byte[] vbExponent)

Parameters

vbModulus byte[]: The common RSA modulus of the new key. Commonly known as the public key. Must not be null. Use the parameterless constructor in order to create a FinSecureKey instance for non-RSA keys.
vbExponent byte[]: Optionally, the private RSA exponent of the new key. Commonly known as the private key. May be null if this represents just the public RSA key.

Exceptions

ArgumentNullException: The parameter vbModulus is null.
ArgumentOutOfRangeException: The parameter nKeyLength is outside of the allowed range.
ArgumentException: The length of vbModulus or vbExponent is zero, or the significant length of vbModulus or vbExponent is greater than nKeyLength.

Fields

DEFAULTKEYLENGTH

The default key length.

public const int DEFAULTKEYLENGTH = 96

Field Value

int

MAXKEYLENGTH

The maximum key byte length that is supported is 512 bytes. This is also the maximum length of the corresponding key blobs in HBCI and FinTS segments.

public const int MAXKEYLENGTH = 512

Field Value

int

MINKEYLENGTH

The minimum key byte length that is allowed is arbitrarily chosen as 32 bytes by this constant. Actually valid HBCI RSA keys currently must not be shorter than 88 bytes with a minimum nominal length of 96 bytes.

public const int MINKEYLENGTH = 32

Field Value

int

Properties

BankCode

The bank code of the key name.

public string BankCode { get; set; }

Property Value

string

CID

Optional CID that shall be used with this key. If null, then no CID will be used.

public byte[] CID { get; set; }

Property Value

byte[]

Certificate

Optional certificate associated with this key. If null, then no certificate is available for this key.

public byte[] Certificate { get; set; }

Property Value

byte[]

CertificateType

The type of certificate associated with this key.

public int CertificateType { get; set; }

Property Value

int

CountryCode

The country code of the key name.

public string CountryCode { get; set; }

Property Value

string

IsPrivateRSA

Indicates whether this is a software RSA key pair with private key.

public bool IsPrivateRSA { get; }

Property Value

bool

IsRSA

Indicates whether this is a software RSA key.

public bool IsRSA { get; }

Property Value

bool

Remarks

This is true when this FinSecureKey is a software RSA key with at least the public key part. Use IsPrivateRSA in order to determine whether this is a software RSA key pair that includes the private and public key.

KeyID

The key identification that uniquely identifies the key on its security media.

public int KeyID { get; set; }

Property Value

int

Remarks

The KeyID is assigned by the IFinSecurityMedia implementation and should be of no meaning to application code, other than to reference that key.

KeyLength

The nominal byte length of the RSA keys.

public int KeyLength { get; }

Property Value

int

Remarks

For classic HBCI this is 96, even if the actual RSA key may be shorter. For longer RSA keys, this equals the number of bytes in the modulus. The value is always in the range from 96 to MAXKEYLENGTH. If this is not a RSA key, then the value is zero.

KeyNumber

The key number in the range from zero through 998.

public int KeyNumber { get; set; }

Property Value

int: The value 999 is reserved to designate the current key number, regardless of its value, and therefore cannot be explicitly assigned to any key.

KeyState

The current state of this key.

public FinSecureKeyState KeyState { get; set; }

Property Value

FinSecureKeyState

KeyType

The type of this key.

public FinSecureKeyType KeyType { get; set; }

Property Value

FinSecureKeyType

KeyTypeLetter

The key type expressed as a single letter according to HBCI.

public string KeyTypeLetter { get; }

Property Value

string

KeyVersion

The key version in the range from zero through 998.

public int KeyVersion { get; set; }

Property Value

int: The value 999 is reserved to designate the highest key version, regardless of its value, and therefore cannot be explicitly assigned to any key.

SignatureID

Optional signature counter associated with this key. If -1, then the signature counter is not maintained with the key, but rather must be maintained externally, e.g. in the FinContact instance.

public long SignatureID { get; set; }

Property Value

long

UserID

The user ID of the key name.

public string UserID { get; set; }

Property Value

string

Methods

Clone()

Creates a new deep copy of this FinSecureKey instance.

public FinSecureKey Clone()

Returns

FinSecureKey

ComputeFingerprint(FinHash)

Computes the hash value over the public key which is used in the Ini-Letter and is also stored on ZKA SECCOS cards.

public byte[] ComputeFingerprint(FinHash nHash)

Parameters

nHash FinHash: NEW: The desired hash algorithm for computing the fingerprint must be provided. This used to be RIPEMD-160 in all cases, but may now also be SHA-256 in some cases.

Returns

byte[]

Exceptions

InvalidOperationException: This is not a RSA key (see IsRSA).

Decrypt(FinOperationMode, byte[])

Decrypt data using the private RSA value of this FinSecureKey.

public byte[] Decrypt(FinOperationMode nOpMode, byte[] vbCrypt)

Parameters

nOpMode FinOperationMode: The cryptographic operation mode that shall be applied.
vbCrypt byte[]

Returns

byte[]

Exceptions

InvalidOperationException: This is not a RSA key pair (see IsPrivateRSA).

Encrypt(FinOperationMode, byte[])

Encrypt data using the public RSA value of this FinSecureKey.

public byte[] Encrypt(FinOperationMode nOpMode, byte[] vbData)

Parameters

nOpMode FinOperationMode: The cryptographic operation mode that shall be applied.
vbData byte[]

Returns

byte[]

Exceptions

InvalidOperationException: This is not a RSA key (see IsRSA).

Generate(int)

Generates a new RSA key pair of the given length.

public static FinSecureKey Generate(int nKeyLength)

Parameters

nKeyLength int: Byte length of the RSA keys to be generated. This must be in the range from MINKEYLENGTH to MAXKEYLENGTH.

Returns

FinSecureKey

GenerateHIISA(int, FinOperationMode)

public FinSegment GenerateHIISA(int nSegmentVersion, FinOperationMode nOpMode)

Parameters

nSegmentVersion int
nOpMode FinOperationMode

Returns

FinSegment

GetPublicExponent()

Provides the public RSA exponent (which is always Fermat 4) as a byte array.

public byte[] GetPublicExponent()

Returns

byte[]: The public exponent or null if this is not a software RSA key.

GetPublicExponent(byte[], int, int)

Provides the public RSA exponent (which is always Fermat 4) as a byte array.

public void GetPublicExponent(byte[] vbBuffer, int nOffset, int nLength)

Parameters

vbBuffer byte[]
nOffset int
nLength int

Remarks

If this is not a software RSA key, then the destination bytes of the byte array are cleared.

Exceptions

ArgumentNullException: The parameter vbBuffer was null.
ArgumentOutOfRangeException: The parameter nOffset or nLength was invalid.

GetPublicModulus()

Provides the common public RSA modulus as a byte array.

public byte[] GetPublicModulus()

Returns

byte[]: Returns a compact byte array that contains only the significant bytes of the public modulus. If this is not a software RSA key, then null is returned.

GetPublicModulus(byte[], int, int)

Provides the common public RSA modulus as a byte array.

public void GetPublicModulus(byte[] vbBuffer, int nOffset, int nLength)

Parameters

vbBuffer byte[]
nOffset int
nLength int

Remarks

If this is not a software RSA key, then the destination bytes of the byte array are cleared.

Exceptions

ArgumentNullException: The parameter vbBuffer was null.
ArgumentOutOfRangeException: The parameter nOffset or nLength was invalid.

ParseHIISA(FinSegment)

Creates a new FinSecureKey instance from a given HIISA segment.

public static FinSecureKey ParseHIISA(FinSegment aHIISA)

Parameters

aHIISA FinSegment

Returns

FinSecureKey

SignHash(FinOperationMode, FinHash, byte[])

Sign hash value using the private RSA value of this FinSecureKey.

public byte[] SignHash(FinOperationMode nOpMode, FinHash nHash, byte[] vbHash)

Parameters

nOpMode FinOperationMode: The cryptographic operation mode that shall be applied.
nHash FinHash: Identifies the hash algorithm that was used to produce the hash value. This is neeed for properly formatting the hash value for the signature operation.
vbHash byte[]

Returns

byte[]

Exceptions

InvalidOperationException: This is not a RSA key pair (see IsPrivateRSA).

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

Verify hash value using the public RSA value of this FinSecureKey.

public bool Verify(FinOperationMode nOpMode, FinHash nHash, byte[] vbHash, byte[] vbSignature)

Parameters

nOpMode FinOperationMode: The cryptographic operation mode that shall be applied.
nHash FinHash: Identifies the hash algorithm that was used to produce the hash value. This is neeed for properly formatting the hash value for the verify operation.
vbHash byte[]
vbSignature byte[]

Returns

bool

Exceptions

InvalidOperationException: This is not a RSA key (see IsRSA).