signing-documentation/README.md

# Class 3 re-signing procedure 2022

The CAcert class3 re-signing in 2021 produced a subordinate CA certificate with at least two known issues:

- The CA certificate has a CA issuer URL that points to itself instead of to the Root CA certificate, this makes at
  least Icinga's `check_ssl_cert` monitoring plugin fail, if a endpoint certificate issued by the 2021 class3
  certificate is checked
- The class 3 subordinate CA certificate does not contain all expected extended key usages, some providers
  (i.e. Google) do not accept the certificate for verifying document or email signatures

The re-signing planned for 2022 is just an intermediate step. We are aware that our current certificate hierarchy is
not state of the art, and we need to do a properly planned re-creation. There is a
[work-in-progress design document](https://nextcloud.cacert.org/s/sZ7NmKHNCJ3GbdF) in the internal Nextcloud instance.

## Requirements for the new class 3 certificate

The class 3 certificate must contain the following fields:

- [Version](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.1):
  v3
- [Serial Number](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.2):
  determined by signing procedure (ascending integer currently)
- [Signature](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.3):
  `sha512WithRSAEncryption` OID [1.2.840.113549.1.1.13](https://www.rfc-editor.org/rfc/rfc5754.html#section-3.2)
- [Issuer](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.4):

  `emailAddress=support@cacert.org,CN=CA Cert Signing Authority,OU=http://www.cacert.org,O=Root CA`
  (Subject of CAcert Root CA certificate aka class1, applied by signing procedure)

- [Validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5):
  include validity duration with a "do not use after" field value before the "do not use after" field value of the root
  certificate and a validity of 5 years (use the smaller/earlier expiry value)

  The Root CA certificate has a validity of

      Validity
        Not Before: Mar 30 12:29:49 2003 GMT
        Not After : Mar 29 12:29:49 2033 GMT

  The class 3 certificate should therefore use `Not Before` = issuing date, `Not After` = issuing date + 5 years

  The timestamps must be encoded as UTCTime (according to
  [RFC-5280 Section 5.1.2.5.1](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5.1))

- [Subject](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.6):

  `CN=CAcert Class 3 Root,OU=http://www.CAcert.org,O=CAcert Inc.`

  using the same encoding (PrintableString) as the current 2021 class 3 CA certificate for all RDNs 

- [SubjectPublicKeyInfo](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.7):
  use the existing [RSA](https://www.rfc-editor.org/rfc/rfc3279#section-2.3.1) key pair

      Public-Key: (4096 bit)
      Modulus:
          00:ab:49:35:11:48:7c:d2:26:7e:53:94:cf:43:a9:
          dd:28:d7:42:2a:8b:f3:87:78:19:58:7c:0f:9e:da:
          89:7d:e1:fb:eb:72:90:0d:74:a1:96:64:ab:9f:a0:
          24:99:73:da:e2:55:76:c7:17:7b:f5:04:ac:46:b8:
          c3:be:7f:64:8d:10:6c:24:f3:61:9c:c0:f2:90:fa:
          51:e6:f5:69:01:63:c3:0f:56:e2:4a:42:cf:e2:44:
          8c:25:28:a8:c5:79:09:7d:46:b9:8a:f3:e9:f3:34:
          29:08:45:e4:1c:9f:cb:94:04:1c:81:a8:14:b3:98:
          65:c4:43:ec:4e:82:8d:09:d1:bd:aa:5b:8d:92:d0:
          ec:de:90:c5:7f:0a:c2:e3:eb:e6:31:5a:5e:74:3e:
          97:33:59:e8:c3:03:3d:60:33:bf:f7:d1:6f:47:c4:
          cd:ee:62:83:52:6e:2e:08:9a:a4:d9:15:18:91:a6:
          85:92:47:b0:ae:48:eb:6d:b7:21:ec:85:1a:68:72:
          35:ab:ff:f0:10:5d:c0:f4:94:a7:6a:d5:3b:92:7e:
          4c:90:05:7e:93:c1:2c:8b:a4:8e:62:74:15:71:6e:
          0b:71:03:ea:af:15:38:9a:d4:d2:05:72:6f:8c:f9:
          2b:eb:5a:72:25:f9:39:46:e3:72:1b:3e:04:c3:64:
          27:22:10:2a:8a:4f:58:a7:03:ad:be:b4:2e:13:ed:
          5d:aa:48:d7:d5:7d:d4:2a:7b:5c:fa:46:04:50:e4:
          cc:0e:42:5b:8c:ed:db:f2:cf:fc:96:93:e0:db:11:
          36:54:62:34:38:8f:0c:60:9b:3b:97:56:38:ad:f3:
          d2:5b:8b:a0:5b:ea:4e:96:b8:7c:d7:d5:a0:86:70:
          40:d3:91:29:b7:a2:3c:ad:f5:8c:bb:cf:1a:92:8a:
          e4:34:7b:c0:d8:6c:5f:e9:0a:c2:c3:a7:20:9a:5a:
          df:2c:5d:52:5c:ba:47:d5:9b:ef:24:28:70:38:20:
          2f:d5:7f:29:c0:b2:41:03:68:92:cc:e0:9c:cc:97:
          4b:45:ef:3a:10:0a:ab:70:3a:98:95:70:ad:35:b1:
          ea:85:2b:a4:1c:80:21:31:a9:ae:60:7a:80:26:48:
          00:b8:01:c0:93:63:55:22:91:3c:56:e7:af:db:3a:
          25:f3:8f:31:54:ea:26:8b:81:59:f9:a1:d1:53:11:
          c5:7b:9d:03:f6:74:11:e0:6d:b1:2c:3f:2c:86:91:
          99:71:9a:a6:77:8b:34:60:d1:14:b4:2c:ac:9d:af:
          8c:10:d3:9f:c4:6a:f8:6f:13:fc:73:59:f7:66:42:
          74:1e:8a:e3:f8:dc:d2:6f:98:9c:cb:47:98:95:40:
          05:fb:e9
      Exponent: 65537 (0x10001)

### Extensions

- [AuthorityKeyIdentifier](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.2.1.1):
  reference the Root CA certificate's public key in the `keyIdentifier` field:

  `16:b5:32:1b:d4:c7:f3:e0:e6:8e:f3:bd:d2:b0:3a:ee:b2:39:18:d1` (sha1 hash of the Root CA certificate's public key)

- [SubjectKeyIdentifier](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.2.1.2):
  reference the own public key

      $ openssl sha1 -c class3_pubkey.der
      SHA1(class3_pubkey.der)= f0:61:d8:3f:95:8f:4d:78:b1:47:b3:13:39:97:8e:a9:c2:51:ba:9b

- [KeyUsage](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.2.1.3):

  `key cert sign, crl sign; critical`

- [CertificatePolicies](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.2.1.4):

      PolicyInformation [
        CertPolicyId 1.3.6.1.4.1.18506.4.4
        PolicyQualifiers [
          id-qt-cps
          cPSuri https://www.cacert.org/policy/CertificationPracticeStatement.html
        ]
      ]

  The CertPolicy OID 1.3.6.1.4.1.18506.4.4 is defined at https://wiki.cacert.org/OidAllocation. The 2021 class 3 CA
  certificate contained a cps.php link, which does not make sense for a static document.

- [BasicConstraints](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.2.1.9):
  `CA: true, patLenConstraint: 0; critical`

- [Extended Key Usage](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.2.1.12):
 
  not set

  *Note:* `server auth, client auth, email protection, code signing, OCSP signing, SmartCard logon, anyExtendedKeyUsage`
  might be a good option, but might confuse at least some relying party applications

  *Note:* this will not be sufficient to fulfill the
  [Google requirements for S/MIME certificates](https://support.google.com/a/answer/7300887)

- [CRL Distribution Points](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.2.1.13):
  http://crl.cacert.org/revoke.crl

  *Note:* CRL URLs must use the http URL scheme, this must be the CRL issued
  by the signing CA (in this case the Root CA)

- [Authority Information Access](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.2.2.1):

  - CA issuers: http://www.cacert.org/certs/root_X0F.der

    Reference the Root CA certificate's canonical DER URL
  - OCSP: URI:http://ocsp.cacert.org/

  *Note:* CA issuers and OCSP URLs must use the http URL scheme

# Re-Signing procedure

According to https://wiki.cacert.org/SystemAdministration/Systems/Signer the signer is running a Debian 5.0 Lenny
minimal system based operating system. The procedure documented here has therefore been tested using a Debian 5.0
virtual machine.

## Generate a CSR from the existing private key and certificate

```shell
export TZ=UTC
openssl x509 -signkey class3.key.pem -x509toreq -in class3.crt.pem -out class3.csr.pem \
  2>&1 | tee -a class3-signing-$(date +%Y%m%d).log
```

## Sign the new CA certificate with the openssl configuration file

```shell
TZ=UTC \
openssl ca \
  -config openssl-class3-resign.conf \  # use CA re-signing configuration
  -extensions class3_ca_ext          \  # use class3 CA extension section
  -in class3.csr.pem                 \  # use the CSR from the previous step
  -startdate $(date +%y%m%d%H%M%SZ --date="today")  \  # use the current date
  -enddate $(date +%y%m%d%H%M%SZ --date="today + 5 years 0:00")  # use 5 years later
  -out class3.crt.pem                \  # output class3 certificate
  2>&1 | tee -a class3-signing-$(date +%Y%m%d).log
```

## Post-signing changes on the signer

Certificates signed by the new class3 CA certificate should contain links to the CRL, OCSP and DER CA certificate URLs
of the new class3 certificate. It would be a good idea to decide and document these URLs in advance.

The CA extension configurations for the different types of end entity certificates should be configured on the signer
accordingly, i.e.

```
[client_ext]
authorityKeyIdentifier = hash
basicConstraints       = CA:FALSE
keyUsage               = digitalSignature,keyEncipherment,keyAgreement
extendedKeyUsage       = emailProtection,clientAuth,msSGC,msEFS,nsSGC
crlDistributionPoints  = URI:http://crl.cacert.org/class3-revoke.crl
authorityInfoAccess    = caIssuers;URI:http://www.cacert.org/certs/CAcert_Class3Root_x14E228.der, OCSP;URI:http://ocsp.cacert.org
```

*Note*: it might be preferable to use a stable URL like http://www.cacert.org/certs/class3_ca.der instead of using a
name containing the serial number. URLs that will cause redirects should be avoided, because some relying party
applications may not follow redirects.

The OCSP, CRL and CAIssuers URLs should use the http URL scheme.