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: [email protected]: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 [email protected]
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 [email protected]
123
+== USER CERT ==
124
+ C:XD
125
+ O:dn42
126
+ OU:dn42 Certificate Authority
127
+ CN:XUU-MNT
128
+ emailAddress:[email protected]
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 [email protected] 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:[email protected]
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:[email protected]
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:[email protected]
193
+ owner:XUU-MNT
194
+ pin-sha256:HdqCid0sedWXX3Q0uG98rYjJyTNOzaT13WfWpr1GvIw=
195
+== REVOKE CERT ==
196
+OK
197
+```
... ...
\ No newline at end of file