Introduction

As a new user, first you need to generate a private/public key pair and a certificate. This is needed to mint handles. The public key will be uploaded in a handle under a specific index. This will be used to authenticate the user. Before starting first confer with SURF which handle and index to use to create the certificate. By default, SURF will use handle <prefix>/USER01 with a specific index (e.g. 310) where <prefix> is the prefix you will have access to.

Please make sure you use the parameters supplied by SURF when following the procedure detailed here. The example below uses prefix 1000 and index 310, so the handle will be 1000/USER01 with index 310.

For Mac OS and Linux users, you can follow the steps below as a new user.
For Windows users, you first need to install the required tools described in this link before you can follow the steps below.

Before you start

Please make sure you have obtained the necessary information from SURF:

• A prefix
• An index

Creating the client certificate and private/public key pair

For authentication using client certificates, a special pair of keys and a certificate file are required. Follow these five steps to create them for your users:

1. Create a private/public key pair

To create the private/public key pair you can use the command line tool hdl-keygen that is shipped together with the Handle.net system software. Install the software, change directory to the install location (or use relative paths) and execute:

bash /.../handlesystem_software/hsj-8.x.x/bin/hdl-keygen \
              -alg rsa \
              -keysize 4096 \ 
               1000_USER01_310_privkey.bin 1000_USER01_310_pubkey.bin

Note: We put 1000_USER01_310 into the name to remember for which user name this key pair is generated! When it asks whether you want to encrypt the key, type ‘n’:

Would you like to encrypt your private key? (y/n) [y] n

2. Send the public key to SURF

Please send your public key file 1000_USER01_310_pubkey.bin to the SURF helpdesk or via the portal.

Create a message for the attention of "The SURF EPIC PID service team". Include your name, the public key and the assigned prefix on the handle system.

3. Transform the binary private key (.bin) to a .pem file

For this, you can use the command line tool hdl-convert-key that is shipped together with the Handle.net system software:

bash /.../handlesystem_software/hsj-8.x.x/bin/hdl-convert-key \
                                    1000_USER01_310_privkey.bin \
                                 -o 1000_USER01_310_privkey.pem

4. Create the certificate file

To create the certificate using openssl with specifying a subject "CN=310:1000/USER01":

openssl req -pubkey -x509 -new -sha256 -subj "/CN=310:1000\/USER01" -days 3652 \
                                -key 1000_USER01_310_privkey.pem \
                                -out 1000_USER01_310_certificate_and_publickey.pem

A file 1000_USER01_310_certificate_and_publickey.pem should be generated.

5. Remove the public key from the certificate file

Execute the following command:

openssl x509 -inform PEM -in 1000_USER01_310_certificate_and_publickey.pem \
                         -out 1000_USER01_310_certificate_only.pem

to remove the public key from the certificate file.

Results

If the previous instructions have been strictly followed, the following files have been generated:

1000_USER01_310_privkey.pem
1000_USER01_310_pubkey.bin
1000_USER01_310_certificate_and_publickey.pem
1000_USER01_310_certificate_only.pem

The file names will be different according to your prefix and index.

Use

For individual API requests to the service, the private key and certificate-only file need to be sent along. The public key must be installed on the service itself by the system administrators.

For consecutive calls to the service, please consider using sessions.