Minerva Highway MASA configuration
This assumes you are running the Highway MASA in a container, but if you are running it as a full VM, then you will login via ssh.
Login:
ssh highway@florean
or:
lxc exec highway -- su - highway
cd current
List of tasks:
rake -T | grep highway
When running rake comments, you may see an annoying warning:
/home/highway/shared/bundle/ruby/2.5.0/gems/cow_proxy-0.2.0/lib/cow_proxy.rb:131:
warning: constant ::Fixnum is deprecated
These are benign, although annoying.
rake highway:h0_setup_masa
summary: Do initial setup of sytem variables
This should be run once after installation. It is interactive. It first prints out the list of the current variables, and then will ask a series of questions and store the result into a database table devoted to configuration information. Hitting enter will accept the previous value.
highway@florean:~/current$ rake highway:h0_setup_masa
hostname: florean.sandelman.ca
inventory_dir: /home/highway/devices
base_mac: 00-d0-E5-03-00-00
masa_url: https://florean.sandelman.ca
Hostname for this instance(default florean.sandelman.ca):
serialnumber: 128590126 BAhVOgtS...tWVzY=
DN prefix for certificates(default ): /DC=ca/DC=sandelman
The first question is what the hostname for this instance will be. The hostname will be embedded into the generated IDevID certificates using the the URL which is shown. That URL MUST be reachable by any BRSKI Registrar that wishes to retrieve a voucher. Enter the FQDN only which will be in DNS (or /etc/hosts if testing).
The inventory_dir (directory) is a place where an inventory of devices will be placed when using the “highway:inventory” task. It should be a directory pathname on this system. If setting up a “store” as described in Jokeshop, then this directory should be visible via a web interface. If it is being used as part of manufacturing process, then putting it on some shared drive might make sense.
The base mac address query asks for a 48-bit EUI that will be used as the base for creating new inventory, and for creating (device) serial-numbers in the IDevID. This is as discussed in section 2.3.1 of draft-ietf-anima-bootstrapping-keyinfra-16. Each time more inventory is created a variable will be added to this 6-byte EUI-48. The default value 00-d0-E5-xx-yy-zz is a legitimate OUI belonging to a defunct company, using it for testing will not cause any conflicts. The OUI 10-00-00-xx-yy-zz was been reserved by the IEEE as a Private use OUI.
This process may be repeated to change any values which might be wrong. Changing the OUI/EUI-48 base will not reset the counter, however.
The DN prefix which is asked for will be used as part of the Distinguished Name that is put into the Subject field of the certificates which will be generated. Generally, this will be a series of DC= components. The hostname provided will go into a CN= field, along with a string indicating the role of the certificate being generated.
The serialnumber attribute is printed and stored, but it is used internally to randomly set the X.509 serial-number of the certificate generated.
rake highway:h1_bootstrap_ca
This method should be run once (after h0) to generate a self-signed certificate to be used to sign other certificates. This certificate will become the anchor certificate for any IDevID certificates created. This certificate will be stored at:
highway@florean:~/current$ ls -l db/cert/vendor*
total 3
-rw-rw-r-- 1 highway highway 818 Nov 3 08:19 vendor_secp384r1.crt
-rw------- 1 highway highway 288 Nov 3 08:15 vendor_secp384r1.key
If another keypair should be used, it can be placed in this location. The environment variable $CERTDIR may also be changed to control where private keys are kept.
rake highway:h2_bootstrap_masa
This method should be run once (after h1) to generate a certificate (signed by the vendor CA certificate) which will be used to sign ownership vouchers produced by the MASA.
highway@florean:~/current$ ls -l db/cert/
total 5
-rw-rw-r-- 1 highway highway 672 Nov 3 08:55 masa_prime256v1.crt
-rw------- 1 highway highway 227 Nov 3 08:55 masa_prime256v1.key
-rw-rw-r-- 1 highway highway 818 Nov 3 08:19 vendor_secp384r1.crt
-rw------- 1 highway highway 288 Nov 3 08:15 vendor_secp384r1.key
highway@florean:~/current$ openssl x509 -in db/cert/masa_prime256v1.crt -text -noout
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 1180464293 (0x465c74a5)
Signature Algorithm: ecdsa-with-SHA256
Issuer: DC = ca, DC = sandelman, CN = florean.sandelman.ca CA
Validity
Not Before: Nov 3 08:55:50 2018 GMT
Not After : Nov 2 08:55:50 2020 GMT
Subject: DC = ca, DC = sandelman, CN = florean.sandelman.ca MASA
Subject Public Key Info:
As above, the location of the private key may be changed to a more secure location with $CERTDIR.
rake highway:h3_bootstrap_mud
This method should be run once (after h1) to generate a certificate (signed by the vendor CA certificate) which will be used to sign Manufacturer Usage Descriptions (MUD) files. This step is optional.
highway@florean:~/current$ ls -l db/cert/
total 6
-rw-rw-r-- 1 highway highway 672 Nov 3 08:55 masa_prime256v1.crt
-rw------- 1 highway highway 227 Nov 3 08:55 masa_prime256v1.key
-rw-rw-r-- 1 highway highway 672 Nov 3 08:58 mud_prime256v1.crt
-rw------- 1 highway highway 227 Nov 3 08:58 mud_prime256v1.key
-rw-rw-r-- 1 highway highway 818 Nov 3 08:19 vendor_secp384r1.crt
-rw------- 1 highway highway 288 Nov 3 08:15 vendor_secp384r1.key
As above, the location of the private key may be changed to a more secure location with $CERTDIR.
rake highway:h4_masa_server_cert
This method should be run once (after h1) to generate a certificate (signed by the vendor CA certificate) which will be used to answer TLS (HTTPS) connections for MASA API operations. This certificate will need to be verifiable by any Registrar which needs to connect to the MASA.
It may be more appropriate to get a certificate from a commerical entity (or LetsEncrypt) for this use. The DNS-01 challenge is appropriate doing this.
highway@florean:~/current$ ls -l db/cert/
total 9
-rw-rw-r-- 1 highway highway 672 Nov 3 08:55 masa_prime256v1.crt
-rw------- 1 highway highway 227 Nov 3 08:55 masa_prime256v1.key
-rw-rw-r-- 1 highway highway 664 Nov 3 09:00 server_prime256v1.crt
-rw------- 1 highway highway 227 Nov 3 09:00 server_prime256v1.key
-rw-rw-r-- 1 highway highway 818 Nov 3 08:19 vendor_secp384r1.crt
-rw------- 1 highway highway 288 Nov 3 08:15 vendor_secp384r1.key
As above, the location of the private key may be changed to a more secure location with $CERTDIR.
rake highway:signmic
The signmic action will look for an entry in the device database with the serial-number given by the argument EUI64= and will store the resulting voucher back into the database.
This is only really useful for deep testing.
rake highway:signcsr
The signcsr action will take a Certificate Signing Request is CSR=file, and it will create a device entry for it, and then produce an IDevID certificate which it will put in the file CERT=file2.pem.
A signing request that has a public key that matches an existing entry will reuse that entry.
A signing request that does not have a matching key, but does match an existing serialNumber will be rejected as a duplicate. Mark the obsolete entry as obsolete first.
highway@highway0:~/current$ rake highway:signcsr CSR=spec/files/csr/sample1.csr CERT=/tmp/n1.pem
highway@highway0:~/current$ openssl x509 -noout -text -in /tmp/n1.pem
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 1361584186 (0x5128203a)
Signature Algorithm: ecdsa-with-SHA256
Issuer: DC = ca, DC = sandelman, DC = dervish, CN = dervish.sandelman.ca CA
Validity
Not Before: Nov 15 03:02:31 2018 GMT
Not After : Dec 31 00:00:00 2999 GMT
Subject: serialNumber = IOTRUS-0123456789
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:ad:97:6a:b1:b9:87:42:df:68:34:75:37:95:6d:
...
a1:ab
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Subject Key Identifier:
2B:BD:D6:9E:9C:32:2A:8D:AB:82:BA:A9:1F:35:E9:08:B7:93:E4:80
X509v3 Basic Constraints:
CA:FALSE
X509v3 Subject Alternative Name:
othername:<unsupported>
1.3.6.1.4.1.46930.2:
..https://dervish.sandelman.ca
rake highway:inventory
The inventory mechanism will generate a number of devices into the database. The default number of devices is 5, but an argument of “INVENTORY=xxx” would ask for number devices. A count of devices which have no ownership voucher created (and therefore no owner) will be made, and if the number is below the desired number of devices, then more devices are generated.
Devices are generated with an incrementing EUI-48 based serial number. A private and public key pair are generated and placed into a temporary directory named for the serial number. The public key is signed by the CA key, and this certificate is considered an 802.1AR IDevID certificate.
The results are compressed with zip, and placed into the directory configured for inventory.
Inside the directory two other certificates are placed: the vendor CA (which will sign the IDevID, which might be needed by the Pledge in it’s TLSClientCertificate chain), and also the MASA key which will be needed by the Pledge to validate the resulting voucher.
highway@florean:~/current$ rake highway:inventory
creating 4 devices to refill inventory to 5
Creating device 1 with mac 00-d0-e5-03-00-02
Running: cd /home/highway/releases/20181103100425/db/devices && zip -r /home/highway/devices/product_00-D0-E5-03-00-02.zip 00-D0-E5-03-00-02
adding: 00-D0-E5-03-00-02/ (stored 0%)
adding: 00-D0-E5-03-00-02/key.pem (deflated 16%)
adding: 00-D0-E5-03-00-02/device.crt (deflated 29%)
adding: 00-D0-E5-03-00-02/masa.crt (deflated 26%)
adding: 00-D0-E5-03-00-02/vendor.crt (deflated 27%)
....
Running: cd /home/highway/releases/20181103100425/db/devices && zip -r /home/highway/devices/product_00-D0-E5-03-00-05.zip 00-D0-E5-03-00-05
adding: 00-D0-E5-03-00-05/ (stored 0%)
adding: 00-D0-E5-03-00-05/vendor.crt (deflated 27%)
adding: 00-D0-E5-03-00-05/key.pem (deflated 15%)
adding: 00-D0-E5-03-00-05/device.crt (deflated 30%)
adding: 00-D0-E5-03-00-05/masa.crt (deflated 26%)
The ZIP files are placed in the directory that was specified in the h0 step:
highway@florean:~/current$ ls -l ~/devices
total 13
-rw-rw-r-- 1 highway highway 2776 Nov 3 10:13 product_00-D0-E5-03-00-02.zip
-rw-rw-r-- 1 highway highway 2773 Nov 3 10:13 product_00-D0-E5-03-00-03.zip
-rw-rw-r-- 1 highway highway 2780 Nov 3 10:13 product_00-D0-E5-03-00-04.zip
-rw-rw-r-- 1 highway highway 2773 Nov 3 10:13 product_00-D0-E5-03-00-05.zip
drwxrwxr-x 2 highway highway 2 Nov 3 09:10 sold
rake highway:obsolete
A product may be marked as obsolete. This marks the device entry as deleted, which causes the inventory system to generate new “product”.
highway@florean:~/current$ rake highway:obsolete PRODUCTID=00-D0-E5-03-00-02
Device 2 marked obsolete
Having marked a device as deleted, a new device will be created with the inventory command:
highway@florean:~/current$ rake highway:inventory
creating 1 devices to refill inventory to 5
Creating device 1 with mac 00-d0-e5-03-00-06
Running: cd /home/highway/releases/20181103100425/db/devices && zip -r /home/highway/devices/product_00-D0-E5-03-00-06.zip 00-D0-E5-03-00-06
adding: 00-D0-E5-03-00-06/ (stored 0%)
adding: 00-D0-E5-03-00-06/vendor.crt (deflated 27%)
adding: 00-D0-E5-03-00-06/key.pem (deflated 16%)
adding: 00-D0-E5-03-00-06/device.crt (deflated 30%)
adding: 00-D0-E5-03-00-06/masa.crt (deflated 26%)
rake highway:mud_json_sign
THis method takes an input MUD file (in JSON format), adds a “mud-signature” entry to it, and then canoncalizes it and writes it out. The signature is calculated over the canonocalized result.
The MUD signature URL is calculated to be a relative URL. The signature is written to the provided input file with .sig appended (unless SIGFILE= is added)
The canonicalized MUD JSON is written to the input file with .json appended (unless OUTFILE= is added).
(No example is provided yet)
rake highway:signvoucher
summary: Sign voucher for device EUI64= to OWNER_ID=xx, with optional NONCE=xx, EXPIRES=yy
This is option is not useful at this time, but is still in the list.
Running Highway MASA
To start the MASA server, once it is configured:
lxc exec highway -- su highway
bin/server -D &
The -D will put a few debug message in the foreground, but the bulk of the debug will be in a lot file.
tail -f shared/log/production.log &
will show the entire log file. This MASA server does not start automatically when the container starts, although this can be configured.
A production load MASA server would use the passenger plugin to Apache to scale better. A high-capacity MASA server would make use of a three-tier web framework (presentation-tier/load-balancer, application server-tier, and database-tier) to do typical web scaling. Setting up such a system is not in the scope for this document, please contact Sandelman Software Works for help setting such an environment up.
Testing the MASA
To test if the MASA is answering correctly, from another machine do:
fountain@eeylops:~/fountain/current$ curl -k https://florean.sandelman.ca/version
highway:
Version: 0.9
Revision: devel
or: curl –cacert db/cert/vendor_secp384r1.crt https://highway-test.example.com/version.json
does the same thing in JSON.
One can also visit the /status and /status.json URLS:
$ curl -k https://florean.sandelman.ca/status
<!DOCTYPE html>
....
$ curl -k https://florean.sandelman.ca/status.json; echo
{"Devices":6,"Inventory":6,"Owners":0,"Vouchers":0,"Requests":0}
One can combine the instructions to start:
lxc exec highway -- su highway -c /home/highway/bin/server