draft-moskowitz-ecdsa-pki.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
  <!ENTITY ieee_802_1ar SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml6/reference.IEEE.802.1AR_2009.xml">
]>

<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
 <?rfc toc="yes" ?>
 <?rfc symrefs="yes" ?>
 <?rfc sortrefs="yes"?>
 <?rfc compact="yes" ?>
 <?rfc subcompact="no" ?>
 <?rfc iprnotified="no" ?>
  <?rfc strict="no" ?>

<rfc category="info" docName="draft-moskowitz-ecdsa-pki-10" ipr="trust200902">
 <front>
<title abbrev="PKI Guide">Guide for building an ECC pki</title>
        <author fullname="Robert Moskowitz" initials="R." surname="Moskowitz" >
        <organization>HTT Consulting</organization>
        <address>
        <postal>
          <street> </street>
          <city>Oak Park</city>
          <region>MI</region>
          <code>48237</code>
        </postal>
        <email>rgm@labs.htt-consult.com</email>
        </address>
        </author>
    <author fullname="Henk Birkholz" initials="H." surname="Birkholz">
      <organization>Fraunhofer SIT</organization>
      <address>
        <postal>
          <street>Rheinstrasse 75</street>
          <city>Darmstadt</city>
          <code>64295</code>
          <country>Germany</country>
        </postal>
        <email>henk.birkholz@sit.fraunhofer.de</email>
      </address>
    </author>
    <author fullname="Liang Xia" initials="L." surname="Xia">
        <organization>Huawei</organization>
        <address>
        <postal>
        <street>No. 101, Software Avenue, Yuhuatai District</street>
        <city>Nanjing</city>
        <country>China</country>
        </postal>
        <email>Frank.xialiang@huawei.com</email>
        </address>
    </author>
    <author fullname="Michael C. Richardson" initials="M."
            surname="Richardson">
      <organization abbrev="Sandelman">Sandelman Software Works</organization>

      <address>
        <email>mcr+ietf@sandelman.ca</email>

        <uri>http://www.sandelman.ca/</uri>
      </address>
    </author>
<date year="2021"/>
   <area>Security Area</area>
   <workgroup>wg TBD</workgroup>
    <keyword>RFC</keyword>
     <keyword>Request for Comments</keyword>
     <keyword>I-D</keyword>
     <keyword>Internet-Draft</keyword>
     <keyword>PKI</keyword>
     <keyword>ECDSA</keyword>
     <keyword>802.1AR</keyword>

<abstract>
<t>
		This memo provides a guide for building a PKI (Public Key
		Infrastructure) using openSSL.  All certificates in this guide
		are ECDSA, P-256, with SHA256 certificates.  Along with common
		End Entity certificates, this guide provides instructions for
		creating IEEE 802.1AR iDevID Secure Device certificates.
</t>
</abstract>
</front>
<middle>
<section anchor="intro" title="Introduction">
<t>
		The IETF has a plethora of security solutions targeted at IoT.
		Yet all too many IoT products are deployed with no or
		improperly configured security.  In particular resource
		constrained IoT devices and non-IP IoT networks have not been
		well served in the IETF.
</t>
<t>
		Additionally, more IETF (e.g. DOTS, NETCONF) efforts are
		requiring secure identities, but are vague on the nature of
		these identities other than to recommend use of X.509 digital
		certificates and perhaps TLS.
</t>
<t>
		This effort provides the steps, using the openSSL application,
		to create such a PKI of ECDSA certificates.  The goal is that
		any developer or tester can follow these steps, create the
		basic objects needed and establish the validity of the
		standard/program design.  This guide can even be used to create
		a production PKi, though additional steps need to be taken.
		This could be very useful to a small vendor needing to include
		<xref target="IEEE.802.1AR_2009">802.1AR</xref> iDevIDs in
		their product.
</t>
<t>
		This guide was tested with openSSL 1.1.0f on Fedora 26 and
		creates PEM-based certificates.  DER based certificates fails
		(see <xref target="DER" />).
