lib/libsecureboot/README.rst

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