idnits 2.17.1 draft-moskowitz-ecdsa-pki-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 30, 2017) is 2402 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 wg TBD R. Moskowitz 3 Internet-Draft Huawei 4 Intended status: Informational H. Birkholz 5 Expires: March 3, 2018 Fraunhofer SIT 6 L. Xia 7 Huawei 8 August 30, 2017 10 Guide for building an ECC pki 11 draft-moskowitz-ecdsa-pki-00 13 Abstract 15 This memo provides a guide for building a PKI (Public Key 16 Infrastructure) using openSSL. All certificates in this guide are 17 ECDSA, P-256, with SHA256 certificates. Along with common End Entity 18 certificates, this guide provides instructions for creating IEEE 19 802.1AR [IEEE.802.1AR_2009] iDevID Secure Device certificates. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on March 3, 2018. 38 Copyright Notice 40 Copyright (c) 2017 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Terms and Definitions . . . . . . . . . . . . . . . . . . . . 3 57 2.1. Requirements Terminology . . . . . . . . . . . . . . . . 3 58 2.2. Notations . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. The Basic PKI feature set . . . . . . . . . . . . . . . . . . 3 61 4. Getting started and the Root level . . . . . . . . . . . . . 4 62 4.1. Setting up the Environment . . . . . . . . . . . . . . . 4 63 4.2. Create the Root Certificate . . . . . . . . . . . . . . . 6 64 5. The Intermediate level . . . . . . . . . . . . . . . . . . . 6 65 5.1. Setting up the Intermediate Certificate Environment . . . 6 66 5.2. Create the Intermediate Certificate . . . . . . . . . . . 7 67 5.3. Create a Server EE Certificate . . . . . . . . . . . . . 9 68 5.4. Create a Client EE Certificate . . . . . . . . . . . . . 9 69 6. The 802.1AR Intermediate level . . . . . . . . . . . . . . . 10 70 6.1. Setting up the 802.1AR Intermediate Certificate 71 Environment . . . . . . . . . . . . . . . . . . . . . . . 10 72 6.2. Create the 802.1AR Intermediate Certificate . . . . . . . 11 73 6.3. Create an 802.1AR iDevID Certificate . . . . . . . . . . 13 74 7. Footnotes . . . . . . . . . . . . . . . . . . . . . . . . . . 14 75 7.1. Certificate Serial Number . . . . . . . . . . . . . . . . 14 76 7.2. subjectAltName support, or lack thereof . . . . . . . . . 15 77 7.3. DER support, or lack thereof . . . . . . . . . . . . . . 15 78 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 79 9. Security Considerations . . . . . . . . . . . . . . . . . . . 16 80 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 81 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 82 11.1. Normative References . . . . . . . . . . . . . . . . . . 17 83 11.2. Informative References . . . . . . . . . . . . . . . . . 17 84 Appendix A. OpenSSL config files . . . . . . . . . . . . . . . . 17 85 A.1. OpenSSL Root config file . . . . . . . . . . . . . . . . 17 86 A.2. OpenSSL Intermediate config file . . . . . . . . . . . . 20 87 A.3. OpenSSL 802.1AR Intermediate config file . . . . . . . . 23 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 90 1. Introduction 92 The IETF has a plethora of security solutions targeted at IoT. Yet 93 all too many IoT products are deployed with no or improperly 94 configured security. In particular resource constrained IoT devices 95 and non-IP IoT networks have not been well served in the IETF. 97 Additionally, more IETF (e.g. DOTS, NETCONF) efforts are requiring 98 secure identities, but are vague on the nature of these identities 99 other than to recommend use of X.509 digital certificates and perhaps 100 TLS. 102 This effort provides the steps, using the openSSL application, to 103 create such a PKI of ECDSA certificates. The goal is that any 104 developer or tester can follow these steps, create the basic objects 105 needed and establish the validity of the standard/program design. 106 This guide can even be used to create a production PKi, though 107 additional steps need to be taken. This could be very useful to a 108 small vendor needing to include 802.1AR iDevIDs in their product. 110 This guide was tested with openSSL 1.1.0f on Fedora 26 and creates 111 PEM-based certificates. DER based certificates fails (see 112 Section 7.3). Also, at this time, CRL and OCSP support is for future 113 work. 115 2. Terms and Definitions 117 2.1. Requirements Terminology 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 121 document are to be interpreted as described in RFC 2119 [RFC2119]. 123 2.2. Notations 125 This section will contain notations 127 2.3. Definitions 129 TBD 131 3. The Basic PKI feature set 133 A basic pki has two levels of hierarchy: Root and Intermediate. The 134 Root level has the greatest risk, and is the least used. It only 135 signs the Intermediate level signing certificate. As such, once the 136 Root level is created and signs the Intermediate level certificate it 137 can be locked up. In fact, the Root level could exist completely on 138 a mSD boot card for an ARM small computer like a RaspberryPi. A copy 139 of this card came be made and securely stored in a different 140 location. 142 The Root level contains the Root certificate private key, a database 143 of all signed certificates, and the public certificate. It can also 144 contain the Intermediate level public certificate and a Root level 145 CRL. 147 The Intermediate level contains the Intermediate certificate private 148 key, the public certificate, a database of all signed certificates, 149 the certificate trust chain, and Intermediate level CRL. It can also 150 contain the End Entity public certificates. The private key file 151 needs to be keep securely. For example as with the Root level, a mSD 152 image for an ARM computer could contain the complete Intermediate 153 level. This image is kept offline. The End Entity CSR is copied to 154 it, signed, and then the signed certificate and updated database are 155 moved to the public image that lacks the private key. 157 For a simple test pki, all files can be kept on a single system that 158 is managed by the tester. 160 End Entities create a key pair and a Certificate Signing Request 161 (CSR). The private key is stored securely. The CSR is delivered to 162 the Intermediate level which uses the CSR to create the End Entity 163 certificate. This certificate, along with the trust chain back to 164 the root, is then returned to the End Entity. 166 There is more to a pki, but this suffices for most development and 167 testing needs. 169 4. Getting started and the Root level 171 This guide was developed on a Fedora 26 armv7hl system (Cubieboard2 172 SoC). It should work on most Linux and similar systems. All work 173 was done in a terminal window with extensive "cutting and pasting" 174 from a draft guide into the terminal window. Users of this guide may 175 find different behaviors based on their system. 177 4.1. Setting up the Environment 179 The first step is to create the pki environment. Modify the 180 variables to suit your needs. 182 export dir=/root/ca 183 export cadir=/root/ca 184 export format=pem 185 mkdir $dir 186 cd $dir 187 mkdir certs crl csr newcerts private 188 chmod 700 private 189 touch index.txt 190 touch serial 191 sn=8 193 countryName="/C=US" 194 stateOrProvinceName="/ST=MI" 195 localityName="/L=Oak Park" 196 organizationName="/O=HTT Consulting" 197 #organizationalUnitName="/OU=" 198 organizationalUnitName= 199 commonName="/CN=Root CA" 200 DN=$countryName$stateOrProvinceName$localityName 201 DN=$DN$organizationName$organizationalUnitName$commonName 202 echo $DN 203 export subjectAltName=email:postmaster@htt-consult.com 205 Where: 207 dir 208 Directory for certificate files 210 cadir 211 Directory for Root certificate files 213 Format 214 File encoding: PEM or DER 215 At this time only PEM works 217 sn 218 Serial Number length in bytes 219 For a public CA the range is 8 to 19 221 The Serial Number length for a public pki ranges from 8 to 19 bytes. 222 The use of 19 rather than 20 is to accommodate the hex representation 223 of the Serial Number. If it has a one in the high order bit, DER 224 encoding rules will place a 0x00 in front. 226 The DN and SAN fields are examples. Change them to appropriate 227 values. If you leave one blank, it will be left out of the 228 Certificate. "OU" above is an example of an empty DN object. 230 Create the file, $dir/openssl-root.cnf from the contents in 231 Appendix A.1. 233 4.2. Create the Root Certificate 235 Next are the openssl commands to create the Root certificate keypair, 236 and the Root certificate. Included are commands to view the file 237 contents. 239 # Create passworded keypair file 241 openssl genpkey -aes256 -algorithm ec\ 242 -pkeyopt ec_paramgen_curve:prime256v1\ 243 -outform $format -pkeyopt ec_param_enc:named_curve\ 244 -out $dir/private/ca.key.$format 245 chmod 400 $dir/private/ca.key.$format 246 openssl pkey -inform $format -in private/ca.key.$format -text -noout 248 # Create Self-signed Root Certificate file 249 # 7300 days = 20 years; Intermediate CA is 10 years. 251 openssl req -config $dir/openssl-root.cnf\ 252 -set_serial 0x$(openssl rand -hex $sn)\ 253 -keyform $format -outform $format\ 254 -key $dir/private/ca.key.$format -subj "$DN"\ 255 -new -x509 -days 7300 -sha256 -extensions v3_ca\ 256 -out $dir/certs/ca.cert.$format 258 # 260 openssl x509 -inform $format -in $dir/certs/ca.cert.$format\ 261 -text -noout 262 openssl x509 -purpose -inform $format\ 263 -in $dir/certs/ca.cert.$format -inform $format 265 5. The Intermediate level 267 5.1. Setting up the Intermediate Certificate Environment 269 The next part is to create the Intermediate pki environment. Modify 270 the variables to suit your needs. 272 export dir=$cadir/intermediate 273 mkdir $dir 274 cd $dir 275 mkdir certs crl csr newcerts private 276 chmod 700 private 277 touch index.txt 278 sn=8 # hex 8 is minimum, 19 is maximum 279 echo 1000 > $dir/crlnumber 281 # cd $dir 282 commonName="/CN=Signing CA" 283 DN=$countryName$stateOrProvinceName$localityName$organizationName 284 DN=$DN$organizationalUnitName$commonName 285 echo $DN 287 Create the file, $dir/openssl-intermediate.cnf from the contents in 288 Appendix A.2. 290 5.2. Create the Intermediate Certificate 292 Here are the openssl commands to create the Intermediate certificate 293 keypair, Intermediate certificate signed request (CSR), and the 294 Intermediate certificate. Included are commands to view the file 295 contents. 297 # Create passworded keypair file 299 openssl genpkey -aes256 -algorithm ec\ 300 -pkeyopt ec_paramgen_curve:prime256v1 \ 301 -outform $format -pkeyopt ec_param_enc:named_curve\ 302 -out $dir/private/intermediate.key.$format 303 chmod 400 $dir/private/intermediate.key.$format 304 openssl pkey -inform $format\ 305 -in $dir/private/intermediate.key.$format -text -noout 307 # Create the CSR 309 openssl req -config $cadir/openssl-root.cnf\ 310 -key $dir/private/intermediate.key.$format \ 311 -keyform $format -outform $format -subj "$DN" -new -sha256\ 312 -out $dir/csr/intermediate.csr.$format 313 openssl req -text -noout -verify -inform $format\ 314 -in $dir/csr/intermediate.csr.$format 316 # Create Intermediate Certificate file 318 openssl rand -hex $sn > $dir/serial # hex 8 is minimum, 19 is maximum 319 # Note 'openssl ca' does not support DER format 320 openssl ca -config $cadir/openssl-root.cnf -days 3650\ 321 -extensions v3_intermediate_ca -notext -md sha256 \ 322 -in $dir/csr/intermediate.csr.$format\ 323 -out $dir/certs/intermediate.cert.pem 325 chmod 444 $dir/certs/intermediate.cert.$format 327 openssl verify -CAfile $cadir/certs/ca.cert.$format\ 328 $dir/certs/intermediate.cert.$format 330 openssl x509 -noout -text -in $dir/certs/intermediate.cert.$format 332 # Create the certificate chain file 334 cat $dir/certs/intermediate.cert.$format\ 335 $cadir/certs/ca.cert.$format > $dir/certs/ca-chain.cert.$format 336 chmod 444 $dir/certs/ca-chain.cert.$format 338 5.3. Create a Server EE Certificate 340 Here are the openssl commands to create a Server End Entity 341 certificate keypair, Server certificate signed request (CSR), and the 342 Server certificate. Included are commands to view the file contents. 344 commonName= 345 DN=$countryName$stateOrProvinceName$localityName 346 DN=$DN$organizationName$organizationalUnitName$commonName 347 echo $DN 348 serverfqdn=www.example.com 349 emailaddr=postmaster@htt-consult.com 350 export subjectAltName="DNS:$serverfqdn, email:$emailaddr" 351 echo $subjectAltName 352 openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:prime256v1\ 353 -pkeyopt ec_param_enc:named_curve\ 354 -out $dir/private/$serverfqdn.key.$format 355 chmod 400 $dir/private/$serverfqdn.$format 356 openssl pkey -in $dir/private/$serverfqdn.key.$format -text -noout 357 openssl req -config $dir/openssl-intermediate.cnf\ 358 -key $dir/private/$serverfqdn.key.$format \ 359 -subj "$DN" -new -sha256 -out $dir/csr/$serverfqdn.csr.$format 361 openssl req -text -noout -verify -in $dir/csr/$serverfqdn.csr.$format 363 openssl rand -hex $sn > $dir/serial # hex 8 is minimum, 19 is maximum 364 # Note 'openssl ca' does not support DER format 365 openssl ca -config $dir/openssl-intermediate.cnf -days 375\ 366 -extensions server_cert -notext -md sha256 \ 367 -in $dir/csr/$serverfqdn.csr.$format\ 368 -out $dir/certs/$serverfqdn.cert.$format 369 chmod 444 $dir/certs/$serverfqdn.cert.$format 371 openssl verify -CAfile $dir/certs/ca-chain.cert.$format\ 372 $dir/certs/$serverfqdn.cert.$format 373 openssl x509 -noout -text -in $dir/certs/$serverfqdn.cert.$format 375 5.4. Create a Client EE Certificate 377 Here are the openssl commands to create a Client End Entity 378 certificate keypair, Client certificate signed request (CSR), and the 379 Client certificate. Included are commands to view the file contents. 381 commonName= 382 UserID="/UID=rgm" 383 DN=$countryName$stateOrProvinceName$localityName 384 DN=$DN$organizationName$organizationalUnitName$commonName$UserID 385 echo $DN 386 clientemail=rgm@example.com 387 export subjectAltName="email:$clientemail" 388 echo $subjectAltName 389 openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:prime256v1\ 390 -pkeyopt ec_param_enc:named_curve\ 391 -out $dir/private/$clientemail.key.$format 392 chmod 400 $dir/private/$clientemail.$format 393 openssl pkey -in $dir/private/$clientemail.key.$format -text -noout 394 openssl req -config $dir/openssl-intermediate.cnf\ 395 -key $dir/private/$clientemail.key.$format \ 396 -subj "$DN" -new -sha256 -out $dir/csr/$clientemail.csr.$format 398 openssl req -text -noout -verify\ 399 -in $dir/csr/$clientemail.csr.$format 401 openssl rand -hex $sn > $dir/serial # hex 8 is minimum, 19 is maximum 402 # Note 'openssl ca' does not support DER format 403 openssl ca -config $dir/openssl-intermediate.cnf -days 375\ 404 -extensions usr_cert -notext -md sha256 \ 405 -in $dir/csr/$clientemail.csr.$format\ 406 -out $dir/certs/$clientemail.cert.$format 407 chmod 444 $dir/certs/$clientemail.cert.$format 409 openssl verify -CAfile $dir/certs/ca-chain.cert.$format\ 410 $dir/certs/$clientemail.cert.$format 411 openssl x509 -noout -text -in $dir/certs/$clientemail.cert.$format 413 6. The 802.1AR Intermediate level 415 6.1. Setting up the 802.1AR Intermediate Certificate Environment 417 The next part is to create the 802.1AR Intermediate pki environment. 418 This is very similar to the Intermediate pki environment. Modify the 419 variables to suit your needs. 421 export dir=$cadir/8021ARintermediate 422 mkdir $dir 423 cd $dir 424 mkdir certs crl csr newcerts private 425 chmod 700 private 426 touch index.txt 427 sn=8 # hex 8 is minimum, 19 is maximum 428 echo 1000 > $dir/crlnumber 430 # cd $dir 431 countryName="/C=US" 432 stateOrProvinceName="/ST=MI" 433 localityName="/L=Oak Park" 434 organizationName="/O=HTT Consulting" 435 organizationalUnitName="/OU=Devices" 436 #organizationalUnitName= 437 commonName="/CN=802.1AR CA" 438 DN=$countryName$stateOrProvinceName$localityName$organizationName 439 DN=$DN$organizationalUnitName$commonName 440 echo $DN 441 export subjectAltName=email:postmaster@htt-consult.com 442 echo $subjectAltName 444 Create the file, $dir/openssl-8021AR.cnf from the contents in 445 Appendix A.3. 447 6.2. Create the 802.1AR Intermediate Certificate 449 Here are the openssl commands to create the 802.1AR Intermediate 450 certificate keypair, 802.1AR Intermediate certificate signed request 451 (CSR), and the 802.1AR Intermediate certificate. Included are 452 commands to view the file contents. 454 # Create passworded keypair file 456 openssl genpkey -aes256 -algorithm ec\ 457 -pkeyopt ec_paramgen_curve:prime256v1 \ 458 -outform $format -pkeyopt ec_param_enc:named_curve\ 459 -out $dir/private/8021ARintermediate.key.$format 460 chmod 400 $dir/private/8021ARintermediate.key.$format 461 openssl pkey -inform $format\ 462 -in $dir/private/8021ARintermediate.key.$format -text -noout 464 # Create the CSR 466 openssl req -config $cadir/openssl-root.cnf\ 467 -key $dir/private/8021ARintermediate.key.$format \ 468 -keyform $format -outform $format -subj "$DN" -new -sha256\ 469 -out $dir/csr/8021ARintermediate.csr.$format 470 openssl req -text -noout -verify -inform $format\ 471 -in $dir/csr/8021ARintermediate.csr.$format 473 # Create 802.1AR Intermediate Certificate file 474 # The following does NOT work for DER 476 openssl rand -hex $sn > $dir/serial # hex 8 is minimum, 19 is maximum 477 # Note 'openssl ca' does not support DER format 478 openssl ca -config $cadir/openssl-root.cnf -days 3650\ 479 -extensions v3_intermediate_ca -notext -md sha256\ 480 -in $dir/csr/8021ARintermediate.csr.$format\ 481 -out $dir/certs/8021ARintermediate.cert.pem 483 chmod 444 $dir/certs/8021ARintermediate.cert.$format 485 openssl verify -CAfile $cadir/certs/ca.cert.$format\ 486 $dir/certs/8021ARintermediate.cert.$format 488 openssl x509 -noout -text\ 489 -in $dir/certs/8021ARintermediate.cert.$format 491 # Create the certificate chain file 493 cat $dir/certs/8021ARintermediate.cert.$format\ 494 $cadir/certs/ca.cert.$format > $dir/certs/ca-chain.cert.$format 495 chmod 444 $dir/certs/ca-chain.cert.$format 497 6.3. Create an 802.1AR iDevID Certificate 499 Here are the openssl commands to create a 802.1AR iDevID certificate 500 keypair, iDevID certificate signed request (CSR), and the iDevID 501 certificate. Included are commands to view the file contents. 503 DevID=Wt1234 504 countryName= 505 stateOrProvinceName= 506 localityName= 507 organizationName="/O=HTT Consulting" 508 organizationalUnitName="/OU=Devices" 509 commonName= 510 serialNumber="/serialNumber=$DevID" 511 DN=$countryName$stateOrProvinceName$localityName 512 DN=$DN$organizationName$organizationalUnitName$commonName 513 DN=$DN$serialNumber 514 echo $DN 516 # hwType is OID for HTT Consulting, devices, sensor widgets 517 export hwType=1.3.6.1.4.1.6715.10.1 518 export hwSerialNum=01020304 # Some hex 519 echo $hwType - $hwSerialNum 521 openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:prime256v1\ 522 -pkeyopt ec_param_enc:named_curve\ 523 -out $dir/private/$DevID.key.$format 524 chmod 400 $dir/private/$DevID.$format 525 openssl pkey -in $dir/private/$DevID.key.$format -text -noout 526 openssl req -config $dir/openssl-8021AR.cnf\ 527 -key $dir/private/$DevID.key.$format \ 528 -subj "$DN" -new -sha256 -out $dir/csr/$DevID.csr.$format 530 openssl req -text -noout -verify\ 531 -in $dir/csr/$DevID.csr.$format 532 openssl asn1parse -i -in $dir/csr/$DevID.csr.pem 533 # offset of start of hardwareModuleName and use that in place of 189 534 openssl asn1parse -i -strparse 189 -in $dir/csr/$DevID.csr.pem 536 openssl rand -hex $sn > $dir/serial # hex 8 is minimum, 19 is maximum 537 # Note 'openssl ca' does not support DER format 538 openssl ca -config $dir/openssl-8021AR.cnf -days 375\ 539 -extensions 8021ar_idevid -notext -md sha256 \ 540 -in $dir/csr/$DevID.csr.$format\ 541 -out $dir/certs/$DevID.cert.$format 542 chmod 444 $dir/certs/$DevID.cert.$format 543 openssl verify -CAfile $dir/certs/ca-chain.cert.$format\ 544 $dir/certs/$DevID.cert.$format 545 openssl x509 -noout -text -in $dir/certs/$DevID.cert.$format 546 openssl asn1parse -i -in $dir/certs/$DevID.cert.pem 548 # offset of start of hardwareModuleName and use that in place of 493 549 openssl asn1parse -i -strparse 493 -in $dir/certs/$DevID.cert.pem 551 7. Footnotes 553 Creating this document was a real education in the state of openSSL, 554 X.509 certificate guidance, and just general level of certificate 555 awareness. Here are a few short notes. 557 7.1. Certificate Serial Number 559 The certificate serial number's role is to provide yet another way to 560 maintain uniqueness of certificates within a pki as well as a way to 561 index them in a data store. It has taken on other roles, most 562 notably as a defense. 564 The CABForum guideline for a public CA is for the serial number to be 565 a random number at least 8 octets long and no longer than 20 bytes. 566 By default, openssl makes self-signed certificates with 8 octet 567 serial numbers. This guide uses openssl's RAND function to generate 568 the random value and pipe it into the -set_serial option. This 569 number MAY have the first bit as a ONE; the DER encoding rules 570 prepend such numbers with 0x00. Thus the limit of '19' for the 571 variable 'ns'. 573 A private CA need not follow the CABForum rules and can use anything 574 number for the serial number. For example, the root CA (which has no 575 security risks mitigated by using a random value) could use '1' as 576 its serial number. Intermediate and End Entity certificate serial 577 numbers can also be of any value if a strong hash, like SHA256 used 578 here. A value of 4 for ns would provide a sufficient population so 579 that a CA of 10,000 EE certificates will have only a 1.2% probability 580 of a collision. For only 1,000 certificates the probability drops to 581 0.012%. 583 The following was proposed on the openssl-user list as an alternative 584 to using the RAND function: 586 Keep k bits (k/8 octets) long serial numbers for all your 587 certificates, chose a block cipher operating on blocks of k bits, and 588 operate this block cipher in CTR mode, with a proper secret key and 589 secret starting counter. That way, no collision detection is 590 necessary, you'll be able to generate 2^(k/2) unique k bits longs 591 serial numbers (in fact, you can generate 2^k unique serial numbers, 592 but after 2^(k/2) you lose some security guarantees). 594 With 3DES, k=64, and with AES, k=128. 596 7.2. subjectAltName support, or lack thereof 598 There is no direct openssl command line option to provide a 599 subjectAltName for a certificate. This is a serious limitation. Per 600 RFC 2818 [RFC2818] SAN is the object for providing email addresses 601 and DNS addresses (FQDN), yet the common practice has been to use the 602 commonName object within the distinguishedName object. How much of 603 this is due to the difficulty in creating certificates with a SAN? 605 Thus the only way to provide a SAN is through the config file. And 606 there are two approaches. This document uses an environment variable 607 to provide the SAN value into the config file. Another approach is 608 to use piping as in: 610 openssl req -new -sha256 -key domain.key\ 611 -subj "/C=US/ST=CA/O=Acme, Inc./CN=foo.com" -reqexts SAN\ 612 -config <(cat /etc/ssl/openssl.cnf\ 613 <(printf "[SAN]\nsubjectAltName=DNS:foo.com,DNS:www.foo.com"))\ 614 -out domain.csr 616 7.3. DER support, or lack thereof 618 The long, hard-fought battle with openssl to create a full DER pki 619 failed. The is no facility to create a DER certificate from a DER 620 CSR. It just is not there in the 'openssl ca' command. Even the 621 'openssl x509 -req' command cannot do this for a simple certificate. 623 Further, there is no 'hack' for making a certificate chain as there 624 is with PEM. With PEM a simple concatenation of the certificates 625 create a usable certificate chain. For DER, some recommend using 626 PKCS#7 [RFC2315], where others point out that this format is poorly 627 support 'in the field', whereas PKCS#12 [RFC7292] works for them. 629 Finally, openssl does supports converting a PEM certificate to DER: 631 openssl x509 -outform der -in certificate.pem -out certificate.der 632 This should also work for the keypair. However, in a highly 633 constrained device it may make more sense to just store the raw 634 keypair in the device's very limited secure storage. 636 8. IANA Considerations 638 TBD. May be nothing for IANA. 640 9. Security Considerations 642 Creating certificates takes a lot of random numbers. A good source 643 of random numbers is critical. Studies have found excessive amount 644 of certificates, all with the same keys due to bad randomness on the 645 generating systems. The amount of entropy available for these random 646 numbers can be tested. On Fedora/Centos use: 648 cat /proc/sys/kernel/random/entropy_avail 650 If the value is low (below 1000) check your system's randomness 651 source. Is rng-tools installed? Consider adding an entropy 652 collection service like haveged from issihosts.com/haveged. 654 During the certificate creation, particularly during keypair 655 generation, the files are vulnerable to theft. This can be mitigate 656 using umask. Before using openssl, set umask: 658 restore_mask=$(umask -p) 659 umask 077 661 Afterwards, restore it with: 663 $restore_mask 665 10. Acknowledgments 667 This work was jump started by the excellent RSA pki guide by Jamie 668 Nguyen. The openssl-user mailing list, with its many supportive 669 experts; in particular: Rich Salz, Jakob Bolm, Viktor Dukhovni, and 670 Erwann Abalea, was of immense help as was the openssl man pages 671 website. 673 Finally, "Professor Google" was always ready to point to answers to 674 questions like: "openssl subjectAltName on the command line". And 675 the Professor, it seems, never tires of answering even trivial 676 questions. 678 11. References 680 11.1. Normative References 682 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 683 Requirement Levels", BCP 14, RFC 2119, 684 DOI 10.17487/RFC2119, March 1997, . 687 11.2. Informative References 689 [IEEE.802.1AR_2009] 690 IEEE, "IEEE Standard for Local and metropolitan area 691 networks - Secure Device Identity", IEEE 802.1AR-2009, 692 DOI 10.1109/ieeestd.2009.5367679, December 2009, 693 . 696 [RFC2315] Kaliski, B., "PKCS #7: Cryptographic Message Syntax 697 Version 1.5", RFC 2315, DOI 10.17487/RFC2315, March 1998, 698 . 700 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 701 DOI 10.17487/RFC2818, May 2000, . 704 [RFC7292] Moriarty, K., Ed., Nystrom, M., Parkinson, S., Rusch, A., 705 and M. Scott, "PKCS #12: Personal Information Exchange 706 Syntax v1.1", RFC 7292, DOI 10.17487/RFC7292, July 2014, 707 . 709 Appendix A. OpenSSL config files 711 A.1. OpenSSL Root config file 713 The following is the openssl-root.cnf file contents 715 # OpenSSL root CA configuration file. 716 # Copy to `$dir/openssl.cnf`. 718 [ ca ] 719 # `man ca` 720 default_ca = CA_default 722 [ CA_default ] 723 # Directory and file locations. 724 dir = $ENV::dir 725 cadir = $ENV::cadir 726 format = $ENV::format 728 certs = $dir/certs 729 crl_dir = $dir/crl 730 new_certs_dir = $dir/newcerts 731 database = $dir/index.txt 732 serial = $dir/serial 733 RANDFILE = $dir/private/.rand 735 # The root key and root certificate. 736 private_key = $cadir/private/ca.key.$format 737 certificate = $cadir/certs/ca.cert.$format 739 # For certificate revocation lists. 740 crlnumber = $dir/crlnumber 741 crl = $dir/crl/ca.crl.pem 742 crl_extensions = crl_ext 743 default_crl_days = 30 745 # SHA-1 is deprecated, so use SHA-2 instead. 746 default_md = sha256 748 name_opt = ca_default 749 cert_opt = ca_default 750 default_days = 375 751 preserve = no 752 policy = policy_strict 753 copy_extensions = copy 755 [ policy_strict ] 756 # The root CA should only sign intermediate certificates that match. 757 # See the POLICY FORMAT section of `man ca`. 758 countryName = match 759 stateOrProvinceName = match 760 organizationName = match 761 organizationalUnitName = optional 762 commonName = optional 764 [ policy_loose ] 765 # Allow the intermediate CA to sign a more 766 # diverse range of certificates. 767 # See the POLICY FORMAT section of the `ca` man page. 768 countryName = optional 769 stateOrProvinceName = optional 770 localityName = optional 771 organizationName = optional 772 organizationalUnitName = optional 773 commonName = optional 775 [ req ] 776 # Options for the `req` tool (`man req`). 777 default_bits = 2048 778 distinguished_name = req_distinguished_name 779 string_mask = utf8only 780 req_extensions = req_ext 782 # SHA-1 is deprecated, so use SHA-2 instead. 783 default_md = sha256 785 # Extension to add when the -x509 option is used. 786 x509_extensions = v3_ca 788 [ req_distinguished_name ] 789 # See . 790 countryName = Country Name (2 letter code) 791 stateOrProvinceName = State or Province Name 792 localityName = Locality Name 793 0.organizationName = Organization Name 794 organizationalUnitName = Organizational Unit Name 795 commonName = Common Name 797 # Optionally, specify some defaults. 798 # countryName_default = US 799 # stateOrProvinceName_default = MI 800 # localityName_default = Oak Park 801 # 0.organizationName_default = HTT Consulting 802 # organizationalUnitName_default = 804 [ req_ext ] 805 subjectAltName = $ENV::subjectAltName 807 [ v3_ca ] 808 # Extensions for a typical CA (`man x509v3_config`). 809 subjectKeyIdentifier = hash 810 authorityKeyIdentifier = keyid:always,issuer 811 basicConstraints = critical, CA:true 812 # keyUsage = critical, digitalSignature, cRLSign, keyCertSign 813 keyUsage = critical, cRLSign, keyCertSign 814 subjectAltName = $ENV::subjectAltName 816 [ v3_intermediate_ca ] 817 # Extensions for a typical intermediate CA (`man x509v3_config`). 818 subjectKeyIdentifier = hash 819 authorityKeyIdentifier = keyid:always,issuer 820 basicConstraints = critical, CA:true, pathlen:0 821 # keyUsage = critical, digitalSignature, cRLSign, keyCertSign 822 keyUsage = critical, cRLSign, keyCertSign 824 [ crl_ext ] 825 # Extension for CRLs (`man x509v3_config`). 826 authorityKeyIdentifier=keyid:always 828 [ ocsp ] 829 # Extension for OCSP signing certificates (`man ocsp`). 830 basicConstraints = CA:FALSE 831 subjectKeyIdentifier = hash 832 authorityKeyIdentifier = keyid,issuer 833 keyUsage = critical, digitalSignature 834 extendedKeyUsage = critical, OCSPSigning 836 A.2. OpenSSL Intermediate config file 838 The following is the openssl-intermediate.cnf file contents 840 # OpenSSL intermediate CA configuration file. 841 # Copy to `$dir/intermediate/openssl.cnf`. 843 [ ca ] 844 # `man ca` 845 default_ca = CA_default 847 [ CA_default ] 848 # Directory and file locations. 849 dir = $ENV::dir 850 cadir = $ENV::cadir 851 format = $ENV::format 853 certs = $dir/certs 854 crl_dir = $dir/crl 855 new_certs_dir = $dir/newcerts 856 database = $dir/index.txt 857 serial = $dir/serial 858 RANDFILE = $dir/private/.rand 860 # The Intermediate key and Intermediate certificate. 861 private_key = $dir/private/intermediate.key.$format 862 certificate = $dir/certs/intermediate.cert.$format 864 # For certificate revocation lists. 865 crlnumber = $dir/crlnumber 866 crl = $dir/crl/ca.crl.pem 867 crl_extensions = crl_ext 868 default_crl_days = 30 870 # SHA-1 is deprecated, so use SHA-2 instead. 871 default_md = sha256 873 name_opt = ca_default 874 cert_opt = ca_default 875 default_days = 375 876 preserve = no 877 policy = policy_loose 878 copy_extensions = copy 880 [ policy_strict ] 881 # The root CA should only sign intermediate certificates that match. 882 # See the POLICY FORMAT section of `man ca`. 883 countryName = match 884 stateOrProvinceName = match 885 organizationName = match 886 organizationalUnitName = optional 887 commonName = optional 889 [ policy_loose ] 890 # Allow the intermediate CA to sign a more 891 # diverse range of certificates. 892 # See the POLICY FORMAT section of the `ca` man page. 893 countryName = optional 894 stateOrProvinceName = optional 895 localityName = optional 896 organizationName = optional 897 organizationalUnitName = optional 898 commonName = optional 899 UID = optional 901 [ req ] 902 # Options for the `req` tool (`man req`). 903 default_bits = 2048 904 distinguished_name = req_distinguished_name 905 string_mask = utf8only 906 req_extensions = req_ext 908 # SHA-1 is deprecated, so use SHA-2 instead. 909 default_md = sha256 911 # Extension to add when the -x509 option is used. 912 x509_extensions = v3_ca 914 [ req_distinguished_name ] 915 # See . 916 countryName = Country Name (2 letter code) 917 stateOrProvinceName = State or Province Name 918 localityName = Locality Name 919 0.organizationName = Organization Name 920 organizationalUnitName = Organizational Unit Name 921 commonName = Common Name 922 UID = User ID 924 # Optionally, specify some defaults. 925 # countryName_default = US 926 # stateOrProvinceName_default = MI 927 # localityName_default = Oak Park 928 # 0.organizationName_default = HTT Consulting 929 # organizationalUnitName_default = 931 [ req_ext ] 932 subjectAltName = $ENV::subjectAltName 934 [ v3_ca ] 935 # Extensions for a typical CA (`man x509v3_config`). 936 subjectKeyIdentifier = hash 937 authorityKeyIdentifier = keyid:always,issuer 938 basicConstraints = critical, CA:true 939 # keyUsage = critical, digitalSignature, cRLSign, keyCertSign 940 keyUsage = critical, cRLSign, keyCertSign 942 [ v3_intermediate_ca ] 943 # Extensions for a typical intermediate CA (`man x509v3_config`). 944 subjectKeyIdentifier = hash 945 authorityKeyIdentifier = keyid:always,issuer 946 basicConstraints = critical, CA:true, pathlen:0 947 # keyUsage = critical, digitalSignature, cRLSign, keyCertSign 948 keyUsage = critical, cRLSign, keyCertSign 950 [ usr_cert ] 951 # Extensions for client certificates (`man x509v3_config`). 952 basicConstraints = CA:FALSE 953 nsCertType = client, email 954 nsComment = "OpenSSL Generated Client Certificate" 955 subjectKeyIdentifier = hash 956 authorityKeyIdentifier = keyid,issuer 957 keyUsage = critical,nonRepudiation,digitalSignature,keyEncipherment 958 extendedKeyUsage = clientAuth, emailProtection 960 [ server_cert ] 961 # Extensions for server certificates (`man x509v3_config`). 962 basicConstraints = CA:FALSE 963 nsCertType = server 964 nsComment = "OpenSSL Generated Server Certificate" 965 subjectKeyIdentifier = hash 966 authorityKeyIdentifier = keyid,issuer:always 967 keyUsage = critical, digitalSignature, keyEncipherment 968 extendedKeyUsage = serverAuth 970 [ crl_ext ] 971 # Extension for CRLs (`man x509v3_config`). 972 authorityKeyIdentifier=keyid:always 974 [ ocsp ] 975 # Extension for OCSP signing certificates (`man ocsp`). 976 basicConstraints = CA:FALSE 977 subjectKeyIdentifier = hash 978 authorityKeyIdentifier = keyid,issuer 979 keyUsage = critical, digitalSignature 980 extendedKeyUsage = critical, OCSPSigning 982 A.3. OpenSSL 802.1AR Intermediate config file 984 The following is the openssl-8021ARintermediate.cnf file contents 986 # OpenSSL 8021ARintermediate CA configuration file. 987 # Copy to `$dir/8021ARintermediate/openssl_8021AR.cnf`. 989 [ ca ] 990 # `man ca` 991 default_ca = CA_default 993 [ CA_default ] 994 # Directory and file locations. 995 # dir = /root/ca/8021ARintermediate 996 dir = $ENV::dir 997 cadir = $ENV::cadir 998 format = $ENV::format 1000 certs = $dir/certs 1001 crl_dir = $dir/crl 1002 new_certs_dir = $dir/newcerts 1003 database = $dir/index.txt 1004 serial = $dir/serial 1005 RANDFILE = $dir/private/.rand 1007 # The root key and root certificate. 1008 private_key = $dir/private/8021ARintermediate.key.$format 1009 certificate = $dir/certs/8021ARintermediate.cert.$format 1011 # For certificate revocation lists. 1012 crlnumber = $dir/crlnumber 1013 crl = $dir/crl/ca.crl.pem 1014 crl_extensions = crl_ext 1015 default_crl_days = 30 1017 # SHA-1 is deprecated, so use SHA-2 instead. 1018 default_md = sha256 1020 name_opt = ca_default 1021 cert_opt = ca_default 1022 default_enddate = 99991231235959Z # per IEEE 802.1AR 1023 preserve = no 1024 policy = policy_loose 1025 copy_extensions = copy 1027 [ policy_strict ] 1028 # The root CA should only sign 8021ARintermediate 1029 # certificates that match. 1030 # See the POLICY FORMAT section of `man ca`. 1031 countryName = match 1032 stateOrProvinceName = match 1033 organizationName = match 1034 organizationalUnitName = optional 1035 commonName = optional 1037 [ policy_loose ] 1038 # Allow the 8021ARintermediate CA to sign 1039 # a more diverse range of certificates. 1040 # See the POLICY FORMAT section of the `ca` man page. 1041 countryName = optional 1042 stateOrProvinceName = optional 1043 localityName = optional 1044 organizationName = optional 1045 organizationalUnitName = optional 1046 commonName = optional 1047 serialNumber = optional 1049 [ req ] 1050 # Options for the `req` tool (`man req`). 1051 default_bits = 2048 1052 distinguished_name = req_distinguished_name 1053 string_mask = utf8only 1054 req_extensions = req_ext 1056 # SHA-1 is deprecated, so use SHA-2 instead. 1058 default_md = sha256 1060 # Extension to add when the -x509 option is used. 1061 x509_extensions = v3_ca 1063 [ req_distinguished_name ] 1064 # See . 1065 countryName = Country Name (2 letter code) 1066 stateOrProvinceName = State or Province Name 1067 localityName = Locality Name 1068 0.organizationName = Organization Name 1069 organizationalUnitName = Organizational Unit Name 1070 commonName = Common Name 1071 serialNumber = Device Serial Number 1073 # Optionally, specify some defaults. 1074 0.organizationName_default = HTT Consulting 1075 organizationalUnitName_default = Devices 1077 [ req_ext ] 1078 subjectAltName = otherName:1.3.6.1.5.5.7.8.4;SEQ:hmodname 1080 [ hmodname ] 1081 hwType = OID:$ENV::hwType 1082 hwSerialNum = FORMAT:HEX,OCT:$ENV::hwSerialNum 1084 [ v3_ca ] 1085 # Extensions for a typical CA (`man x509v3_config`). 1086 subjectKeyIdentifier = hash 1087 authorityKeyIdentifier = keyid:always,issuer 1088 basicConstraints = critical, CA:true 1089 keyUsage = critical, digitalSignature, cRLSign, keyCertSign 1091 [ v3_8021ARintermediate_ca ] 1092 # Extensions for a typical 1093 # 8021ARintermediate CA (`man x509v3_config`). 1094 subjectKeyIdentifier = hash 1095 authorityKeyIdentifier = keyid:always,issuer 1096 basicConstraints = critical, CA:true, pathlen:0 1097 # keyUsage = critical, digitalSignature, cRLSign, keyCertSign 1098 keyUsage = critical, cRLSign, keyCertSign 1100 [ 8021ar_idevid ] 1101 # Extensions for IEEE 802.1AR iDevID 1102 # certificates (`man x509v3_config`). 1103 basicConstraints = CA:FALSE 1104 authorityKeyIdentifier = keyid,issuer:always 1105 keyUsage = critical, digitalSignature, keyEncipherment 1107 [ crl_ext ] 1108 # Extension for CRLs (`man x509v3_config`). 1109 authorityKeyIdentifier=keyid:always 1111 [ ocsp ] 1112 # Extension for OCSP signing certificates (`man ocsp`). 1113 basicConstraints = CA:FALSE 1114 subjectKeyIdentifier = hash 1115 authorityKeyIdentifier = keyid,issuer 1116 keyUsage = critical, digitalSignature 1117 extendedKeyUsage = critical, OCSPSigning 1119 Authors' Addresses 1121 Robert Moskowitz 1122 Huawei 1123 Oak Park, MI 48237 1125 Email: rgm@labs.htt-consult.com 1127 Henk Birkholz 1128 Fraunhofer SIT 1129 Rheinstrasse 75 1130 Darmstadt 64295 1131 Germany 1133 Email: henk.birkholz@sit.fraunhofer.de 1135 Liang Xia 1136 Huawei 1137 No. 101, Software Avenue, Yuhuatai District 1138 Nanjing 1139 China 1141 Email: Frank.xialiang@huawei.com