</t>
</section>
<section anchor="terms" title="Terms and Definitions">
<section title="Requirements Terminology">
<t>
                The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
                NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
                "OPTIONAL" in this document are to be interpreted as described
                in <xref target="RFC2119">RFC 2119</xref>.
</t>
</section>
<section title="Notations">
 <t> This section will contain notations </t>
</section>
<section title="Definitions">
        <t>
                There are no draft specific definitions at this time
        </t>
</section>
</section>
<section anchor="BasicPKI" title="The Basic PKI feature set">
<t>
	A basic pki has two levels of hierarchy: Root and Intermediate. The
	Root level has the greatest risk, and is the least used.  It only
	signs the Intermediate level signing certificate.  As such, once
	the Root level is created and signs the Intermediate level
	certificate it can be locked up.  In fact, the Root level could
	exist completely on a mSD boot card for an ARM small computer like
	a RaspberryPi.  A copy of this card can be made and securely stored
	in a different location.
</t>
<t>
	The Root level contains the Root certificate private key, a
	database of all signed certificates, and  the public certificate.
	It can also contain the Intermediate level public certificate and a
	Root level CRL.
</t>
<t>
	The Intermediate level contains the Intermediate certificate
	private key, the public certificate, a database of all signed
	certificates, the certificate trust chain, and Intermediate level
	CRL.  It can also contain the End Entity public certificates.  The
	private key file needs to be keep securely.  For example as with
	the Root level, a mSD image for an ARM computer could contain the
	complete Intermediate level. This image is kept offline.  The End
	Entity CSR is copied to it, signed, and then the signed certificate
	and updated database are moved to the public image that lacks the
	private key.
</t>
<t>
	For a simple test pki, all files can be kept on a single system
	that is managed by the tester.
</t>
<t>
	End Entities create a key pair and a Certificate Signing Request
	(CSR).  The private key is stored securely.  The CSR is delivered
	to the Intermediate level which uses the CSR to create the End
	Entity certificate.  This certificate, along with the trust chain
	back to the root, is then returned to the End Entity.
</t>
<t>
	There is more to a pki, but this suffices for most development and
	testing needs.
</t>
</section>
<section anchor="RootLevel" title="Getting started and the Root level">
<t>
    This guide was developed on a Fedora 26 armv7hl system (Cubieboard2
    SoC).  It should work on most Linux and similar systems.  All work
    was done in a terminal window with extensive "cutting and pasting"
    from a draft guide into the terminal window.  Users of this guide
    may find different behaviors based on their system.
</t>
<section anchor="FirstStep" title="Setting up the Environment">
<t>
    The first step is to create the pki environment.  Modify the
    variables to suit your needs.
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/setup1.sh END
</figure>
<t>
	Where:

<list style="hanging" hangIndent="9">
	<t hangText="dir">
		<vspace />
		Directory for certificate files
	</t>
	<t hangText="cadir">
		<vspace />
		Directory for Root certificate files
	</t>
	<t hangText="Format">
		<vspace />
		File encoding:  PEM or DER
		<vspace />
              At this time only PEM works
	</t>
	<t hangText="sn">
		<vspace />
		         Serial Number length in bytes
		         <vspace />
                For a public CA the range is 8 to 19
	<vspace />
	</t>
</list>
</t>
<t>
    The Serial Number length for a public pki ranges from 8 to 19
    bytes.  The use of 19 rather than 20 is to accommodate the hex
    representation of the Serial Number.  If it has a one in the high
    order bit, DER encoding rules will place a 0x00 in front.
</t>
<t>
	The DN and SAN fields are examples.  Change them to appropriate
	values.  If you leave one blank, it will be left out of the
	Certificate.  "OU" above is an example of an empty DN object.
</t>
<t>
	Create the file, $dir/openssl-root.cnf from the contents in <xref
	target="Rootconfig" />.
