Requesting certificates with upcerreq

To generate a request for an application certificate on UNIX, use the commandline certificate request utility, sdk_installdir/bin/upcerreq.

The upcerreq utility generates an email message containing a public-private key pair and a certificate request, which it sends to a specified Certificate Authority. The Certificate Authority responds to the email with a certificate, which you should save and install as described in Installing certificates with upcerins.

To get a certificate, follow these steps:

1. Set your path so that it includes the UP.SDK bin directory.
2. Set the UPSDK environment variable (optional).

To simplify the use of UP.SDK notification tools, you can also set the UPSDK environment variable. The tools use this variable to determine the default locations of your key and certificate files. For example, if you installed the UP.SDK in /home/jkh/sdk on a UNIX system, type:

setenv UPSDK /home/jkh/sdk


If you intend to use UP.SDK notification tools frequently, it is recommended that you set the UPSDK environment variable in your .cshrc file.

3. Edit and save a certificate request information file.

A sample certificate request information file is provided in Example certificate request and in sdk_installdir/bin/reqinfo.txt.

The certificate request information file contains the following fields:

Field	Description
Common-Name	Specify a fully or partially qualified domain name. The Common-name must match exactly, or be an immediate subdomain of, the domain that hosts the notification alert and prefetch URLs.  For example, if you specify foo.com, the UP.Link server accepts notifications that specify URLs such as the following:  http://bar.com/mydeck.hdml  It does not accept:  http://foo.bar.com/mydeck.hdml   Alternatively, if you specify foo.bar.com, the UP.Link server accepts notifications that specify URLs such as the following:  http://foo.bar.com/mydeck.hdml http://bar.com/mydeck.hdml   It does not accept:  http://gold.bar.com/mydeck.hdml http://foo.fred.com/mydeck.hdml   Unwired Planet recommends that you use a Common-Name that specifies a subdomain of the domain that hosts the notification URLs.1  If the domain changes, you must obtain another certificate from the Certificate Authority.
Organization	Specify the name of the organization providing the HDML service.
Organization Unit	Specify the name of the business unit providing the HDML service (for example, Engineering).
Locality	Specify the town or city where the organization providing the HDML service is located. Do not abbreviate.
State	Specify the state where the organization providing the HDML service is located. Do not abbreviate.
Country	Specify the country where the organization providing the HDML service is located. Use a two-letter code.
Webmaster	Specify the fully qualified email address of the person requesting the certificate on behalf of the UP.Link service. For example:  jane_doe@mycompany.com  The upcerreq tool provides this address as the "Reply to" address in the certificate request. The Certificate Authority returns the certificate to this address.
Phone	Specify the phone number of the requestor. The phone number will not appear in the certificate itself. It is only used for administrative purposes.

1 This is because most Certificate Authorities will not permit you to have two certificates for the same domain. For example, if you already have a server certificate for foo.com, you can't also get an application certificate for that domain. So, you should request the application certificate for a subdomain of foo.com, such as bar.foo.com. If your application certificate specifies bar.foo.com, the UP.Link server will honor your notifications as long as the alert and prefetch URLs have the domain bar.foo.com (or just foo.com).

---

IMPORTANT     You must specify the Common-Name correctly. If you do not, the UP.Link server will not accept notifications from your service. When you specify the Common-Name, keep in mind that the UP.Link server will accept notifications only if the notification URL domain matches the Common-Name domain exactly or the Common-Name is an immediate subdomain of the notification URL domain.

---

4. Run the Certificate Request utility.

The utility has the following options:

upcerreq -i request_info_file -r csr_archive_file
    [-p private_key_file] [-h]

Option	Description
-i request_info_file	Specify the name of the certificate request information file that you edited in Step 3.
-r csr_archive_file	Specify a file in which to save the entire certificate request. This file is commonly known as the Certificate Signing Request (CSR) file.  Later, you will need to paste the CSR file contents into a Certificate Authority Web form to request the certificate.
-p private_key_file	Specify a full path to the file in which the private key is to be stored.   If you do not specify this option, but the environment variable UPSDK is defined, the tool creates the private key file in $UPSDK/config/priv_key.pem. You might need to create the $UPSDK/config directory if it doesn't already exist.
-h	Print help text.




When you run it, the certificate request utility prompts you to enter and reenter a password for the certificate.

5. Enter a password for the certificate.

Remember the password you enter. You will need it to send notifications.

After you enter the password, upcerreq generates a private key file and archives the request to the CSR file specified by the -r option (or to $UPSDK/config/priv_key.pem if you didn't specify the -r option).

6. Copy and paste the contents of the archived CSR into a Certificate Authority's certificate request form.

Most Certificate Authorities provide WWW forms that allow you to request certificates. The URLs of Verisign's request forms are:

https://digitalid.verisign.com/server_ids.html (real)
http://digitalid.verisign.com/test_server_ids.html (test)

Some Certificate Authorities also provide email addresses to which you can directly email the CSR.

Within several days of when you submit the certificate request, the Certificate Authority should send you a certificate response by email.

7. Save the certificate response email from the Certificate Authority to a file.

To use the certificate, you must save the email to a file and then install it as described in Installing certificates with CertMaker.

---

Example certificate request

Suppose your service's URLs are hosted on www.mycompany.com and you want to request a test certificate from Verisign. First make sure that the UP.SDK bin directory is in your path and the UPSDK environment variable is set. Then, edit the certificate request information file to look something like the following:

Common-Name: ntfn.www.mycompany.com
Organization: My Company Inc.
Organization Unit: Engineering
Locality: San Francisco
State: California
Country: US
Webmaster: jane_doe@mycompany.com
Phone: 415-555-1234

If you save this file to $UPSDK/bin/reqinfo.txt, you can use the following command to create the certificate request:

upcerreq -i $UPSDK/bin/reqinfo.txt -r $UPSDK/bin/mycsr.txt

The upcerreq utility will prompt you to enter and re-enter a password. Then it stores the Certificate Signing Request (CSR) to mycsr.txt and the private key to $UPSDK/config/priv_key.pem. To request the test certificate, you simply email the mycsr.txt file to test-request-id@verisign.com..