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 SURFsara which handle and index to use for the certificate to create. By default, SURFsara 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 SURFsara when following the procedure. 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 SURFsara:
- 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 is required. Follow these five steps to create them for your users:
- Create a private/public key pair
- Send the public key to SURFsara
- Transform the binary private key (.bin) to a .pem file
- Create the certificate file
Remove the public key from the certificate
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:
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’:
2. Send the public key to SURFsara
Create a message for the attention of "The SURFsara 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:
4. Create the certificate file
To create the certificate using openssl with specifying a subject "CN=310:1000/USER01":
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:
to remove the public key from the certificate file.
If the previous instructions have been strictly followed, the following files have been generated:
The file names will be different according to your prefix and index.
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.