Class PrivateKey

A secret part of a key pair involved in ECDSA, the digital signature algorithm on which the Libplanet is based. It can be used to create signatures, which can be verified with the corresponding PublicKey, as well as to decrypt messages which were encrypted with the corresponding PublicKey.

Note that it uses secp256k1 as the parameters of the elliptic curve, which is the same to Bitcoin and Ethereum. It means private keys generated for Bitcoin/Ethereum can be used by Libplanet-backed games/apps too.

Inheritance

Object

PrivateKey

Inherited Members

Object.Equals(Object)

Object.Equals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ReferenceEquals(Object, Object)

Object.ToString()

Namespace: Libplanet.Crypto

Assembly: Libplanet.dll

Syntax

public class PrivateKey

Remarks

These (and any derived representations, e.g., ByteArray) must be kept secret, if they are exposed, an attacker will be able to forge signatures.

Every PrivateKey object is immutable.

Constructors

PrivateKey()

Generates a new unique PrivateKey instance. It can be analogous to creating a new account in a degree.

Declaration

public PrivateKey()

PrivateKey(IReadOnlyList<Byte>)

Creates a PrivateKey instance from the given Bytes (i.e., privateKey), which encodes a valid ECDSA private key.

Declaration

public PrivateKey(IReadOnlyList<byte> privateKey)

Parameters

Type	Name	Description
IReadOnlyList<Byte>	privateKey	A valid Bytes that encodes an ECDSA private key.

Remarks

A valid Byte array for a PrivateKey can be encoded using ByteArray property.

See Also

ByteArray

Properties

ByteArray

An encoded Byte array representation.

Declaration

[Pure]
public ImmutableArray<byte> ByteArray { get; }

Property Value

Type	Description
ImmutableArray<Byte>

Remarks

An encoded Byte array representation can be recovered to a PrivateKey instance again using PrivateKey(IReadOnlyList<Byte>) constructor.

As like PrivateKey instances, it also must be kept secret. In practice, this must not be sent over the network, and be securely stored in the file system. If you just want to store the in-memory private key in the persistent storage, use ProtectedPrivateKey or Web3KeyStore.

To get a mutable array instead of immutable one, use ToByteArray() method instead.

See Also

ToByteArray()

PrivateKey(IReadOnlyList<Byte>)

PublicKey

The corresponding PublicKey of this private key.

Declaration

public PublicKey PublicKey { get; }

Property Value

Type	Description
PublicKey

Methods

Decrypt(ImmutableArray<Byte>)

Decrypts a ciphertext which was encrypted with the corresponding PublicKey to the original plain text.

Declaration

[Pure]
public ImmutableArray<byte> Decrypt(ImmutableArray<byte> ciphertext)

Parameters

Type	Name	Description
ImmutableArray<Byte>	ciphertext	The encrypted message.

Returns

Type	Description
ImmutableArray<Byte>	The decrypted original message.

Remarks

Although the parameter name ciphertext has the word “text”, both a ciphertext and a returned message are Bytes, not Unicode Strings.

Exceptions

Type	Condition
InvalidCiphertextException	Thrown when the given ciphertext is invalid.

See Also

Encrypt(ImmutableArray<Byte>)

Decrypt(Byte[])

Decrypts a ciphertext which was encrypted with the corresponding PublicKey to the original plain text.

Declaration

[Pure]
public byte[] Decrypt(byte[] ciphertext)

Parameters

Type	Name	Description
Byte[]	ciphertext	The encrypted message.

Returns

Type	Description
Byte[]	The decrypted original message.

Remarks

Although the parameter name ciphertext has the word “text”, both a ciphertext and a returned message are Bytes, not Unicode Strings.

Exceptions

Type	Condition
InvalidCiphertextException	Thrown when the given ciphertext is invalid.

See Also

Encrypt(Byte[])

ExchangeKey(PublicKey)

Securely exchange a SymmetricKey with a peer's PublicKey. Two parties can agree on a (new, unique, and typically temporal) key without revealing to any eavesdropping party what key has been agreed upon.

