Skip to main content

Securing Call Home

A host that performs the initial call-home must present a unique host-id and once a host with that host-id has called home, no other host is allowed to perform the initial call home with the same host-id. This ensures a certain level of security since the host-id is to be regarded as a shared secret.

It is sometimes desirable to add an additional layer of security on the TLS layer and use client certificates as well as server certificates, ie, mutual TLS.

There is a trade-off between security and the burden of managing the on-boarding process. Three different flavours of call home certificates are supported:

  1. host specific certificates
  2. site specific certificates
  3. system specific certificates

When using unique certificates for each host, ie the first above, a unique on-boarding command needs to be generated for each host. This complicates roll-out somewhat, but also provides the most secure call home procedure. The certificate can be created with a short TTL and is unique for each host.

Using site specific certificates makes it easier to on-board hosts since only one certificate needs to be generated per site. The site certificate can be generated with a short TTL. If a host needs to be added after the original certificate has expired a new site client certificate can be generated.

Finally, a system specific client certificate can be generated. This ensures that only hosts with a proper certificate issued by the current system instance is allowed to connect.

Note that it is important to generate call home certificates with as short TTLs as is convenient. It is always possible to generate new certificates is the call home process is delayed. On the other hand, the TTL must be long enough for the host to be shipped to the site and connected.

In this case the CA used to generate the certificates is the same CA that issues the API certificates for the system. There is no need to configure any additional TLS CAs for this functionality.

To require host specific call home certificates do the following:

supctl create system call-home settings <<EOF
client-certificate:
  verify: host-id
EOF

To generate a call home certificate for a host with host-id d6785b90-df4c-4008-888d-2d56e68decdf:

