Class PbeOptions

Namespace

CryptoHives.Foundation.Security.Cryptography

Assembly

CryptoHives.Foundation.Security.Cryptography.dll

Selects how a private key is protected when exported in the PKCS#8 EncryptedPrivateKeyInfo format.

public sealed class PbeOptions

Inheritance

object

PbeOptions

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

Examples

using CryptoHives.Foundation.Security.Cryptography;
using CryptoHives.Foundation.Security.Cryptography.Dsa;

var options = new PbeOptions(
    PbeEncryptionAlgorithm.Aes256Cbc, Pbkdf2Prf.HmacSha256, iterationCount: 600_000);

using var key = MLDsa.GenerateKey(MLDsaAlgorithm.MLDsa65);
string pem = key.ExportEncryptedPkcs8PrivateKeyPem("correct horse", options);

Remarks

This is the one place the key-format surface deliberately differs from System.Security.Cryptography, which passes a PbeParameters here. Two reasons:

• The base class library only gained PbeParameters in .NET Standard 2.1, and this library targets .NET Framework 4.6.2 upward. Supplying the type ourselves would mean defining it in a namespace we do not own, which collides with any consumer that also references a package defining it.
• PbeParameters names its pseudorandom function with HashAlgorithmName, an open string wrapper, so an unencodable choice can only fail at export. PBES2 has a finite set of pseudorandom functions - the ones RFC 8018 gives an OID - so Pbkdf2Prf makes that a compile-time choice instead.

Every other member of the key-format surface keeps its in-box signature; only the nine encrypted-export members take this type.

Exports always use PBES2 (RFC 8018 §6.2). Imports additionally accept the legacy PKCS#12 schemes, so nothing here constrains what can be read.

Constructors

PbeOptions(PbeEncryptionAlgorithm, Pbkdf2Prf, int)

Initializes a new instance of the PbeOptions class.

public PbeOptions(PbeEncryptionAlgorithm encryptionAlgorithm, Pbkdf2Prf prf, int iterationCount)

Parameters

encryptionAlgorithm PbeEncryptionAlgorithm

The content encryption algorithm.

prf Pbkdf2Prf

The PBKDF2 pseudorandom function.

iterationCount int

The PBKDF2 iteration count. OWASP recommends at least 600,000 for HMAC-SHA-256; the minimum enforced here is 1, because test vectors and interoperability fixtures legitimately use small counts.

Remarks

Validation happens here rather than at export, so a bad combination fails next to the line that chose it instead of several calls later.

Exceptions

ArgumentOutOfRangeException

encryptionAlgorithm or prf is Unknown or undefined, or iterationCount is less than 1.

Properties

EncryptionAlgorithm

Gets the content encryption algorithm.

public PbeEncryptionAlgorithm EncryptionAlgorithm { get; }

Property Value

PbeEncryptionAlgorithm

IterationCount

Gets the PBKDF2 iteration count.

public int IterationCount { get; }

Property Value

int

Prf

Gets the PBKDF2 pseudorandom function.

public Pbkdf2Prf Prf { get; }

Property Value

Pbkdf2Prf