This chapter will guide you through securing your existing client application using ARWebService with symmetric cryptography features. It can also be used for troubleshooting existing installations.

Note: This chapter follows Installing and Configuring the ARWebService and the Client Application chapter and assumes that your application is configured and working correctly with unsecured ARWebService.

Configuring ARWebService for Symmetric Cryptography

1. Updating ARWebService settings in its Web.config file.
   
   Parameters in the <appSettings> section:
   
   

                                   i.            SecureAccessSymmetricKey - if you want to use symmetric encryption, it is necessary to specify shared  symmetric key, that will be used for encrypting/decrypting messages; the same symmetric key must be deployed to the client application configuration files (.config files) as well; the value must be 24 bytes long hexadecimally encoded value. Please note that you can write your own symmetric key provider and choose some other storage of the symmetric key.
    

                                  ii.            SecureAccessRuleSymmetricEncryptionRequired - indicates whether the symmetric encryption is required for both incoming and outgoing messages. If it's set to true, requests that are not symmetrically encrypted will be refused. Possible values are "true" or "false".
   
   

   <appSettings>     <!-- Shared Symmetric Key to be used for encrypting/decrypting the responses/requests -->     <add key="SecureAccessSymmetricKey" value="104FEE68517937764D25651347C0D87BE3846F068A427B28" />     <add key="SecureAccessRuleSymmetricEncryptionRequired" value="true" />   </appSettings>

    

   The <decryptionKeyProvider> section specifies a user-defined class that implements the IDecryptionKeyProvider interface and retrieves the key needed to decrypt SOAP messages that were encrypted using the symmetric key. You can use either the included PortSight Secure Acccess provide (as shown below) or write your one.
   
   

   <!-- This is the WSE configuration section -->     <microsoft.web.services>         <!-- Set the enabled attribute to "true" for input and output tracing -->         <security>             <x509 storeLocation="CurrentUser" />            <decryptionKeyProvider type="PortSight.SecureAccess.WebServices.Common.ARWSDecryptionKeyProvider, PortSight.SecureAccess.WebServices.Common" />         </security>     </microsoft.web.services>

   
   

2. The Secure Access Web Service should be working now. Please continue with configuration of the client.
   
3. You can verify that the ARWebService has been configured correctly by running test sample called SampleARWSTestFormVB.exe - you can find this file including the source code project in the "Examples\VB\TestARWebService\bin" folder under the PortSight Secure Access installation folder.
   
   Delete the values in the "Encoding Cert Key ID" and "Signing Cert Key ID" fields. Enter value "104FEE68517937764D25651347C0D87BE3846F068A427B28" in the "Encrypting Symmetric Key" field, enter the correct catalog name (it's case-sensitive!), login name and password and click "Try Login". You should get be the confirmation or detailed error message.

1. Updating settings in the <Your Client App Name>.exe.config file:
   
   

   In the appSettings section, it is necessary to specify shared symmetric key if you want to symmetrically encrypt the requests and decrypt the incoming symmetrically encrypted responses. The symmetric key must be the same as specified in the service Web.config file.
   
   This configuratiom parameter is used only by ARWSDecryptionKeyProvider class. We recommend you to write your own DecryptionKeyProvider from scratch or at least derive your own DecryptionKeyProvider from ARWSDecryptionKeyProvider and override the GetSymmetricKey() method, since storing symmetric key in .config files is insecure - see chapter Developing Your Own Decryption Key Provider.

   
   Parameters in the <appSettings> section:

                                   i.            SecureAccessSymmetricKey - if you want to use symmetric encryption, it is necessary to specify shared  symmetric key, that will be used for encrypting/decrypting messages; the same symmetric key must be deployed to the client application configuration files (.config files) as well; the value must be 24 bytes long hexadecimally encoded value. Please note that you can write your own symmetric key provider and choose some other storage of the symmetric key.

                                  ii.            SecureAccessRuleSymmetricEncryptionRequired - indicates whether the symmetric encryption is required for both incoming and outgoing messages. If it's set to true, requests that are not symmetrically encrypted will be refused. Possible values are "true" or "false".

   
   
   

   <appSettings>     <!-- Shared Symmetric Key to be used for encrypting/decrypting the responses/requests -->     <add key="SecureAccessSymmetricKey" value="104FEE68517937764D25651347C0D87BE3846F068A427B28" />     <add key="SecureAccessRuleSymmetricEncryptionRequired" value="true" />   </appSettings>

   
    

   The section <decryptionKeyProvider> specifies a user-defined class that implements the IDecryptionKeyProvider interface and retrieves the key needed to decrypt SOAP messages that were encrypted using the symmetric key.

   
   
   

   <!-- This is the WSE configuration section -->     <microsoft.web.services>         <!-- Set the enabled attribute to "true" for input and output tracing -->         <security>             <x509 storeLocation="CurrentUser" />            <decryptionKeyProvider type="PortSight.SecureAccess.WebServices.Common.ARWSDecryptionKeyProvider, PortSight.SecureAccess.WebServices.Common" />         </security>     </microsoft.web.services>

   
    

2. Now your application should be ready for using ARWebService secured with symmetric cryptography.