supctl  do system call-home issue-host-cert d6785b90-df4c-4008-888d-2d56e68decdf 4d
b64-tar-package: H4sIAAAAAAAAA+2WS5ObOBDHc+ZT5O7aHYzxg0MOkpBBtgUWFmC42eABg208fgn49IvtyWYqyWaS2pp9VM3/AogGdbf0a3W0Opx+36+2H95QcluWe6r6Qb7r62unp8of2qqqKkpP7Xev4225rzTXt3Tqs87H0+LQTPl3//N1cP8T/XYVxAaxPiLscDIkCHB8G5UoIeiiIwS24wQIAkFCOBgdu7RFogQWFTijOKxYB83U0uBgDJPkKc0ze8qYDjI4kqhDBAaB7jFmYrHhsaFlCyW9LA25RDUYwcTyIAg42FhDygZCZzfbMRYhjLfDWooUXA454HfDI9cNZx91nGrhj9qxsbksM7A2wKCiOqmpHpSWDhSa4coeFoFeEyHRjAorwyrVo9LmQPYzqNKZLMbiNpOOKycLeK5YNajCWTsPFKZOOKtCn54CTlTJRu0trZnSDHQpDzqhTkucAXb3KOLIs+SlYh0WhnZccjyhIDdA28UwpciV3VLSa2DdjQsO86ESzK064NijkN4MUUlpaGzq2Bztg50nL3ztTIe5wCIwx0VIpDqTEWABuT409zpgkc4SgBNhV11lX057Kzf3yrnP92p3PnWNZLMbLE0as2BdlJkjbZncrNQh5ifNdNiuy3aas5tc8j4beOF2qQQjcZny82iUbiePCxtqHMFBhuD6unKOnEmQGICavTTsORtq0NLQgX8PiXJdfg5pBqGL8yTaapdYxzMKwT0PJR1Jbse5BMqpWCrlibKjQPd1NrAYcYfjKQXyPRcpNdg8TKOOlVLHvebgajeRsCjzxdySo+1mHc+d/VLpISwQaCKG/VFMz+f4UODi1BWutZoGwhM31x04BIIXJJcCBXetLBJ0655Cw8ptJMt062UTv9ksenIKMypbzbPNsWIprE7W4Zd9wdVEmvhOFjaGlj7aBFU7pVmiTvygtvRwE9R5aWVxTmtAr3kxnSb6xwEGGQAUFAZCT4Y0o6rWJAwBOQEUu4iAaOVc/LIXHy/LZVgdZgcXD6rVqT+0++v9kwdPiMzHw3biN5scA6mjx7FKV7pmZL4tovzxMK+8tabntdvENm8PVNJVHraFvS4+STeAsaV/C/VrwK/rBvjM+AI8QbssN48buep1lXMyW3d2kLVVLfsG+KwBPhHD5Bktod0gbhhOmAdHxBxdlh32Q3qkr/H5VXqkGz6I3Oh/hl80laG5dzt+mkxpBqqmSnRu72osWzxeUJz/6ZX0M1D/yCvpZ6D+K6YXmQ2kdB1Npj6b9nuarBXpbnDurzbzpN3yHtJ0xoz2uJsFShnXwjHNB3tNdLdbKUMCu2UqTy+yZD7G66hzeNSexoXWE4vOkw2VBup2A3Wa3KGG5kA8Loa7veGKoMYBhcEtRFDSqfSZQYKHbDaD1VLR5F+p5dL3ivmrtbwgMy/hxWZnF9J6PzVoWFpeXUSH1mRPgXp1L9YFhg+C4evuTDMwe4kb0puSw8wHkDS0UBTdPjAFSyhUhTkGiwKujeE2lWMT9CaVlkVbcQ6eQ51su5sYDQRK7qtyLbvXWfQZAMJhJJlvoKNYDsl2YO8/0OXkNN8RFquHsWg43yOIervaXU12Vo4I0zfSaeK3FNmZuUdneZY9UThhPKLqUW099fvzljny9Xh1Luee+PQDXt/6/I+u/V++qt5yjlf6P7nTvPu2/+u+93//gF4cBxh9nDrEa3bexzEOnk8EM2oKFcaENGDu8SaP7I7B1As+KPmAtnYFVtom4ZfZ+LwzLY5aCifF85F3PfEkILBZuOyXOpaXDYv0asfCXuLzvRikfzvH73rXu971X9QfuTpkPAASAAA=
serial: 9b:39:33:e2:1c:80:1a:32:02:e0:9d:67:24:37:09:2e:31:19
created: 2023-06-14T07:19:04.117455Z
expires: 2023-06-18T07:19:04.000000Z

To generate a site specific call home certificate for site-a:

