Security.Cryptography.RSACng


The RSACng class provides a wrapper for the CNG implementation of the RSA algorithm. The interface provided by RSACng is derived from the System.Security.Cryptography.RSA base type, and not from the System.Security.Cryptography.RSACryptoServiceProvider class. Consequently, it is not a drop in replacement for existing uses of RSACryptoServiceProvider.

RSACng uses a programming model more similar to the System.Security.Cryptography.ECDsaCng class than RSACryptoServiceProvider. For instance, unlike RSACryptoServiceProvider which has a key directly tied into the operations of the type itself, the key used by RsaCng is managed by a separate System.Security.Cryptography.CngKey object. Additionally, operations such as signing and verifying signatures take their parameters from a set of properties set on the RSACng object, similar to how ECDsaCng uses properties of its object to control the signing and verification operations.

RSACng uses the NCrypt layer of CNG to do its work, and requires Windows Vista and the .NET Framework 3.5.

Example usage: 
// Create an RSA-SHA256 signature using the key stored in "MyKey"
byte[] dataToSign = Encoding.UTF8.GetBytes("Data to sign");
using (CngKey signingKey = CngKey.Open("MyKey");
using (RSACng rsa = new RSACng(signingKey))
{
    rsa.SignatureHashAlgorithm = CngAlgorithm.Sha256;
    return rsa.SignData(dataToSign);
}



APIs

.ctor()

Create an RSACng algorithm with a random 2048 bit key pair.

.ctor(int keySize)

Creates a new RSACng object that will use a randomly generated key of the specified size. Valid key sizes range from 384 to 16384 bits, in increments of 8. It's suggested that a minimum size of 2048 bits be used for all keys.

Parameters:
keySize size of hte key to generate, in bits


Exceptions:
System.Security.Cryptography.CryptographicException if keySize is not valid


.ctor(System.Security.Cryptography.CngKey key)

Creates a new RSACng object that will use the specified key. The key's System.Security.Cryptography.CngKey.AlgorithmGroup must be Rsa.

Parameters:
key key to use for RSA operations


Exceptions:
System.ArgumentException if key is not an RSA key
System.ArgumentNullException if key is null


System.Security.Cryptography.CngAlgorithm EncryptionHashAlgorithm { get; set; }

Sets the hash algorithm to use when encrypting or decrypting data using the OAEP padding method. This property is only used if data is encrypted or decrypted and the EncryptionPaddingMode is set to AsymmetricEncryptionPaddingMode.Oaep. The default value is Sha256.
Exceptions:
System.ArgumentNullException if EncryptionHashAlgorithm is set to null



Security.Cryptography.AsymmetricPaddingMode EncryptionPaddingMode { get; set; }

Sets the padding mode to use when encrypting or decrypting data. The default value is AsymmetricPaddingMode.Oaep.
Exceptions:
System.ArgumentNullException if EncryptionPaddingMOde is set to null



System.Security.Cryptography.CngKey Key { get; }

Gets the key that will be used by the RSA object for any cryptographic operation that it uses. This key object will be disposed if the key is reset, for instance by changing the KeySize property, using ImportParamers to create a new key, or by Disposing of the parent RSA object. Therefore, you should make sure that the key object is no longer used in these scenarios. This object will not be the same object as the CngKey passed to the RSACng constructor if that constructor was used, however it will point at the same CNG key.
Permission Requirements:
System.Security.Permissions.SecurityPermission SecurityPermission/UnmanagedCode is required to read this property.


System.String KeyExchangeAlgorithm { get; }

Returns "RSA-PKCS1-KeyEx". This property should not be used.

System.Security.Cryptography.CngProvider Provider { get; }

Key storage provider being used for the algorithm

System.String SignatureAlgorithm { get; }

Returns "http://www.w3.org/2000/09/xmldsig#rsa-sha1". This property should not be used.

System.Security.Cryptography.CngAlgorithm SignatureHashAlgorithm { get; set; }

Gets or sets the hash algorithm to use when signing or verifying data. The default value is Sha256.
Exceptions:
System.ArgumentNullException if SignatureHashAlgorithm is set to null



Security.Cryptography.AsymmetricPaddingMode SignaturePaddingMode { get; set; }

Gets or sets the padding mode to use when encrypting or decrypting data. The default value is AsymmetricPaddingMode.Pkcs1.
Exceptions:
System.ArgumentOutOfRangeException if SignaturePaddingMode is set to a mode other than Pkcs1 or Pss



int SignatureSaltBytes { get; set; }

Gets or sets the number of bytes of salt to use when signing data or verifying a signature using the PSS padding mode. This property is only used if data is being signed or verified and the SignaturePaddingMode is set to AsymmetricEncryptionPaddingMode.Pss. The default value is 20 bytes.
Exceptions:
System.ArgumentOutOfRangeException if SignatureSaltBytes is set to a negative number



System.Security.Cryptography.RSAParameters ExportParameters(bool includePrivateParameters)

Exports the key used by the RSA object into an RSAParameters object.

Parameters:
includePrivateParameters


Permission Requirements:
System.Security.Permissions.KeyContainerPermission If the includePrivateParameters parameter is true and the CngKey is not ephemeral, KeyContainerPermission will be demanded.


void ImportParameters(System.Security.Cryptography.RSAParameters parameters)


ImportParameters will replace the existing key that RSACng is working with by creating a new CngKey for the parameters structure. If the parameters structure contains only an exponent and modulus, then only a public key will be imported. If the parameters also contain P and Q values, then a full key pair will be imported.

The default KSP used by RSACng does not support importing full RSA key pairs on Windows Vista. If the ImportParameters method is called with a full key pair, the operation will fail with a CryptographicException stating that the operation was invalid. Other KSPs may have similar restrictions. To work around this, make sure to only import public keys when using the default KSP.


Parameters:
parameters


Exceptions:
System.ArgumentException if parameters contains neither an exponent nor a modulus
System.Security.Cryptography.CryptographicException if parameters is not a valid RSA key or if parameters is a full key pair and the default KSP is used


System.Byte[] DecryptValue(System.Byte[] rgb)

DecryptValue decrypts the input data using the padding mode specified in the EncryptionPaddingMode property. The return value is the decrypted data.

Parameters:
rgb encrypted data to decrypt


Exceptions:
System.ArgumentNullException if rgb is null
System.Security.Cryptography.CryptographicException if rgb could not be decrypted


Permission Requirements:
System.Security.Permissions.KeyContainerPermission This method requires KeyContainerPermission to the key in use if it is not ephemeral.


System.Byte[] EncryptValue(System.Byte[] rgb)

EncryptValue encrypts the input data using the padding mode specified in the EncryptionPaddingMode property. The return value is the encrypted data.

Parameters:
rgb data to encrypt


Exceptions:
System.ArgumentNullException if rgb is null
System.Security.Cryptography.CryptographicException if rgb could not be decrypted


System.Byte[] SignData(System.Byte[] data)

SignData signs the given data after hashing it with the SignatureHashAlgorithm algorithm.

Parameters:
data data to sign


Exceptions:
System.ArgumentNullException if data is null
System.Security.Cryptography.CryptographicException if data could not be signed
System.InvalidOperationException if SignatureHashAlgorithm is not MD5, SHA-1, SHA-256, SHA-384, or SHA-512


Permission Requirements:
System.Security.Permissions.KeyContainerPermission This method will demand KeyContainerPermission if the key being used is not ephemeral.


System.Byte[] SignData(System.Byte[] data, int offset, int count)

SignData signs the given data after hashing it with the SignatureHashAlgorithm algorithm.

Parameters:
data data to sign
offset offset into the data that the signature should begin covering
count number of bytes to include in the signed data


Exceptions:
System.ArgumentNullException if data is null
System.ArgumentOutOfRangeException if offset or count are negative, or if count specifies more bytes than are available in data .
System.Security.Cryptography.CryptographicException if data could not be signed
System.InvalidOperationException if SignatureHashAlgorithm is not MD5, SHA-1, SHA-256, SHA-384, or SHA-512


Permission Requirements:
System.Security.Permissions.KeyContainerPermission This method will demand KeyContainerPermission if the key being used is not ephemeral.


System.Byte] SignData([url:System.IO.Stream data)

SignData signs the given data after hashing it with the SignatureHashAlgorithm algorithm.

Parameters:
data data to sign


Exceptions:
System.ArgumentNullException if data is null
System.Security.Cryptography.CryptographicException if data could not be signed
System.InvalidOperationException if SignatureHashAlgorithm is not MD5, SHA-1, SHA-256, SHA-384, or SHA-512


Permission Requirements:
System.Security.Permissions.KeyContainerPermission This method will demand KeyContainerPermission if the key being used is not ephemeral.


System.Byte[] SignHash(System.Byte[] hash)

Sign data which was hashed using the SignatureHashAlgorithm; if the algorithm used to hash the data was different, use the SignHash(byte[], CngAlgorithm) overload instead.

Parameters:
hash hash to sign


Exceptions:
System.ArgumentNullException if hash is null
System.Security.Cryptography.CryptographicException if data could not be signed
System.InvalidOperationException if SignatureHashAlgorithm is not MD5, SHA-1, SHA-256, SHA-384, or SHA-512


Permission Requirements:
System.Security.Permissions.KeyContainerPermission This method will demand KeyContainerPermission if the key being used is not ephemeral.


System.Byte] SignHash(System.Byte[] hash, [url:System.Security.Cryptography.CngAlgorithm hashAlgorithm)

Sign already hashed data, specifying the algorithm it was hashed with. This method does not use the SignatureHashAlgorithm property.

Parameters:
hash hash to sign
hashAlgorithm algorithm hash was signed with


Exceptions:
System.ArgumentNullException if hash or hashAlgorithm are null
System.Security.Cryptography.CryptographicException if data could not be signed


Permission Requirements:
System.Security.Permissions.KeyContainerPermission This method will demand KeyContainerPermission if the key being used is not ephemeral.


bool VerifyData(System.Byte[] data, System.Byte[] signature)

VerifyData verifies that the given signature matches given data after hashing it with the SignatureHashAlgorithm algorithm.

Parameters:
data data to verify
signature signature of the data


Exceptions:
System.ArgumentNullException if data or signature are null
System.InvalidOperationException if SignatureHashAlgorithm is not MD5, SHA-1, SHA-256, SHA-384, or SHA-512


Return Value:
true if the signature verifies for the data, false if it does not

bool VerifyData(System.Byte[] data, int offset, int count, System.Byte[] signature)

VerifyData verifies that the given signature matches given data after hashing it with the SignatureHashAlgorithm algorithm.

Parameters:
data data to verify
offset offset into the data that the signature should begin covering
count number of bytes to include in the signed data
signature signature of the data


Exceptions:
System.ArgumentNullException if data or signature are null
System.ArgumentOutOfRangeException if offset or count are negative, or if count specifies more bytes than are available in data .
System.InvalidOperationException if SignatureHashAlgorithm is not MD5, SHA-1, SHA-256, SHA-384, or SHA-512


Return Value:
true if the signature verifies for the data, false if it does not

bool VerifyData(System.IO.Stream data, System.Byte[] signature)

VerifyData verifies that the given signature matches given data after hashing it with the SignatureHashAlgorithm algorithm.

Parameters:
data data to verify
signature signature of the data


Exceptions:
System.ArgumentNullException if data or signature are null
System.InvalidOperationException if SignatureHashAlgorithm is not MD5, SHA-1, SHA-256, SHA-384, or SHA-512


Return Value:
true if the signature verifies for the data, false if it does not

bool VerifyHash(System.Byte[] hash, System.Byte[] signature)

Verify data which was signed and already hashed with the SignatureHashAlgorithm; if a different hash algorithm was used to hash the data use the VerifyHash(byte[], byte[], CngAlgorithm) overload instead.

Parameters:
hash hash to verify
signature signature of the data


Exceptions:
System.ArgumentNullException if hash or signature are null
System.InvalidOperationException if SignatureHashAlgorithm is not MD5, SHA-1, SHA-256, SHA-384, or SHA-512


Return Value:
true if the signature verifies for the hash, false if it does not

bool VerifyHash(System.Byte] hash, System.Byte[] signature, [url:System.Security.Cryptography.CngAlgorithm hashAlgorithm)

Verify data which was signed and hashed with the given hash algorithm. This overload does not use the SignatureHashAlgorithm property.

Parameters:
hash hash to verify
signature signature of the data
hashAlgorithm algorithm that hash was hashed with


Exceptions:
System.ArgumentNullException if hash , signature , or hashAlgorithm are null


Return Value:
true if the signature verifies for the hash, false if it does not


Last edited Jun 4, 2009 at 12:48 AM by shawnfa, version 4

Comments

No comments yet.