Link-OS Multiplatform SDK

Webservices

Introduction

This information describes the certificate requirements and configuration for a Tomcat based implementation of a Websocket server as it relates to the Zebra Link-OS Multiplatform SDK. The implementation allows Zebra DNA printers running Link-OS ® to connect securely and communicate using the Link-OS Multiplatform SDK.

You will need an SSL certificate in order to establish communications between your Websocket server and a Zebra DNA printer. Although you may request and obtain a Zebra signed certificate, Zebra strongly recommends either creating and using your own self-signed certificates, or obtaining them from a Publicly Trusted Certificate Authority. That provides you with greater flexibility and control of the certificates and ongoing management of them. Zebra is not a trusted certificate authority, so there's no advantage to obtaining a Zebra signed certificate.
The following sections describe the requirements and steps needed to create your own certificates or obtain one from Zebra.

API documentation for the SDK Weblink support is included in the Java API documentation.

More information regarding the Weblink/Websocket protocol can be found in this Application Note. Printer specific information and troubleshooting can be found in the Using Weblink section of the Programming Guide.

Certificate Requirement Overview

This information supersedes what's included in the v2.14.5198 and prior SDK releases due to changes in our certificate signing process and the ability to use self-signed or publicly trusted CA signed certificates.

Prior to Link-OS v4.x, our printers only contained an embedded SHA-1 certificate for weblink connections. Link-OS versions 5.x through 7.1 included both embedded SHA-1 and SHA-256 certificates. SHA-1 support has been removed in Link-OS v7.2 to enhance product security.

If you have an existing application using a Zebra signed SHA-1 certificate for weblink connections, Zebra recommends transitioning to SHA-256 for enhanced security.

       Upgrading a printer to Link-OS 7.2 will cause it to not connect to an application that's using a Zebra signed SHA-1 certificate.

Zebra shall only issue SHA-256 signed certificates in accordance with security best practices.

Using your own certificates

Zebra recommends using your own certificates which require a certificate chain to be deployed to every printer that needs to connect to your server. Security and certificate information related to Zebra printers can be found in our PrintSecure Administration Guide available here.
This support article contains the instructions to create your own self-signed certificates.

Using Zebra signed certificates

Please note the following important information if you wish to use Zebra signed SHA-256 certificates:

  • The time to sign and return certificate requests may take 7 – 10 days.
  • Zebra SHA-256 signed certificates have a 3-year expiration period and will need to be renewed prior to the expiration date.
       Zebra does not provide a notification service of certificate expiry.
  • Where certificates are required for development and test, the common name maybe a computer hostname or static IP address. Since Zebra cannot verify domain ownership in this case, the certificate expiration period shall be shorter.
  • Zebra recommends the latest Link-OS version (available here) in order to successfully connect using the signed certificate.
  • A SHA-256 CA chain is required in combination with the SHA-256 signed certificate. If you have previously installed the SHA-1 ZebraCAChain.cer file, you will need to remove it and install the CA chain provided with the signed certificate.

In addition, certificate requests must conform to these requirements:

  1. The domain for the common name field of the certificate to be signed shall be either:
    1. a specific non-wildcard subdomain (acceptable example: something.mydomain.com)
    2. a wildcard that must contain a 'z' or 'zebra' or 'zserver' subdomain.
 Acceptable Examples  Unacceptable Examples
 *.z.mydomain.com  *.mydomain.com
 *.z.subdomain.mydomain.com  *.subdomain.mydomain.com
 *.zebra.mydomain.com  
 *.zebra.subdomain.mydomain.com  
 *.zserver.mydomain.com  
 *.zserver.subdomain.mydomain.com  

    1. a computer hostname or static IP address (for development and test only which will have a shorter expiration period).
  1. The CSR must contain all the fields listed here with the addition of the email field.
    1. It must include the correct 2-character ISO format country code detailed in the link above.
  1. Shall not use a SHA1 signature algorithm.
  1. Proof of domain ownership by either of the following methods:
    1. Sending the CSR to Zebra in an email where the email domain matches the domain in the CSR.
    2. A Domain Control Validation challenge. Upload an HTML page with content we specify to a folder on the website for the common name you're using.
        This is not a requirement for certificates used for development & test as noted in section 1c above.
  1. Usage on AWS
    1. If you’re using AWS, the cryptographic algorithm of an imported certificate must match the algorithm of the signing CA. Zebra maintains an ECC Prime-256 Weblink server CA and therefore for use on AWS you should provide us a CSR using ECC algorithm and not RSA.
This online tool can be used to verify the fields in your CSR before sending it to Zebra for signing.

Certificate Request Generation