Technically it is ECDH, a Diffie–Hellman key exchange of elliptic-curve version.

Declaration

[Pure]
public SymmetricKey ExchangeKey(PublicKey publicKey)

Parameters

Type	Name	Description
PublicKey	publicKey	The PublicKey possessed by a peer to whom exchange a private key with.

Returns

Type	Description
SymmetricKey	An exchanged (agreed) SymmetricKey. Note that it is not an elliptic-curve private key, but an AES key.

FromString(String)

Creates a PrivateKey instance from hexadecimal string of bytes.

Declaration

[Pure]
public static PrivateKey FromString(string hex)

Parameters

Type	Name	Description
String	hex	A hexadecimal string of a private key's ByteArray.

Returns

Type	Description
PrivateKey	A created PrivateKey instance.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the given hex string is null.
ArgumentOutOfRangeException	Thrown when the length of the given hex string is an odd number, or it is empty.
FormatException	Thrown when the given hex string is not a valid hexadecimal string.

Sign(ImmutableArray<Byte>)

Creates a signature from the given message.

A created signature can be verified by the corresponding PublicKey.

Signatures can be created by only the PrivateKey which corresponds a PublicKey to verify these signatures.

To sum up, a signature is used to guarantee:

• that the message was created by someone possessing the corresponding PrivateKey,
• that the possessor cannot deny having sent the message, and
• that the message was not forged in the middle of transit.

Declaration

public ImmutableArray<byte> Sign(ImmutableArray<byte> message)

Parameters

Type	Name	Description
ImmutableArray<Byte>	message	A message Bytes to sign.

Returns

Type	Description
ImmutableArray<Byte>	A signature that proves the authenticity of the message. It can be verified using Verify(IReadOnlyList<Byte>, IReadOnlyList<Byte>) method.

See Also

Verify(IReadOnlyList<Byte>, IReadOnlyList<Byte>)

Sign(Byte[])

Creates a signature from the given message.

A created signature can be verified by the corresponding PublicKey.

Signatures can be created by only the PrivateKey which corresponds a PublicKey to verify these signatures.

To sum up, a signature is used to guarantee:

• that the message was created by someone possessing the corresponding PrivateKey,
• that the possessor cannot deny having sent the message, and
• that the message was not forged in the middle of transit.

Declaration

public byte[] Sign(byte[] message)

Parameters

Type	Name	Description
Byte[]	message	A message Bytes to sign.

Returns

Type	Description
Byte[]	A signature that proves the authenticity of the message. It can be verified using Verify(IReadOnlyList<Byte>, IReadOnlyList<Byte>) method.

See Also

Verify(IReadOnlyList<Byte>, IReadOnlyList<Byte>)

ToByteArray()

Encodes the private key into a corresponding mutable Byte array representation.

Declaration

[Pure]
public byte[] ToByteArray()

Returns

Type	Description
Byte[]	An encoded Byte array representation. It guarantees that returned arrays are never reused, and mutating on them does not affect PrivateKey instance's internal states.

Remarks

An encoded Byte array representation can be recovered to a PrivateKey instance again using PrivateKey(IReadOnlyList<Byte>) constructor.

As like PrivateKey instances, it also must be kept secret. In practice, this must not be sent over the network, and be securely stored in the file system. If you just want to store the in-memory private key in the persistent storage, use ProtectedPrivateKey or Web3KeyStore.

To get an immutable array instead of mutable one, use ByteArray property.

See Also

ByteArray

PrivateKey(IReadOnlyList<Byte>)

Operators

Equality(PrivateKey, PrivateKey)

Declaration

public static bool operator ==(PrivateKey left, PrivateKey right)

Parameters

Type	Name	Description
PrivateKey	left
PrivateKey	right

Returns

Type	Description
Boolean

Inequality(PrivateKey, PrivateKey)

Declaration

public static bool operator !=(PrivateKey left, PrivateKey right)

Parameters

Type	Name	Description
PrivateKey	left
PrivateKey	right

Returns

Type	Description
Boolean

Extension Methods

AddressExtensions.ToAddress(PrivateKey)

See Also

PublicKey