Skip to content

Tool Certificates

Jump to bottom
Tom Mitchell edited this page Jul 13, 2017 · 5 revisions

GENI Tool Certificates

GENI tools must communicate with GENI services (member authorities, slice authorities, aggregate managers, etc.) via SSL with a client-side certificate. Tools that run on the experimenter's computer can use the experimenter's certificate and private key for these communications because they are under the control of the experimenter. Tools that run on remote servers ("hosted tools"), like web-based tools or long-running services, should use their own certificate and private key for secure communications. When hosted tools want to invoke GENI services on behalf of experimenters they should use a "speaks-for" credential provided to them by the experimenter.

Requesting a tool certificate

Requesting a GENI tool certificate is easy. A GENI tool developer creates a certificate signing request (CSR) and associated private key. The CSR is sent to a GENI Clearinghouse for signing and a tool certificate is returned. This certificate contains the public key that matches the private key generated (or used) when the CSR was created.

  1. Choose a unique name for your tool and tool instance for the tool URN. The general form is ''tool''-''instance''. For example, portal-gpo for the GENI Portal running at the GPO, or genidesktop-uky for the GENI Desktop running at the University of Kentucky.

  2. Choose an email address for administrators of your tool. This will probably be an email list but could be the email address of an individual.

  3. Create a certificate signing request

    1. If you want to generate a new private key (preferred):

      openssl req -batch -new -newkey rsa:2048 -keyout PRIVATE_KEY_FILE -out CSR_FILE

    2. If you have a private key already:

      openssl req -batch -new -key PRIVATE_KEY_FILE -out CSR_FILE

  4. Create a ticket requesting a tool certificate

    1. Edit the summary to say something like "Sign CSR for YOUR_TOOL at YOUR_INSTANCE"
    2. Include the unique name (tool and instance) in the description
    3. Include the administrator email address in the description
    4. Attach the CSR to the ticket

  5. We'll create a new certificate from the attached CSR and attach the resulting certificate to the ticket. You can then download the certificate and use it with the private key used when you created the CSR.

Creating a tool certificate

This section is for GENI operators.

There are three pieces of information required to generate a tool certificate:

  1. A certificate signing request (CSR) from the tool developer or admin
  2. A unique id for use in the tool's URN
    • This is generally something like ''tool''-''instance'' and must follow the rules for tool URNs
  3. An email address for the developer or admin of this tool instance
    • Often a mailing list, but may be an individual developer

Tool certificates are signed by the member authority (MA) because they are actors in GENI and thus similar to members. The logic goes that generally speaking, certificates signed by an MA are used to secure communications with GENI services while certificates signed by a slice authority (SA) are for passive objects in GENI (projects, slices). In the future we may want to introduce a new "tool authority" but for now the MA will suffice.

Signing the tool CSR

  • Use geni-sign-tool-csr to sign tool CSRs and thus generate tool certificates.
  • Run the command via user apache because the CA directory where certificates are stored is owned by apache
    • N.B. Take care that apache may not have permission to write the certificate to your directory. It is advisable to write the certificate to /tmp. If geni-sign-tool-csr cannot write to the requested file it will write it to stdout so that it is not lost. If for some reason it does get lost you can find it manually in /usr/share/geni-ch/CA/newcerts where all generated certificates are stored.
  • Use the MA key (/usr/share/geni-ch/ma/ma-key.pem) and MA certificate (/usr/share/geni-ch/ma/ma-cert.pem) to sign the tool certificate.
  • Use the authority found in the URN of the MA certificate (probably ch.geni.net unless you're testing on a development host)

Here is a sample command for a instance "instance1" of tool "tool1" with admin email address "tool-admins@example.com":

# Set environment variables
export TOOL_EMAIL=example@example.com
export TOOL_NAME=collector-example
export TOOL_CSR=collector-example.csr
export TOOL_EXPIRATION=1825  # 5 years

# Generate the certificate
sudo -u apache geni-sign-tool-csr -k /usr/share/geni-ch/ma/ma-key.pem -c /usr/share/geni-ch/ma/ma-cert.pem \
    -a ch.geni.net -d "${TOOL_EXPIRATION}" -e "${TOOL_EMAIL}" -i "${TOOL_NAME}" --csr "${TOOL_CSR}" > /tmp/"${TOOL_NAME}".pem

Compute expiration days

Here are a few lines of Python to compute how many days between now and a future date. We are expiring certificates in early September right now, so we use that as the future date. The output goes in the above signing command as the $TOOL_EXPIRATION.

import datetime
x= datetime.datetime(2014, 9, 4)
(x - datetime.datetime.now()).days + 1

Preserving the Subject

N.B. This is an advanced use case and atypical.

In rare circumstances we want to preserve the Subject present in the certificate signing request. This is not the default behavior of the geni-sign-tool-csr script, but available as a command line option. The default behavior is to ignore the Subject in the CSR and generate our own using UUID and email address.

If the CSR contains a subject that should be present in the resulting certificate, use the --use-csr-subject to carry it forward from the CSR to the certificate.

Clone this wiki locally