</t>
</section>
<section anchor="RootCert" title="Create the Root Certificate">
<t>
	Next are the openssl commands to create the Root certificate
	keypair, and the Root certificate.  Included are commands to view
	the file contents.
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/rootcert.sh END
</figure>
</section>
</section>
<section anchor="IntermediateLevel" title="The Intermediate level">
<section anchor="NextStep" title="Setting up the Intermediate Certificate Environment">
<t>
	The next part is to create the Intermediate pki environment. Modify
	the variables to suit your needs.  In particular, set the variables
	for CRL and/or OCSP support.
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/intermediate_setup.sh END
</figure>
<t>
	Create the file, $dir/openssl-intermediate.cnf from the contents in
	<xref target="Intermediateconfig" />.  Uncomment lines for
	crlDistributionPoints and authorityInfoAccess if using CRLs or OSCP
	repectfully.
</t>
</section>
<section anchor="IntermediateCert" title="Create the Intermediate Certificate">
<t>
	Here are the openssl commands to create the Intermediate
	certificate keypair, Intermediate certificate signed request (CSR),
	and the Intermediate certificate.  Included are commands to view
	the file contents.
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/intermediate_cert.sh END
</figure>
</section>
<section anchor="ServerCert" title="Create a Server EE Certificate">
<t>
	Here are the openssl commands to create a Server End Entity
	certificate keypair, Server certificate signed request (CSR),
	and the Server certificate.  Included are commands to view
	the file contents.
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/end-server.sh END
</figure>
</section>
<section anchor="ClientCert" title="Create a Client EE Certificate">
<t>
	Here are the openssl commands to create a Client End Entity
	certificate keypair, Client certificate signed request (CSR),
	and the Client certificate.  Included are commands to view
	the file contents.
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/end-client-dn.sh END
</figure>
<figure>
INSERT_TEXT_FROM_FILE scripts/end-client.sh END
</figure>
</section>
</section>
<section anchor="Intermediate8021ARLevel" title="The 802.1AR Intermediate level">
<section anchor="Step8021AR" title="Setting up the 802.1AR Intermediate Certificate Environment">
<t>
	The next part is to create the 802.1AR Intermediate pki
	environment.  This is very similar to the Intermediate pki
	environment.  Modify the variables to suit your needs.
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/intermediate_1ar_setup.sh END
</figure>
<t>
	Create the file, $dir/openssl-8021ARintermediate.cnf from the
	contents in <xref target="Intermediate8021ARconfig" />.  Uncomment
	lines for crlDistributionPoints and authorityInfoAccess if using
	CRLs or OSCP repectfully.

</t>
</section>
<section anchor="Intermediate8021ARCert" title="Create the 802.1AR Intermediate Certificate">
<t>
	Here are the openssl commands to create the 802.1AR Intermediate
	certificate keypair, 802.1AR Intermediate certificate signed
	request (CSR), and the 802.1AR Intermediate certificate.  Included
	are commands to view the file contents.
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/intermediate_1ar_cert.sh END
</figure>
</section>
<section anchor="Cert8021AR" title="Create an 802.1AR iDevID Certificate">
<t>
	Here are the openssl commands to create a 802.1AR iDevID
	certificate keypair, iDevID certificate signed request (CSR), and
	the iDevID certificate.  Included are commands to view the file
	contents.
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/idevid-csr-cert.sh END
</figure>
</section>
</section>
<section anchor="CRL" title="Setting up a CRL for an Intermediate CA">
<t>
	This part provides CRL support to an Intermediate CA.  In this memo
	it applies to both Intermediate CAs.  Set the crlDistributionPoints
	as provided via the environment variables.
</t>
<section anchor="createCRL" title="Create (or recreate) the CRL">
<t>
	It is simple to create the CRL.  The CRL consists of the
	certificates flagged with an R (Revoked) in index.txt:
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/crl-creation.sh END
</figure>
</section>
<section anchor="RevokeCert" title="Revoke a Certificate">
<t>
	Revoking a certificate is a two step process.  First identify the
	target certificate, examples are listed below.  Revoke it then
	publish a new CRL.
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/revoke-step1.sh END
</figure>
<t>
	Recreate the CRL using <xref target="createCRL" />.
