Class Argon2Memory

Manages memory for a Argon2.

Inheritance

object

Argon2Memory

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Isopoh.Cryptography.Argon2

Assembly: Isopoh.Cryptography.Argon2.dll

Syntax

public sealed class Argon2Memory : IDisposable

Constructors

| Edit this page View Source

Argon2Memory(Argon2Config, Argon2MemoryPolicy, LockMemoryPolicy?)

Initializes a new instance of the Argon2Memory class.

Declaration

public Argon2Memory(Argon2Config config, Argon2MemoryPolicy shrinkMemoryPolicy, LockMemoryPolicy? lockMemory)

Parameters

Type	Name	Description
Argon2Config	config	The initial configuration to use. Can be updated later with a call to Reset(Argon2Config) (or Reset(string, Argon2Password)).
Argon2MemoryPolicy	shrinkMemoryPolicy	Indicates whether to shrink memory to fit upon calling Reset(string, Argon2Password) or Reset(Argon2Config) with an Argon2Config that requires less memory. Note: the memory will always grow as needed.
LockMemoryPolicy?	lockMemory	The lock memory policy to use. Null to not secure memory at all.

Fields

| Edit this page View Source

Argon2WorkingBufferSize

Size in bytes required for the Argon2 working buffer.

Declaration

public const int Argon2WorkingBufferSize = 2560

Field Value

Type	Description
int

| Edit this page View Source

CsharpMaxBlocksPerArray

C# has a limit of 0X7FEFFFFF elements per array (0x7FFFFFC7 per byte array). The blocks are 1024 bytes long, the elements are 8 bytes (ulong). This gives 0X7FEFFFFF / 128 blocks per C# array.

Declaration

public const int CsharpMaxBlocksPerArray = 16769023

Field Value

Type	Description
int

Properties

| Edit this page View Source

Argon2WorkingBuffer

Gets the byte-based working buffer sized for Argon2 to use internally.

Declaration

public Memory<byte> Argon2WorkingBuffer { get; }

Property Value

Type	Description
Memory<byte>

Remarks

This gets used and overwritten on every hash.

| Edit this page View Source

AssociatedData

Gets the associated data used in the password hash.

Declaration

public Span<byte> AssociatedData { get; }

Property Value

Type	Description
Span<byte>

| Edit this page View Source

BlockCount

Gets the memory block count for the latest Argon2Config that this Argon2Memory supports.

Declaration

public int BlockCount { get; }

Property Value

Type	Description
int

Remarks

Can change on every call to Reset(string, Argon2Password) or Reset(Argon2Config).

| Edit this page View Source

Blocks

Gets the Blocks for this Argon2Memory.

Declaration

public Blocks Blocks { get; }

Property Value

Type	Description
Blocks

Remarks

This gets used and overwritten on every hash.

Can change on every call to Reset(string, Argon2Password) or Reset(Argon2Config).

| Edit this page View Source

ClearPassword

Gets a value indicating whether to clear the password as soon as it is no longer needed.

Declaration

public bool ClearPassword { get; }

Property Value

Type	Description
bool

Remarks

If true and the configuration has a password, the configuration cannot be used more than once without resetting the password (unless you want an all zero password).

| Edit this page View Source

ClearSecret

Gets a value indicating whether to clear the secret as soon as it is no longer needed.

Declaration

public bool ClearSecret { get; }

Property Value

Type	Description
bool

Remarks

If true and the configuration has a secret, the configuration cannot be used more than once without resetting the secret (unless you want an all zero secret).

| Edit this page View Source

FillMemoryBlocksWorkingBuffer

Gets the ulong-based working buffer sized for Argon2's internal memory-filling operation.

Declaration

public Memory<ulong> FillMemoryBlocksWorkingBuffer { get; }

Property Value

Type	Description
Memory<ulong>

Remarks

This gets used and overwritten on every hash.

Can change on every call to Reset(string, Argon2Password) or Reset(Argon2Config).

| Edit this page View Source

FillMemoryBlocksWorkingBufferLength

Gets the count of ulong values in the FillMemoryBlocksWorkingBuffer.

Declaration

public int FillMemoryBlocksWorkingBufferLength { get; }

Property Value

Type	Description
int

Remarks

Can change on every call to Reset(string, Argon2Password) or Reset(Argon2Config).

| Edit this page View Source

Hash

Gets the span associated with the final Argon2 hash value.

Declaration

public Span<byte> Hash { get; }

Property Value

Type	Description
Span<byte>

Remarks

This gets used and overwritten on every hash.

Can change on every call to Reset(string, Argon2Password) or Reset(Argon2Config).

| Edit this page View Source

HashLength

Gets the hash length to output. Minimum of 4. Default 32.

Declaration

public int HashLength { get; }

Property Value

Type	Description
int

| Edit this page View Source

InUse

Gets a value indicating whether the memory is currently in use.

Declaration

public bool InUse { get; }

Property Value

Type	Description
bool

| Edit this page View Source

KeyIdentifier

Gets the key identifier used in the password hash.

Declaration

public Span<byte> KeyIdentifier { get; }

Property Value

Type	Description
Span<byte>

| Edit this page View Source

LaneBlockCount

Gets the number of memory blocks per lane. SegmentBlockCount * SyncPointCount.

Declaration

public int LaneBlockCount { get; }

Property Value

Type	Description
int

Remarks

Can change on every call to Reset(string, Argon2Password) or Reset(Argon2Config).

| Edit this page View Source

Lanes

Gets the lanes used in the password hash. Minimum of 1. Defaults to 4.

Declaration

public int Lanes { get; }

Property Value

Type	Description
int

Remarks

