Apache2
md.h
Go to the documentation of this file.
1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2  * contributor license agreements. See the NOTICE file distributed with
3  * this work for additional information regarding copyright ownership.
4  * The ASF licenses this file to You under the Apache License, Version 2.0
5  * (the "License"); you may not use this file except in compliance with
6  * the License. You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef mod_md_md_h
18 #define mod_md_md_h
19 
20 #include <apr_time.h>
21 
22 #include "md_time.h"
23 #include "md_version.h"
24 
25 struct apr_array_header_t;
26 struct apr_hash_t;
27 struct md_json_t;
28 struct md_cert_t;
29 struct md_job_t;
30 struct md_pkey_t;
31 struct md_result_t;
32 struct md_store_t;
33 struct md_srv_conf_t;
34 struct md_pkey_spec_t;
35 
36 #define MD_PKEY_RSA_BITS_MIN 2048
37 #define MD_PKEY_RSA_BITS_DEF 2048
38 
39 /* Minimum age for the HSTS header (RFC 6797), considered appropriate by Mozilla Security */
40 #define MD_HSTS_HEADER "Strict-Transport-Security"
41 #define MD_HSTS_MAX_AGE_DEFAULT 15768000
42 
43 #define PROTO_ACME_TLS_1 "acme-tls/1"
44 
45 #define MD_TIME_LIFE_NORM (apr_time_from_sec(100 * MD_SECS_PER_DAY))
46 #define MD_TIME_RENEW_WINDOW_DEF (apr_time_from_sec(33 * MD_SECS_PER_DAY))
47 #define MD_TIME_WARN_WINDOW_DEF (apr_time_from_sec(10 * MD_SECS_PER_DAY))
48 #define MD_TIME_OCSP_KEEP_NORM (apr_time_from_sec(7 * MD_SECS_PER_DAY))
49 
50 #define MD_OTHER "other"
51 
52 typedef enum {
53  MD_S_UNKNOWN = 0, /* MD has not been analysed yet */
54  MD_S_INCOMPLETE = 1, /* MD is missing necessary information, cannot go live */
55  MD_S_COMPLETE = 2, /* MD has all necessary information, can go live */
56  MD_S_EXPIRED_DEPRECATED = 3, /* deprecated */
57  MD_S_ERROR = 4, /* MD data is flawed, unable to be processed as is */
58  MD_S_MISSING_INFORMATION = 5, /* User has not agreed to ToS */
59 } md_state_t;
60 
61 typedef enum {
66 } md_require_t;
67 
68 typedef enum {
69  MD_RENEW_DEFAULT = -1, /* default value */
70  MD_RENEW_MANUAL, /* manually triggered renewal of certificate */
71  MD_RENEW_AUTO, /* automatic process performed by httpd */
72  MD_RENEW_ALWAYS, /* always renewed by httpd, even if not necessary */
74 
75 typedef struct md_t md_t;
76 struct md_t {
77  const char *name; /* unique name of this MD */
78  struct apr_array_header_t *domains; /* all DNS names this MD includes */
79  struct apr_array_header_t *contacts; /* list of contact uris, e.g. mailto:xxx */
80 
81  int transitive; /* != 0 iff VirtualHost names/aliases are auto-added */
82  md_require_t require_https; /* Iff https: is required for this MD */
83 
84  int renew_mode; /* mode of obtaining credentials */
85  struct md_pkeys_spec_t *pks; /* specification for generating private keys */
86  int must_staple; /* certificates should set the OCSP Must Staple extension */
87  md_timeslice_t *renew_window; /* time before expiration that starts renewal */
88  md_timeslice_t *warn_window; /* time before expiration that warnings are sent out */
89 
90  const char *ca_url; /* url of CA certificate service */
91  const char *ca_proto; /* protocol used vs CA (e.g. ACME) */
92  const char *ca_account; /* account used at CA */
93  const char *ca_agreement; /* accepted agreement uri between CA and user */
94  struct apr_array_header_t *ca_challenges; /* challenge types configured for this MD */
95  struct apr_array_header_t *cert_files; /* != NULL iff pubcerts explicitly configured */
96  struct apr_array_header_t *pkey_files; /* != NULL iff privkeys explicitly configured */
97 
98  md_state_t state; /* state of this MD */
99 
100  struct apr_array_header_t *acme_tls_1_domains; /* domains supporting "acme-tls/1" protocol */
101  int stapling; /* if OCSP stapling is enabled */
102 
103  int watched; /* if certificate is supervised (renew or expiration warning) */
104  const struct md_srv_conf_t *sc; /* server config where it was defined or NULL */
105  const char *defn_name; /* config file this MD was defined */
106  unsigned defn_line_number; /* line number of definition */
107 
108  const char *configured_name; /* name this MD was configured with, if different */
109 };
110 
111 #define MD_KEY_ACCOUNT "account"
112 #define MD_KEY_ACME_TLS_1 "acme-tls/1"
113 #define MD_KEY_ACTIVATION_DELAY "activation-delay"
114 #define MD_KEY_ACTIVITY "activity"
115 #define MD_KEY_AGREEMENT "agreement"
116 #define MD_KEY_AUTHORIZATIONS "authorizations"
117 #define MD_KEY_BITS "bits"
118 #define MD_KEY_CA "ca"
119 #define MD_KEY_CA_URL "ca-url"
120 #define MD_KEY_CERT "cert"
121 #define MD_KEY_CERT_FILES "cert-files"
122 #define MD_KEY_CERTIFICATE "certificate"
123 #define MD_KEY_CHALLENGE "challenge"
124 #define MD_KEY_CHALLENGES "challenges"
125 #define MD_KEY_CMD_DNS01 "cmd-dns-01"
126 #define MD_KEY_COMPLETE "complete"
127 #define MD_KEY_CONTACT "contact"
128 #define MD_KEY_CONTACTS "contacts"
129 #define MD_KEY_CSR "csr"
130 #define MD_KEY_CURVE "curve"
131 #define MD_KEY_DETAIL "detail"
132 #define MD_KEY_DISABLED "disabled"
133 #define MD_KEY_DIR "dir"
134 #define MD_KEY_DOMAIN "domain"
135 #define MD_KEY_DOMAINS "domains"
136 #define MD_KEY_ENTRIES "entries"
137 #define MD_KEY_ERRORED "errored"
138 #define MD_KEY_ERROR "error"
139 #define MD_KEY_ERRORS "errors"
140 #define MD_KEY_EXPIRES "expires"
141 #define MD_KEY_FINALIZE "finalize"
142 #define MD_KEY_FINISHED "finished"
143 #define MD_KEY_FROM "from"
144 #define MD_KEY_GOOD "good"
145 #define MD_KEY_HTTP "http"
146 #define MD_KEY_HTTPS "https"
147 #define MD_KEY_ID "id"
148 #define MD_KEY_IDENTIFIER "identifier"
149 #define MD_KEY_KEY "key"
150 #define MD_KEY_KEYAUTHZ "keyAuthorization"
151 #define MD_KEY_LAST "last"
152 #define MD_KEY_LAST_RUN "last-run"
153 #define MD_KEY_LOCATION "location"
154 #define MD_KEY_LOG "log"
155 #define MD_KEY_MDS "managed-domains"
156 #define MD_KEY_MESSAGE "message"
157 #define MD_KEY_MUST_STAPLE "must-staple"
158 #define MD_KEY_NAME "name"
159 #define MD_KEY_NEXT_RUN "next-run"
160 #define MD_KEY_NOTIFIED "notified"
161 #define MD_KEY_NOTIFIED_RENEWED "notified-renewed"
162 #define MD_KEY_OCSP "ocsp"
163 #define MD_KEY_OCSPS "ocsps"
164 #define MD_KEY_ORDERS "orders"
165 #define MD_KEY_PERMANENT "permanent"
166 #define MD_KEY_PKEY "privkey"
167 #define MD_KEY_PKEY_FILES "pkey-files"
168 #define MD_KEY_PROBLEM "problem"
169 #define MD_KEY_PROTO "proto"
170 #define MD_KEY_READY "ready"
171 #define MD_KEY_REGISTRATION "registration"
172 #define MD_KEY_RENEW "renew"
173 #define MD_KEY_RENEW_AT "renew-at"
174 #define MD_KEY_RENEW_MODE "renew-mode"
175 #define MD_KEY_RENEWAL "renewal"
176 #define MD_KEY_RENEWING "renewing"
177 #define MD_KEY_RENEW_WINDOW "renew-window"
178 #define MD_KEY_REQUIRE_HTTPS "require-https"
179 #define MD_KEY_RESOURCE "resource"
180 #define MD_KEY_RESPONSE "response"
181 #define MD_KEY_REVOKED "revoked"
182 #define MD_KEY_SERIAL "serial"
183 #define MD_KEY_SHA256_FINGERPRINT "sha256-fingerprint"
184 #define MD_KEY_STAPLING "stapling"
185 #define MD_KEY_STATE "state"
186 #define MD_KEY_STATUS "status"
187 #define MD_KEY_STORE "store"
188 #define MD_KEY_SUBPROBLEMS "subproblems"
189 #define MD_KEY_TEMPORARY "temporary"
190 #define MD_KEY_TOKEN "token"
191 #define MD_KEY_TOTAL "total"
192 #define MD_KEY_TRANSITIVE "transitive"
193 #define MD_KEY_TYPE "type"
194 #define MD_KEY_UNKNOWN "unknown"
195 #define MD_KEY_UNTIL "until"
196 #define MD_KEY_URL "url"
197 #define MD_KEY_URI "uri"
198 #define MD_KEY_VALID "valid"
199 #define MD_KEY_VALID_FROM "valid-from"
200 #define MD_KEY_VALUE "value"
201 #define MD_KEY_VERSION "version"
202 #define MD_KEY_WATCHED "watched"
203 #define MD_KEY_WHEN "when"
204 #define MD_KEY_WARN_WINDOW "warn-window"
205 
206 /* Check if a string member of a new MD (n) has
207  * a value and if it differs from the old MD o
208  */
209 #define MD_VAL_UPDATE(n,o,s) ((n)->s != (o)->s)
210 #define MD_SVAL_UPDATE(n,o,s) ((n)->s && (!(o)->s || strcmp((n)->s, (o)->s)))
211 
215 int md_contains(const md_t *md, const char *domain, int case_sensitive);
216 
220 int md_domains_overlap(const md_t *md1, const md_t *md2);
221 
225 int md_equal_domains(const md_t *md1, const md_t *md2, int case_sensitive);
226 
230 int md_contains_domains(const md_t *md1, const md_t *md2);
231 
235 const char *md_common_name(const md_t *md1, const md_t *md2);
236 
240 apr_size_t md_common_name_count(const md_t *md1, const md_t *md2);
241 
245 md_t *md_get_by_name(struct apr_array_header_t *mds, const char *name);
246 
250 md_t *md_get_by_domain(struct apr_array_header_t *mds, const char *domain);
251 
256 md_t *md_get_by_dns_overlap(struct apr_array_header_t *mds, const md_t *md);
257 
262 
267 
271 md_t *md_clone(apr_pool_t *p, const md_t *src);
272 
276 md_t *md_copy(apr_pool_t *p, const md_t *src);
277 
283 struct md_json_t *md_to_json (const md_t *md, apr_pool_t *p);
284 md_t *md_from_json(struct md_json_t *json, apr_pool_t *p);
285 
286 int md_is_covered_by_alt_names(const md_t *md, const struct apr_array_header_t* alt_names);
287 
288 /* how many certificates this domain has/will eventually have. */
289 int md_cert_count(const md_t *md);
290 
291 #define LE_ACMEv1_PROD "https://acme-v01.api.letsencrypt.org/directory"
292 #define LE_ACMEv1_STAGING "https://acme-staging.api.letsencrypt.org/directory"
293 
294 #define LE_ACMEv2_PROD "https://acme-v02.api.letsencrypt.org/directory"
295 #define LE_ACMEv2_STAGING "https://acme-staging-v02.api.letsencrypt.org/directory"
296 
297 
298 /**************************************************************************************************/
299 /* notifications */
300 
301 typedef apr_status_t md_job_notify_cb(struct md_job_t *job, const char *reason,
302  struct md_result_t *result, apr_pool_t *p, void *baton);
303 
304 /**************************************************************************************************/
305 /* domain credentials */
306 
307 typedef struct md_pubcert_t md_pubcert_t;
308 struct md_pubcert_t {
309  struct apr_array_header_t *certs; /* chain of const md_cert*, leaf cert first */
310  struct apr_array_header_t *alt_names; /* alt-names of leaf cert */
311  const char *cert_file; /* file path of chain */
312  const char *key_file; /* file path of key for leaf cert */
313 };
314 
315 #define MD_OK(c) (APR_SUCCESS == (rv = c))
316 
317 #endif /* mod_md_md_h */
Definition: mod_md_config.h:76
size_t apr_size_t
Definition: apr.h:393
Definition: md.h:54
struct md_cert_t md_cert_t
Definition: md_crypt.h:122
struct md_json_t * md_to_json(const md_t *md, apr_pool_t *p)
Definition: md.h:76
Definition: md_store.h:307
struct md_json_t md_json_t
Definition: md_json.h:29
Definition: md.h:62
Definition: md.h:53
md_state_t state
Definition: md.h:98
Definition: apr_tables.h:62
struct apr_array_header_t * acme_tls_1_domains
Definition: md.h:100
struct apr_array_header_t * cert_files
Definition: md.h:95
Definition: md.h:58
int must_staple
Definition: md.h:86
Definition: md.h:70
apr_size_t md_common_name_count(const md_t *md1, const md_t *md2)
int renew_mode
Definition: md.h:84
md_t * md_clone(apr_pool_t *p, const md_t *src)
Definition: md.h:64
const struct md_srv_conf_t * sc
Definition: md.h:104
int transitive
Definition: md.h:81
unsigned defn_line_number
Definition: md.h:106
struct apr_array_header_t * ca_challenges
Definition: md.h:94
md_require_t
Definition: md.h:61
const char * key_file
Definition: md.h:312
int md_cert_count(const md_t *md)
int md_equal_domains(const md_t *md1, const md_t *md2, int case_sensitive)
const char * configured_name
Definition: md.h:108
md_t * md_copy(apr_pool_t *p, const md_t *src)
apr_status_t md_job_notify_cb(struct md_job_t *job, const char *reason, struct md_result_t *result, apr_pool_t *p, void *baton)
Definition: md.h:301
Definition: md.h:65
md_require_t require_https
Definition: md.h:82
md_state_t
Definition: md.h:52
Definition: md_status.h:52
struct apr_array_header_t * contacts
Definition: md.h:79
int md_domains_overlap(const md_t *md1, const md_t *md2)
int md_contains_domains(const md_t *md1, const md_t *md2)
md_t * md_create(apr_pool_t *p, struct apr_array_header_t *domains)
md_t * md_get_by_dns_overlap(struct apr_array_header_t *mds, const md_t *md)
const char * ca_proto
Definition: md.h:91
const char * cert_file
Definition: md.h:311
struct apr_array_header_t * certs
Definition: md.h:309
dav_error * src
Definition: mod_dav.h:186
md_t * md_get_by_name(struct apr_array_header_t *mds, const char *name)
struct md_pkeys_spec_t * pks
Definition: md.h:85
const char * defn_name
Definition: md.h:105
int watched
Definition: md.h:103
md_t * md_get_by_domain(struct apr_array_header_t *mds, const char *domain)
md_timeslice_t * warn_window
Definition: md.h:88
Definition: md.h:57
struct apr_hash_t apr_hash_t
Definition: apr_hash.h:52
Definition: md_time.h:60
int stapling
Definition: md.h:101
Definition: md_result.h:29
const char * ca_account
Definition: md.h:92
apr_pool_t * p
Definition: md.h:71
md_renew_mode_t
Definition: md.h:68
struct apr_array_header_t * alt_names
Definition: md.h:310
Definition: md.h:308
Definition: md.h:72
md_t * md_create_empty(apr_pool_t *p)
struct apr_array_header_t * domains
Definition: md.h:78
md_t * md_from_json(struct md_json_t *json, apr_pool_t *p)
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
const char * md_common_name(const md_t *md1, const md_t *md2)
Definition: md_crypt.h:73
Definition: md.h:55
int apr_status_t
Definition: apr_errno.h:44
Definition: md.h:56
const char * name
Definition: md.h:77
struct apr_array_header_t * pkey_files
Definition: md.h:96
APR Time Library.
int md_contains(const md_t *md, const char *domain, int case_sensitive)
Definition: md.h:63
const char * ca_agreement
Definition: md.h:93
const char * ca_url
Definition: md.h:90
struct md_pkey_t md_pkey_t
Definition: md_crypt.h:49
int md_is_covered_by_alt_names(const md_t *md, const struct apr_array_header_t *alt_names)
Definition: md.h:69
Definition: md_crypt.h:65
md_timeslice_t * renew_window
Definition: md.h:87