diff --git a/xml/System.Security.Cryptography/RSA.xml b/xml/System.Security.Cryptography/RSA.xml index da6fbec6720..cca30d9db9d 100644 --- a/xml/System.Security.Cryptography/RSA.xml +++ b/xml/System.Security.Cryptography/RSA.xml @@ -40,11 +40,8 @@ supports key lengths from 384 bits to 16384 bits in increments of 8 bits if you have the Microsoft Enhanced Cryptographic Provider installed. It supports key lengths from 384 bits to 512 bits in increments of 8 bits if you have the Microsoft Base Cryptographic Provider installed. +Developers are encouraged to program against the `RSA` base class rather than any specific derived class. The derived classes are intended for interop with the underlying system cryptographic libraries. ]]> @@ -185,7 +182,7 @@ A new ephemeral RSA key with the specified key size. To be added. - is different than . + is not supported by the default implementation. @@ -220,6 +217,8 @@ Creates a new ephemeral RSA key with the specified RSA key parameters. A new ephemeral RSA key. To be added. + does not represent a valid RSA key. + @@ -309,7 +308,22 @@ When overridden in a derived class, decrypts the input data using the specified padding mode. The decrypted data. To be added. + or is . A derived class must override this method. + is unknown, or not supported by this implementation. + +-or- + +The length of is not equal to the number of bytes for . + +-or- + +This instance represents only a public key. + +-or- + +The decryption operation failed. + @@ -360,6 +374,7 @@ ]]> This method call is not supported. This exception is thrown starting with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)]. + Cryptographic Services @@ -406,7 +421,18 @@ When overridden in a derived class, encrypts the input data using the specified padding mode. The encrypted data. To be added. + or is . A derived class must override this method. + is unknown, or not supported by this implementation. + +-or- + +The length of is too long for the combination of and the selected padding. + +-or- + +The encryption operation failed. + @@ -457,6 +483,7 @@ ]]> This method call is not supported. This exception is thrown starting with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)]. + Cryptographic Services @@ -500,6 +527,7 @@ When overridden in a derived class, exports the . The parameters for . To be added. + The parameters could not be exported. Cryptographic Services @@ -1208,7 +1236,7 @@ The algorithm-specific key import failed. - The input data for which to compute the hash. + The input data to hash and sign. The hash algorithm to use to create the hash value. The padding mode. Computes the hash value of the specified byte array using the specified hash algorithm and padding mode, and signs the resulting hash value. @@ -1222,6 +1250,17 @@ The algorithm-specific key import failed. is . . is or . + is unknown, or not supported by this implementation. + +-or- + +This instance represents only a public key. + +-or- + +An error occurred creating the signature. + + @@ -1259,7 +1298,7 @@ The algorithm-specific key import failed. - The input stream for which to compute the hash. + The input stream to hash and sign. The hash algorithm to use to create the hash value. The padding mode. Computes the hash value of the specified stream using the specified hash algorithm and padding mode, and signs the resulting hash value. @@ -1273,6 +1312,17 @@ The algorithm-specific key import failed. is . . is or . + is unknown, or not supported by this implementation. + +-or- + +This instance represents only a public key. + +-or- + +An error occurred creating the signature. + + @@ -1312,7 +1362,7 @@ The algorithm-specific key import failed. - The input data for which to compute the hash. + The input data to hash and sign. The offset into the array at which to begin using data. The number of bytes in the array to use as data. The hash algorithm to use to create the hash value. @@ -1338,6 +1388,17 @@ The algorithm-specific key import failed. -or- + - 1 results in an index that is beyond the upper bound of . + is unknown, or not supported by this implementation. + +-or- + +This instance represents only a public key. + +-or- + +An error occurred creating the signature. + + @@ -1382,10 +1443,24 @@ The algorithm-specific key import failed. The hash value of the data to be signed. The hash algorithm used to create the hash value of the data. The padding. - When overridden in a derived class, computes the signature for the specified hash value by encrypting it with the private key using the specified padding. + When overridden in a derived class, computes the signature for the specified hash value using the specified padding. The RSA signature for the specified hash value. To be added. A derived class must override this method. + or is . + + . is or . + is unknown, or not supported by this implementation. + +-or- + +This instance represents only a public key. + +-or- + +An error occurred creating the signature. + + @@ -1495,13 +1570,39 @@ The algorithm-specific key import failed. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The data to decrypt. + The buffer to receive the decrypted data. + The padding mode. + When this method returns, the total number of bytes written into . This parameter is treated as uninitialized. + Attempts to decrypt the input data using the specified padding mode, writing the result into a provided buffer. + + if is long enough to receive the decrypted data; otherwise, . + + and copies the result to `destination`. +Derived types should override this method to avoid the intermediate array creation. + +The RSA decryption algorithm will always produce an output smaller than the input, therefore this method will never return `false` when `destination.Length >= data.Length`. + + ]]> + + is . + is unknown, or not supported by this implementation. + +-or- + +The length of is not equal to the number of bytes for . + +-or- + +This instance represents only a public key. + +-or- + +The decryption operation failed. + @@ -1533,13 +1634,35 @@ The algorithm-specific key import failed. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The data to encrypt. + The buffer to receive the encrypted data. + The padding mode. + When this method returns, the total number of bytes written into . This parameter is treated as uninitialized. + Attempts to encrypt the input data with a specified padding mode into a provided buffer. + + if is long enough to receive the encrypted data; otherwise, . + + and copies the result to `destination`. +Derived types should override this method to avoid the intermediate array creation. + +The RSA encryption algorithm will always produce an output equal to the number of bytes required for bits. + + ]]> + + is . + is unknown, or not supported by this implementation. + +-or- + +The length of is too long for the combination of and the selected padding. + +-or- + +The encryption operation failed. + @@ -1815,13 +1938,22 @@ The algorithm-specific key import failed. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The data to be hashed. + The buffer to receive the hash value. + The algorithm to use in hash the data. + When this method returns, the total number of bytes written into . This parameter is treated as uninitialized. + Attempts to compute the hash of the provided data by using the specified algorithm, writing the results into a provided buffer. + + if is long enough to receive the hash value; otherwise, . + + and copies the result to `destination`. +Derived types should override this method to avoid the intermediate array creation. + + ]]> + @@ -1854,14 +1986,32 @@ The algorithm-specific key import failed. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The input data to hash and sign. + The buffer to receive the RSA signature. + The hash algorithm used to create the hash value of the data. + The padding mode. + When this method returns, the total number of bytes written into . This parameter is treated as uninitialized. + Attempts to hash the provided data with the specified algorithm and sign the hash with the current key, writing the signature into a provided buffer. + + if is long enough to receive the RSA signature; otherwise, . + + bits. + + ]]> + + is . + + . is or . + This instance represents only a public key. + +-or- + +An error occurred creating the signature. + + @@ -1894,14 +2044,39 @@ The algorithm-specific key import failed. - To be added. + The hash value of the data to be signed. To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The hash algorithm used to create the hash value of the data. + The padding. + When this method returns, the total number of bytes written into . This parameter is treated as uninitialized. + Attempts to sign the hash with the current key, writing the signature into a provided buffer. + + if is long enough to receive the RSA signature; otherwise, . + + and copies the result to `destination`. +Derived types should override this method to avoid the intermediate array creation. + +The RSA signature algorithm will always produce an output equal to the number of bytes required for bits. + + ]]> + + is . + + . is or . + is unknown, or not supported by this implementation. + +-or- + +This instance represents only a public key. + +-or- + +An error occurred creating the signature. + + @@ -1972,6 +2147,7 @@ The algorithm-specific key import failed. is . . is or . + is unknown, or not supported by this implementation. @@ -2030,6 +2206,7 @@ The algorithm-specific key import failed. is . . is or . + is unknown, or not supported by this implementation. @@ -2061,13 +2238,17 @@ The algorithm-specific key import failed. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The signed data. + The signature data to be verified. + The hash algorithm used to create the hash value of the data. + The padding mode. + Verifies that a digital signature is valid by calculating the hash value of the specified data using the specified hash algorithm and padding, and comparing it to the provided signature. + + if the signature is valid; otherwise, . To be added. + + . is or . + is unknown, or not supported by this implementation. @@ -2140,6 +2321,7 @@ The algorithm-specific key import failed. -or- + - 1 results in an index that is beyond the upper bound of . + is unknown, or not supported by this implementation. @@ -2191,6 +2373,10 @@ The algorithm-specific key import failed. if the signature is valid; otherwise, . To be added. A derived class must override this method. + or is . + + . is or . + is unknown, or not supported by this implementation. @@ -2222,13 +2408,26 @@ The algorithm-specific key import failed. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The hash value of the signed data. + The signature data to be verified. + The hash algorithm used to create the hash value. + The padding mode. + Verifies that a digital signature is valid by determining the hash value in the signature using the specified hash algorithm and padding, and comparing it to the provided hash value. + + if the signature is valid; otherwise, . + + . +Derived types should override this method to avoid the intermediate array creation. + + ]]> + + or is . + + . is or . + is unknown, or not supported by this implementation. diff --git a/xml/System.Security.Cryptography/RSACng.xml b/xml/System.Security.Cryptography/RSACng.xml index 2bee62cc62d..b1fcf0c1c85 100644 --- a/xml/System.Security.Cryptography/RSACng.xml +++ b/xml/System.Security.Cryptography/RSACng.xml @@ -82,7 +82,17 @@ Initializes a new instance of the class with a random 2,048-bit key pair. - To be added. + + property to 2048 and when a key is needed one is generated using the property value. +If a key is loaded via the method, or other key import method, the key size from this constructor has no meaning. + + ]]> + @@ -119,7 +129,11 @@ property to `keySize` and when a key is needed one is generated using the property value. +If a key is loaded via the method, or other key import method, the key size from this constructor has no meaning. ]]> @@ -288,8 +302,9 @@ - To be added. - To be added. + + to release both managed and unmanaged resources; to release only unmanaged resources. + Releases the unmanaged resources used by the and optionally releases the managed resources. To be added. @@ -447,10 +462,10 @@ - To be added. - To be added. - To be added. - To be added. + The binary stream to hash. + The hash algorithm. + Computes the hash value of a specified binary stream by using a specified hashing algorithm. + The hashed data. To be added. @@ -487,12 +502,12 @@ - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The data to be hashed. + The index of the first byte in that is to be hashed. + The number of bytes to hash. + The algorithm to use in hash the data. + Computes the hash value of a specified portion of a byte array by using a specified hashing algorithm. + The hashed data. To be added. @@ -538,7 +553,10 @@ value with the new key, +any already open key is unaffected by this method. ]]> @@ -646,8 +664,8 @@ System.Security.Cryptography.KeySizes[] - To be added. - To be added. + Gets the key sizes, in bits, that are supported by this implementation of RSA. + An array that contains the key sizes supported by the algorithm. To be added. diff --git a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml index aa363f78a4d..e30ff560e74 100644 --- a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml @@ -117,16 +117,17 @@ - Initializes a new instance of the class using the default key. + Initializes a new instance of the class with a random key pair. key pair suitable to encrypt session keys so that they can be safely stored and exchanged with other users. The generated key corresponds to a key generated using the `AT_KEYEXCHANGE` value used in the unmanaged Microsoft Cryptographic API (CAPI). +This constructor creates an key pair suitable to encrypt session keys so that they can be safely stored and exchanged with other users. The generated key corresponds to a key generated using the `AT_KEYEXCHANGE` value used in the unmanaged Microsoft Cryptographic API (CAPI). - +This constructor does not generate a new public/private keypair immediately. +If no key is loaded via the method, or any other key import method, before a key is needed then a 1024-bit ephemeral key is created on demand. + ## Examples The following code example uses the class to encrypt a string into an array of bytes and then decrypt the bytes back into a string. @@ -177,15 +178,16 @@ The size of the key to use in bits. - Initializes a new instance of the class with the specified key size. + Initializes a new instance of the class with a random key pair of the specified key size. key pair suitable to encrypt session keys so that they can be safely stored and exchanged with other users. The generated key corresponds to a key generated using the `AT_KEYEXCHANGE` value used in the unmanaged Microsoft Cryptographic API (CAPI). + +This constructor creates an key pair suitable to encrypt session keys so that they can be safely stored and exchanged with other users. The generated key corresponds to a key generated using the `AT_KEYEXCHANGE` value used in the unmanaged Microsoft Cryptographic API (CAPI). +This constructor does not generate a new public/private keypair immediately. +If no key is loaded via the method, or any other key import method, before a key is needed then a `dwKeySize`-bit ephemeral key is created on demand. ## Examples @@ -455,7 +457,7 @@ The data to be decrypted. - to perform direct decryption using OAEP padding (only available on a computer running Microsoft Windows XP or later); otherwise, to use PKCS#1 v1.5 padding. + to perform direct decryption using OAEP padding; otherwise, to use PKCS#1 v1.5 padding. Decrypts data with the algorithm. The decrypted data, which is the original plain text before encryption. @@ -485,13 +487,10 @@ -or- - The parameter is and OAEP is not supported. - - -or- - The key does not match the encrypted data. However, the exception wording may not be accurate. For example, it may say Not enough storage is available to process this command. is . + for permission to decrypt. Security action: . Associated enumeration: Cryptographic Services @@ -694,11 +693,10 @@ ## Remarks The following table describes the padding supported by different versions of Microsoft Windows and the maximum length of `rgb` allowed by the different combinations of operating systems and padding. -|Padding|Operating System Supported|Maximum Length of rgb Parameter| -|-------------|--------------------------------|-------------------------------------| -|OAEP padding (PKCS#1 v2)|Windows XP or later.|Modulus size -2 -2*hLen, where hLen is the size of the hash.| -|Direct Encryption (PKCS#1 v1.5)|Microsoft Windows 2000 or later with the high encryption pack installed.|Modulus size - 11. (11 bytes is the minimum padding possible.)| -|Direct Encryption and OAEP padding not supported|Microsoft Windows 98, Windows Millennium Edition, or Windows 2000 or later without the high encryption pack installed.|The maximum size allowed for a symmetric key.| +|Padding|Maximum Length of rgb Parameter| +|-------------|-------------------------------------| +|OAEP padding (PKCS#1 v2)|Modulus size -2 -2*hLen, where hLen is the size of the hash.| +|Direct Encryption (PKCS#1 v1.5)|Modulus size - 11. (11 bytes is the minimum padding possible.)| Use to decrypt the results of this method. @@ -717,13 +715,10 @@ -or- - The length of the parameter is greater than the maximum allowed length. - - -or- - - The parameter is and OAEP padding is not supported. + The length of the parameter is greater than the maximum allowed length. is . + Cryptographic Services @@ -963,7 +958,7 @@ - To be added. + Releases the unmanaged resources held by this instance. To be added. @@ -1004,10 +999,10 @@ - To be added. - To be added. - To be added. - To be added. + The binary stream to hash. + The hash algorithm. + Computes the hash value of a specified binary stream by using a specified hashing algorithm. + The hashed data. To be added. @@ -1050,12 +1045,12 @@ - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The data to be hashed. + The index of the first byte in that is to be hashed. + The number of bytes to hash. + The algorithm to use in hash the data. + Computes the hash value of a specified portion of a byte array by using a specified hashing algorithm. + The hashed data. To be added. @@ -1522,7 +1517,7 @@ The supported RSA key sizes depend on the available cryptographic service provid - The input data for which to compute the hash. + The input data to hash and sign. The hash algorithm to use to create the hash value. Computes the hash value of the specified byte array using the specified hash algorithm, and signs the resulting hash value. The signature for the specified data. @@ -1547,6 +1542,7 @@ The supported RSA key sizes depend on the available cryptographic service provid The parameter is . The parameter is not a valid type. + Cryptographic Services @@ -1590,7 +1586,7 @@ The supported RSA key sizes depend on the available cryptographic service provid - The input data for which to compute the hash. + The input stream to hash and sign. The hash algorithm to use to create the hash value. Computes the hash value of the specified input stream using the specified hash algorithm, and signs the resulting hash value. The signature for the specified data. @@ -1613,6 +1609,7 @@ The supported RSA key sizes depend on the available cryptographic service provid The parameter is . The parameter is not a valid type. + Cryptographic Services @@ -1658,7 +1655,7 @@ The supported RSA key sizes depend on the available cryptographic service provid - The input data for which to compute the hash. + The input data to hash and sign. The offset into the array from which to begin using data. The number of bytes in the array to use as data. The hash algorithm to use to create the hash value. @@ -1691,6 +1688,7 @@ The supported RSA key sizes depend on the available cryptographic service provid The parameter is . The parameter is not a valid type. + Cryptographic Services @@ -1701,7 +1699,7 @@ The supported RSA key sizes depend on the available cryptographic service provid 4.1.0.0 - Computes the signature for the specified hash value by encrypting it with the private key. + Computes the signature for the specified hash value. @@ -1746,7 +1744,7 @@ The supported RSA key sizes depend on the available cryptographic service provid The hash value of the data to be signed. The hash algorithm identifier (OID) used to create the hash value of the data. - Computes the signature for the specified hash value by encrypting it with the private key. + Computes the signature for the specified hash value. The signature for the specified hash value. for permission to sign a file using the key. Security action: . Associated enumeration: + Cryptographic Services @@ -1813,7 +1812,7 @@ The supported RSA key sizes depend on the available cryptographic service provid The hash value of the data to be signed. The hash algorithm name used to create the hash value of the data. The padding. - Computes the signature for the specified hash value by encrypting it with the private key using the specified padding. + Computes the signature for the specified hash value using the specified padding. The signature for the specified hash value. To be added. @@ -1959,6 +1958,7 @@ The supported RSA key sizes depend on the available cryptographic service provid The parameter is . The parameter is not a valid type. + Cryptographic Services @@ -2048,6 +2048,7 @@ The supported RSA key sizes depend on the available cryptographic service provid -or- The signature cannot be verified. + Cryptographic Services diff --git a/xml/System.Security.Cryptography/RSAOpenSsl.xml b/xml/System.Security.Cryptography/RSAOpenSsl.xml index 2f961faa900..8359cf2aa23 100644 --- a/xml/System.Security.Cryptography/RSAOpenSsl.xml +++ b/xml/System.Security.Cryptography/RSAOpenSsl.xml @@ -17,7 +17,7 @@ - To be added. + Provides an implementation of the RSA algorithm backed by OpenSSL. - To be added. - To be added. + Initializes a new instance of the class with a random 2048-bit key pair. + + property to 2048 and when a key is needed one is generated using the property value. +If a key is loaded via the method, or other key import method, the key size from this constructor has no meaning. + + ]]> + @@ -68,9 +78,21 @@ - To be added. - To be added. + The size of the key to generate in bits. + Initializes a new instance of the class with a randomly generated key of the specified size. To be added. + + property to `keySize` and when a key is needed one is generated using the property value. +If a key is loaded via the method, or other key import method, the key size from this constructor has no meaning. + + ]]> + + + is not valid. @@ -92,9 +114,22 @@ - To be added. - To be added. - To be added. + The OpenSSL RSA* value to use as the key. + Initializes a new instance of the class from an existing OpenSSL key represented as an RSA*. + + [!IMPORTANT] +> OpenSSL supports multiple library versions being loaded within the same process. +> Before calling this constructor, verify your pointer value came from the same version of OpenSSL that this class uses. +> For more information, see . + + ]]> + + + is not a valid RSA*. @@ -116,9 +151,18 @@ - To be added. - To be added. - To be added. + The parameters for the key. + Initializes a new instance of the class using specified key parameters. + + . + + ]]> + + + is not a valid RSA key. @@ -140,9 +184,22 @@ - To be added. - To be added. - To be added. + The OpenSSL EVP_PKEY* value to use as the key, represented as a . + Initializes a new instance of the class from an existing OpenSSL key represented as an EVP_PKEY*. + + [!IMPORTANT] +> OpenSSL supports multiple library versions being loaded within the same process. +> Before calling this constructor, verify your pointer value came from the same version of OpenSSL that this class uses. +> For more information, see . + + ]]> + + + does not represent an RSA key. @@ -168,11 +225,26 @@ - To be added. - To be added. - To be added. - To be added. + The data to decrypt. + The padding mode. + Decrypts the input data using the specified padding mode. + The decrypted data. To be added. + or is . + is unknown, or not supported by this implementation. + +-or- + +The length of is not equal to the number of bytes for . + +-or- + +This instance represents only a public key. + +-or- + +The decryption operation failed. + @@ -197,8 +269,9 @@ - To be added. - To be added. + + to release both managed and unmanaged resources; to release only unmanaged resources. + Releases the unmanaged resources used by the and optionally releases the managed resources. To be added. @@ -222,9 +295,18 @@ - To be added. - To be added. - To be added. + Gets a representation of the cryptographic key. + A representation of the cryptographic key. + + object with its own lifetime. +The objects returned by this method can safely be used even after this instance has been disposed. + +]]> + @@ -250,11 +332,22 @@ - To be added. - To be added. - To be added. - To be added. + The data to encrypt. + The padding mode. + Encrypts the input data using the specified padding mode. + The encrypted data. To be added. + or is . + is unknown, or not supported by this implementation. + +-or- + +The length of is too long for the combination of and the selected padding. + +-or- + +The encryption operation failed. + @@ -279,10 +372,12 @@ - To be added. - To be added. - To be added. + + to include private parameters; otherwise, . + Exports the . + The parameters for . To be added. + The parameters could not be exported. @@ -308,10 +403,10 @@ - To be added. - To be added. - To be added. - To be added. + The binary stream to hash. + The hash algorithm. + Computes the hash value of a specified binary stream by using a specified hashing algorithm. + The hashed data. To be added. @@ -340,12 +435,12 @@ - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The data to be hashed. + The index of the first byte in that is to be hashed. + The number of bytes to hash. + The algorithm to use in hash the data. + Computes the hash value of a specified portion of a byte array by using a specified hashing algorithm. + The hashed data. To be added. @@ -371,9 +466,11 @@ - To be added. - To be added. + The parameters for . + Imports the specified . To be added. + + is not a valid RSA key. @@ -395,9 +492,20 @@ System.Int32 - To be added. - To be added. - To be added. + Gets or sets the size, in bits, of the key modulus used by the asymmetric algorithm. + The size, in bits, of the key modulus used by the asymmetric algorithm. + + + + + is not permitted by . @@ -419,8 +527,8 @@ System.Security.Cryptography.KeySizes[] - To be added. - To be added. + Gets the key sizes, in bits, that are supported by this implementation of RSA. + An array that contains the key sizes supported by the algorithm. To be added. @@ -448,12 +556,26 @@ - To be added. - To be added. - To be added. - To be added. - To be added. + The hash value of the data to be signed. + The hash algorithm used to create the hash value of the data. + The padding. + Computes the signature for the specified hash value using the specified padding. + The RSA signature for the specified hash value. To be added. + or is . + + . is or . + is unknown, or not supported by this implementation. + +-or- + +This instance represents only a public key. + +-or- + +An error occurred creating the signature. + + @@ -481,13 +603,18 @@ - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The hash value of the signed data. + The signature data to be verified. + The hash algorithm used to create the hash value. + The padding mode. + Verifies that a digital signature is valid by determining the hash value in the signature using the specified hash algorithm and padding, and comparing it to the provided hash value. + + if the signature is valid; otherwise, . To be added. + or is . + + . is or . + is unknown, or not supported by this implementation.