Class FinSecureKey

Holds a RSA key pair and its attributes.

Inheritance

System.Object

FinSecureKey

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: Subsembly.FinTS

Assembly: Subsembly.FinTS.Core.dll

Syntax

public class FinSecureKey

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, Int32, Int32) 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.

Declaration

public FinSecureKey()

FinSecureKey(Byte[], Byte[])

Creates a new FinSecureKey instance.

Declaration

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

Parameters

Type	Name	Description
System.Byte[]	vbModulus	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.
System.Byte[]	vbExponent	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

Type	Condition
System.ArgumentNullException	The parameter vbModulus is null.
System.ArgumentOutOfRangeException	The parameter nKeyLength is outside of the allowed range.
System.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.

Declaration

public const int DEFAULTKEYLENGTH = 96

Field Value

Type	Description
System.Int32

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.

Declaration

public const int MAXKEYLENGTH = 512

Field Value

Type	Description
System.Int32

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.

Declaration

public const int MINKEYLENGTH = 32

Field Value

Type	Description
System.Int32

Properties

BankCode

The bank code of the key name.

Declaration

public string BankCode { get; set; }

Property Value

Type	Description
System.String

Certificate

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

Declaration

public byte[] Certificate { get; set; }

Property Value

Type	Description
System.Byte[]

CertificateType

The type of certificate associated with this key.

Declaration

public int CertificateType { get; set; }

Property Value

Type	Description
System.Int32

CID

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

Declaration

public byte[] CID { get; set; }

Property Value

Type	Description
System.Byte[]

CountryCode

The country code of the key name.

Declaration

public string CountryCode { get; set; }

Property Value

Type	Description
System.String

IsPrivateRSA

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

Declaration

public bool IsPrivateRSA { get; }

Property Value

Type	Description
System.Boolean

IsRSA

Indicates whether this is a software RSA key.

Declaration

public bool IsRSA { get; }

Property Value

Type	Description
System.Boolean

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.

Declaration

public int KeyID { get; set; }

Property Value

Type	Description
System.Int32

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.

Declaration

public int KeyLength { get; }

Property Value

Type	Description
System.Int32

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.

Declaration

public int KeyNumber { get; set; }

Property Value

Type	Description
System.Int32	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.

Declaration

public FinSecureKeyState KeyState { get; set; }

Property Value

Type	Description
FinSecureKeyState

KeyType

The type of this key.

Declaration

public FinSecureKeyType KeyType { get; set; }

Property Value

Type	Description
FinSecureKeyType

KeyTypeLetter

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

Declaration

public string KeyTypeLetter { get; }

Property Value

Type	Description
System.String

KeyVersion

The key version in the range from zero through 998.

Declaration

public int KeyVersion { get; set; }

Property Value

Type	Description
System.Int32	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.

Declaration

public long SignatureID { get; set; }

Property Value

Type	Description
System.Int64

UserID

The user ID of the key name.

Declaration

public string UserID { get; set; }

Property Value

Type	Description
System.String

Methods

Clone()

Creates a new deep copy of this FinSecureKey instance.

Declaration

public FinSecureKey Clone()

Returns

Type	Description
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.

Declaration

public byte[] ComputeFingerprint(FinHash nHash)

Parameters

Type	Name	Description
FinHash	nHash	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

Type	Description
System.Byte[]

Exceptions

Type	Condition
System.InvalidOperationException	This is not a RSA key (see IsRSA).

Decrypt(FinOperationMode, Byte[])

Decrypt data using the private RSA value of this FinSecureKey.

Declaration

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

Parameters

Type	Name	Description
FinOperationMode	nOpMode	The cryptographic operation mode that shall be applied.
System.Byte[]	vbCrypt

Returns

Type	Description
System.Byte[]

Exceptions

Type	Condition
System.InvalidOperationException	This is not a RSA key pair (see IsPrivateRSA).

Encrypt(FinOperationMode, Byte[])

Encrypt data using the public RSA value of this FinSecureKey.

Declaration

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

Parameters

Type	Name	Description
FinOperationMode	nOpMode	The cryptographic operation mode that shall be applied.
System.Byte[]	vbData

Returns

Type	Description
System.Byte[]

Exceptions

Type	Condition
System.InvalidOperationException	This is not a RSA key (see IsRSA).

Generate(Int32)

Generates a new RSA key pair of the given length.

Declaration

public static FinSecureKey Generate(int nKeyLength)

Parameters

Type	Name	Description
System.Int32	nKeyLength	Byte length of the RSA keys to be generated. This must be in the range from MINKEYLENGTH to MAXKEYLENGTH.

Returns

Type	Description
FinSecureKey

GenerateHIISA(Int32, FinOperationMode)

Declaration

public FinSegment GenerateHIISA(int nSegmentVersion, FinOperationMode nOpMode)

Parameters

Type	Name	Description
System.Int32	nSegmentVersion
FinOperationMode	nOpMode

Returns

Type	Description
FinSegment

GetPublicExponent()

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

Declaration

public byte[] GetPublicExponent()

Returns

Type	Description
System.Byte[]	The public exponent or null if this is not a software RSA key.

GetPublicExponent(Byte[], Int32, Int32)

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

Declaration

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

Parameters

Type	Name	Description
System.Byte[]	vbBuffer
System.Int32	nOffset
System.Int32	nLength

Remarks

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

Exceptions

Type	Condition
System.ArgumentNullException	The parameter vbBuffer was null.
System.ArgumentOutOfRangeException	The parameter nOffset or nLength was invalid.

GetPublicModulus()

Provides the common public RSA modulus as a byte array.

Declaration

public byte[] GetPublicModulus()

Returns

Type	Description
System.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[], Int32, Int32)

Provides the common public RSA modulus as a byte array.

Declaration

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

Parameters

Type	Name	Description
System.Byte[]	vbBuffer
System.Int32	nOffset
System.Int32	nLength

Remarks

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

Exceptions

Type	Condition
System.ArgumentNullException	The parameter vbBuffer was null.
System.ArgumentOutOfRangeException	The parameter nOffset or nLength was invalid.

ParseHIISA(FinSegment)

Creates a new FinSecureKey instance from a given HIISA segment.

Declaration

public static FinSecureKey ParseHIISA(FinSegment aHIISA)

Parameters

Type	Name	Description
FinSegment	aHIISA

Returns

Type	Description
FinSecureKey

SignHash(FinOperationMode, FinHash, Byte[])

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

Declaration

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

Parameters

Type	Name	Description
FinOperationMode	nOpMode	The cryptographic operation mode that shall be applied.
FinHash	nHash	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.
System.Byte[]	vbHash

Returns

Type	Description
System.Byte[]

Exceptions

Type	Condition
System.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.

Declaration

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

Parameters

Type	Name	Description
FinOperationMode	nOpMode	The cryptographic operation mode that shall be applied.
FinHash	nHash	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.
System.Byte[]	vbHash
System.Byte[]	vbSignature

Returns

Type	Description
System.Boolean

Exceptions

Type	Condition
System.InvalidOperationException	This is not a RSA key (see IsRSA).