Documentation

XML File Encryption

Most Edge80 rule files do not contain sensitive data and simply contain adaptation rules. However, at times, secure information such as SSL certificates, password authentication information, or other sensitive information needs to be stored within rules files. This is especially true of XML Authentication and XML Credentials files.

Edge80 provides a means so that customers can completely encrypt such files and assure that unencrypted information never leaves their premises. Such encryption can be applied to any Edge80 XML format, including normal rules files. These files can also be uploaded in the Edge80 Development Console. Note however that these files, once uploaded, appear as binary files and cannot be edited directly. Only the customer has the original unencrypted files.

To encrypt these files, the customer creates an RFC-2315 cryptographic message which is protected with AES-256 encryption. AES-256 was adopted by the U.S. and Canadian governments as the chosen standard encryption, and is considered by most experts the strongest most secure encryption standard in the world. Once encrypted, only Edge80 servers themselves can read the information in order to process the rules or credentials information. The Edge80 servers themselves are locked down using a proprietary software solution which assures that no employee, contractor, or even hackers who may intercept traffic can obtain the information needed to read such files.

Important: While Edge80's security implementation assures privacy of encrypted data, it is up to the customer to assure that data is properly handled, encrypted, and stored and that no critical private information is divulged to the wrong party. Therefore, Edge80 cannot take responsibility for breaches of privacy which do not specifically involve the failure of our implementation.


Security Best Practices

Before describing XML file encryption, it is important to assure that data handling is well understood by the customer, and that the customer is prepared to take full responsibility for the encryption and storage of private information.

We recommend the following best practices:

  1. Keep secure, unencrypted information (such as SSL private keys and certificates) at secure locations in your organization. Do not store such information on servers, send it in email, or make backups containing such information unless it is stored in a format which has been secured by industry-standard key storage software. If at all possible, store such private information in physical vaults so that it cannot be easily accessed or transmitted or inadvertently copied.
  2. Limit access to private information and encryption procedures to the fewest number of employees possible.
  3. Assure that your IT Administrator understands the basic principles of Public Key Cryptography. Creating encrypted files, decoding them, and storing them is beyond what is needed for setting up a simple https site on your web server. A good starting point for administrators is The MDN Introduction to Public Key Cryptography.
  4. When first setting up a secure Edge80 site, ask us to provide you with a "test certificate". This is a dummy certificate that you can use to verify that your setup is correct before using your real certificate. See Obtaining a Test Certificate for more information.


Encrypting an XML File

In order to encrypt an XML file, you'll need a copy of the openssl package. This package is installed by default on Mac OSX and on almost all Linux systems. You can also obtain a Win32 copy of openssl from this Shining Light Productions page. However, we strongly recommend using the version which is installed under OSX.

The procedure itself is quite simple:

  1. Store your private version of the XML file locally on your system. This contains sensitive information so protect it according to our best practices.
  2. Obtain a copy of the Edge80 public key (You can download it here: Edge80-public-141224.txt).
  3. Use the openssl command (given below) to create an encrypted version which will normally have a .PEM extension.
  4. Upload the encrypted file (.PEM) to the Edge80 Development console and use it's name wherever you would normally use the name of the original XML file.

Encryption is performed using the following command:

openssl smime -encrypt -aes256 -in your-file.xml -binary -outform PEM -out 'your-file.xml.pem' Edge80-public-141224.txt

You now have a resulting .PEM file that you can safely give to anyone to upload to your Edge80 project. So long as you do not release the contents of your original XML file, the contents is safe. If you look at the PEM file you will see that it is a text format, so you can also email it to your developers, for example, so they can store it. However, be sure to indicate exactly what the file is and how it should be used.


An example

Assume you have developed an Edge80 site which is to be accessed at "https://orders.swiftautomotive.com.au".

In your Edge80 rules file, you'll declare the credentials file like this:

  <?xml version="1.0"?>
  <resource xmlns="http://schema.modapt.com/pub/modapt-resource/1.0">

      <configuration>
        <security>
          <credentials url="swiftauto-credentials.xml.pem"/>
        </security>
      </configuration>

      <include url="~/rglibrary/rulebook/1.0/framework.xml" />

      <rule name="user.page_edits">

      ....

  </resource>

Before you encrypt it, you will have a file called swiftauto-credentials.xml Again, this file will contain critical private key information that needs to be protected!

Using Edge80's Credentials XML format, the file will look like this (you can download the complete original example if you wish):

  <?xml version="1.0"?>
  <credentials xmlns="http://schema.modapt.com/pub/modapt-credentials/1.0">

    <x509-certificate-bundle domain="orders.switftautomotive.com.au">
      <certificate-list>
        <certificate>
          <!-- Godaddy certificate for orders.swiftautoomotive.com.au -->
          <![CDATA[
              -----BEGIN CERTIFICATE-----
              MIIHIjCCBQqgAwIBAgIBBDANBgkqhkiG9w0BAQUFADCBkjELMAkGA1UEBhMCQVUx
              ...
              -----END CERTIFICATE-----
          ]]>
        </certificate>

        <!-- Godaddy CA certificate bundle (contains 3 certificates). -->
        <certificate>
        ...
        ...
  </credentials>

Now, use openssl to encrypt the file:

  openssl smime -encrypt -aes256 -in swiftauto-credentials.xml -binary -outform PEM -out swiftauto-credentials.xml.pem Edge80-public-141224.txt

You can now safely store the .PEM file in your project, and the credentials element will automatically recognise the contents even though it is encrypted.