1.3. Set up the Solution#

After completing the steps in Subscribe to inoQulate from the Azure Marketplace, the deployment should complete in a few minutes.

_images/inoQulate_deployed.png

1.3.1. References for this page#

The table below provides values that you will use in the setup process below. You can retrieve values specific to your deployment in the Deployment Output page:

  1. Navigate to the page in the screenshot above. If you are not at the page,

    1. Navigate to the inoQulate resource group.

    2. Click Deployments on the left panel.

    3. Click the deployment.

  2. Click the inoQulate Managed Application resource.

  3. Click the managed resource group on the right of the top panel.

  4. Click Deployments on the left panel.

  5. Click the inoQulate resource.

  6. Click Outputs on the left panel. If you are following the setup process, consider leaving a browser tab on this page.

The following table summarises how the URL is generated. This is just for information; you may skip this table.

Table 1.3 Solution Configuration References#

EJBCA Admin Page caAdminPage

https://<CA Domain Name Label>.<location>.cloudapp.azure.com/ejbca/adminweb/
e.g., https://demo-inoqulate-ca.southeastasia.cloudapp.azure.com/ejbca/adminweb/
EJBCA Root Domain caRootDomain
https://<CA Domain Name Label>.<location>.cloudapp.azure.com
e.g., https://demo-inoqulate-ca.southeastasia.cloudapp.azure.com
Signserver Admin Page signerAdminPage
https://<Signer Domain Name Label>.<location>.cloudapp.azure.com/signserver/adminweb/
e.g., https://demo-inoqulate-signer.southeastasia.cloudapp.azure.com/signserver/adminweb/
Signserver Hostname signerHostname
<Signer Domain Name Label>.<location>.cloudapp.azure.com
e.g., demo-inoqulate-signer.southeastasia.cloudapp.azure.com
  • Substitute <CA Domain Name Label> for the CA Domain Name Label value configured in Kubernetes Cluster. The default value is <domain-prefix>-inoqulate-ca.

  • Substitute <Signer Domain Name Label> for the Signer Domain Name Label value configured in Kubernetes Cluster. The default value is <domain-prefix>-inoqulate-signer.

  • Substitute <location> for the region code name of the Kubernetes cluster deployment.

1.3.2. Log in to the VM#

  1. In the Azure portal, enter Virtual Machines in the search box. Select Virtual Machines.

  2. Click inoQulate-admin-VM.

  3. If the Virtual Machine is not started, click Start.

  4. Click Connect.

  5. In the Connect page, click Check Access. It should return Accessible.

    _images/admin_vm_connect.png
  6. In the Native RDP box, click Select, and then Download RDP File.

  7. Open the RDP file when the download completes.

  8. Click Connect.

  9. Log in to the VM with the credentials as per VM Credentials.

  10. Accept the certificate warnings, if any.

  11. If you are connecting for the first time, go through the setup process.

  12. Open File Explorer. Click View, select Show, then click File name extensions.

  13. Open Microsoft Edge. Click the three-dots menu and click Settings.

  14. Click Start, home, and new tabs in the left panel.

  15. Select Open tabs from the previous session.

  16. Download Java installer from https://www.java.com/en/download/. You may close the tab when the download completes.

  17. Run the Java installer and click Install. Click Close when it is done.

  18. Download Adobe Acrobat Reader from https://get.adobe.com/reader/. You may close the tab when the download completes.

  19. Run the Adobe Acrobat Reader installer and click Finish when it is done.