</t>
</section>
</section>
<section anchor="OCSP" title="Setting up OCSP for an Intermediate CA">
<t>
	This part provides OCSP support to an Intermediate CA.  In this
	memo it applies to both Intermediate CAs.  Set the
	authorityInfoAccess as provided via the environment variables.
</t>
<section anchor="createOCSP" title="Create the OCSP Certificate">
<t>
	OCSP needs a signing certificate.  This certificate must be signed
	by the CA that signed the certificate being checked.  The steps to
	create this certificate is the similar to a Server certificate for
	the CA:
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/ocsp-setup.sh END
</figure>
</section>
<section anchor="RevokeCertOCSP" title="Revoke a Certificate">
<t>
	Revoke the certificate as in <xref target="RevokeCert" />.  The
	OCSP responder SHOULD detect the flag change in index.txt and, when
	queried respond appropriately.
</t>
</section>
<section anchor="TestingOCSP" title="Testing OCSP with Openssl">
<t>
	OpenSSL provides a simple OCSP service that can be used to test the
	OCSP certificate and revocation process (Note that this only reads
	the index.txt to get the certificate status at startup).
</t>
<t>
	In a terminal window, set variables dir and ocspurl (examples
	below), then run the simple OCSP service:
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/run-ocsp-server.sh END
</figure>
<t>
	In another window, test out a certificate status with:
</t>
<figure>
INSERT_TEXT_FROM_FILE scripts/test-ocsp-server.sh END
</figure>
<t>
	Revoke the certificate, <xref target="RevokeCert" />, restart the
	test Responder again as above, then check the certificate status.
</t>
</section>
</section>
<section anchor="Footnotes" title="Footnotes">
<t>
	Creating this document was a real education in the state of
	openSSL, X.509 certificate guidance, and just general level of
	certificate awareness.  Here are a few short notes.
</t>
<section anchor="SerNum" title="Certificate Serial Number">
<t>
	The certificate serial number's role is to provide yet another way
	to maintain uniqueness of certificates within a pki as well as a
	way to index them in a data store.  It has taken on other roles,
	most notably as a defense.
</t>
<t>
	The CABForum guideline for a public CA is for the serial number to
	be a random number at least 8 octets long and no longer than 20
	bytes. By default, openssl makes self-signed certificates with 8
	octet serial numbers.  This guide uses openssl's RAND function to
	generate the random value and pipe it into the -set_serial option.
	This number MAY have the first bit as a ONE; the DER encoding rules
	prepend such numbers with 0x00.  Thus the limit of '19' for the
	variable 'ns'.
</t>
<t>
	A private CA need not follow the CABForum rules and can use
	anything number for the serial number.  For example, the root CA
	(which has no security risks mitigated by using a random value)
	could use '1' as its serial number.  Intermediate and End Entity
	certificate serial numbers can also be of any value if a strong
	hash, like SHA256 used here.  A value of 4 for ns would provide a
	sufficient population so that a CA of 10,000 EE certificates will
	have only a 1.2% probability of a collision.  For only 1,000
	certificates the probability drops to 0.012%.
</t>
<t>
	The following was proposed on the openssl-user list as an
	alternative to using the RAND function:
</t>
<t>
	Keep k bits (k/8 octets) long serial numbers for all your
	certificates, chose a block cipher operating on blocks of k bits,
	and operate this block cipher in CTR mode, with a proper secret key
	and secret starting counter. That way, no collision detection is
	necessary, you’ll be able to generate 2^(k/2) unique k bits longs
	serial numbers (in fact, you can generate 2^k unique serial
	numbers, but after 2^(k/2) you lose some security guarantees).
</t>
<t>
	With 3DES, k=64, and with AES, k=128.
</t>
</section>
<section anchor="Config" title="Some OpenSSL config file limitations">
<t>
	There is a bit of inconsistency in how different parts and fields
	in the config file are used.  Environment variables can only be
	used as values.  Some fields can have null values, others cannot.
	The lack of allowing null fields means a script cannot feed in an
	environment variable with value null.  In such a case, the field
	has to be removed from the config file.
