15fff9558SSimon J. Gerratylibsecureboot 25fff9558SSimon J. Gerraty************* 35fff9558SSimon J. Gerraty 4*f486ebb5SSimon J. GerratyThis library depends one way or another on verifying detached digital 5*f486ebb5SSimon J. Gerratysignatures. 65fff9558SSimon J. GerratyTo do that, the necessary trust anchors need to be available. 75fff9558SSimon J. Gerraty 85fff9558SSimon J. GerratyThe simplest (and most attractive for an embedded system) is to 95fff9558SSimon J. Gerratycapture them in this library. 105fff9558SSimon J. Gerraty 115fff9558SSimon J. GerratyThe makefile ``local.trust.mk`` is responsible for doing that. 125fff9558SSimon J. GerratyThe file provided is just an example and depends on the environment 135fff9558SSimon J. Gerratyhere at Juniper. 145fff9558SSimon J. Gerraty 155fff9558SSimon J. GerratyWithin Juniper we use signing servers, which apart from signing things 165fff9558SSimon J. Gerratyprovide access to the necessary trust anchors. 175fff9558SSimon J. GerratyThat signing server is freely available - see 185fff9558SSimon J. Gerratyhttp://www.crufty.net/sjg/docs/signing-server.htm 195fff9558SSimon J. Gerraty 20*f486ebb5SSimon J. GerratyX.509 certificate chains offer a lot of flexibility over time and are 215fff9558SSimon J. Gerratya great solution for an embedded vendor like Juniper or even 225fff9558SSimon J. GerratyFreeBSD.org, but are probably overkill for personal or small site use. 235fff9558SSimon J. Gerraty 245fff9558SSimon J. GerratySetting up a CA for this is rather involved so I'll just provide a 255fff9558SSimon J. Gerratylink below to suitable tutorial below. 265fff9558SSimon J. Gerraty 275fff9558SSimon J. GerratyUsing OpenPGP is much simpler. 285fff9558SSimon J. Gerraty 295fff9558SSimon J. Gerraty 305fff9558SSimon J. GerratyOpenPGP 315fff9558SSimon J. Gerraty======== 325fff9558SSimon J. Gerraty 335fff9558SSimon J. GerratyThis is very simple to setup and use. 345fff9558SSimon J. Gerraty 355fff9558SSimon J. GerratyAn RSA key pair can be generated with:: 365fff9558SSimon J. Gerraty 375fff9558SSimon J. Gerraty GNUPGHOME=$PWD/.gnupg gpg --openpgp \ 385fff9558SSimon J. Gerraty --quick-generate-key --batch --passphrase '' "keyname" RSA 395fff9558SSimon J. Gerraty 405fff9558SSimon J. GerratyThe use of ``GNUPGHOME=$PWD/.gnupg`` just avoids messing with personal 415fff9558SSimon J. Gerratykeyrings. 425fff9558SSimon J. GerratyWe can list the resulting key:: 435fff9558SSimon J. Gerraty 445fff9558SSimon J. Gerraty GNUPGHOME=$PWD/.gnupg gpg --openpgp --list-keys 455fff9558SSimon J. Gerraty 465fff9558SSimon J. Gerraty gpg: WARNING: unsafe permissions on homedir 475fff9558SSimon J. Gerraty '/h/sjg/openpgp/.gnupg' 485fff9558SSimon J. Gerraty gpg: Warning: using insecure memory! 495fff9558SSimon J. Gerraty /h/sjg/openpgp/.gnupg/pubring.kbx 505fff9558SSimon J. Gerraty --------------------------------- 515fff9558SSimon J. Gerraty pub rsa2048 2018-03-26 [SC] [expires: 2020-03-25] 525fff9558SSimon J. Gerraty AB39B111E40DD019E0E7C171ACA72B4719FD2523 535fff9558SSimon J. Gerraty uid [ultimate] OpenPGPtest 545fff9558SSimon J. Gerraty 555fff9558SSimon J. GerratyThe ``keyID`` we want later will be the last 8 octets 565fff9558SSimon J. Gerraty(``ACA72B4719FD2523``) 575fff9558SSimon J. GerratyThis is what we will use for looking up the key. 585fff9558SSimon J. Gerraty 595fff9558SSimon J. GerratyWe can then export the private and public keys:: 605fff9558SSimon J. Gerraty 615fff9558SSimon J. Gerraty GNUPGHOME=$PWD/.gnupg gpg --openpgp \ 625fff9558SSimon J. Gerraty --export --armor > ACA72B4719FD2523.pub.asc 635fff9558SSimon J. Gerraty GNUPGHOME=$PWD/.gnupg gpg --openpgp \ 645fff9558SSimon J. Gerraty --export-secret-keys --armor > ACA72B4719FD2523.sec.asc 655fff9558SSimon J. Gerraty 665fff9558SSimon J. GerratyThe public key ``ACA72B4719FD2523.pub.asc`` is what we want to 675fff9558SSimon J. Gerratyembed in this library. 685fff9558SSimon J. GerratyIf you look at the ``ta_asc.h`` target in ``openpgp/Makefile.inc`` 695fff9558SSimon J. Gerratywe want the trust anchor in a file named ``t*.asc`` 705fff9558SSimon J. Gerratyeg. ``ta_openpgp.asc``. 715fff9558SSimon J. Gerraty 725fff9558SSimon J. GerratyThe ``ta_asc.h`` target will capture all such ``t*.asc`` into that 735fff9558SSimon J. Gerratyheader. 745fff9558SSimon J. Gerraty 755fff9558SSimon J. GerratySignatures 765fff9558SSimon J. Gerraty---------- 775fff9558SSimon J. Gerraty 78*f486ebb5SSimon J. GerratyWe expect ascii armored (``.asc``) detached signatures 79*f486ebb5SSimon J. GerratyEg.:: 80*f486ebb5SSimon J. Gerraty 81*f486ebb5SSimon J. Gerraty gpg -a --detach-sign manifest 82*f486ebb5SSimon J. Gerraty 83*f486ebb5SSimon J. Gerratyshould produce the expected signature in ``manifest.asc`` 845fff9558SSimon J. Gerraty 855fff9558SSimon J. GerratyWe only support version 4 signatures using RSA (the default for ``gpg``). 865fff9558SSimon J. Gerraty 875fff9558SSimon J. Gerraty 885fff9558SSimon J. GerratyOpenSSL 895fff9558SSimon J. Gerraty======== 905fff9558SSimon J. Gerraty 915fff9558SSimon J. GerratyThe basic idea here is to setup a private CA. 925fff9558SSimon J. Gerraty 935fff9558SSimon J. GerratyThere are lots of good tutorials on available on this topic; 945fff9558SSimon J. Gerratyjust google *setup openssl ca*. 955fff9558SSimon J. GerratyA good example is https://jamielinux.com/docs/openssl-certificate-authority/ 965fff9558SSimon J. Gerraty 975fff9558SSimon J. GerratyAll we need for this library is a copy of the PEM encoded root CA 985fff9558SSimon J. Gerratycertificate (trust anchor). This is expected to be in a file named 995fff9558SSimon J. Gerraty``t*.pem`` eg. ``ta_rsa.pem``. 1005fff9558SSimon J. Gerraty 1015fff9558SSimon J. GerratyThe ``ta.h`` target in ``Makefile.inc`` will combine all such 1025fff9558SSimon J. Gerraty``t*.pem`` files into that header. 1035fff9558SSimon J. Gerraty 1045fff9558SSimon J. GerratySignatures 1055fff9558SSimon J. Gerraty---------- 1065fff9558SSimon J. Gerraty 1075fff9558SSimon J. GerratyFor Junos we currently use EC DSA signatures with file extension 1085fff9558SSimon J. Gerraty``.esig`` so the signature for ``manifest`` would be ``manifest.esig`` 1095fff9558SSimon J. Gerraty 1105fff9558SSimon J. GerratyThis was the first signature method we used with the remote signing 1115fff9558SSimon J. Gerratyservers and it ends up being a signature of a hash. 1125fff9558SSimon J. GerratyIe. client sends a hash which during signing gets hashed again. 1135fff9558SSimon J. GerratySo for Junos we define VE_ECDSA_HASH_AGAIN which causes ``verify_ec`` 1145fff9558SSimon J. Gerratyto hash again. 1155fff9558SSimon J. Gerraty 116*f486ebb5SSimon J. GerratyLater I added a FakeHash class to the signing server so we could 117*f486ebb5SSimon J. Gerratygenerate signatures compatible with our previous RSA scheme and 118*f486ebb5SSimon J. Gerratyothers. 119*f486ebb5SSimon J. Gerraty 1205fff9558SSimon J. GerratyOtherwise our EC DSA and RSA signatures are the default used by 1215fff9558SSimon J. GerratyOpenSSL - an original design goal was that a customer could verify our 1225fff9558SSimon J. Gerratysignatures using nothing but an ``openssl`` binary. 1235fff9558SSimon J. Gerraty 1245fff9558SSimon J. Gerraty 1255fff9558SSimon J. GerratySelf tests 1265fff9558SSimon J. Gerraty========== 1275fff9558SSimon J. Gerraty 1285fff9558SSimon J. GerratyIf you want the ``loader`` to perform self-test of a given signature 1295fff9558SSimon J. Gerratyverification method on startup (a must for FIPS 140-2 certification) 1305fff9558SSimon J. Gerratyyou need to provide a suitable file signed by each supported trust 1315fff9558SSimon J. Gerratyanchor. 1325fff9558SSimon J. Gerraty 1335fff9558SSimon J. GerratyThese should be stored in files with names that start with ``v`` and 1345fff9558SSimon J. Gerratyhave the same extension as the corresponding trust anchor. 1355fff9558SSimon J. GerratyEg. for ``ta_openpgp.asc`` we use ``vc_openpgp.asc`` 1365fff9558SSimon J. Gerratyand for ``ta_rsa.pem`` we use ``vc_rsa.pem``. 1375fff9558SSimon J. Gerraty 1385fff9558SSimon J. GerratyNote for the X.509 case we simply extract the 2nd last certificate 1395fff9558SSimon J. Gerratyfrom the relevant chain - which is sure to be a valid certificate 1405fff9558SSimon J. Gerratysigned by the corresponding trust anchor. 1415fff9558SSimon J. Gerraty 1425fff9558SSimon J. Gerraty-------------------- 143