1.3.3. Connect the network drive and create directories#

  1. If you are inside the VM, minimise your VM.

  2. In the Azure portal, enter Storage Accounts in the search box. Select Storage Accounts.

  3. Click the name of the storage account of Kind StorageV2 and Resource Group that starts with mc_mrg. In the example below, this would be the storage account underlined in red, where the resource group is mc_mrg-pqcee-inoqulate-solution....

    _images/storage_accounts.png
  4. In the left panel, under the Data Storage section, click File shares.

  5. There should be only one file share listed. Click the file share.

  6. Click Connect.

  7. In the Windows tab, choose Drive letter Z, and Authentication Method Storage account key.

  8. Click Show Script and copy the script.

  9. Go back into the VM.

  10. Click the Windows Start Menu and search for powershell. Click on Windows Powershell.

  11. Right-click inside the Powershell terminal. If prompted, click Paste anyway. Wait for the command to complete.

  12. Hit Enter. You should see CMDKEY: Credential added successfully.

  13. Run the following command in the Powershell terminal:

    cd Z:
    New-Item -ItemType directory -Force -Path @( `
       'config', `
       'data', `
       'management-ca', `
       'proofs', `
       'servicerunner-tls-truststore', `
       'signserver-tls-keystore', `
       'data/toInoQulate')
    

Run the powershell command tree /F at Z:\ to check that it has this directory structure:

Z:\
├── config
├── data
│   └── toInoQulate
├── ejbca-tokens
├── management-ca
├── proofs
├── servicerunner-tls-truststore
└── signserver-tls-keystore

1.3.4. Download Additional Configuration Files#

  1. Run the following script in the Powershell terminal:

    Invoke-WebRequest https://raw.githubusercontent.com/pqcee/public/83b5fd9391ade87b1e7e54a8ca64f72395b1fec1/inoQulate-v1.1.0-config.zip -OutFile inoQulate-v1.1.0-config.zip
    Expand-Archive -Path .\inoQulate-v1.1.0-config.zip -DestinationPath config
    Remove-Item .\inoQulate-v1.1.0-config.zip
    
  2. Run the powershell command tree /F at Z:\ to check that it has this directory structure:

    Z:\
    ├── config
    │   ├── 1_certprofiles.zip
    │   ├── 2_entityprofiles.zip
    │   ├── 3_CryptoWorker.properties
    │   ├── 4_TimestampSigner.properties
    │   ├── inoQulate.PDF.Verifier_1.0.0_x64_en-US.msi
    │   └── sample.pdf
    ├── data
    │   └── toInoQulate
    ├── ejbca-tokens
    ├── management-ca
    ├── proofs
    ├── servicerunner-tls-truststore
    └── signserver-tls-keystore
    

1.3.5. Set up Authenticated Access to EJBCA#

1.3.5.1. Access the EJBCA page#

  1. In your VM, open Microsoft Edge browser and access the EJBCA Admin Page caAdminPage in References for this page.

  2. If you encounter a browser warning, click Advanced and click through the warning.

1.3.5.2. Import pre-configured profiles#

  1. In the left panel, under CA Functions, click Certificate Profiles.

  2. Under the Import/Export section, click Choose File.

  3. Select 1_certprofiles.zip in Z:\config and click Open.

  4. Click Import Profiles.

  5. In the left panel, under RA Functions, click End Entity Profiles.

  6. Under the Import/Export section, click Choose File.

  7. Select 2_entityprofiles.zip in Z:\config and click Open.

  8. Click Import. You may ignore the Non existent CAs messages.

  9. In the list of profiles, click SUPERADMIN and click Edit End Entity Profile.

  10. Under the Main Certificate Data section, for Available CAs, click ManagementCA and click Save.

    _images/cert_profile_available_cas.png
  11. In the list of profiles, click SIGNSERVER and click Edit End Entity Profile.

  12. Under the Main Certificate Data section, for Available CAs, click ManagementCA and click Save.

1.3.5.3. Request and Install a Client Certificate#

  1. At the bottom of the left panel, click RA Web.

  2. Click Make New Request.

  3. In the Certificate Type dropdown box, select SUPERADMIN.

  4. Select By the CA.

  5. For Enrollment Code, enter the credentials as prepared in Client Certificate Password.

    _images/request_superadmin.png
  6. Click Download PKCS#12.

  7. Close RA Web browser tab.

  8. Open the Downloads folder in File Explorer. Cut the SuperAdmin.p12 file and paste in Z:\config.

  9. Open Z:\config in File Explorer. Double-click the SuperAdmin.p12 file.

  10. Click Next two times in the Certificate Import Wizard.

  11. Type in the same enrollment code for the password.

  12. Click Next two times and click Finish.

  13. Click Yes in the Security Warning dialog. Click OK.

1.3.5.4. Remove Unauthenticated Access from EJBCA#

  1. In the EJBCA Admin Page, under System Functions, click Roles and Access Rules.

  2. Click Delete on Public Access Role. Click Delete again.

  3. Click Members on Super Administrator Role.

  4. In the Match with dropdown box, select X509: CN, Common name.

  5. Enter SuperAdmin for Match Value.

    _images/superadmin_role_access.png
  6. Click Add.

  7. Minimise the VM.

  8. In the Azure portal, enter Kubernetes Services in the search box. Select Kubernetes Services.

  9. Click inoQulate.

  10. Click Connect.

  11. Follow the instructions in the Set cluster context section under the Cloud shell tab.

  12. In the Cloud shell, enter the command below.

    if kubectl get namespaces -o name | grep inoqulate; then                                                                                                                                                               100%  ─╯
       kubectl config set-context --current --namespace=inoqulate
    fi
    kubectl rollout restart deployment ejbca
    

    This restarts the EJBCA application.

  13. Enter your VM again. Restart (close and open) the Microsoft Edge browser.

  14. Allow about 10 to 15 minutes for the restart to complete. You will know the restart is complete when the webpage is available again.

  15. You are prompted to select a certificate. Select SuperAdmin and click OK.

  16. Click Delete on PublicAccessAuthenticationToken. Click Delete again.

1.3.6. Create certificates for the other services#

1.3.6.1. Import ManagementCA Certification Authority into Signserver#

  1. At the bottom of the left panel, click RA Web.

  2. Click CA Certificates and CRLs at the top of the page.

  3. Under the ManagementCA line, click DER.

    _images/download_ca_certs.png
  4. Copy ManagementCA.crt from Downloads folder to Z:\management-ca.

1.3.6.2. Import ManagementCA Certification Authority into Service runner#

  1. Back in RA Web, under the ManagementCA line, click JKS.

  2. Run the following command in the Powershell terminal:

    & 'C:\Program Files\Java\jre-1.8\bin\keytool.exe' `
        -keystore "$HOME\Downloads\ManagementCA-chain.jks" `
        -storepasswd
    
  3. You are first prompted for a password. Enter changeit.

  4. Enter the credentials twice as prepared in Trust Store Credentials.

    _images/change_managementca-chain_password.png
  5. Copy ManagementCA-chain.jks from Downloads folder to Z:\servicerunner-tls-truststore.

1.3.6.3. Request a TLS certificate for Signserver#

  1. Go back to RA Web.

  2. Hover over Enroll and click Make New Request.

  3. In the Certificate Type dropdown box, select SIGNSERVER.

  4. Select By the CA.

  5. Enter for both CN, Common Name and DNS Name fields the Signserver Hostname signerHostname in References for this page.

  6. Enter in Enrollment Code and Confirm Enrollment code the password as prepared in TLS Keystore for Signserver.

  7. Click Download JKS.

1.3.6.4. Install the TLS certificate in Signserver#

  1. In your Downloads folder, rename the .jks file just downloaded to server.jks.

  2. Copy server.jks from Downloads folder to Z:\signserver-tls-keystore.

  3. Open Notepad from the Windows Start Menu.

  4. Type the same enrollment code in the Notepad window.

  5. Save the file as Z:\signserver-tls-keystore\server.storepasswd, making sure that the file is saved as type All files (*.*) so that the file does not have a .txt extension.

1.3.6.5. Summary#

  1. Run the powershell command tree /F at Z:\ to check that it has this directory structure:

    Z:\
    ├── config
    │   ├── 1_certprofiles.zip
    │   ├── 2_entityprofiles.zip
    │   ├── 3_CryptoWorker.properties
    │   ├── 4_TimestampSigner.properties
    │   ├── inoQulate.PDF.Verifier_1.0.0_x64_en-US.msi
    │   ├── sample.pdf
    │   └── SuperAdmin.p12
    ├── data
    │   └── toInoQulate
    ├── ejbca-tokens
    ├── management-ca
    │   └── ManagementCA.crt
    ├── proofs
    ├── servicerunner-tls-truststore
    │   └── ManagementCA-chain.jks
    └── signserver-tls-keystore
        ├── server.jks
        └── server.storepasswd
    
  2. Minimise the VM.

  3. Back in your Cloud shell instance, enter the command below.

    kubectl rollout restart deployment signserver
    

1.3.7. Create a Certification Authority#

1.3.7.1. Initialise HSM Token#

  1. Still in your Cloud shell instance, enter the command below.

    kubectl exec -it deployment/ejbca -- sh
    
  2. Then, enter the command below.

    softhsm2-util --init-token --label newtoken --free
    
  3. Enter the CA SO PIN twice as prepared in Certification Authority Application - HSM Token SO PIN.

  4. Enter the CA User PIN twice as prepared in Certification Authority Application - HSM Token User PIN.

  5. Enter exit.

1.3.7.2. Create a Crypto Token#

  1. Go back into the VM, to the EJBCA Administration tab in your browser.

  2. In the left panel, under CA Functions, click Crypto Tokens.

  3. Click Create new….

  4. For Name, enter inoQulate Token.

  5. For Type, select PKCS#11.

  6. Ensure Auto-activation is ticked.

  7. For PKCS#11: Reference Type, select Slot/Token Label.

  8. For Authentication Code, enter the CA User PIN as prepared in Certification Authority Application - HSM Token User PIN.

  9. Repeat the CA User PIN in Repeat Authentication Code.

  10. Click Save.

  11. In the dropdown box, select ECDSA prime256v1 / secp256r1 / P-256.

  12. Click Generate new key pair.

    _images/create_crypto_token.png

1.3.7.3. Create a new Certification Authority#

  1. In the left panel, under CA Functions, click Certification Authorities.

  2. Under Add CA, enter a CA name in the text field, e.g., <company> CA, substituting <company> for your company name.

  3. Click Create.

  4. For Crypto Token, select inoQulate Token.

  5. Under the CA Certificate Data section, for Certificate Profile, select inoQulate ROOTCA.

  6. In Validity, enter 3y.

    _images/create_ca_1.png
  7. In the Default CA defined validation data section, for Default CRL Distribution Point, click Generate.

  8. In the text field, replace the root domain, i.e., http://localhost:8080 portion of the address, with the EJBCA Root Domain caRootDomain in References for this page.

  9. For OCSP service Default URI, click Generate.

  10. In the text field, replace the root domain, i.e., http://localhost:8080 portion of the address, with the EJBCA Root Domain caRootDomain in References for this page.

    _images/create_ca_2.png
  11. Click Create.

1.3.7.4. Edit End Entity Profiles to select the new CA#

  1. In the left panel, under RA Functions, click End Entity Profiles.

  2. Select TIMESTAMPER and click Edit End Entity Profile.

  3. In the Main Certificate Data section, ensure the Default CA is the new CA you created.

  4. In Available CAs, select the new CA you created.

  5. Click Save.

1.3.8. Set up an inoQulate service#

1.3.8.1. Initialise HSM Token#

  1. Minimise your VM.

  2. In your Cloud shell instance, enter the command below.

    kubectl exec -it deployment/signserver -- sh
    
  3. Then, enter the command below.

    softhsm2-util --init-token --label newtoken --free
    
  4. Enter the Signer SO PIN twice as prepared in Signer Application - HSM Token SO PIN.

  5. Enter the Signer User PIN twice as prepared in Signer Application - HSM Token User PIN.

  6. Enter exit.

1.3.8.2. Create a CryptoWorker#

  1. In your VM, open a new tab in the browser and access the Signserver Admin Page signerAdminPage in References for this page.

  2. You are prompted to select a certificate. Select SuperAdmin and click OK.

  3. Make sure that the Signserver website is secure by verifying that there is a lock icon beside the page’s address bar.

    _images/signserver_secure.png

    If it says Not Secure, please double-check that the steps in Install the TLS certificate in Signserver have been done correctly.

  4. Click Add….

  5. Click FROM FILE.

  6. Click Choose File and select Z:\config\3_CryptoWorker.properties.

  7. At the bottom of the text field, add a new line WORKERGENID1.PIN=<Signer User PIN>, substituting <Signer User PIN> with the Signer User PIN as prepared in Signer Application - HSM Token User PIN.

  8. Click Apply.

  9. Click the worker CryptoWorker.

  10. Click Crypto Token.

  11. Click Generate key….

  12. In New Key Alias, enter testkey.

  13. In Key Algorithm, select ECDSA.

  14. Confirm that the Key Specification is prime256v1 / secp256r1 / P-256.

  15. Click GENERATE.

  16. Click Generate key… again.

  17. In New Key Alias, enter ts0001.

  18. In Key Algorithm, select ECDSA.

  19. Confirm that the Key Specification is prime256v1 / secp256r1 / P-256.

  20. Click GENERATE.

1.3.8.3. Create a TimestampSigner Worker#

  1. At the top of the page, click Workers.

  2. Click Add….

  3. Click FROM FILE.

  4. Click Choose File and select Z:\config\4_TimestampSigner.properties.

  5. Click APPLY.

  6. Tick TimeStampSigner and click GENERATE CSR.

  7. Ensure that the Signature Algorithm is SHA256withECDSA.

  8. In DN, enter CN=<company> inoQulate Service, substituting <company> for your company name.

    _images/generate_csr.png
  9. Click GENERATE.

  10. In the Result field, click DOWNLOAD. TimeStampSigner-ts0001.p10 is downloaded to your Downloads folder.

  11. Copy TimeStampSigner-ts0001.p10 from your Downloads folder to Z:\config.

  12. Switch to the EJBCA’s RA GUI browser tab.

  13. Hover over Enroll and click Make New Request.

  14. For Certificate Type, select TIMESTAMPER.

  15. For Key-pair generation, select Provided by user.

  16. Click Choose File and select TimeStampSigner-ts0001.p10 in your Z:\config folder.

  17. Click Download PEM full chain. A .pem file is downloaded to your Downloads folder.

  18. Copy the .pem file from your Downloads folder to Z:\config.

  19. Switch to the Signserver browser tab.

  20. Click the TimeStampSigner worker.

  21. Click INSTALL CERTIFICATES….

  22. Click Choose File and select the .pem file in Z:\config.

  23. Click ADD.

  24. Click INSTALL.

  25. Check that TimeStampSigner Worker is now ACTIVE.

    _images/workers_active.png

1.3.8.4. Summary#

  1. Run the powershell command tree /F at Z:\ to check that it has a similar structure:

    Z:\
    ├── config
    │   ├── 1_certprofiles.zip
    │   ├── 2_entityprofiles.zip
    │   ├── 3_CryptoWorker.properties
    │   ├── 4_TimestampSigner.properties
    │   ├── inoQulate.PDF.Verifier_1.0.0_x64_en-US.msi
    │   ├── Demo inoQulate Service.pem
    │   ├── sample.pdf
    │   ├── SuperAdmin.p12
    │   └── TimeStampSigner-ts0001.p10
    ├── data
    │   └── toInoQulate
    ├── ejbca-tokens
    │   └── ...
    ├── management-ca
    │   └── ManagementCA.crt
    ├── proofs
    │   └── ...
    ├── servicerunner-tls-truststore
    │   └── ManagementCA-chain.jks
    ├── signserver-tls-keystore
    │   ├── server.jks
    │   └── server.storepasswd
    └── signserver-tokens
        └── ...
    

1.3.9. Install the inoQulate PDF Verifier#

  1. In your VM, browse to Z:\config\ and double-click inoQulate.PDF.Verifier_1.0.0_x64_en-US.msi to run the installer.

  2. Go through the installer wizard to the Completed page by clicking Next and Install. You do not need to change any settings in the wizard.

  3. Uncheck Launch inoQulate PDF Verifier and click Finish.

  4. Ensure that an inoQulate PDF Verifier desktop icon appears on your VM’s desktop.

1.3.10. Test run the service#

  1. Copy Z:\config\sample.pdf to Z:\data\toInoQulate.

  2. Minimise your VM.

  3. In your Cloud shell, enter the command below.

    kubectl create job testrun --from=cronjob/servicerunner
    
  4. After a few seconds, the job completes. The data folder should look similar to this:

    Z:\data
    ├── done
    │   └── sample.pdf
    ├── error
    ├── inoQulated
    │   └── sample.pdf
    ├── report
    │   ├── 2023-07-11T05.12.03+0000.txt
    └── toInoQulate
    
  5. Open Z:\data\inoQulated\sample.pdf in Adobe Acrobat Reader.

  6. Click the Signature Panel button.

  7. Expand the Rev. 1 signature. Expand Signature Details and click Certificate Details.

  8. In the left panel of the Certificate Viewer, click the CA that you created.

  9. Click the Trust tab.

  10. Click Add to Trusted Certificates….

  11. Click OK three times.

  12. Right-click Rev. 1 signature and click Validate Signature. Click Cancel if the ManagementCA prompts pop up.

  13. The panel should read Signed and all signatures are valid.

  14. If not already open, double-click the inoQulate PDF Verifier application on your desktop.

  15. Leave the input fields unchanged and click Verify.

  16. Verify that sample.pdf is successfully verified. You can also view the report in Z:\data\report.

Your inoQulate service is set up and working.

1.3.11. Stop unncessary resources#

It is recommended to leave the VM shut down when not in use, as the compute resource is chargeable.

  1. Go into your VM. Close all the open windows and shut down from the Windows Start Menu.

  2. In the Azure portal, enter Virtual Machines in the search box. Select Virtual Machines.

  3. Click inoQulate-admin-VM.

  4. Click Stop.