As a new user, first you need to generate a private/public keypair 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 index 310.

Please make sure you use the parameters supplied by SURFsara when following the procedure. The example below uses foo/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.

Creating the client certificate

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:

1. Create a private/public key pair
2. Send the public key to SURFsara
3. Transform the binary private key (.bin) to a .pem file
4. Create the certificate file
5. 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:

bash /.../handlesystem_software/hsj-8.x.x/bin/hdl-keygen
              -alg rsa
              -keysize 4096
               foo_USER01_310_privkey.bin foo_USER01_310_pubkey.bin

Note: We put foo_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 SURFsara

Please send your public key file foo_USER01_310_pubkey.bin to the SURFsara helpdesk.

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:

bash /.../handlesystem_software/hsj-8.x.x/bin/hdl-convert-key
                                    foo_USER01_310_privkey.bin
                                 -o foo_USER01_310_privkey.pem

4. Create the certificate file

To create the certificate using openssl with specifying a subject:

openssl req -pubkey -x509 -new -sha256 -subj "/CN=310:foo\/USER01" -days 3652
                                -key foo_USER01_310_privkey.pem
                                -out foo_USER01_310_certificate_and_publickey.pem

A file foo_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 foo_USER01_310_certificate_and_publickey.pem
                         -out foo_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:

foo_USER01_310_privkey.pem
foo_USER01_310_pubkey.bin
foo_USER01_310_certificate_and_publickey.pem
foo_USER01_310_certificate_only.pem

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.