</t>
<t>
	The expectation is each CA within a PKI has its own config file,
	customized to the certificates supported by that CA.
</t>
</section>
<section anchor="SAN" title="subjectAltName support, or lack thereof">
<t>
	There is no direct openssl command line option to provide a
	subjectAltName for a certificate.  This is a serious limitation.
	Per <xref target="RFC5280">RFC 5280</xref> SAN is the object for
	providing email addresses and DNS addresses (FQDN), yet the common
	practice has been to use the commonName object within the
	distinguishedName object.  How much of this is due to the
	difficulty in creating certificates with a SAN?
</t>
<t>
	Thus the only way to provide a SAN is through the config file.  And
	there are two approaches.  This document uses an environment
	variable to provide the SAN value into the config file.  Another
	approach is to use piping as in:
<figure>
INSERT_TEXT_FROM_FILE scripts/san-creation-pipe.sh END
</figure>
</t>
</section>
<section anchor="CriticalSAN" title="Certificates with only subjectAltName">
<t>
	Also in <xref target="RFC5280">RFC 5280</xref> (sec 4.2.1.6):  if
	the only subject identity in the certificate is in subjectAltName,
	then Subject MUST be empty and subjectAltName MUST be marked as
	critical.
</t>
<t>
	This can be achieved with the variable DN=/ and subjectAltName
	(example given):
</t>
<figure> <artwork>

DN=/
export subjectAltName=critical,email:postmaster@htt-consult.com

</artwork> </figure>
</section>
<section anchor="DER" title="DER support, or lack thereof">
<t>
	The long, hard-fought battle with openssl to create a full DER pki
	failed.  The is no facility to create a DER certificate from a DER
	CSR.  It just is not there in the 'openssl ca' command.  Even the
	'openssl x509 -req' command cannot do this for a simple certificate.
</t>
<t>
	Further, there is no 'hack' for making a certificate chain as there
	is with PEM.  With PEM a simple concatenation of the certificates
	create a usable certificate chain.  For DER, some recommend using
	<xref target="RFC2315">PKCS#7</xref>, where others point out that
	this format is poorly support 'in the field', whereas <xref
	target="RFC7292">PKCS#12</xref> works for them.
</t>
<t>
	Finally, openssl does supports converting a PEM certificate to DER:
<figure> <artwork><![CDATA[

openssl x509 -outform der -in certificate.pem -out certificate.der

]]></artwork> </figure>
	This should also work for the keypair.  However, in a highly
	constrained device it may make more sense to just store the raw
	keypair in the device's very limited secure storage.
</t>
</section>
</section>
<section anchor="IANA" title="IANA Considerations">
<t>
        TBD.  May be nothing for IANA.
</t>
</section>
<section title="Security Considerations">
<section anchor="Randomness" title="Adequate Randomness">
<t>
	Creating certificates takes a lot of random numbers.  A good source
	of random numbers is critical.  <xref
	target="WeakKeys">Studies</xref> have found excessive amount of
	certificates, all with the same keys due to bad randomness on the
	generating systems.  The amount of entropy available for these
	random numbers can be tested.  On Fedora/Centos and most Linux systems use:
<figure> <artwork><![CDATA[
cat /proc/sys/kernel/random/entropy_avail
]]></artwork> </figure>
</t>
<t>
	If the value is low (below 1000) check your system's randomness
	source.  Is rng-tools installed?  Consider adding an entropy
	collection service like haveged from issihosts.com/haveged.
</t>
</section>
<section anchor="Theft" title="Key pair Theft">
<t>
	During the certificate creation, particularly during keypair
	generation, the files are vulnerable to theft.  This can be
	mitigate using umask.  Before using openssl, set umask:
<figure> <artwork><![CDATA[
restore_mask=$(umask -p)
umask 077
]]></artwork> </figure>
	Afterwards, restore it with:
