Nexus' software components have new names:

Nexus PRIME -> Smart ID Identity Manager
Nexus Certificate Manager -> Smart ID Certificate Manager
Nexus Hybrid Access Gateway -> Smart ID Digital Access component
Nexus Personal -> Smart ID clients

Go to Nexus homepage for overviews of Nexus' solutions, customer cases, news and more.


Skip to end of metadata
Go to start of metadata

This article describes how to upgrade Protocol Gateway.


Expand/Collapse All

Prerequisites

 Prerequisites

The following prerequisites apply: 

Step-by-step instruction

Stop Tomcat 

 Stop Tomcat
  1. Stop the Tomcat service.

Replace Protocol Gateway file and folder 

 Backup files

Back up the Protocol Gateway folder: 

  1. Navigate to the Tomcat /webapps folder.
  2. Make a backup of the existing /pgwy folder for reference and delete the original.
 Replace .war file

Replace the Protocol Gateway .war file: 

  1. Replace pgwy.war in the webapps folder with the new version.

Additional tasks to upgrade from certain version

The following configurations are done in configuration files in <configroot>

 About <configroot>
<configroot> corresponds to the following paths: 
Windows <configroot>
%ALLUSERSPROFILE%/Nexus/cm-gateway/
Linux <configroot>
/var/cm-gateway/
 Upgrade from 7.18 or earlier


 Configure REST API

The numbering of the handlers has been changed in the file <configroot>/api.properties:

  1. If the file is unmodified, remove this file and it will be recreated with new defaults when restarting Protocol Gateway.
  2. If the file has been modified, then do the following:
    1. Open the file <configroot>/api.properties for editing. 
    2. Change the numbers on all configured handlers and their related configuration so that the number corresponds to the following numbering scheme:

      Example: api.properties
      handler.0.filter = certificates
      handler.10.filter = certificates/revoke
      handler.11.filter = certificates/reinstate
      handler.20.filter = certificates/[a-z0-9A-Z]+/details
      handler.21.filter = certificates/[a-z0-9A-Z]+/download
      handler.30.filter = certificates/pkcs10
      handler.50.filter = procedures
      
    3. Add the following lines at an appropriate place in the file:

      Example: api.properties
      # Process PKCS10 request -> PKCS12 response
      handler.31.filter = certificates/pkcs10-to-pkcs12
      handler.31.format = api/certificates-pkcs10-to-pkcs12
      handler.31.tokenprocedure = Token Procedure Name - must be configured
    4. Save the file.

 Configure V2X API

The settings in c2x.properties have changed:

  1. If this file exists in your environment, remove it. A new version with default values will appear when restarting Protocol Gateway.

 Upgrade from 8.0 or earlier


 Configure Protocol Gateway properties

Protocol Gateway has gained the ability to send metrics to InfluxDB. To be able to use this feature, do the following updates:

  1. Open the file <configroot>/cm-gateway.properties for editing. 
  2. Add the following lines after the setting for cmhost:

    Example: cm-gateway.properties
    # CM-Connections is the maximum amount of concurrent officer connections to CF
    # to allocate to the officer pool.
    cmconnections = 20
  3. Add the following lines at the end of the file:

    Example: cm-gateway.properties
    #= Metrics reporter
    #
    # metrics.influxdb.url - If non-empty, PGW will report metrics to an
    # InfluxDB database at this URL.
    #
    #metrics.influxdb.url = http://localhost:8086
    # metrics.influxdb.user - The user name to be used when reporting metrics
    # to InfluxDB.
    #
    #metrics.influxdb.user =
    # metrics.influxdb.password - The password to be used when reporting
    # metrics to InfluxDB.
    #
    #metrics.influxdb.password =
    # metrics.influxdb.dbname - The InfluxDB database name where metrics will
    # be stored. The database must already exist in InfluxDB. Defaults to
    # "cm_metrics" if not specified.
    #
    #metrics.influxdb.dbname = cm_metrics
    # metrics.influxdb.interval - How often metrics should be sent to
    # InfluxDB (in seconds). Defaults to 30s if not specified.
    #
    #metrics.influxdb.interval = 30
  4. Save the file. 
 Configure REST API

