Key Class
Represents a symmetric key or an asymmetric private key.
public sealed class Key : IDisposable
Summary
Constructors
Key(Algorithm, in KeyCreationParameters)
Initializes a new instance of the Key class with a random key.
public Key( Algorithm algorithm, in KeyCreationParameters creationParameters = default)
Parameters
- algorithm
- The algorithm for the key.
- creationParameters
- A KeyCreationParameters value that specifies advanced parameters for the creation of the Key instance.
Exceptions
- ArgumentNullException
algorithm
isnull
.- NotSupportedException
- The specified algorithm does not use keys.
Properties
Algorithm
Gets the algorithm for the key.
public Algorithm Algorithm { get; }
Property Value
An instance of the Algorithm class.
ExportPolicy
Gets the export policy for the key.
public KeyExportPolicies ExportPolicy { get; }
Property Value
A bitwise combination of KeyExportPolicies values that specifies the export policy for the key.
HasPublicKey
Specifies whether the current instance of the Key class represents a private key.
public bool HasPublicKey { get; }
Property Value
true
if the current instance is a represents a private key; otherwise,
false
.
PublicKey
Gets the public key if the current instance of the Key class represents a private key.
public PublicKey PublicKey { get; }
Property Value
An instance of the PublicKey class if the current instance represents a private key.
Exceptions
- InvalidOperationException
- The current instance does not represent a private key.
Remarks
This property throws an InvalidOperationException if the HasPublicKey property returns false
.
Size
Gets the size of the key.
public int Size { get; }
Property Value
The key size, in bytes.
Static Methods
Create(Algorithm, in KeyCreationParameters)
Creates a new instance of the Key class with a random key.
public static Key Create( Algorithm algorithm, in KeyCreationParameters creationParameters = default)
Parameters
- algorithm
- The algorithm for the key.
- creationParameters
- A KeyCreationParameters value that specifies advanced parameters for the creation of the Key instance.
Return Value
A new instance of the Key class that represents the new key.
Exceptions
- ArgumentNullException
algorithm
isnull
.- NotSupportedException
- The specified algorithm does not use keys.
Import(Algorithm, ReadOnlySpan<byte>, KeyBlobFormat, in KeyCreationParameters)
Imports the specified key BLOB in the specified format.
public static Key Import( Algorithm algorithm, ReadOnlySpan<byte> blob, KeyBlobFormat format, in KeyCreationParameters creationParameters = default)
Parameters
- algorithm
- The algorithm for the imported key.
- blob
- The key BLOB to import.
- format
- One of the KeyBlobFormat values that specifies the format of the key BLOB.
- creationParameters
- A KeyCreationParameters value that specifies advanced parameters for the creation of the Key instance.
Return Value
A new instance of the Key class that represents the imported key.
Exceptions
- ArgumentNullException
algorithm
isnull
.- ArgumentException
- The specified format is not supported by the specified algorithm.
- FormatException
- The key BLOB is not in the correct format.
- NotSupportedException
- The specified algorithm does not support importing keys.
TryImport(Algorithm, ReadOnlySpan<byte>, KeyBlobFormat, out Key?, in KeyCreationParameters)
Attempts to import the specified key BLOB in the specified format.
public static bool TryImport( Algorithm algorithm, ReadOnlySpan<byte> blob, KeyBlobFormat format, out Key? result, in KeyCreationParameters creationParameters = default)
Parameters
- algorithm
- The algorithm for the imported key.
- blob
- The key BLOB to import.
- format
- One of the KeyBlobFormat values that specifies the format of the key BLOB.
- result
- When this method returns, contains a new instance of the Key
class that represents the imported key, or
null
if the import fails. - creationParameters
- A KeyCreationParameters value that specifies advanced parameters for the creation of the Key instance.
Return Value
true
if the import succeeds; otherwise, false
.
Exceptions
- ArgumentNullException
algorithm
isnull
.- ArgumentException
- The specified format is not supported by the specified algorithm.
- NotSupportedException
- The specified algorithm does not support importing keys.
Methods
Dispose()
Securely erases the key from memory and releases all resources used by the current instance of the Key class.
public void Dispose();
Export(KeyBlobFormat)
Exports the key as a BLOB in the specified format and returns it as an array of bytes.
public byte[] Export( KeyBlobFormat format)
Parameters
- format
- One of the KeyBlobFormat values that specifies the format of the key BLOB.
Return Value
A BLOB that contains the key in the specified format.
Exceptions
- ArgumentException
- The algorithm for the key does not support the specified format.
- InvalidOperationException
- The export policy for the key does not allow the key to be exported.
- NotSupportedException
- The algorithm for the key does not support exporting keys.
- ObjectDisposedException
- The key has been disposed.
GetExportBlobSize(KeyBlobFormat)
Returns the BLOB size of the key if it were exported in the specified format.
public int GetExportBlobSize( KeyBlobFormat format)
Parameters
- format
- One of the KeyBlobFormat values that specifies the format of the key BLOB.
Return Value
The size (in bytes) of the key if it were exported as a BLOB in the specified format.
Exceptions
- ArgumentException
- The algorithm for the key does not support the specified format.
- NotSupportedException
- The algorithm for the key does not support exporting keys.
- ObjectDisposedException
- The key has been disposed.
TryExport(KeyBlobFormat, Span<byte>, out int)
Exports the specified key BLOB in the specified format and attempts to fill the specified span of bytes with the BLOB.
public bool TryExport( KeyBlobFormat format, Span<byte> blob, out int blobSize)
Parameters
- format
- One of the KeyBlobFormat values that specifies the format of the key BLOB.
- blob
- The span to fill with the exported key BLOB.
The length of the span must be greater than or equal to
GetExportBlobSize(format)
. - blobSize
- When this method returns, contains the number of bytes written into the output span.
Return Value
false
if there is not enough space in the output span to write the key BLOB;
otherwise true
.
Exceptions
- ArgumentException
- The algorithm for the key does not support the specified format.
- InvalidOperationException
- The export policy for the key does not allow the key to be exported.
- NotSupportedException
- The algorithm for the key does not support exporting keys.
- ObjectDisposedException
- The key has been disposed.
Thread Safety
Any public static members of this type are thread safe. Any instance members are not guaranteed to be thread safe.