<figure> <artwork><![CDATA[
$restore_mask
]]></artwork> </figure>
or just close the shell that was used, and start a new one.  (The -p option to umask is a bash-ism)
</t>
<t>
There is nothing in these recipes that requires super-user on the system creating the
certificates.  Provided that adequate randomness is available, a virtual machine or container
is entirely appropriate.  Containers tend to have better access to randomness than virtual
machines.
</t>
<t>
The scripts and configuration files and in particular, private keys, may be kept offline
on a USB key for instance, and loaded when needed.
</t>
<t>
The OCSP server needs to be online and available to all clients that will use the
certificates. This may mean available on the Internet.  A firewall can protect the
OCSP server, and port-forwards and/or ACL rules can restrict access to just the OCSP port.
OCSP artifacts are signed by a key designed for that purpose only so do not require that
the associated CA key be available online.
</t>
<t>
Generating new CRLs, however, requires that the CA signing key be online, which is one of
the reasons for creating an intermediate CA.
</t>
</section>

</section>
<section title="Acknowledgments">
<t>
	This work was jump started by the excellent RSA pki guide by Jamie
	Nguyen.  The openssl-user mailing list, with its many supportive
	experts; in particular:  Rich Salz, Jakob Bolm, Viktor Dukhovni,
	and Erwann Abalea, was of immense help as was the openssl man pages
	website.
</t>
<t>
	Finally, "Professor Google" was always ready to point to answers to
	questions like: "openssl subjectAltName on the command line".  And
	the Professor, it seems, never tires of answering even trivial
	questions.
</t>
</section>

</middle>
<back>
<references title="Normative References">
        <?rfc include="reference.RFC.2119.xml"?>
</references>
<references title="Informative References">
        &ieee_802_1ar;
        <?rfc include="reference.RFC.2315.xml"?>
        <?rfc include="reference.RFC.5280.xml"?>
        <?rfc include="reference.RFC.7292.xml"?>
<reference anchor="WeakKeys" target="https://www.usenix.org/system/files/conference/usenixsecurity12/sec12-final228.pdf">
  <front>
    <title>Detection of Widespread Weak Keys in Network Devices</title>
<author fullname="Nadia Heninger" initials="N.H." surname="Heninger">
	<organization>University of California, San Diego</organization>
	<address/>
</author>
<author fullname="Zakir Durumeric" initials="Z.D." surname="Durumeric">
	<organization>The University of Michigan</organization>
	<address/>
</author>
<author fullname="Eric Wustrow" initials="E.W." surname="Wustrow">
	<organization>The University of Michigan</organization>
	<address/>
</author>
<author fullname="J. Alex Halderman" initials="J.A.H." surname="Halderman">
	<organization>The University of Michigan</organization>
	<address/>
</author>
<date month="July" year="2011"/>
</front>
</reference>
</references>
<section anchor="config" title="OpenSSL config files">
<section anchor="Rootconfig" title="OpenSSL Root config file">
<t>
	The following is the openssl-root.cnf file contents
</t>
<figure>
INSERT_TEXT_FROM_FILE configs/openssl-root.cnf END
</figure>
</section>
<section anchor="Intermediateconfig" title="OpenSSL Intermediate config file">
<t>
	The following is the openssl-intermediate.cnf file contents.
</t>
<t>
	Remove the crlDistributionPoints to drop CRL support and
	authorityInfoAccess to drop OCSP support.
</t>
<figure>
INSERT_TEXT_FROM_FILE configs/openssl-intermediate.cnf END
</figure>
</section>
<section anchor="Intermediate8021ARconfig" title="OpenSSL 802.1AR Intermediate config file">
<t>
	The following is the openssl-8021ARintermediate.cnf file contents.
</t>
<t>
	Remove the crlDistributionPoints to drop CRL support and
	authorityInfoAccess to drop OCSP support.
</t>
<figure>
INSERT_TEXT_FROM_FILE configs/openssl-8021ARintermediate.cnf END
</figure>
</section>
</section>
</back>
</rfc>