Configuring_the_API_Host_Server

Configuring the API Host Server

The API Host Server is configured to make the new certificates available to devices.

API Servers Used to Manage Devices

Partner managed devices are managed via API functions that are used to communicate to and from the managed devices. Two servers; written in Python are provided in this example. Both servers need to be running on the same server host.

An unsecure API server is necessary for initial load of the security certificate. After device commissioning, the secured device requests a certificate from the server. Once it is validated with the site key, that certificate is downloaded into the device.

Server Setup:

The unsecured API server is a python-based script that runs on a server host and services requests on port 80.
The secured API server is a python-based script that runs on a server host and services requests on port 443.

For more details on creating and hosting an ENGAGE Device Server, refer to the Create and Host an ENGAGE Device Server page.

System Requirements

Python Version 3.7.x
- Downloaded and installed. See Download and Install Python and Flask Software sub-section from the Create and Host an ENGAGE Device Server page.
Data Structure
- Two server examples are included
- The file structure must be located on the Windows 10 device that hosts the API servers
- This Windows 10 server must have python installed on it
- The file structure is:
  - ./API_Server – This directory contains the API Servers
  - ./API_Server/Engage_Data – Device JSON files
  - ./API_Server/static/Device_Certificates – Self Signed Certificates

Serving the Certificates:

In both python servers;
- Example_Non_Secure_API_Server.py
- Example_Secure_API_TLS_Server.py
Perform the following modifications:
- @app.route('/swordfish/lock/certificates/current')
  - The return statement contains the name of the .der file created earlier in the procedure
  - In this example, the .der file is named partner_intermediate.der
  - The HASH value changes to the value created earlier in Example 4: HASH ENCRYPTION
  - Modify the IP address to be the address of the server
    - This is the IPv4 address from the ipconfig command in the PowerShell
  - Modify the .der file and HASH to be the .der file and HASH generated in Example 4 earlier
```
@app.route('/swordfish/lock/certificates/current')
def sam_certificates():
    print('Sending Certificate URL and hash to Client.')
    return 
'{"cert_url":"http://10.44.68.128/static/Device_Certificates/partner_CA.der","hash":"2t86cWeynRQV1nJw59R4aOktjR0="}', 200
```

Only in the secure script: Example_Secure_API_TLS_Server.py

Modify the context.load_cert_chain command to contain the pem and .key certs generated in this document

context.load_cert_chain(certfile='./static/Device_Certificates/partner_server.pem',
                        keyfile='./static/Device_Certificates/partner_server.key')

To run the API Servers.
- Start two Windows in PowerShell(Admin), one for each script (secure and non-secure)
- From each power shell window, execute command ipconfig for the IPv4 address
- This IPv4 address is the server address
Edit Example_Non_Secure_API_Server.py

At the end of the py script is the app.run command

#  Start the web server.
#  This is an example Flask web server that is open to all network Addresses
#  No web address control is implemented.
#  It is the responsibility of the user enterprise to implement web and
#  server security.
#  The route handle_other_network():  will return an un-authorized message to
#  connection attempts, but this is NOT an adiquate security layer.


if __name__ == "__main__":
    print("Host Name ", socket.gethostbyname(socket.gethostname()))
    app.run(host='10.44.68.128', port=80)

In this example the server executes at IP address 10.44.68.128, port 80
You need to use the IPv4 address that is given from the Power Shell output from the ipconfig command shown above
Make the same edit to the IPv4 address for Example_Secure_API_TLS_Server.py for port 443

To execute the python server scripts, perform the following:

Inside the PowerShell set the directory to the ./API_Server data area
Execute:
- Example_Non_Secure_API_Server.py
Repeat for the Secure server.
- Example_Secure_API_TLS_Server.py

Server API Format

The ENGAGE enabled device performs a non-secured request. This standard HTTP GET request (shown below) is made to the configured host (URL assigned during commissioning of the device) using the defined format.

GET /swordfish/lock/certificates/current

The host needs to respond to the request with the following:

Response:
    HTTP status code 200
        OK
        Body
            Type: application/json
            Body Content:
                { “cert_url”:“<URLtoNewCertificate>”,
                “hash”:“<HMACValue>” }
            Where: 
                <URLtoNewCertificate> is the URL from which the device should retrieve the new certificate. 
                When requested by the ENGAGE device, this certificate should be served as a DER encoded 
                certificate file (binary).

                <HMACValue> is a hash-based message authentication code computed for the new certificate 
                using the SiteKey associated with the account. The algorithm used for authentication code 
                generation must be HMAC-SHA1 as defined by RFC 2104. <HMACValue> should be the MIME Base64 
                encoding of the resultant HMAC.

Distribution of Server (SSL) Certificate

The following files are ready to be deployed to the server:

partner_intemediate.der
partner_server.key
partner_server.pem

IMPORTANT NOTE: The ENGAGE NDE and MT20W both have internal memory limitations on the length of the entire certificate chain supported during a TLS negotiation. These devices support a total chain length (top level root authority certificate + intermediate certificate(s) + SSL host certificate) of no longer than 4096 bytes. Chain lengths greater than 4096 bytes may cause the device to fail host communication, reporting a TLS Connection Error audit, at each attempt.

NOTE 2: In addition, no individual key size can be longer than 2048 bits.

Allegion Developer Portal