1 /* $NetBSD: tls.h,v 1.1.1.4 2013/01/02 18:59:04 tron Exp $ */ 2 3 #ifndef _TLS_H_INCLUDED_ 4 #define _TLS_H_INCLUDED_ 5 6 /*++ 7 /* NAME 8 /* tls 3h 9 /* SUMMARY 10 /* libtls internal interfaces 11 /* SYNOPSIS 12 /* #include <tls.h> 13 /* DESCRIPTION 14 /* .nf 15 16 /* 17 * Utility library. 18 */ 19 #include <name_code.h> 20 #include <argv.h> 21 22 /* 23 * TLS enforcement levels. Non-sentinel values may also be used to indicate 24 * the actual security level of a session. 25 * 26 * XXX TLS_LEV_NOTFOUND no longer belongs in this list. The SMTP client will 27 * have to use something else to report that policy table lookup failed. 28 */ 29 #define TLS_LEV_INVALID -2 /* sentinel */ 30 #define TLS_LEV_NOTFOUND -1 /* XXX not in policy table */ 31 #define TLS_LEV_NONE 0 /* plain-text only */ 32 #define TLS_LEV_MAY 1 /* wildcard */ 33 #define TLS_LEV_ENCRYPT 2 /* encrypted connection */ 34 #define TLS_LEV_FPRINT 3 /* "peer" CA-less verification */ 35 #define TLS_LEV_VERIFY 4 /* certificate verified */ 36 #define TLS_LEV_SECURE 5 /* "secure" verification */ 37 38 extern const NAME_CODE tls_level_table[]; 39 40 #define tls_level_lookup(s) name_code(tls_level_table, NAME_CODE_FLAG_NONE, (s)) 41 #define str_tls_level(l) str_name_code(tls_level_table, (l)) 42 43 #ifdef USE_TLS 44 45 /* 46 * OpenSSL library. 47 */ 48 #include <openssl/lhash.h> 49 #include <openssl/bn.h> 50 #include <openssl/err.h> 51 #include <openssl/pem.h> 52 #include <openssl/x509.h> 53 #include <openssl/x509v3.h> 54 #include <openssl/rand.h> 55 #include <openssl/ssl.h> 56 57 #if (OPENSSL_VERSION_NUMBER < 0x00905100L) 58 #error "need OpenSSL version 0.9.5 or later" 59 #endif 60 61 /* 62 * Utility library. 63 */ 64 #include <vstream.h> 65 #include <name_mask.h> 66 #include <name_code.h> 67 68 /* 69 * Names of valid tlsmgr(8) session caches. 70 */ 71 #define TLS_MGR_SCACHE_SMTPD "smtpd" 72 #define TLS_MGR_SCACHE_SMTP "smtp" 73 #define TLS_MGR_SCACHE_LMTP "lmtp" 74 75 /* 76 * TLS session context, also used by the VSTREAM call-back routines for SMTP 77 * input/output, and by OpenSSL call-back routines for key verification. 78 * 79 * Only some members are (read-only) accessible by the public. 80 */ 81 #define CCERT_BUFSIZ 256 82 83 typedef struct { 84 /* Public, read-only. */ 85 char *peer_CN; /* Peer Common Name */ 86 char *issuer_CN; /* Issuer Common Name */ 87 char *peer_fingerprint; /* ASCII fingerprint */ 88 char *peer_pkey_fprint; /* ASCII public key fingerprint */ 89 int peer_status; /* Certificate and match status */ 90 const char *protocol; 91 const char *cipher_name; 92 int cipher_usebits; 93 int cipher_algbits; 94 /* Private. */ 95 SSL *con; 96 char *cache_type; /* tlsmgr(8) cache type if enabled */ 97 char *serverid; /* unique server identifier */ 98 char *namaddr; /* nam[addr] for logging */ 99 int log_mask; /* What to log */ 100 int session_reused; /* this session was reused */ 101 int am_server; /* Are we an SSL server or client? */ 102 /* Built-in vs external SSL_accept/read/write/shutdown support. */ 103 char *fpt_dgst; /* Certificate fingerprint digest */ 104 VSTREAM *stream; /* Blocking-mode SMTP session */ 105 } TLS_SESS_STATE; 106 107 /* 108 * Peer status bits. TLS_CERT_FLAG_MATCHED implies TLS_CERT_FLAG_TRUSTED 109 * only in the case of a hostname match. 110 */ 111 #define TLS_CERT_FLAG_PRESENT (1<<0) 112 #define TLS_CERT_FLAG_ALTNAME (1<<1) 113 #define TLS_CERT_FLAG_TRUSTED (1<<2) 114 #define TLS_CERT_FLAG_MATCHED (1<<3) 115 116 #define TLS_CERT_IS_PRESENT(c) ((c) && ((c)->peer_status&TLS_CERT_FLAG_PRESENT)) 117 #define TLS_CERT_IS_ALTNAME(c) ((c) && ((c)->peer_status&TLS_CERT_FLAG_ALTNAME)) 118 #define TLS_CERT_IS_TRUSTED(c) ((c) && ((c)->peer_status&TLS_CERT_FLAG_TRUSTED)) 119 #define TLS_CERT_IS_MATCHED(c) ((c) && ((c)->peer_status&TLS_CERT_FLAG_MATCHED)) 120 121 /* 122 * Opaque client context handle. 123 */ 124 typedef struct TLS_APPL_STATE TLS_APPL_STATE; 125 126 #ifdef TLS_INTERNAL 127 128 /* 129 * Log mask details are internal to the library. 130 */ 131 extern int tls_log_mask(const char *, const char *); 132 133 /* 134 * What to log. 135 */ 136 #define TLS_LOG_NONE (1<<0) 137 #define TLS_LOG_SUMMARY (1<<1) 138 #define TLS_LOG_UNTRUSTED (1<<2) 139 #define TLS_LOG_PEERCERT (1<<3) 140 #define TLS_LOG_CERTMATCH (1<<4) 141 #define TLS_LOG_VERBOSE (1<<5) 142 #define TLS_LOG_CACHE (1<<6) 143 #define TLS_LOG_DEBUG (1<<7) 144 #define TLS_LOG_TLSPKTS (1<<8) 145 #define TLS_LOG_ALLPKTS (1<<9) 146 147 /* 148 * Client and Server application contexts 149 */ 150 struct TLS_APPL_STATE { 151 SSL_CTX *ssl_ctx; 152 int log_mask; 153 char *cache_type; 154 char *cipher_exclusions; /* Last cipher selection state */ 155 char *cipher_list; /* Last cipher selection state */ 156 int cipher_grade; /* Last cipher selection state */ 157 VSTRING *why; 158 }; 159 160 /* 161 * tls_misc.c One time finalization of application context. 162 */ 163 extern void tls_free_app_context(TLS_APPL_STATE *); 164 165 /* 166 * tls_misc.c 167 */ 168 169 extern void tls_param_init(void); 170 171 /* 172 * Protocol selection. 173 */ 174 #define TLS_PROTOCOL_INVALID (~0) /* All protocol bits masked */ 175 #define TLS_PROTOCOL_SSLv2 (1<<0) /* SSLv2 */ 176 #define TLS_PROTOCOL_SSLv3 (1<<1) /* SSLv3 */ 177 #define TLS_PROTOCOL_TLSv1 (1<<2) /* TLSv1 */ 178 #ifdef SSL_TXT_TLSV1_1 179 #define TLS_PROTOCOL_TLSv1_1 (1<<3) /* TLSv1_1 */ 180 #else 181 #define TLS_PROTOCOL_TLSv1_1 0 /* Unknown */ 182 #undef SSL_OP_NO_TLSv1_1 183 #define SSL_OP_NO_TLSv1_1 0L /* Noop */ 184 #endif 185 #ifdef SSL_TXT_TLSV1_2 186 #define TLS_PROTOCOL_TLSv1_2 (1<<4) /* TLSv1_2 */ 187 #else 188 #define TLS_PROTOCOL_TLSv1_2 0 /* Unknown */ 189 #undef SSL_OP_NO_TLSv1_2 190 #define SSL_OP_NO_TLSv1_2 0L /* Noop */ 191 #endif 192 #define TLS_KNOWN_PROTOCOLS \ 193 ( TLS_PROTOCOL_SSLv2 | TLS_PROTOCOL_SSLv3 | TLS_PROTOCOL_TLSv1 \ 194 | TLS_PROTOCOL_TLSv1_1 | TLS_PROTOCOL_TLSv1_2 ) 195 196 extern int tls_protocol_mask(const char *); 197 198 /* 199 * Cipher grade selection. 200 */ 201 #define TLS_CIPHER_NONE 0 202 #define TLS_CIPHER_NULL 1 203 #define TLS_CIPHER_EXPORT 2 204 #define TLS_CIPHER_LOW 3 205 #define TLS_CIPHER_MEDIUM 4 206 #define TLS_CIPHER_HIGH 5 207 208 extern const NAME_CODE tls_cipher_grade_table[]; 209 210 #define tls_cipher_grade(str) \ 211 name_code(tls_cipher_grade_table, NAME_CODE_FLAG_NONE, (str)) 212 #define str_tls_cipher_grade(gr) \ 213 str_name_code(tls_cipher_grade_table, (gr)) 214 215 /* 216 * Cipher lists with exclusions. 217 */ 218 extern const char *tls_set_ciphers(TLS_APPL_STATE *, const char *, 219 const char *, const char *); 220 221 #endif 222 223 /* 224 * tls_client.c 225 */ 226 typedef struct { 227 const char *log_param; 228 const char *log_level; 229 int verifydepth; 230 const char *cache_type; 231 const char *cert_file; 232 const char *key_file; 233 const char *dcert_file; 234 const char *dkey_file; 235 const char *eccert_file; 236 const char *eckey_file; 237 const char *CAfile; 238 const char *CApath; 239 const char *fpt_dgst; /* Fingerprint digest algorithm */ 240 } TLS_CLIENT_INIT_PROPS; 241 242 typedef struct { 243 TLS_APPL_STATE *ctx; 244 VSTREAM *stream; 245 int timeout; 246 int tls_level; /* Security level */ 247 const char *nexthop; /* destination domain */ 248 const char *host; /* MX hostname */ 249 const char *namaddr; /* nam[addr] for logging */ 250 const char *serverid; /* Session cache key */ 251 const char *protocols; /* Enabled protocols */ 252 const char *cipher_grade; /* Minimum cipher grade */ 253 const char *cipher_exclusions; /* Ciphers to exclude */ 254 const ARGV *matchargv; /* Cert match patterns */ 255 const char *fpt_dgst; /* Fingerprint digest algorithm */ 256 } TLS_CLIENT_START_PROPS; 257 258 extern TLS_APPL_STATE *tls_client_init(const TLS_CLIENT_INIT_PROPS *); 259 extern TLS_SESS_STATE *tls_client_start(const TLS_CLIENT_START_PROPS *); 260 261 #define tls_client_stop(ctx, stream, timeout, failure, TLScontext) \ 262 tls_session_stop(ctx, (stream), (timeout), (failure), (TLScontext)) 263 264 #define TLS_CLIENT_INIT(props, a1, a2, a3, a4, a5, a6, a7, a8, a9, \ 265 a10, a11, a12, a13) \ 266 tls_client_init((((props)->a1), ((props)->a2), ((props)->a3), \ 267 ((props)->a4), ((props)->a5), ((props)->a6), ((props)->a7), \ 268 ((props)->a8), ((props)->a9), ((props)->a10), ((props)->a11), \ 269 ((props)->a12), ((props)->a13), (props))) 270 271 #define TLS_CLIENT_START(props, a1, a2, a3, a4, a5, a6, a7, a8, a9, \ 272 a10, a11, a12, a13) \ 273 tls_client_start((((props)->a1), ((props)->a2), ((props)->a3), \ 274 ((props)->a4), ((props)->a5), ((props)->a6), ((props)->a7), \ 275 ((props)->a8), ((props)->a9), ((props)->a10), ((props)->a11), \ 276 ((props)->a12), ((props)->a13), (props))) 277 278 /* 279 * tls_server.c 280 */ 281 typedef struct { 282 const char *log_param; 283 const char *log_level; 284 int verifydepth; 285 const char *cache_type; 286 long scache_timeout; 287 int set_sessid; 288 const char *cert_file; 289 const char *key_file; 290 const char *dcert_file; 291 const char *dkey_file; 292 const char *eccert_file; 293 const char *eckey_file; 294 const char *CAfile; 295 const char *CApath; 296 const char *protocols; 297 const char *eecdh_grade; 298 const char *dh1024_param_file; 299 const char *dh512_param_file; 300 int ask_ccert; 301 const char *fpt_dgst; /* Fingerprint digest algorithm */ 302 } TLS_SERVER_INIT_PROPS; 303 304 typedef struct { 305 TLS_APPL_STATE *ctx; /* TLS application context */ 306 VSTREAM *stream; /* Client stream */ 307 int fd; /* Event-driven file descriptor */ 308 int timeout; /* TLS handshake timeout */ 309 int requirecert; /* Insist on client cert? */ 310 const char *serverid; /* Server instance (salt cache key) */ 311 const char *namaddr; /* Client nam[addr] for logging */ 312 const char *cipher_grade; 313 const char *cipher_exclusions; 314 const char *fpt_dgst; /* Fingerprint digest algorithm */ 315 } TLS_SERVER_START_PROPS; 316 317 extern TLS_APPL_STATE *tls_server_init(const TLS_SERVER_INIT_PROPS *); 318 extern TLS_SESS_STATE *tls_server_start(const TLS_SERVER_START_PROPS *props); 319 extern TLS_SESS_STATE *tls_server_post_accept(TLS_SESS_STATE *); 320 321 #define tls_server_stop(ctx, stream, timeout, failure, TLScontext) \ 322 tls_session_stop(ctx, (stream), (timeout), (failure), (TLScontext)) 323 324 #define TLS_SERVER_INIT(props, a1, a2, a3, a4, a5, a6, a7, a8, a9, \ 325 a10, a11, a12, a13, a14, a15, a16, a17, a18, a19, a20) \ 326 tls_server_init((((props)->a1), ((props)->a2), ((props)->a3), \ 327 ((props)->a4), ((props)->a5), ((props)->a6), ((props)->a7), \ 328 ((props)->a8), ((props)->a9), ((props)->a10), ((props)->a11), \ 329 ((props)->a12), ((props)->a13), ((props)->a14), ((props)->a15), \ 330 ((props)->a16), ((props)->a17), ((props)->a18), ((props)->a19), \ 331 ((props)->a20), (props))) 332 333 #define TLS_SERVER_START(props, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10) \ 334 tls_server_start((((props)->a1), ((props)->a2), ((props)->a3), \ 335 ((props)->a4), ((props)->a5), ((props)->a6), ((props)->a7), \ 336 ((props)->a8), ((props)->a9), ((props)->a10), (props))) 337 338 /* 339 * tls_session.c 340 */ 341 extern void tls_session_stop(TLS_APPL_STATE *, VSTREAM *, int, int, TLS_SESS_STATE *); 342 343 #ifdef TLS_INTERNAL 344 345 #include <vstring.h> 346 347 extern VSTRING *tls_session_passivate(SSL_SESSION *); 348 extern SSL_SESSION *tls_session_activate(const char *, int); 349 350 /* 351 * tls_stream.c. 352 */ 353 extern void tls_stream_start(VSTREAM *, TLS_SESS_STATE *); 354 extern void tls_stream_stop(VSTREAM *); 355 356 /* 357 * tls_bio_ops.c: a generic multi-personality driver that retries SSL 358 * operations until they are satisfied or until a hard error happens. 359 * Because of its ugly multi-personality user interface we invoke it via 360 * not-so-ugly single-personality wrappers. 361 */ 362 extern int tls_bio(int, int, TLS_SESS_STATE *, 363 int (*) (SSL *), /* handshake */ 364 int (*) (SSL *, void *, int), /* read */ 365 int (*) (SSL *, const void *, int), /* write */ 366 void *, int); 367 368 #define tls_bio_connect(fd, timeout, context) \ 369 tls_bio((fd), (timeout), (context), SSL_connect, \ 370 NULL, NULL, NULL, 0) 371 #define tls_bio_accept(fd, timeout, context) \ 372 tls_bio((fd), (timeout), (context), SSL_accept, \ 373 NULL, NULL, NULL, 0) 374 #define tls_bio_shutdown(fd, timeout, context) \ 375 tls_bio((fd), (timeout), (context), SSL_shutdown, \ 376 NULL, NULL, NULL, 0) 377 #define tls_bio_read(fd, buf, len, timeout, context) \ 378 tls_bio((fd), (timeout), (context), NULL, \ 379 SSL_read, NULL, (buf), (len)) 380 #define tls_bio_write(fd, buf, len, timeout, context) \ 381 tls_bio((fd), (timeout), (context), NULL, \ 382 NULL, SSL_write, (buf), (len)) 383 384 /* 385 * tls_dh.c 386 */ 387 extern void tls_set_dh_from_file(const char *, int); 388 extern DH *tls_tmp_dh_cb(SSL *, int, int); 389 extern int tls_set_eecdh_curve(SSL_CTX *, const char *); 390 391 /* 392 * tls_rsa.c 393 */ 394 extern RSA *tls_tmp_rsa_cb(SSL *, int, int); 395 396 /* 397 * tls_verify.c 398 */ 399 extern char *tls_peer_CN(X509 *, const TLS_SESS_STATE *); 400 extern char *tls_issuer_CN(X509 *, const TLS_SESS_STATE *); 401 extern const char *tls_dns_name(const GENERAL_NAME *, const TLS_SESS_STATE *); 402 extern char *tls_fingerprint(X509 *, const char *); 403 extern char *tls_pkey_fprint(X509 *, const char *); 404 extern int tls_verify_certificate_callback(int, X509_STORE_CTX *); 405 406 /* 407 * tls_certkey.c 408 */ 409 extern int tls_set_ca_certificate_info(SSL_CTX *, const char *, const char *); 410 extern int tls_set_my_certificate_key_info(SSL_CTX *, 411 /* RSA */ const char *, const char *, 412 /* DSA */ const char *, const char *, 413 /* ECDSA */ const char *, const char *); 414 415 /* 416 * tls_misc.c 417 */ 418 extern int TLScontext_index; 419 420 extern TLS_APPL_STATE *tls_alloc_app_context(SSL_CTX *, int); 421 extern TLS_SESS_STATE *tls_alloc_sess_context(int, const char *); 422 extern void tls_free_context(TLS_SESS_STATE *); 423 extern void tls_check_version(void); 424 extern long tls_bug_bits(void); 425 extern void tls_print_errors(void); 426 extern void tls_info_callback(const SSL *, int, int); 427 extern long tls_bio_dump_cb(BIO *, int, const char *, int, long, long); 428 429 /* 430 * tls_seed.c 431 */ 432 extern void tls_int_seed(void); 433 extern int tls_ext_seed(int); 434 435 #endif /* TLS_INTERNAL */ 436 437 /* LICENSE 438 /* .ad 439 /* .fi 440 /* The Secure Mailer license must be distributed with this software. 441 /* AUTHOR(S) 442 /* Wietse Venema 443 /* IBM T.J. Watson Research 444 /* P.O. Box 704 445 /* Yorktown Heights, NY 10598, USA 446 /* 447 /* Victor Duchovni 448 /* Morgan Stanley 449 /*--*/ 450 451 #endif /* USE_TLS */ 452 #endif /* _TLS_H_INCLUDED_ */ 453