This page describes how to set up the tools that are needed to generate handles and certificates on Mac and Linux machines.

Install tools

Install Java

If you do not already have Java version 8 or higher installed, download and follow the instruction on the Java website here.

Install Handle.net software

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 Handle.net software by downloading the software and unpacking it.

Generating 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 steps to create them for your users after receiving your prefix and index from SURF:

1. Create a private/public key pair

Go to the install directory and execute, replacing <index> and <prefix> with your provided index and prefix:

bash /.../handle-9.x.x/bin/hdl-keygen -alg rsa -keysize 4096 <prefix>_USER01_<index>_privkey.bin <prefix>_USER01_<index>_pubkey.bin

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 (e.g. 1000_USER01_310_pubkey.bin) to the SURF helpdesk or portal.

Address your message to the "SURF ePIC PID service team". Make sure to include your name, username, your public key and your assigned prefix on the handle system.

Wait until you have received confirmation that your public key file has been uploaded.

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

To transform your binary private key into a .pem file you can use the command line tool hdl-convert-key that is shipped together with the Handle.net system software.

Go to the install directory and execute:

bash /.../handle-9.x.x/bin/hdl-convert-key <prefix>_USER01_<index>_privkey.bin -o <prefix>_USER01_<index>_privkey.pem

4. Create the certificate file

Create the certificate using openssl, making sure to include the subject (-subj) following the convention of /CN=<index>:<prefix>\/USER01 (e.g. /CN=310:1000\/USER01) and output filename (-out) following the convention <prefix>_<username>_<index>_certificate_and_publickey.pem (e.g. 1000_USER01_310_certificate_and_publickey.pem):

openssl req -pubkey -x509 -new -sha256 -subj "/CN=<index>:<prefix>\/USER01" -days 3652 -key <prefix>_USER01_<index>_privkey.pem -out <prefix>_USER01_<index>_certificate_and_publickey.pem

5. Remove the public key from the certificate file

Execute the following command to remove the public key from the certificate file, replacing the filenames per previous steps:

openssl x509 -inform PEM -in <prefix>_USER01_<index>_certificate_and_publickey.pem -out <prefix>_USER01_<index>_certificate_only.pem

Results

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

<prefix>_USER01_<index>_privkey.pem
<prefix>_USER01_<index>_pubkey.bin
<prefix>_USER01_<index>_certificate_and_publickey.pem
<prefix>_USER01_<index>_certificate_only.pem

Or based on an example:

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