supctl do system call-home issue-site-cert site-a 4d
b64-tar-package: H4sIAAAAAAAAA+2WW5OiRhTH95lPse9WIgLeHvahb0AjjXIT8Q1BQVBRURv89FFnpjLZnewmm9pNUjX/KssuPXAu3b/TJ14eT7/ul9sPP1BiRxR7ivJBfNLn37IiSx86iqJIUq8ryXe7jtjvdD+IPzKoF52rU3S8ufyn7/k8uf+JfrkLEo1aHxFxPKpSBDzy+FVglKIAIwRWUgo4hSClrt4aq5fdAiuL81iJlaDqFUfel2QGSg2hg+YyZQgBQ4wUtUByYMPUmkIQe2hqiQvJOkbasFp4xGSg0EDHJzBjyBf9Gl+B9WRberBQpXBmXYXQI1MG2cMQ1YzNtc010Y19uJuKUTA8M0RDfKWc5YxbOREZDhsLUyXI0gnLQSOwK5CYl3LrShuGnYip5StPzIM7a59o/unmyGUQPEVUM8OXnUsonUphIdUnZlcc2SGe2rZGuOE5HpkwID5FlTHNns2zWLYy5vic8IedSXhdRDNLFOLtZp3MnP1CUnjgAQ+m8SEr8vHEphCm6fOaQcgtBIDXETHZ8oqZVd494lPtCvq8lbVXqKu2zRxNJ4ueyePOkU7tvXLoQLLsNtAZyy1xoxuSa3VNe2brh2iBU8vdngbrjeBOlHOpaBdGter2offcdZeRNAR8dVB3e83n4ZWEDIaPlEDNJi8pUaLaguvCZiENReZQTsAjP53wjZdowzySsstCE2t0BcZTUUMPbCyV2QOOn2o2Egifw2SrXmOJ1OqjBnfDysOas49lp4kCo5Nom8uipB6gaJcXerURm1s3OKfuWt4J0O4owxw4j9AdQlAOaJrOr9HM2ZgB4fgelSN6wNbbEFAOMBj9XlwbCyC1DIChBtYENKm5MyfZXnVnsRoeO1qdj+tVw3dBu5oWw3nPrKMjPhRGO0XUxsZU17lAR+kANq5lwA4bXbRun4aB2jpUFouafJkUUYnHC/Dpk/BAh1j4S5y+hdr6ekMt115Qe7MSz4X4Q3Igh7nAnJSr6aPemPDhS7lTewoNqhuXhWzXX8NR+Cs8fg1H4Q0e+Y3H29qXX3i0MJAf/12JaHlJdO8SL1EJ39slXqIS/rRLqMWdS31Uzuk1FxGwQ/q8xsCOsZ0CEuVjIGTr2JwE9qTfG4rDMtsNzv3lZpZ2WtN2lrm21hl181Cqkyt3dL09XlPsdxtJpbBbZ+LkIgr6KlnH8nE1PIzKYY9H8mEMJQ/BTo5glj7OaA71AV9Fb2MnvObue7ATXnP3N7Bzp6lXbnbjUljvJxqb19b0WsbHlrlnQLmHl2BOYJvb5H46sxy4TyjeeuZqQBC+dc4beiAlQGAofjygcztlUOH6CEQlXGvqNhMTHfTMZpjHW34On1M1t91NggYcpU+7Ity25e4FuwBwx6bpbAMdyXJovgP7oM0W5mm2o3aiHEcc5GCPIOrtrv7S3FnFndeNcDKDliQ6rl85i7M45aUzTwymVErr0O/PWroR4GR5rmdT/jVe/+2b+ecovs9/xbL5kT6+Mf/dBkDly/lPkt/nv5+gV5cSQR8nDp3ezv/HEQmf7yU9vrVLQiiyA1x2b7T2u6Ybz6o6CSpe7lsRbaJN0SkCg16K4hyM1V75ahQUACd66duPHjtMQG1UJkZ92op4P/YzaVWuZH52Vo1ya2xSaz3QrahR/dFydLId/Ryngu+d2ifDaZIiX7qiKsLedssV7O+PK7r385aZvob4rRyEf7vG73rXu971X9Rvew4OFgASAAA=
serial: 1f:e3:85:be:76:c3:e1:bb:8e:e1:ce:16:b3:a9:2b:c3:bd:b7
created: 2023-06-14T07:22:04.199208Z
expires: 2023-06-18T07:22:04.000000Z

To generate a system specific call home certificate for the-company:

supctl do system call-home issue-system-cert the-company 100d
b64-tar-package: H4sIAAAAAAAAA+2WXZOiOBSG55pfMffWroCozcVcJCFA0KB8i3cINhposP3oIL9+UXtmunq7dnZ2q/ejqt8qyxQczTnvyZMkXe+Pv+7WD5/eUaIkiiNF+STe9Pp7oCijT5KiKLI8GspjqXsuiWN58El8z6S+6nQ4Jvtuyr/7P6+L+5/ol4sgNoj9GWHXJzpBwMfXpwIlBMUMIZBvc8AJBDnxgT3OqpE2H6/Kdo/7bL/SJ01zwK0PJjDPHzcFm80dRwMMWgJ1Cccg1kLHMTEv/cxQWSJvnlaG2KAWWDC3QwhiH5S2Tp07rjnX2AnmS5g96K2QyrjRfeDfAg++Zri7dOCek8iSMqN8WjGwNcDdmWqkpVrc0BYMKOvGUh1rLeECZZTPfNIFpOdu3EYM3lPX4Ti/zqRhfhQTIzjGsnpMDf209rFHITCAFGDYUEsIBu5TLB/rldwcqXPg6Jaigbnluz6eUyBeg9GGGs5iuUkH9oa6Acf8GjcVMG+KZGGL6UO5zRbubiUrPLqWlD6bReB34yiE3EYA+Ps+qEdowGbCOMp243HuJ8NS6c14Sap4vkjteCwS1OpncTnGZsxas7CGa2go+dQo3bVnlc6pjWaVXAhufq8c9NMgmLh5rRgiJUbTfcjFVNOjnRWA3z/q1c4IeNzimML4WhJo6PxSknCpiWDd8Tx4Xsmq+LNtFV739YdtrbuFRlDFCvNQiueRMJRPubcdVNCRFJWB6Jq6i7HWAjvPX7cQ0Nv7rpH3dxgwAAQKagOhR8OjigoBRUDMAcUBIsaEuDo6u+wU6R4RwVHU7by/L5JiKkuhRjwuawiNhSx8UMAWAz6ZyPNxbM+14NE7T3oWmCb7Q1mMUsyjIoRTdpyd9GrrVfiLcMUI29rv0foRdtu2w44Z37F74cYrM15jxzrscq5/W+DqV8tzJ4QWMa2n1cBpMAPOzf7UR6EtrmR7nxjqYeXjaedWcSNgQ1EgBs3F5ltw7cNCl+OF3cY+Dimkt8XfULo0yjYzrV1chaKQROqJInJl8IKgzTDv+OzGwSDa5HPKwNnWLqx271os2n6WUFx8y0p4K62fyUp4K61rVnpxYdOc1EvSMhEBJybPYw04qebkACdsBoTNNp3OI2c+HqmiWm+qu9N4XS5yqRf2NxvPMaTJkMVyk7XcNc3+bEu0YHiWdQKHzUacP4mCeZ9t08H+Xn2c1OqIJ4PHGZR9BCWG4ObSHVdk0Lzj98nb6Alft5O/ip7w1pb6J9Dzwtyvy2pWC9vd3KDLxg7bOt33pjsKlEt6mcYx7HMHX1bnhgHvJW5I63ZPx+yDHHfYofT6A5M7OYUKNycgqeHW0B82YmaC0fSssvSBn+LnUqcPwzJDdxzlt64IXVsus2geANx1SL4ooSvbLmEV2EV9upoeFxVxMmU/4R3nOwTRqGqD9bSyC0QcrRSO06gni64XHNzVSQx57S4ziyoHpfc4Hi96phVp2frULEL+5Q94/bdP6fdTern/Fevze87xg/vf5QL4xv1P+bj//QN6cRBh9HnukrBb858nOH4+i8y02yIxJqjGeU0f9+tguY3m9tPBWFtD1qv6WMxVdTa0z+d9FM4ye6jUL85aAXBs1oFz3VdHfT6Z5UelPUlVsu4pWD4t13N2sDxL1qSBFs1UBA5NejTWDZTJXTNEa2GRuyeCml2wKLbLYHqQ2E7d4djsTeHqKKEiBi/BfasG4d/2+EMf+tCH/ov6DRa5HQ8AEgAA
serial: de:dd:9f:a0:cf:ed:b9:73:ac:4f:e3:ad:b1:4a:c7:1b:04:cd
created: 2023-06-14T07:22:33.213336Z
expires: 2023-09-22T07:22:33.000000Z

The certificates are used when invoking the install script as follows. Note that it is the b64-tar-package value that should be used for cert. This is a base64 encoded compressed tar file containing the certificate and key. It can be unpacked for inspection using the shell command echo "H4sIAA...AAA=" | base64 -d | tar xfz -.

curl -s https://api.sl-test.the-company.avassa.net/install | sudo /bin/sh -s -- --cert H4sIAA...AAA=