The REST API configuration has been extended with additional endpoints. To be able to use the latest features, do the following updates:

  1. Open the file <configroot>/api.properties for editing. 
  2. Add the following lines at the end of the file:

    Example: api.properties
    # Registration Endpoints
    # HTTP GET: search
    # HTTP POST: create
    # HTTP PUT: edit
    # registrations/{procid}
    handler.60.filter = registrations/[a-z0-9A-Z\- ]+
    handler.60.format = api/registrations-list
    handler.60.getformat = api/registrations-list
    handler.60.postformat = api/registrations-create
    handler.60.putformat = api/registrations-update
    # registrations/{procid}/{protocol}
    handler.61.filter = registrations/[a-z0-9A-Z\- ]+/(?i)(est|acme|cmp|scep)
    handler.61.format = api/registrations-list-protocol
    handler.61.getformat = api/registrations-list-protocol
    handler.61.postformat = api/registrations-create-protocol
    handler.61.putformat = api/registrations-update-protocol
    # registrations/certificate/{certid}
    handler.62.filter = registrations/certificate/[0-9]+
    handler.62.format = api/registrations-get-certid
    ################
    # ACME Endpoints
    # registrations/{procid}/acme/accounts
    handler.70.filter = registrations/[a-z0-9A-Z\- ]+/acme/accounts
    handler.70.format = api/registrations-list-acme-accounts
  3. Save the file.

 Configure EST

The EST configuration has been extended with additional options. To be able to use the latest features, do the following updates:

  1. Open the file <configroot>/est.properties for editing. 
  2. Replace the description of the parameters to the following:

    Example: est.properties
    #- Parameters
    #
    # filter - contains a filter for the handler part of the URL
    # specified as a regular expression. NOTE: If using the CoAP proxy,
    # regular expressions in the filters are not supported.
    #
    # format - contains the name of a format definition file. For regular
    # EST the format definition files with the prefix 'est-' should be used. For
    # EST over CoAPs the files with the prefix 'estcoaps-' should be used instead.
    #
    # tokenprocedure - contains the description or id of a token procedure
    # in the CM server.
    #
    # ra.keyfile - is the token to sign the fullcmc responses.
    # Not required if fullcmc is disabled.
    #
    # ra.password - is the password to the keyfile. It is recommended to
    # obfuscate sensitive data with .encrypted.
    #
    # requiredRoRoles - optional, contains a space or comma separated list
    # of required Registration Officer roles. This requires client
    # authentication to be enabled in Tomcat, and verifies that the
    # client certificate is an officer. If the role "none" is entered,
    # the client certificate must be issued by CM but does not need to
    # be an officer. "/cacerts" must not be protected behind client
    # authentication, and therefore no default role should be set.
    #
    # authtype - optional, enables HTTP Basic/Digest authentication by
    # specificing the desired authentication type. May only be set
    # for filters simpleenroll and simplereenroll.
    # Example:
    # handler.<n>.authtype = Basic
    # handler.<n>.authtype = Digest
    #
    # realm - required if authtype is set, may be empty. Determines which
    # realm the login should occur on. Can only be set for filters
    # simpleenroll and simplereenroll.
    #
    # qop - optional, determines the quality of protection used with
    # Digest authentication. Valid value is 'auth'. If not specified
    # then no Quality of Protection will be required.
  3. Save the file.

 Upgrade from 8.1 or earlier


 Configure REST API

The REST API configuration has been extended with additional endpoints. To be able to use the latest features, do the following updates:

  1. Open the file <configroot>/api.properties for editing. 
  2. Add the following lines below the certificate endpoints:

    Example: api.properties
    # Process PKCS10 request -> PKCS7 (secure key injection package) response
    handler.32.filter = certificates/skip
    handler.32.format = api/certificates-skip
    handler.32.tokenprocedure = Token Procedure Name - must be configured
    
    # Process X509 certificate import
    handler.33.filter = certificates/import-pki-x509
    handler.33.format = api/certificates-import-pki-x509
    handler.33.importlimit = 100
    handler.33.tokenprocedure = Token Procedure Name - must be configured
  3. Save the file.

 Upgrade from 8.2 or earlier


 Configure SCEP

The SCEP implementation has been updated in the following ways:

