Overview
IBM i Digital Certificate Manager can be used in conjunction with MDRest4i, to create and verify signatures for payloads as used in JWT or JWS messages. The MDRST/MDRCVTJWT program creates the JWS/JWT tokens. The RSA certificates used to create and validate signatures for theses tokens, are stored in the IBM i DCM.
The IBM i QSYS API used by MDRest4i – Qc3CalculateSignature requires that an *OBJECTSIGNING certificate store containing a valid RSA certificate, and an application that uses the RSA certificate. This application is used in the w_dcmpp variable passed to MDRST/MDRCVTJWT when creating the token.
| Special Note: The IBM i API Qc3CalculateSignature, looks at ALL certificate stores for the name provided in the w_dcmapp parameter passed to the program that creates the Tokens (MDRST/MDRCVTJWT). Not just the *OBJECTSIGNING Certificate store. it does however ONLY look at the *OBJECTSIGNING store for the RSA certificate.
Therefore all DCM Applications must be unique, regardless of which store they are created in. This also has the implication that if a valid RSA certificate has been added to the *OBJECTSIGNING certificate store, AND that RSA certificate is assigned to a Client Application in the *SYSTEM certificate store, the *SYSTEM Client Application can be used to pass to the w_dcmapp parameter when using MDRST/MDRCVTJWT to create a token. This makes it unnecessary to create an additional Application in the *OBJECTSIGNING store, and assigning the same RSA Certificate in the *OBJECTSIGNING store. The Certificate need only be in the *OBJECTSIGNING store in this instance. HOWEVER: In practice it is advisable to create a specific application in the *OBJECTSIGNING store for the RSA certificate. This will avoid problems if an application is removed inadvertently from the *SYSTEM certificate store, plus any confusion when using the DCM for both SSL and for JWT/JWS signing in MDRest4i. |
|---|
Creating an *OBJECTSIGNING Certificate Store
- If there is no “*OBJECTSIGNING” store, select “Create New Certificate Store” in the left hand menu
and select *OBJECTSIGNING and the continue button from the list that appears on the right-hand side
- From the next page select option “NO” and the continue button
- Provide a password and continue
You have now created the *OBJECTSIGNING Store. An RSA certificate must now be added, an application added, and the certificate assigned to the application, all in the newly created *OBJECTSIGNING store.
Exporting existing RSA certificate into *OBJECTSIGNING Store
| Please Note: A certificate provided by the REST API host specifically for signing tokens may be required. In this case, this host certificate will need to be imported to the *OBJECTSIGNING Certificate store. |
|---|
If there is no specific requirement, and you already have an RSA 2048 certificate in another store (an SSL certificate used in the *SYSTEM store for example) it will contain a public and private key that can be used to create the signature used for the JWT/JWS token.
This can then be exported from the *SYSTEM store into the *OBJECTSIGNING store and used for signing JWT/JWS tokens.
- In the DCM web gui, choose “select certificate store”.
- Select store “*SYSTEM” and continue, providing the password in the next screen
Select continue…
- With the *SYSTEM store selected, expand the Manage Certificates menu option, and select “Export Certificate…
- Select “Server or Client” option the right hand side, and continue…
- Select the certificate you wish to export, and press the “export” button
- Select the “Certificate Store” option and continue button…
- In the Target field specify “*OBJECTSIGNING” and provide the *OBJECTSIGNING store password and press the continue button…
The exported certificate is now available in the *OBJECTSIGNING Certificate store used to create the signature of the token in MDRST/MDRCVTJWT.
Create an Application in *OBJECTSIGNING Store
- In the DCM web gui, choose “select certificate store”.
- Select store “**OBJECTSIGNING” and continue, providing the password in the next screen
- With the *OBJECTSIGNING store selected, expand the Manage Applications menu option, and select “Add application” from the menu…
- In the wizard screen that appears on the right-hand side, provide an “Application ID” and select and enter an “Application description”. Press the add button
Assign RSA Certificate to *OBJECTSIGNING Application
- In the DCM web gui, choose “select certificate store”.
- Select store “**OBJECTSIGNING” and continue, providing the password in the next screen
- With the *OBJECTSIGNING store selected, expand the Manage Applications menu option, and select “Update certificate assignment” from the menu…
- In the wizard screen that appears on the right-hand side, select the appropriate certificate, and press the “Assign New Certificate” button
The certificate is now assigned to this application and can be used to sign tokens.
