This lesson is being piloted (Beta version)

DUNE HWDB Training: Obtaining a FNAL certificate



Questions, Requests, and the Liaisons

Any question/comments, including requests of examples to be added as training materials, should be directed to the liaison of your consortium (click the button below) as well as the followings: Norm Buchanan, Ana Paula, and Hajime Muramatsu. For issues of the HWDB itself, also inform here.

Objectives

Requirement

Do you have your account in the HWDB?

Anybody with a FNAL Services account should have their account ready in the HWDB.

Perhaps, the best way to check this to try to log into one of the HWDB versions available. There are two versions of the DUNE HWDB, the development version and the production version. You can practice in the development version (e.g., to go through this training site), while the production version is the official DUNE Hardware Database. Go ahead to try log into one of them with your Web browser:

Production version : https://dbweb0.fnal.gov/cdb/login/sso

Development version: https://dbweb0.fnal.gov/cdbdev/login/sso

If you can login, that confirms that you have your account ready in the HWDB. And let us know if you cannot.

There are two ways to communicate with the DUNE HWDB, through the WEB UI and the REST API (more on these methods later!). If you can login there, you are ready to go through the training with the WEB UI.

To communicate through the REST API, however, you would need a FNAL certificate. The followings describe how to obtain yours.

Obtaining your certificate

By following the procedure described below, you will obtain your password-protected certificate in the “PKCS #12 format” that bundles a private key with its X.509 certificate from https://www.cilogon.org.

  1. With your web browser, go to https://www.cilogon.org

  2. Select Log On from its side menu.

  3. Select Fermi National Accelerator Laboratory as your Identity Provider and click Log On.

  4. Provide your FNAL Services account credential.

  5. Select Create Password-Protected Certificate (usually shows up at the top).

  6. Enter the password, which is not necessarily the same as the one for your FNAL Services account (preferentially a different password).

  7. Select Get New Certificate.

  8. Select Download Your Certificate.

  9. Select Log Off (or close your browser).

  10. You should have a file, usercred.p12, downloaded on your computer now.

  11. In your terminal, try the following commands to convert the downloaded usercred.p12 to a pem file:

    openssl version


    If it shows OpenSSL 1.X, do the following to convert your downloaded usercred.p12 to a pem file, in which you would need to provide the password you entered in the Step 6. You would also need to provide a unique phrase. Give anything you like here, but remember it. We will use it.

    As for the output file name, Output, give any name you like.

    openssl pkcs12 -in usercred.p12 -out Output.pem

    If, on the other hand, your OpenSSL version is 3.X or newer, do the following to obtain your pem file.

    openssl pkcs12 -in usercred.p12 -out Output.pem --legacy

Let’s try to use it!

This exercise will use your downloaded certificate to communicate with the REST API of the HWDB.

  1. This step may not be necessary. But there are certain lines that repeatedly show up in curl commands during the tutorials. So let us define the followings:

    alias CURL='curl --cert Output.pem --pass YourPhrase'
export APIPATH='https://dbwebapi2.fnal.gov:8443/cdbdev/api/v1'

    In the above, Output.pem is the pem file you obtained earlier. We are assuming it sits in the current directory. Else, provide the appropriate path in front of it.

    YourPhrase’ is the phrase you provided when you converted your downloaded usercred.p12 to your pem file.

    cdbdev allows us to communicate with the development version of the HWDB (and cdb allows to communicate with the production version).

  2. Let’s use an API endpoint, /users/whoami, to display your HWDB account info.

    CURL "${APIPATH}/users/whoami"

    If everything is correct, you should see your account information in JSON like the following:

    {"data":{"active":true,"administrator":true,"affiliation":"University of Minnesota","architect":true,"email":"hmuramat@umn.edu","full_name":"Hajime Muramatsu","roles":[{"id":30,"name":"HVS-CPA"},{"id":32,"name":"HVS-EW"},{"id":31,"name":"HVS-FC"},{"id":4,"name":"tester"},{"id":3,"name":"type-manager"}],"user_id":12624,"username":"hajime3"},"link":{"href":"/cdbdev/api/v1/users/12624","rel":"self"},"status":"OK"}

    Sometimes the response might be too long. If commands like json_pp or jq are available, you could also pipe into them:

    CURL "${APIPATH}/users/whoami" | json_pp -json_opt pretty,canonical
or
CURL "${APIPATH}/users/whoami" | jq

    Then the above JSON response would look nicer, easier to read as the following:

    {
  "data": {
 "active": true,
 "administrator": true,
 "affiliation": "University of Minnesota",
 "architect": true,
 "email": "hmuramat@umn.edu",
 "full_name": "Hajime Muramatsu",
 "roles": [
   {
     "id": 30,
     "name": "HVS-CPA"
   },
   {
     "id": 32,
     "name": "HVS-EW"
   },
   {
     "id": 31,
     "name": "HVS-FC"
   },
   {
     "id": 4,
     "name": "tester"
   },
   {
     "id": 3,
     "name": "type-manager"
   }
 ],
 "user_id": 12624,
 "username": "hajime3"
  },
  "link": {
 "href": "/cdbdev/api/v1/users/12624",
 "rel": "self"
  },
  "status": "OK"
}