To be able to use the new features, do the following updates: 

  1. If the file <configroot>/scep.properties is unmodified, remove this file and it will be recreated with new defaults when restarting Protocol Gateway.
  2. If the file has been modified, then do the following: 
    1. Open the file <configroot>/scep.properties for editing. 
    2. Add the following lines below default.racachainlength = 0:

      Example: scep.properties
      # Changes the response format for the GetCACert call to return the RA
      # certificate in binary format if set to true.
      # Only works if racachainlength is set to 1.
      default.responseasbinary = false
      
    3. Add the following lines below default.ra.signature.keyusage = digitalsignature:

      Example: scep.properties
      # SCEP INTUNE
      #
      # SCEP Intune allows for integration with Azure AD to automatically
      # enroll and manage iOS, Android, Windows and Mac devices.
      #
      # tenant - is the Tenant which is the fully qualified domain name (FQDN)
      # of the organization configured in Intune.
      #
      # azure_app_id - specifies the azure application id of the app
      # registration.
      #
      # azure_app_key - specifies the client secret of the app registration.
      #
      # certificateAuthority - specifies the name of the CA performing the
      # requests to Intune.
      
    4. Append the following lines at the end of the file:

      Example: scep.properties
      # http://<pgwy-host>:<port>/pgwy/scep/ndeschallenge/
      #
      # Handler for SCEP dynamic challenge endpoint (NDES compliant)
      #
      handler.3.filter = ndeschallenge/
      handler.3.format = scep-ndes
      handler.3.ndesUsername = ndesadmin
      handler.3.ndesPassword = ndespassword
      handler.3.ndesChallengeValidity = PT15M
      # http://<pgwy-host>:<port>/pgwy/scep/ndesrequest
      #
      # Handler for SCEP request using dynamic challenge password
      (NDES compliant)
      #
      handler.4.filter = ndesrequest
      handler.4.format = scep
      handler.4.tokenprocedure = SCEP Registration and Enroll Procedure
      with NDES Challenge
      
      # http://<pgwy-host>:<port>/pgwy/scep/intune/pkiclient.exe
      #
      # Handler for requests that should be validated against a Microsoft
      # Intune server.
      handler.5.filter = intune/pkiclient.exe
      handler.5.format = scep-intune
      handler.5.tenant = tenant
      handler.5.azure_app_id = app-id
      handler.5.azure_app_key = app-key
      handler.5.certificateAuthority = CA
    5. Save the file.

 Configure CMC

Support for CMC revoke request has been added.

  1. If the file <configroot>/cmc.properties is unmodified, remove this file and it will be recreated with new defaults when restarting Protocol Gateway.
  2. If the file has been modified, then do the following:
    1. Open the file <configroot>/cmc.properties for editing.
    2. Add the following lines below default.tokenprocedure = TLS Web Server Token:

      Example: cmc.properties
      # ra.keyfile - is the token to sign the fullcmc responses,
      required for CMC Revoke.
      # Not required if CMC Revoke handler is disabled.
      # ra.password - is the password to the keyfile. It is recommended to
      # obfuscate sensitive data with .encrypted.
    3. Append the following lines at the end of the file:

      Example: cmc.properties
      handler.2.filter = revoke
      handler.2.filterContentType = application/pkcs7-mime;\h*smime-type\h*=
      \h*CMC-request
      handler.2.format = cmc-revoke
      # fullcmc responses (required as response to Revocation request) require
      an RA token to be signed with
      handler.2.ra.keyfile = protocol-gateway-ra.p12
      handler.2.ra.password = abcd1234
    4. Save the file.
 Configure V2X API

Support for configuring connection properties to the authorization server has been added.

  1. If the file <configroot>/c2x.properties is unmodified, remove this file and it will be recreated with new defaults when restarting Protocol Gateway.
  2. If it has been modified, then do the following:
    1. Open the file <configroot>/c2x.properties for editing.
    2. Replace the line #default.authorizationUrl = <authorization-server-url> with the following lines:

      c2x.properties
      # Parameters for the AccessTokenVerifier modifier.
      #
      # default.authorizationUrl = <authorization-server-url>
      # default.authKeyCacheLifeSpan = P365D
      # default.authKeyCacheRefreshTime = P1D
      #
      # Timeout values in ms.
      # default.authKeyConnectTimeout = 1000
      # default.authKeyReadTimeout = 1000
    3. Save the file.

 Upgrade from 8.3 or earlier


 Configure EST

The EST configuration has been extended with additional options.

To be able to use the new features, do the following updates in <configroot>/est.properties:

  1. Add the new parameter and description to the simplereenroll handler, default handler 2:

    Example: est.properties
    # Controls if the client TLS certificate must match the latest issued certificate
    # for the requested subject. Set to false as default.
    # handler.2.allowRenewalWithOldCertificates = false

Restart Tomcat

 Restart Tomcat
  1. Restart the Tomcat service.