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.