This describes the maximum parallelism that can be achieved. Each "lane" can be processed individually in its own thread. Setting Threads to a value greater than one when there is more than one lane will allow the use of multiple cores to speed up hashing.

| Edit this page View Source

LockMemory

Gets the lock memory policy. Null to not secure arrays at all.

Declaration

public LockMemoryPolicy? LockMemory { get; }

Property Value

Type	Description
LockMemoryPolicy?

| Edit this page View Source

MemoryCost

Gets the memory cost used in the password hash. Minimum of 1. Defaults to 65536.

Declaration

public int MemoryCost { get; }

Property Value

Type	Description
int

Remarks

This translates into a target count of memory blocks to use for hashing. A memory block is 1024 bytes so the default 65536 is for a 64MB hash.

If this value is less than 2*SyncPointCount*Lanes, than 2*SyncPointCount*Lanes will be used.

If this value is not a multiple of SyncPointCount*Lanes, then it is rounded down to a multiple of SyncPointCount*Lanes.

| Edit this page View Source

Password

Gets the password to hash.

Declaration

public Span<byte> Password { get; }

Property Value

Type	Description
Span<byte>

| Edit this page View Source

Salt

Gets the salt used in the password hash. If non-null, must be at least 8 bytes.

Declaration

public Span<byte> Salt { get; }

Property Value

Type	Description
Span<byte>

| Edit this page View Source

Secret

Gets the secret used in the password hash.

Declaration

public Span<byte> Secret { get; }

Property Value

Type	Description
Span<byte>

| Edit this page View Source

SegmentBlockCount

Gets the number of memory blocks per segment. This value gets derived from the memory cost. The memory cost value is a request for that number of blocks. If that request is less than (2 * SyncPointCount) times the number of lanes requested, it is first bumped up to that amount. Then, it may be reduced to fit on a SyncPointCount times the number of lanes requested boundary.

Declaration

public int SegmentBlockCount { get; }

Property Value

Type	Description
int

Remarks

Can change on every call to Reset(string, Argon2Password) or Reset(Argon2Config).

| Edit this page View Source

ShrinkMemoryPolicy

Gets or sets the policy that determines whether to shrink memory when resetting with a new Argon2Config.

Declaration

public Argon2MemoryPolicy ShrinkMemoryPolicy { get; set; }

Property Value

Type	Description
Argon2MemoryPolicy

| Edit this page View Source

Threads

Gets the threads used in the password hash. Minimum of 1. Defaults to 1.

Declaration

public int Threads { get; }

Property Value

Type	Description
int

Remarks

This value makes no difference in the result. A value greater than one causes that many threads to get spawned to do the work on top of the main thread that orchestrates which thread does what work.

Lanes defines the maximum parallelism that can be achieved. Setting Threads to a value greater than Lanes will not result in more than Lanes threads running.

| Edit this page View Source

TimeCost

Gets the time cost used in the password hash. Minimum of 1. Defaults to 3.

Declaration

public int TimeCost { get; }

Property Value

Type	Description
int

Remarks

This is the number of iterations to perform. There are attacks on the Argon2Version.Sixteen with less than three iterations (if I'm reading the paper correctly). So, use a value greater than 3 here if you are not using Argon2Version.Nineteen.

| Edit this page View Source

Type

Gets the Argon2 type. Default to hybrid.

Declaration

public Argon2Type Type { get; }

Property Value

Type	Description
Argon2Type

| Edit this page View Source

Version

Gets the Argon2 version used in the password hash. Defaults to Argon2Version.Nineteen (0x13).

Declaration

public Argon2Version Version { get; }

Property Value

Type	Description
Argon2Version

Methods

| Edit this page View Source

Dispose()

Dispose.

Declaration

public void Dispose()

| Edit this page View Source

EndUse()

Mark this memory as free to use again.

Declaration

public void EndUse()

| Edit this page View Source

RequiredBlockCounts(Argon2Config)

Gets the required block count for the given Argon2Config.

Declaration

public static (int SegmentBlockCount, int LaneBlockCount, ulong BlockCount) RequiredBlockCounts(Argon2Config config)

Parameters

Type	Name	Description
Argon2Config	config	Used to determine the required block count.

Returns

Type	Description
(int SegmentBlockCount, int LaneBlockCount, ulong BlockCount)	The required segment, lane, and total block count for the given Argon2Config.

Exceptions

Type	Condition
ArgumentNullException	`config` is null.

| Edit this page View Source

Reset(Argon2Config)

Reset this Argon2Memory to what the given Argon2Config requires.

Declaration

public void Reset(Argon2Config config)

Parameters

Type	Name	Description
Argon2Config	config	The configuration used to determine memory required.

Exceptions

Type	Condition
OutOfMemoryException	If the memory could not be allocated. Usually because of operating system enforced limits on securing the allocated arrays.

| Edit this page View Source

Reset(string, Argon2Password)

Reset this Argon2Memory to what the given Argon2Config requires.

Declaration

public void Reset(string hash, Argon2Password password)

Parameters

Type	Name	Description
string	hash	The configuration used to determine memory required.
Argon2Password	password	The password to use after reset (or Argon2Password.Keep for no change).

Exceptions

Type	Condition
OutOfMemoryException	If the memory could not be allocated. Usually because of operating system enforced limits on securing the allocated arrays.

| Edit this page View Source

StartUse()

Start the use of this memory. Argon2Memory should not be used by more than one hash operation as a time.

Declaration

public void StartUse()

Implements

IDisposable

Extension Methods

DecodeExtension.DecodeString(Argon2Memory, string)

EncodeExtension.EncodeString(Argon2Memory, Span<byte>)