1libsecureboot 2************* 3 4This library depends one way or another on verifying digital signatures. 5To do that, the necessary trust anchors need to be available. 6 7The simplest (and most attractive for an embedded system) is to 8capture them in this library. 9 10The makefile ``local.trust.mk`` is responsible for doing that. 11The file provided is just an example and depends on the environment 12here at Juniper. 13 14Within Juniper we use signing servers, which apart from signing things 15provide access to the necessary trust anchors. 16That signing server is freely available - see 17http://www.crufty.net/sjg/docs/signing-server.htm 18 19X.509 certificates chains offer a lot of flexibility over time and are 20a great solution for an embedded vendor like Juniper or even 21FreeBSD.org, but are probably overkill for personal or small site use. 22 23Setting up a CA for this is rather involved so I'll just provide a 24link below to suitable tutorial below. 25 26Using OpenPGP is much simpler. 27 28 29OpenPGP 30======== 31 32This is very simple to setup and use. 33 34An RSA key pair can be generated with:: 35 36 GNUPGHOME=$PWD/.gnupg gpg --openpgp \ 37 --quick-generate-key --batch --passphrase '' "keyname" RSA 38 39The use of ``GNUPGHOME=$PWD/.gnupg`` just avoids messing with personal 40keyrings. 41We can list the resulting key:: 42 43 GNUPGHOME=$PWD/.gnupg gpg --openpgp --list-keys 44 45 gpg: WARNING: unsafe permissions on homedir 46 '/h/sjg/openpgp/.gnupg' 47 gpg: Warning: using insecure memory! 48 /h/sjg/openpgp/.gnupg/pubring.kbx 49 --------------------------------- 50 pub rsa2048 2018-03-26 [SC] [expires: 2020-03-25] 51 AB39B111E40DD019E0E7C171ACA72B4719FD2523 52 uid [ultimate] OpenPGPtest 53 54The ``keyID`` we want later will be the last 8 octets 55(``ACA72B4719FD2523``) 56This is what we will use for looking up the key. 57 58We can then export the private and public keys:: 59 60 GNUPGHOME=$PWD/.gnupg gpg --openpgp \ 61 --export --armor > ACA72B4719FD2523.pub.asc 62 GNUPGHOME=$PWD/.gnupg gpg --openpgp \ 63 --export-secret-keys --armor > ACA72B4719FD2523.sec.asc 64 65The public key ``ACA72B4719FD2523.pub.asc`` is what we want to 66embed in this library. 67If you look at the ``ta_asc.h`` target in ``openpgp/Makefile.inc`` 68we want the trust anchor in a file named ``t*.asc`` 69eg. ``ta_openpgp.asc``. 70 71The ``ta_asc.h`` target will capture all such ``t*.asc`` into that 72header. 73 74Signatures 75---------- 76 77We expect ascii armored (``.asc``) detached signatures. 78Eg. signature for ``manifest`` would be in ``manifest.asc`` 79 80We only support version 4 signatures using RSA (the default for ``gpg``). 81 82 83OpenSSL 84======== 85 86The basic idea here is to setup a private CA. 87 88There are lots of good tutorials on available on this topic; 89just google *setup openssl ca*. 90A good example is https://jamielinux.com/docs/openssl-certificate-authority/ 91 92All we need for this library is a copy of the PEM encoded root CA 93certificate (trust anchor). This is expected to be in a file named 94``t*.pem`` eg. ``ta_rsa.pem``. 95 96The ``ta.h`` target in ``Makefile.inc`` will combine all such 97``t*.pem`` files into that header. 98 99Signatures 100---------- 101 102For Junos we currently use EC DSA signatures with file extension 103``.esig`` so the signature for ``manifest`` would be ``manifest.esig`` 104 105This was the first signature method we used with the remote signing 106servers and it ends up being a signature of a hash. 107Ie. client sends a hash which during signing gets hashed again. 108So for Junos we define VE_ECDSA_HASH_AGAIN which causes ``verify_ec`` 109to hash again. 110 111Otherwise our EC DSA and RSA signatures are the default used by 112OpenSSL - an original design goal was that a customer could verify our 113signatures using nothing but an ``openssl`` binary. 114 115 116Self tests 117========== 118 119If you want the ``loader`` to perform self-test of a given signature 120verification method on startup (a must for FIPS 140-2 certification) 121you need to provide a suitable file signed by each supported trust 122anchor. 123 124These should be stored in files with names that start with ``v`` and 125have the same extension as the corresponding trust anchor. 126Eg. for ``ta_openpgp.asc`` we use ``vc_openpgp.asc`` 127and for ``ta_rsa.pem`` we use ``vc_rsa.pem``. 128 129Note for the X.509 case we simply extract the 2nd last certificate 130from the relevant chain - which is sure to be a valid certificate 131signed by the corresponding trust anchor. 132 133-------------------- 134$FreeBSD$ 135