4adc9006183ec32172864af3febcaf9ad6402f03
services/Automatic-CA.md
| ... | ... | @@ -0,0 +1,197 @@ |
| 1 | +DN42 Self-Serve CA |
|
| 2 | +================== |
|
| 3 | + |
|
| 4 | +This client is used for automating the process of requesting TLS certificates. |
|
| 5 | + |
|
| 6 | + |
|
| 7 | +VALIDATION PROCESS |
|
| 8 | +================== |
|
| 9 | + |
|
| 10 | +The process validates ownership by verifying control of both a users MNT object in the registry and the authoritative DNS server. |
|
| 11 | +The following steps take place in creating a signed certificate. |
|
| 12 | + |
|
| 13 | +*User Flow* |
|
| 14 | + |
|
| 15 | +1. User generates a 2048+ bit rsa key and CSR for their MNT object. |
|
| 16 | +2. User generates a sha256 hash of the rsa public key (commonly known as a [public keypin][keypin]) and adds it as a remark in their MNT |
|
| 17 | +3. User submits the csr to the CA to validate and sign. |
|
| 18 | +4. CA checks for the keypin in their MNT object (if it does not find it in the local copy of the [monotone repo][ca-mtn] it will check against io.nixnodes.dn42) |
|
| 19 | +5. (optional) CA revokes prior certificate as superseded. |
|
| 20 | +6. CA signs and returns the user certificate. |
|
| 21 | + |
|
| 22 | +*Server Flow* |
|
| 23 | + |
|
| 24 | +1. User generates a 2048+ bit rsa key and CSR for the dns CN. Also including any SAN domains. |
|
| 25 | +2. User generates a sha256 hash of the rsa public key (commonly known as a [public keypin][keypin]) and adds it as a txt record in their DNS. |
|
| 26 | +3. User uses the user certificate to authenticate and submits the csr to the CA to validate and sign. |
|
| 27 | +4. CA checks for the user keypin in their MNT object (if it does not find it in the local copy of the [monotone repo][ca-mtn] it will check against io.nixnodes.dn42) |
|
| 28 | +5. CA checks the dns records for the CN and each SAN for the tls keypin. |
|
| 29 | +6. (optional) CA revokes prior certificate as superseded. |
|
| 30 | +7. CA signs and returns the tls certificate. |
|
| 31 | + |
|
| 32 | +*User Renewals* |
|
| 33 | + |
|
| 34 | +User certificates are signed for 180 days. To renew follow the steps above starting from number 3. |
|
| 35 | + |
|
| 36 | +*Server renewals* |
|
| 37 | + |
|
| 38 | +Server certificates are signed for 45 days. To renew follow the steps above starting from number 3. |
|
| 39 | + |
|
| 40 | +[keypin]: https://developer.mozilla.org/en-US/docs/Web/Security/Public_Key_Pinning |
|
| 41 | +[ca-mtn]: https://ca.dn42/reg/mntner/ |
|
| 42 | + |
|
| 43 | +*Certificate Revocations* |
|
| 44 | + |
|
| 45 | +1. User uses the user certificate to authenticate and submits the serial and revoke reason to CA. |
|
| 46 | +2. CA checks user keypin in their MNT object (if it does not find it in the local copy of the [monotone repo][ca-mtn] it will check against io.nixnodes.dn42) |
|
| 47 | +3. CA checks that owner in certificate matches. |
|
| 48 | +4. CA revokes certificate and updates revocation list. |
|
| 49 | + |
|
| 50 | +INSTALL |
|
| 51 | +======= |
|
| 52 | + |
|
| 53 | +get the script here: |
|
| 54 | + |
|
| 55 | +curl https://ca.dn42/ca.dn42 > ca.dn42; chmod +x ca.dn42 |
|
| 56 | + |
|
| 57 | +available via git: anon@git.dn42:dn42/ca-client |
|
| 58 | + |
|
| 59 | + |
|
| 60 | +KNOWN ISSUES |
|
| 61 | +============ |
|
| 62 | + |
|
| 63 | +## openssl prior to 1.0.2 returns "SSL certificate problem: permitted subtree violation" |
|
| 64 | + |
|
| 65 | +The way openssl validated name constraints prevented it from accepting dns names that started with a dot. |
|
| 66 | +Because the name constraint is "DNS:.dn42" it fails to validate. |
|
| 67 | + |
|
| 68 | +[Read more on this mailing list thread][libssl-1] |
|
| 69 | + |
|
| 70 | + |
|
| 71 | +[libssl-1]: https://groups.google.com/forum/#!topic/mailing.openssl.dev/drG3U-S4iaE |
|
| 72 | + |
|
| 73 | + |
|
| 74 | +## X.509 nameConstraints on certificates not supported on OS X |
|
| 75 | + |
|
| 76 | +Browsers and clients that rely on Apple's [Secure Transport][osx-1] library does not support X.509's nameConstraints. |
|
| 77 | + |
|
| 78 | +Read more on this [stack exchange post][osx-2] |
|
| 79 | + |
|
| 80 | + |
|
| 81 | +[osx-1]: https://developer.apple.com/library/mac/documentation/Security/Reference/secureTransportRef/ |
|
| 82 | +[osx-2]: http://security.stackexchange.com/a/97133 |
|
| 83 | + |
|
| 84 | + |
|
| 85 | +How to Run |
|
| 86 | +========== |
|
| 87 | + |
|
| 88 | +Usage: # OWNER is your MNT handle. |
|
| 89 | + ./ca.dn42 user-gen OWNER EMAIL # Output to OWNER.csr and OWNER.key |
|
| 90 | + ./ca.dn42 user-sig OWNER # Output to OWNER.crt and OWNER.p12 |
|
| 91 | + ./ca.dn42 tls-gen DNS OWNER EMAIL [SAN] # Output to OWNER_DNS.csr and OWNER.key |
|
| 92 | + ./ca.dn42 tls-sig DNS OWNER # Output to OWNER_DNS.crt and OWNER_DNS.p12 |
|
| 93 | + ./ca.dn42 revoke OWNER CERTFILE [REASON] |
|
| 94 | + |
|
| 95 | +Revoke Reasons: unspecified, keyCompromise, affiliationChanged, |
|
| 96 | + superseded, cessationOfOperation, certificateHold, removeFromCRL |
|
| 97 | + |
|
| 98 | +Environtment Options: |
|
| 99 | + DN42CA_PKCS12 = 1 # Generate pkcs12 file for certificate. |
|
| 100 | + |
|
| 101 | +Example |
|
| 102 | +======= |
|
| 103 | + |
|
| 104 | +Generate the user key |
|
| 105 | + |
|
| 106 | +``` |
|
| 107 | +$ ./ca.dn42 user-gen XUU-MNT xuu@sour.is |
|
| 108 | +Generating a 2048 bit RSA private key |
|
| 109 | +...............................+++ |
|
| 110 | +.........................+++ |
|
| 111 | +writing new private key to 'XUU-MNT.key' |
|
| 112 | +----- |
|
| 113 | += |
|
| 114 | += You need to have this pin added to your mnt object before proceeding to the next step. |
|
| 115 | += |
|
| 116 | +|MNT Key Pin| remarks: pin-sha256:HdqCid0sedWXX3Q0uG98rYjJyTNOzaT13WfWpr1GvIw= |
|
| 117 | +``` |
|
| 118 | + |
|
| 119 | +## Sign the user key |
|
| 120 | + |
|
| 121 | +```` |
|
| 122 | +$ ./ca.dn42 user-sign XUU-MNT xuu@sour.is |
|
| 123 | +== USER CERT == |
|
| 124 | + C:XD |
|
| 125 | + O:dn42 |
|
| 126 | + OU:dn42 Certificate Authority |
|
| 127 | + CN:XUU-MNT |
|
| 128 | + emailAddress:xuu@sour.is |
|
| 129 | + owner:XUU-MNT |
|
| 130 | + pin-sha256:HdqCid0sedWXX3Q0uG98rYjJyTNOzaT13WfWpr1GvIw= |
|
| 131 | +OK https://ca.dn42/crt/XUU-MNT.crt |
|
| 132 | +Enter Export Password: |
|
| 133 | +Verifying - Enter Export Password: |
|
| 134 | +``` |
|
| 135 | + |
|
| 136 | +## Generate the server key |
|
| 137 | + |
|
| 138 | +``` |
|
| 139 | +$ ./ca.dn42 tls-gen ca.dn42 XUU-MNT xuu@sour.is DNS:ca.dn42 |
|
| 140 | + |
|
| 141 | +Generating a 2048 bit RSA private key |
|
| 142 | +...........................................+++ |
|
| 143 | +.......................+++ |
|
| 144 | +writing new private key to 'XUU-MNT_ca.dn42.key' |
|
| 145 | +----- |
|
| 146 | +writing RSA key |
|
| 147 | += |
|
| 148 | += |DNS Key Pin| You need to have this pin added to your dns records before proceeding to the next step. |
|
| 149 | += |
|
| 150 | +_dn42_tlsverify.ca.dn42. IN TXT XUU-MNT:pin-sha256:Qu/X5GNqOo05TdL7oexkamE34OUuDE60T+f0xc60UPQ= |
|
| 151 | +``` |
|
| 152 | + |
|
| 153 | + |
|
| 154 | +## Sign the server key |
|
| 155 | + |
|
| 156 | +``` |
|
| 157 | +$ ./ca.dn42 tls-sign ca.dn42 XUU-MNT |
|
| 158 | +== USER CERT == |
|
| 159 | + C:XD |
|
| 160 | + O:dn42 |
|
| 161 | + OU:dn42 Certificate Authority |
|
| 162 | + CN:XUU-MNT |
|
| 163 | + emailAddress:xuu@sour.is |
|
| 164 | + owner:XUU-MNT |
|
| 165 | + pin-sha256:HdqCid0sedWXX3Q0uG98rYjJyTNOzaT13WfWpr1GvIw= |
|
| 166 | +== DNS CSR == |
|
| 167 | + C:XD |
|
| 168 | + O:dn42 |
|
| 169 | + OU:dn42 Certificate Authority |
|
| 170 | + CN:ca.dn42 |
|
| 171 | + emailAddress:xuu@sour.is |
|
| 172 | + owner:XUU-MNT |
|
| 173 | + pin-sha256:Qu/X5GNqOo05TdL7oexkamE34OUuDE60T+f0xc60UPQ= |
|
| 174 | +== DNS Tests == |
|
| 175 | + CN Record: ca.dn42 PASSED |
|
| 176 | + SAN Record: ca.dn42 PASSED |
|
| 177 | +OK https://ca.dn42/crt/XUU-MNT_ca.dn42.crt |
|
| 178 | +Enter Export Password: **** |
|
| 179 | +Verifying - Enter Export Password: **** |
|
| 180 | +``` |
|
| 181 | + |
|
| 182 | + |
|
| 183 | +## Revoke a certificate. |
|
| 184 | + |
|
| 185 | +``` |
|
| 186 | +$ ./ca.dn42 revoke XUU-MNT XUU-MNT.crt |
|
| 187 | +== USER CERT == |
|
| 188 | + C:XD |
|
| 189 | + O:dn42 |
|
| 190 | + OU:dn42 Certificate Authority |
|
| 191 | + CN:XUU-MNT |
|
| 192 | + emailAddress:xuu@sour.is |
|
| 193 | + owner:XUU-MNT |
|
| 194 | + pin-sha256:HdqCid0sedWXX3Q0uG98rYjJyTNOzaT13WfWpr1GvIw= |
|
| 195 | +== REVOKE CERT == |
|
| 196 | +OK |
|
| 197 | +``` |
|
| ... | ... | \ No newline at end of file |