Use secure URLs to protect calendars

If your calendar contains proprietary or other confidential data that you're providing to your group on an intranet or secure server, you can add a level of security by publishing the calendar with a secure URL.

The secure URL publishing mode uses a secure key to generate a unique hash and expiration time for how long the spud code can be used to access the calendar's spuds.

This makes it possible for visitors to see the secure calendar without providing a password. In addition:

• If visitors copy the spud code to make the calendar available elsewhere, the code will expire and the calendar will not display.
• If someone tries to access your calendar that is hosted on the Trumba servers (www.trumba.com/calendars/yourcalendarname), Trumba Connect returns a page that is blank except for a message indicating that you cannot display the information without a secure URL.

What you can learn in the rest of this topic:

• Requirements for creating secure URLs
• Steps for creating secure URLs

Requirements for creating secure URLs

Creating secure URLs is an advanced, developer-level procedure.

This topic describes how you can create secure URLs by using PHP or ASP.Net with C#. The minimum requirements that you must meet before you attempt to create secure URLs are that you:

• Are proficient with ASP.Net, PHP, or a similar Web server scripting language.

Note Knowledge of HTML and CSS is also important for creating pages that host secure Trumba Connect spuds, but it is not sufficient. You must know a server scripting language.

• Have an environment in which you can build and view these pages in a browser.

  For the ASP.Net+C# example, typically that means Microsoft® Windows, Microsoft IIS, and the ASP.Net 2.0 (or higher) Framework. For PHP, you can use any Web server (for example, Apache) that has PHP installed.

• Have publishing permission for the Trumba calendar and are familiar with calendar spud code.

If you do not meet the requirements for creating secure URLs, we recommend that you consult with a Web developer.

High-levels steps for creating secure URLs

1. Publish the calendar. On the Publish Settings page, generate a secure key.
2. Use code provided by Trumba development to create your secure URLs.

   Use your secure key and your calendar's web name to replace the placeholder text in secure.aspx or secure.php. This is a file that you download from this topic, which contains ASP.Net or PHP code created by Trumba development.

3. In the webpage that contains your calendar spud, in the spud code, instead of entering the static URL for your published calendar, enter code that follows the example in secure.aspx (or secure.php). The secure spud code calls the CreateSecureHash() function, which generates the unique hash and expiration time that is returned to the user.

Get a secure key for your published calendar

1. In your Trumba account, display the calendar you want to publish or have published, and click Publish.
2. If the calendar is already published, the Publishing Control Panel appears. On the Publish Settings tab, click Edit Publish Settings.
3. In the Publish Settings section of the publish settings page, for Access type, click Secure URL.
4. Click Set your secure key, and then in the form that appears, enter and confirm a password for your calendar, and then click Set.
5. In the Publish Settings page, click Display secure key.
6. Copy the secure key and paste it in a place where you will be able to access it when it's time to paste the information into secure.aspx (or .php), the downloadable file (see the next section) that contains the code you will use to create your secure URLs.
7. Make any other changes you want on the publish settings page, and then click OK.

Use code provided by Trumba development to create your secure URLs

After you get your secure key from Trumba publishing settings, you need to use that key along with your calendar's web name in code that Trumba development has created for you to generate the secure URLs.

1. Download the sample code to use as a guideline for generating secure URLs.
   • ASP.Net
   • PHP
2. The sample code in the downloaded file returns a unique, secure URL to the user who requests the calendar page on your secure site. It does the following to create the URL:
   • Sets the secure URL to expire one day from the time the user requests the calendar. (You can change the expiration time to whatever works best for your group.)
   • Uses your secure key and the expiration time to generate an MD5 hash, which it plugs into a hash parameter.
   • In the sample webpage you download, instead of entering a static URL for displaying your calendar, it calls the CreateSecureHash() function, which generates and returns the secure URL. Client-side browsers show the end result of the calculations, not the function.
3. In the downloaded sample code file, plug your calendar into the example by:
   • Pasting the secure key you obtained in publish settings over the placeholder text that says YOUR KEY GOES HERE.
   • Typing your calendar's web name over the the placeholder text that says YOUR WEBNAME GOES HERE.
   • If you want to set an expiration time different from one day, for LIFETIME = 1.0, change 1.0 to the number of days you prefer.

     Tip To set the expiration time to less than a day, use a value smaller than 1.

   • Save the file to a location where you can test it on your production server to make sure the sample HTML code displays your spuds correctly.
   • In your production content, use the script code that contains the CreateSecureHash() function, your secure key, and your calendar web name. The code can live in the same .aspx or .php file that contains your calendar content, in the code-behind for the file, or in another file, as long as it's visible to the page in which you place your secure spuds.
   • In the code for each of the spuds you embed, remember to use the url argument (as shown below) to include a call to the CreateSecureHash() function.
     <script type="text/javascript">
     $Trumba.addSpud({
     webName: "name",
     spudType: "type",
     url: { <%= CreateSecureHash() %> }
     });
     </script>

Tip If you think the security of your secure URL has been compromised, you can update it with a new secure key. Open the Edit Publish Settings page (as described above). In the Publish Settings section, under Access type, click Change your secure key. When you get the new key, display it, copy it, and then paste it into the code on your web server.

Using your own code

If your use something other than the .Net Framework or PHP for your web server computing environment, you can use your own code to implement secure URLs. However, we strongly recommend that you read the sample code provided by Trumba Development because it is a working example of how to generate the secure spuds. This section describes the steps you need to complete.

Get the required parameters

Spud code that you enter in your page to display a calendar that is protected through secure URLs must carry two parameters:

• expires

  The expires parameter is a UTC date in yyyyMMddHHmm format. It tells Trumba Connect how long access to the calendar should be granted with the URL. The default duration is one day.

• hash

  The hash parameter is a hexadecimal string that contains the MD5 hash of a query string that you build using your calendar name and the other two required parameters. The query string looks like this:

  calendar=webname&expires=expiration&hash=yoursecurekey

  Replace the blue placeholder text with the appropriate values. The expires parameter requires the same date format described in the previous bullet.

Plug the required parameters into the spud code

Once you have an MD5 hash of your query string, you provide the hash and your expires value to the $Trumba.addSpud() call. These values must appear in string fields on the url parameter.

What follows is an example of an expiration time and hash that have been dynamically generated by a call to the CreateSecureHash() function.

Tip Take a look at the PHP or ASP.Net example code to clarify the above example.

Additional information

When you create your secure key in the publishing settings, you cannot display your calendar any way other than by going through the process of generating an MD5 hash, as in the procedures above. Using your secure key with a hash parameter in a static URL will not work.

Your secure key is also stored on the Trumba server in association with your calendar. When a user tries to display your calendar, Trumba Connect generates an MD5 hash from your secure key. If the MD5 hash generated from Trumba Connect doesn't match yours, Trumba Connect cannot display your calendar.