ProtectApp .NET to CADP for .NET Core
Prerequisites
CipherTrust Manager is up and running at a supported version. For more details, refer to CipherTrust Manager Deployment.
The CADP for .NET Core library is built on .NET standard 2.1. Click here to refer the supported .NET/.NET Core application versions.
Recommended version: NET 6.0 or higher.
The supported version should be installed on your machine.
While updating your application to the supported version, ensure to:
Update all the Microsoft libraries used in the project.
Update dependent projects and libraries to the supported version.
Supported Versions
Current Setup
Product | Version |
---|---|
ProtectApp .NET | 8.11.0 |
KeySecure Classic | 8.5.0 or higher |
Target Setup
Product | Version |
---|---|
CADP for .NET Core | 8.12.0, 8.13.0, or 8.14.0 |
CipherTrust Manager | 2.2 or higher |
Installation Steps
Back up the
ProtectAppForDotNet.properties
file. By default, this file is placed atC:\Program Files\SafeNet ProtectApp\DotNet\ProtectAppForDotNet.properties
in Registry.Remove the old references of ProtectApp .NET Library from your project.
In Visual Studio, go to Solution Explorer > References and remove the reference of
ingdnp.dll
.Comment out the
"using Ingrian.Security.Cryptography;"
line in your project. This will give build errors.
Add the
CipherTrust.CADP.NETCore
package to your project. For details, refer to Adding NuGet Package to the Project. All the dependent libraries will be downloaded automatically to the default NuGet installation directoryC:\Users\%UserName%\.nuget\packages\ciphertrust.cadp.netcore\<product-version>\
.Configure the
CADP.NETCore_Properties.xml
file (placed atC:\Users\%UserName%\.nuget\packages\ciphertrust.cadp.netcore\<product-version>\content\
) similar to the old properties file (backed-up in step 1).
After performing the above steps, you can now change your application as described in the subsequent sections.
Properties File
The following table compares the parameters in ProtectApp .NET and CADP for .NET Core properties files. We have only listed the differences in both files.
The following parameters have been renamed in CADP for .NET Core.
Cert_File
is renamed toClientCert
.Symmetric_Key_Cache_Expiry
is renamed toKey_Cache_Expiry
.
Default file locations are:
ProtectApp .NET:
C:\Program Files\SafeNet ProtectApp\DotNet\ProtectAppForDotNet.properties
CADP for .NET Core:
C:\Users\%UserName%\.nuget\packages\ciphertrust.cadp.netcore\<product-version>\content
Property Name | ProtectApp .Net | CADP for .NET Core |
---|---|---|
FIPS_Mode | Yes | No |
KMIP_Spec_File | Yes | No |
KMIP_IP | Yes | No |
KMIP_Port | Yes | No |
Cipher_Spec | Yes | No |
Cert_File_Location | Yes | No |
EToken_Name | Yes | No |
EToken_Password | Yes | No |
Key_File | Yes | No |
EvpContext_Idle_Timeout | Yes | No |
Ignore_DNS_Resolution_Failure | Yes | No |
FPE_Unicode_File | Yes | No |
Property Name | ProtectApp .Net | CADP for .NET Core |
---|---|---|
FIPS_Mode | Yes | No |
KMIP_Spec_File | Yes | No |
KMIP_IP | Yes | No |
KMIP_Port | Yes | No |
Cipher_Spec | Yes | No |
Cert_File_Location | Yes | No |
EToken_Name | Yes | No |
EToken_Password | Yes | No |
Key_File | Yes | No |
EvpContext_Idle_Timeout | Yes | No |
Persistent_Cache_Enabled | Yes | No |
Persistent_Cache_Directory | Yes | No |
Persistent_Cache_Expiry_Keys | Yes | No |
Persistent_Cache_Max_Size | Yes | No |
Ignore_DNS_Resolution_Failure | Yes | No |
FPE_Unicode_File | Yes | No |
Property Name | ProtectApp .Net | CADP for .NET Core |
---|---|---|
FIPS_Mode | Yes | No |
KMIP_Spec_File | Yes | No |
KMIP_IP | Yes | No |
KMIP_Port | Yes | No |
Syslog_Server_IP | Yes | No |
Syslog_Server_Port | Yes | No |
Syslog_Server_Protocol | Yes | No |
Syslog_no_of_retries | Yes | No |
Syslog_Retry_Interval | Yes | No |
Syslog_Retry_Limit | Yes | No |
Syslog_CA | Yes | No |
Syslog_Cert | Yes | No |
Syslog_Key | Yes | No |
Syslog_Passphrase | Yes | No |
Cipher_Spec | Yes | No |
Cert_File_Location | Yes | No |
EToken_Name | Yes | No |
EToken_Password | Yes | No |
Key_File | Yes | No |
EvpContext_Idle_Timeout | Yes | No |
Persistent_Cache_Enabled | Yes | No |
Persistent_Cache_Directory | Yes | No |
Persistent_Cache_Expiry_Keys | Yes | No |
Persistent_Cache_Max_Size | Yes | No |
Ignore_DNS_Resolution_Failure | Yes | No |
FPE_Unicode_File | Yes | No |
Limitations
This section lists limitations in CADP for .NET Core.
Configuration Parameters
Cipher_Spec and Ignore_DNS_Resolution_Failure are not supported.
Crypto operations
Sign and Verify certificates in CMS format, Execution of Bulk operation on passed IV list, inDataList (input data list), UserSpecList for any Key, Random Load Balancing, and FPE Formats are not supported.
Key Management
AES Key Wrapping, Deriving any symmetric key from any symmetric key, Modifying Group Permissions for a Key, and Importing Symmetric and Asymmetric Key are not supported.
ExportWrappedAESKey API has limited support in CADP for .NET Core. You can only export symmetric key bytes wrapped with RSA key bytes. ECC, TDES, and AES are not supported.
DN_T_KeyLifecycleState is not supported in SetKeyParameter.
NAE Certificate Management
Exporting a CA Chain, Deleting a Certificate, ExportCertificate, GetKeyNames, and Retrieves a list of key names that are accessible by the authenticated user are not supported.
Algorithms
DES algorithms are not supported.
For EC keys, encryption and decryption is not supported.
MAC and Verify For MAC
For versioned keys, the MAC generated using ProtectApp .NET in local mode with
ComputeHash
API doesn't match the MAC generated by CADP for .NET Core. This leads to the failure of MACverify using CADP for .NET Core.Below are the possible workarounds:
Workaround 1
You can use this workaround if all the data is hashed using the latest key version.
Clone the latest key version and rename the cloned key. For example, clone the "pa_net_key_latest_version" key and change its name to "cadp_net_core_key".
Clear the Versioned Key check box under NAE tab for the new cloned key ("cadp_net_core_key").
Use the key ("cadp_net_core_key") in CADP for .NET Core for the MACVerify operation.
Workaround 2
Rehash the original data using ProtectApp .NET in remote mode before migrating to CADP for .NET Core.
Configuration Parameters
Persistent Key Cache-related parameters, Cipher_Spec, and Ignore_DNS_Resolution_Failure are not supported.
Crypto operations
CryptoDataUtility, Sign and Verify certificates in CMS format, Execution of Bulk operation on passed IV list, inDataList (input data list), UserSpecList for any Key, Random Load Balancing, and FPE Formats are not supported.
Key Management
AES Key Wrapping, Deriving any symmetric key from any symmetric key, Key Group Permissions and Modifying Group Permissions for a Key, and Importing Symmetric and Asymmetric Key are not supported.
ExportWrappedAESKey API has limited support in CADP for .NET Core. You can only export symmetric key bytes wrapped with RSA key bytes. ECC, TDES, and AES are not supported.
DN_T_KeyLifecycleState is not supported in SetKeyParameter.
NAE Certificate Management
Exporting a CA Chain, Deleting a Certificate, ExportCertificate, GetKeyNames, and Retrieves a list of key names that are accessible by the authenticated user are not supported.
Algorithms
EC and DES algorithms are not supported.
MAC and Verify For MAC
For versioned keys, the MAC generated using ProtectApp .NET in local mode with
ComputeHash
API doesn't match the MAC generated by CADP for .NET Core. This leads to the failure of MACverify using CADP for .NET Core.Below are the possible workarounds:
Workaround 1
You can use this workaround if all the data is hashed using the latest key version.
Clone the latest key version and rename the cloned key. For example, clone the "pa_net_key_latest_version" key and change its name to "cadp_net_core_key".
Clear the Versioned Key check box under NAE tab for the new cloned key ("cadp_net_core_key").
Use the key ("cadp_net_core_key") in CADP for .NET Core for the MACVerify operation.
Workaround 2
Rehash the original data using ProtectApp .NET in remote mode before migrating to CADP for .NET Core.
Configuration Parameters
Syslog-related parameters, Persistent Key Cache-related parameters, Cipher_Spec, and Ignore_DNS_Resolution_Failure are not supported.
Crypto operations
CryptoDataUtility, Sign and Verify certificates in CMS format, Execution of Bulk operation on passed IV list, inDataList (input data list), UserSpecList for any Key, Random Load Balancing, and FPE Formats are not supported.
Key Management
AES Key Wrapping, Deriving any symmetric key from any symmetric key, Key Group Permissions and Modifying Group Permissions for a Key, and Importing Symmetric and Asymmetric Key are not supported.
DN_T_KeyLifecycleState is not supported in SetKeyParameter.
ExportWrappedAESKey API has limited support in CADP for .NET Core. You can only export symmetric key bytes wrapped with RSA key bytes. ECC, TDES, and AES are not supported.
NAE Certificate Management
Exporting a CA Chain, Deleting a Certificate, ExportCertificate, GetKeyNames, and Retrieves a list of key names that are accessible by the authenticated user are not supported.
Algorithms
EC and DES algorithms are not supported.
MAC and Verify For MAC
For versioned keys, the MAC generated using ProtectApp .NET in local mode with
ComputeHash
API doesn't match the MAC generated by CADP for .NET Core. This leads to the failure of MACverify using CADP for .NET Core.Below are the possible workarounds:
Workaround 1
You can use this workaround if all the data is hashed using the latest key version.
Clone the latest key version and rename the cloned key. For example, clone the "pa_net_key_latest_version" key and change its name to "cadp_net_core_key".
Clear the Versioned Key check box under NAE tab for the new cloned key ("cadp_net_core_key").
Use the key ("cadp_net_core_key") in CADP for .NET Core for the MACVerify operation.
Workaround 2
Rehash the original data using ProtectApp .NET in remote mode before migrating to CADP for .NET Core.
Deprecated Support
FIPS_Mode
KMIP
EvpContext_Idle_Timeout
EToken_Name, EToken_Password
FPE_Unicode_File
Note
You can directly provide the charset range in the application.
Mapping Legacy Calls to CADP for .NET Core
Class Replacements
ProtectApp .NET | CADP for .NET Core | References |
---|---|---|
NAESession | NaeSession | CADP.NetCore.Sessions; |
NAEException | NaeException | CADP.NetCore.ExceptionHandler; |
NAERijndaelKey | NaeRijndaelKey | CADP.NetCore.Crypto; |
Rijndael | NaeRijndaelKey | CADP.NetCore.Crypto; |
NAEFPE | NaeFpe | CADP.NetCore.Crypto; |
FPE_Cardinality.CARD10 | NaeFpe.Cardinality.CARD10 | CADP.NetCore.Crypto; New enum is introduced for Cardinality. |
FPE_Cardinality.CARD62 | NaeFpe.Cardinality.CARD62 | CADP.NetCore.Crypto; |
FPE_Cardinality.CARD26 | NaeFpe.Cardinality.CARD26 | CADP.NetCore.Crypto; |
NAEAESGCM | NaeAesGcm | CADP.NetCore.Crypto; |
NAEHMACSHA1 | NaeHmacKey | CADP.NetCore.Crypto; |
HMAC | NaeHmacKey | CADP.NetCore.Crypto; |
NAERSAKey | NaeRsaKey | CADP.NetCore.Crypto; |
NAEKeyManagement | NaeKeyManagement | CADP.NetCore.KeyManagement; |
NAEECKey | NaeECIESKey | CADP.NetCore.Crypto |
NAEECKey.I_T_Curve_ID.I_T_prime256v1 | NaeECIESKey.SupportedCurves.prime256v1_256 | CADP.NetCore.Crypto |
ProtectApp .NET | CADP for .NET Core | References |
---|---|---|
NAESession | NaeSession | CADP.NetCore.Sessions; |
NAEException | NaeException | CADP.NetCore.ExceptionHandler; |
NAERijndaelKey | NaeRijndaelKey | CADP.NetCore.Crypto; |
Rijndael | NaeRijndaelKey | CADP.NetCore.Crypto; |
NAEFPE | NaeFpe | CADP.NetCore.Crypto; |
FPE_Cardinality.CARD10 | NaeFpe.Cardinality.CARD10 | CADP.NetCore.Crypto; New enum is introduced for Cardinality. |
FPE_Cardinality.CARD62 | NaeFpe.Cardinality.CARD62 | CADP.NetCore.Crypto; |
FPE_Cardinality.CARD26 | NaeFpe.Cardinality.CARD26 | CADP.NetCore.Crypto; |
NAEAESGCM | NaeAesGcm | CADP.NetCore.Crypto; |
NAEHMACSHA1 | NaeHmacKey | CADP.NetCore.Crypto; |
HMAC | NaeHmacKey | CADP.NetCore.Crypto; |
NAERSAKey | NaeRsaKey | CADP.NetCore.Crypto; |
NAEKeyManagement | NaeKeyManagement | CADP.NetCore.KeyManagement; |
ProtectApp .NET | CADP for .NET Core | References |
---|---|---|
NAESession | NaeSession | CADP.NetCore.Sessions; |
NAEException | NaeException | CADP.NetCore.ExceptionHandler; |
NAERijndaelKey | NaeRijndaelKey | CADP.NetCore.Crypto; |
Rijndael | NaeRijndaelKey | CADP.NetCore.Crypto; |
NAEFPE | NaeFpe | CADP.NetCore.Crypto; |
FPE_Cardinality.CARD10 | NaeFpe.Cardinality.CARD10 | CADP.NetCore.Crypto; New enum is introduced for Cardinality. |
FPE_Cardinality.CARD62 | NaeFpe.Cardinality.CARD62 | CADP.NetCore.Crypto; |
FPE_Cardinality.CARD26 | NaeFpe.Cardinality.CARD26 | CADP.NetCore.Crypto; |
NAEAESGCM | NaeAesGcm | CADP.NetCore.Crypto; |
NAEHMACSHA1 | NaeHmacKey | CADP.NetCore.Crypto; |
HMAC | NaeHmacKey | CADP.NetCore.Crypto; |
NAERSAKey | NaeRsaKey | CADP.NetCore.Crypto; |
NAEKeyManagement | NaeKeyManagement | CADP.NetCore.KeyManagement; |
API Call Replacements
Create an NAE Session
ProtectApp .NET | CADP for .NET Core |
---|---|
Property File is read from Registry. | After installing the NuGet package, the new properties file is available at the default installation location of the NuGet package. For more details, refer to Create an NAE Session. For sample, refer to CryptoOpRijndael. |
|
|
Get Keys
ProtectApp .NET | CADP for .NET Core |
---|---|
| Use NaeKeyManagement API to get a key.
For more details, refer to Getting an Instance of a Key Object and Alternative Method to Get an Instance of a Key Object. For sample, refer to CryptoOpRijndael. |
Export Keys
ProtectApp .NET | CADP for .NET Core |
---|---|
| To export a key, pass key name and its type using enum NaeKeyManagement.KeyType. The key type can be public, private, or both. For more details, refer to Exporting a Key. |
| To export all versions of the versioned key, pass value as true . For more details, refer to Exporting all Versions of a Versioned Key. |
If the boolean value includePrivateParameters is true , both the public and private parts of the key are exported. If the value is false, only the public part of the key is exported. |
This will export public part of the key.Use NaeKeyManagement.KeyType.PublicPrivate to export both the public and private parts of the key.For more details, refer to Exporting a Key. For versioned key, refer to Exporting all Versions of a Versioned Key. |
Get Attributes of Keys
ProtectApp .NET | CADP for .NET Core |
---|---|
| Pass both the dictionaries to fill in the attributes. For more details, refer to Getting Attributes of a Key. For sample, refer to NaeKeyManagement. |
| The SystemAttr is a dictionary; therefore, it returns all the attributes as key-value pairs. |
| The SystemAttr is a dictionary; therefore, it returns all the attributes as key-value pairs. |
| Use enum NaeKeyManagement.KeyParameterType.KeyVersion and NaeKeyManagement.KeyParameterValue.VersionIncrement to increment the key version.For more details, refer to Creating a New Version of the Versioned Key. |
Delete Keys
ProtectApp .NET | CADP for .NET Core |
---|---|
| For more details, refer to Deleting a Key using the Key Name. |
Export Wrapped Keys
ProtectApp .NET | CADP for .NET Core |
---|---|
NAEKeyBytes wrappedBytes = new NAEKeyBytes(); naeKeyMgmt.ExportWrappedKey(session,"SafeNet_example_Rijndael_key", pubKeyBytes.keyBytes, KeyWrapFormat.RAW_PKCS1v15, wrappedBytes); | For more details, refer to Exporting a Wrapped Key. For sample, refer to ExportWrappedKey. |
Encryption and Decryption
ProtectApp .NET | CADP for .NET Core |
---|---|
| If key is already created, the Tag_length should be provided while creating the NaeAesGcm() object.For more details, refer to NaeAesGcm. For sample, refer to CryptoOpAesGcm. |
| Since InitializeAESGCM() is not present; therefore, the AAD_Data needs to be provided when performing any crypto operation such as Encrypt and Decrypt. Also, the UserSpec cannot be used to initialize TagLength and AAD Data (Tag length supported is 12 to 16).For more details, refer to AES/GCM. |
| Passed during the encrypt and decrypt calls. The IV should be 12 bytes. |
Remove all CreateEncryptor() along with MemoryStream and CryptoStream. | This tag will return with encrypted data and should be passed while decrypting. The AAD data will be passed in Encrypt() and is exposed in the aes gcm class object. |
Remove all CreateDecryptor() along with MemoryStream and CryptoStream. |
|
ProtectApp .NET | CADP for .NET Core |
---|---|
| Since InitializeFPE is not provided in UserSpec; therefore, create object and provide TweakData and TweakAlgo. For more details, refer to NaeFpe and Format Preserving Encryption.For sample, refer to CryptoOpFpe. |
| To use FPE/AES/CARD10, use NaeFpe.AlgorithmName.FPE_AES_CARD10 enum. FPE has many variants such as FF1v2 and FF3. For more details, refer to FPE/AES. |
ProtectApp .NET | CADP for .NET Core |
---|---|
| Provide the "RSAEncryptionPadding" enum value. For more details, refer to Encrypt a String Using an RSA Key and NaeRSAKey. For sample, refer to CryptoOpRSAEncDec. |
|
Provide the "RSAEncryptionPadding" enum value. For more details, refer to Decrypt a String Using an RSA Key and RSA. |
Sign and Verify
ProtectApp .NET | CADP for .NET Core |
---|---|
| Pass the Hash Algorithm and RSA Sign Padding. For more details, refer to Sign and SignVerify Data using an RSA Key and NaeRSAKey. For sample, refer to CryptoOpRsaSignVerify. |
| Pass the Hash Algorithm and RSA Sign Padding. For more details, refer to RSA. |
| Hash Algorithm is already passed when key is created. |
| Hash Algorithm is already passed when key is created. |
ProtectApp .NET | CADP for .NET Core |
---|---|
| Pass the Hash Algorithm. For more details, refer to Supported Algorithms. For sample, refer to CryptoOpECSignVerify.cs. For EC keys, encryption and decryption is not supported. |
|
|
| NOTE: ecKey.CurveID = (int)(NaeECIESKey.SupportedCurves.brainpoolP224r1_224); To set the curve, pass the value in NaeECIESkey constructor. Setting the value using "CurveID" property is not supported. |
Mac and Verify for HMAC
ProtectApp .NET | CADP for .NET Core |
---|---|
| Since NaeHmacKey supports multiple HMAC Algorithms; therefore, enum can be passed with multiple values. For more details, refer to HMAC-SHA. |
| For more details, refer to MAC/Hash-related Calls. For sample, refer to CryptoOpMacVerify. |
| Same as ProtectApp .NET. |
Not applicable. | This is a new method exposed to Generate MAC. |
Not applicable. | The input bytes and Mac are passed to the VerifyMac() function, it returns true if hash matches else false is returned. For more details, refer to Generate and Verify MAC. |