These are the steps to request a Zebra signed SHA-256 certificate.

  1. Download and install the latest version of OpenSSL on your computer.
  2. Create a folder on your computer named zebra_certs. This folder may reside anywhere you choose (desktop, etc.).
  3. From the Start menu, choose "Run" and type cmd.exe. This opens a Command Prompt.
      This step requires you have administrator privileges.
  1. In the Command Prompt, navigate to your zebra_certs folder and type the following commands, pressing Enter after each command. All the following openssl commands should be run in this Command Prompt.
    set RANDFILE=.rnd
    openssl
  1. Zebra supports RSA and ECC certificates. Listed below are command examples for generating certificate signing requests (csr) for both RSA and ECC encryption algorithms. Enter the appropriate command for either RSA or ECC and substitute the field values for your information:
    These are the required certificate fields used in the certificate request generation command: "/C=xx/ST=yyyyy/L=aaaaa/O=jjjjj/OU=rrrrrr/emailAddress=sssss/CN=uuuuu" -key uuuuu.key -out uuuuu.csr

    Where:

    xx is the two-digit ISO Country Code
    yyyyy is the full State name
    aaaaa is the City or town name
    jjjjj is the Organization or company name
    rrrrrr is the Organizational unit name
    sssss is the contact email address for the certificate creator
    uuuuu is the full DNS name of the server

    RSA Option

    Type the following commands followed by Enter:

    genrsa -out zserver.abccompanyinc.com.key 2048
    req -new -sha256 -subj "/C=US/ST=Illinois/L=Anytown/O=ABC Company Inc/OU=IT Team/emailAddress=John@abccompanyinc.com/CN=zserver.abccompanyinc.com" -key zserver.abccompanyinc.com.key -out zserver.abccompanyinc.com.csr

    ECC Option

    Type the following commands followed by Enter:

    ecparam -out ec_params.pem -name prime256v1
    req -new -sha256 -subj "/C=US/ST=Illinois/L=Anytown/O=ABC Company Inc/OU=IT Team/emailAddress=John@abccompanyinc.com/CN=zserver.abccompanyinc.com" -newkey ec:ec_params.pem -keyout zserver.abccompanyinc.com.key -out zserver.abccompanyinc.com.csr -nodes
      zserver.abccompanyinc.com is the full DNS name of your server. The DNS name must match the DNS name supplied to the printer as the weblink location URL.

       These commands generate the key which is part of the security for the server communications. It should be kept secure and backed up and not given out to anyone. If unauthorized individuals get the key, the security of the connection between the Zebra printer and the Zebra Servlet may be compromised.
  1. Email the certificate request file (.csr file) to WTech@Zebra.com
  2. The certificate will be signed and sent back to you.
  3. Copy the zip file containing the signed certificate files to the zebra_certs folder.
  4. Extract the signed certificate files into the same folder.
  5. Enter the following command and replace the filenames where necessary:
    pkcs12 -export -in zserver.abccompanyinc.com.crt -inkey zserver.abccompanyinc.com.key -out zserver.abccompanyinc.com.p12 -name tomcat -CAfile WeblinkCAChain.crt -caname root –chain
    Where zserver.abccompanyinc.com is the full DNS name of your server.
      This step converts the certificate and asks you to set a passkey.
  1. Enter a standard alphanumeric passkey, but do not include any special characters (for example, do not use characters such as $, %, &, or @).
      The passkey should not be distributed to anyone and is required for the steps in the next section.
  1. Configure your server to use the certificate file and passkey from the steps above.

Steps to configure a Tomcat server

  1. Navigate to the Tomcat server.xml file in the following folder:
    2. %TOMCAT_INSTALL_LOCATION%\conf
  1. Modify the ssl connector to use the new key/certificate combination. Edit the server.xml file to add the following within the <Service> tag, changing the appropriate values where necessary. This example applies to Tomcat 10 or later.
    <Service name="Catalina">
    ...
    <Connector connectionTimeout="20000" maxParameterCount="1000" port="8080" protocol="HTTP/1.1" redirectPort="8443"/>
    <Connector
    SSLEnabled="true"
    compression="on"
    defaultSSLHostConfigName="yourServerFQDN"
    maxConnections="-1"
    maxThreads="150"
    port="8443"
    protocol="org.apache.coyote.http11.Http11NioProtocol"
    scheme="https"
    secure="true"
    socket.soKeepAlive="true"/>

    <SSLHostConfig
    certificateVerification="optional"
    ciphers="ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256,ECDHE-ECDSA-AES256-GCM-SHA384,ECDHE-RSA-AES256-GCM-SHA384"
    hostName="yourServerFQDN"
    protocols="TLSv1.2"
    sessionTimeout="0"
    sslProtocol="TLS"
    truststoreFile="path/to/myTrustStore"
    truststorePassword="myTrustStorePassword"
    truststoreType="JKS">

    <Certificate
    certificateKeystoreFile="/conf/myServerCertificate.p12"
    certificateKeystorePassword="theP12password"
    certificateKeystoreType="pkcs12"/>
    </SSLHostConfig>
    </Connector>
    ...
    </Service>
    Where zserver.abccompanyinc.com is the full DNS name of your server.
    Where YourPasskey = passkey from Step 11 above.
  1. Run the following command from the zebra_certs folder. Ensure you run the command for the same JRE used by the Tomcat instance.
    keytool -importcert -file WeblinkCAChain.crt –keystore "%JRE_HOME%\lib\security\cacerts" -alias "ZebraCAChain"
      The default password for the Java cacert keystore is: changeit
  1. Copy zebra.war from $ZEBRA_SDK_INSTALL_PATH$\link-os_sdk\Webservices\VERSION\lib to $TOMCAT_INSTALL_LOCATION$\webapps
  2. Restart the Tomcat server.
  3. Ensure the printer weblink.ip.conn[1|2].location value is set to "https://$CN$/zebra/weblink/". Where $CN$ is your server host name and ensure the / is present at the end or the printer will fail to connect.