This is an old revision of the document!


Cryptography

iPXE supports the HTTPS protocol, which allows you to encrypt all communication with a web server and to verify the server's identity. To enable support for the HTTPS protocol, you must enable the DOWNLOAD_PROTO_HTTPS build configuration option.

iPXE also supports code signing, which allows you to verify the authenticity and integrity of files downloaded by iPXE. To enable support for code signing, you must enable the IMAGE_TRUST_CMD build configuration option, and use the imgtrust command within an embedded script.

Supported configurations

Protocol versions TLSv1.0 TLSv1.1 TLSv1.2
Public-key algorithms RSA
Block cipher algorithms AES-128-CBC AES-256-CBC
Hash algorithms MD5 SHA-1 SHA-256

The exact list of supported cipher suites is RSA_WITH_AES_256_CBC_SHA256, RSA_WITH_AES_128_CBC_SHA256, RSA_WITH_AES_256_CBC_SHA, and RSA_WITH_AES_128_CBC_SHA.

Trusted root certificates

In the default configuration, iPXE trusts only a single root certificate: the "iPXE root CA" certificate.

If you want more control over the chain of trust, then you can generate your own private root certificate ca.crt using:

  openssl req -x509 -newkey rsa:2048 -out ca.crt -keyout ca.key -days 1000

You can change the list of trusted root certificates when you build iPXE using the TRUST=... build parameter. For example, to trust your private root certificate ca.crt:

  make bin/ipxe.iso TRUST=ca.crt

This will create a custom version of the iPXE binary ipxe.iso which trusts your private root certificate ca.crt.

You can specify multiple root certificates to trust. For example:

  make bin/ipxe.iso TRUST=/path/to/ca1.crt,/path/to/ca2.crt

Certificates must be in PEM format.

Some books

Issuing certificates

You can use your private root certificate ca.crt to issue certificates that will be trusted by iPXE. To do this, you must create a minimal private CA infrastructure:

  echo 01 > ca.srl
  touch ca.idx
  mkdir signed

You must also create a minimal CA configuration file ca.cnf, containing:

  [ ca ]
  default_ca             = ca_default
  
  [ ca_default ]
  certificate            = ca.crt
  private_key            = ca.key
  serial                 = ca.srl
  database               = ca.idx
  new_certs_dir          = signed
  default_md             = default
  policy                 = policy_anything
  preserve               = yes
  default_days           = 90
  
  [ policy_anything ]
  countryName            = optional
  stateOrProvinceName    = optional
  localityName           = optional
  organizationName       = optional
  organizationalUnitName = optional
  commonName             = optional
  emailAddress           = optional
  
  [ cross ]
  basicConstraints       = critical,CA:true
  keyUsage               = critical,cRLSign,keyCertSign
  
  [ codesigning ]
  keyUsage                = digitalSignature
  extendedKeyUsage        = codeSigning

You can now generate a new server certificate server.crt and the corresponding private key server.key using:

  openssl req -newkey rsa -keyout server.key -out server.req
  openssl ca -config ca.cnf -in server.req -out server.crt

This will create a server certificate server.crt which is signed by your private root certificate.

Cross-signing certificates

You can use your private CA infrastructure to cross-sign an existing public CA root certificate. For example, to cross-sign the StartCom root certificate:

  openssl ca -config ca.cnf -extensions cross -notext -preserveDN -ss_cert startcom.crt -out startcom-cross.crt

This will create a cross-signed certificate startcom-cross.crt. This allows you to extend the trust from your private root certificate to include certificates signed by startcom.crt, without having to directly include startcom.crt as an iPXE trusted root certificate.

Code signing

You can use a code-signing certificate to sign a binary so that it will be trusted by iPXE. Certificates used for code signing must include the digitalSignature key usage extension and the codeSigning extended key usage extension. You can generate a new code-signing certificate codesign.crt and the corresponding private key codesign.key using:

  openssl req -newkey rsa -keyout codesign.key -out codesign.req
  openssl ca -config ca.cnf -extensions codesigning -in codesign.req -out codesign.crt

You can now use this certificate to sign a binary that will then be trusted by iPXE. For example, to sign the binary vmlinuz:

  openssl cms -sign -binary -noattr -in vmlinuz \
              -signer codesign.crt -inkey codesign.key -certfile ca.crt \
              -outform DER -out vmlinuz.sig

This will create the signature file vmlinuz.sig, which you can use with the imgverify command to verify the binary vmlinuz. For example, suppose that you want to use an embedded script to download vmlinuz over an untrusted network:

  #!ipxe
  
  imgtrust --permanent
  dhcp
  kernel http://${next-server}/boot/vmlinuz
  imgverify vmlinuz http://${next-server}/boot/vmlinuz.sig
  boot vmlinuz

This embedded script would refuse to boot unless the downloaded version of vmlinuz could be successfully verified using the signature file vmlinuz.sig.

Client certificates

You can embed a client certificate (and the corresponding private) key when you build iPXE using the CERT=... and KEY=... build parameters. For example, to use the client certificate client.crt with the corresponding private key in client.key:

make bin/ipxe.iso CERT=client.crt KEY=client.key

This will create a custom version of the iPXE binary which includes your client certificate (and the corresponding private key). You can now configure your web server to require the use of this client certificate for authentication.

The certificate and key must both be in PEM format.

Warning

Note that the private key is stored unencrypted within the iPXE binary. You should therefore treat the iPXE binary as being confidential information.

Using a client certificate will add a noticeable delay (approximately one second) to each HTTPS connection.

crypto.1336329981.txt.gz · Last modified: 2012/05/06 18:46 by mcb30
Recent changes RSS feed CC Attribution-Share Alike 4.0 International Driven by DokuWiki
All uses of this content must include an attribution to the iPXE project and the URL https://ipxe.org
References to "iPXE" may not be altered or removed.