1 /* $NetBSD: tls.h,v 1.1.1.1 2009/06/23 10:08:57 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 #define TLS_BIO_BUFSIZE 8192 69 70 /* 71 * Names of valid tlsmgr(8) session caches. 72 */ 73 #define TLS_MGR_SCACHE_SMTPD "smtpd" 74 #define TLS_MGR_SCACHE_SMTP "smtp" 75 #define TLS_MGR_SCACHE_LMTP "lmtp" 76 77 /* 78 * TLS session context, also used by the VSTREAM call-back routines for SMTP 79 * input/output, and by OpenSSL call-back routines for key verification. 80 * 81 * Only some members are (read-only) accessible by the public. 82 */ 83 #define CCERT_BUFSIZ 256 84 85 typedef struct { 86 /* Public, read-only. */ 87 char *peer_CN; /* Peer Common Name */ 88 char *issuer_CN; /* Issuer Common Name */ 89 char *peer_fingerprint; /* ASCII fingerprint */ 90 int peer_status; /* Certificate and match status */ 91 const char *protocol; 92 const char *cipher_name; 93 int cipher_usebits; 94 int cipher_algbits; 95 /* Private. */ 96 SSL *con; 97 BIO *internal_bio; /* postfix/TLS side of pair */ 98 BIO *network_bio; /* network side of pair */ 99 char *cache_type; /* tlsmgr(8) cache type if enabled */ 100 char *serverid; /* unique server identifier */ 101 char *namaddr; /* nam[addr] for logging */ 102 int log_level; /* TLS library logging level */ 103 int session_reused; /* this session was reused */ 104 int am_server; /* Are we an SSL server or client? */ 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 #define TLS_CERT_FLAG_LOGGED (1<<4) /* Logged trust chain error */ 116 117 #define TLS_CERT_IS_PRESENT(c) ((c) && ((c)->peer_status&TLS_CERT_FLAG_PRESENT)) 118 #define TLS_CERT_IS_ALTNAME(c) ((c) && ((c)->peer_status&TLS_CERT_FLAG_ALTNAME)) 119 #define TLS_CERT_IS_TRUSTED(c) ((c) && ((c)->peer_status&TLS_CERT_FLAG_TRUSTED)) 120 #define TLS_CERT_IS_MATCHED(c) ((c) && ((c)->peer_status&TLS_CERT_FLAG_MATCHED)) 121 122 /* 123 * Opaque client context handle. 124 */ 125 typedef struct TLS_APPL_STATE TLS_APPL_STATE; 126 127 #ifdef TLS_INTERNAL 128 129 /* 130 * Client and Server application contexts 131 */ 132 struct TLS_APPL_STATE { 133 SSL_CTX *ssl_ctx; 134 char *cache_type; 135 char *cipher_exclusions; /* Last cipher selection state */ 136 char *cipher_list; /* Last cipher selection state */ 137 int cipher_grade; /* Last cipher selection state */ 138 VSTRING *why; 139 }; 140 141 /* 142 * tls_misc.c One time finalization of application context. 143 */ 144 extern void tls_free_app_context(TLS_APPL_STATE *); 145 146 /* 147 * tls_misc.c 148 */ 149 150 extern void tls_param_init(void); 151 152 /* 153 * Protocol selection. 154 */ 155 #define TLS_PROTOCOL_INVALID (~0) /* All protocol bits masked */ 156 #define TLS_PROTOCOL_SSLv2 (1<<0) /* SSLv2 */ 157 #define TLS_PROTOCOL_SSLv3 (1<<1) /* SSLv3 */ 158 #define TLS_PROTOCOL_TLSv1 (1<<2) /* TLSv1 */ 159 #define TLS_KNOWN_PROTOCOLS \ 160 ( TLS_PROTOCOL_SSLv2 | TLS_PROTOCOL_SSLv3 | TLS_PROTOCOL_TLSv1 ) 161 162 extern int tls_protocol_mask(const char *); 163 164 /* 165 * Cipher grade selection. 166 */ 167 #define TLS_CIPHER_NONE 0 168 #define TLS_CIPHER_NULL 1 169 #define TLS_CIPHER_EXPORT 2 170 #define TLS_CIPHER_LOW 3 171 #define TLS_CIPHER_MEDIUM 4 172 #define TLS_CIPHER_HIGH 5 173 174 extern const NAME_CODE tls_cipher_grade_table[]; 175 176 #define tls_cipher_grade(str) \ 177 name_code(tls_cipher_grade_table, NAME_CODE_FLAG_NONE, (str)) 178 #define str_tls_cipher_grade(gr) \ 179 str_name_code(tls_cipher_grade_table, (gr)) 180 181 /* 182 * Cipher lists with exclusions. 183 */ 184 extern const char *tls_set_ciphers(TLS_APPL_STATE *, const char *, 185 const char *, const char *); 186 187 #endif 188 189 /* 190 * tls_client.c 191 */ 192 typedef struct { 193 int log_level; 194 int verifydepth; 195 const char *cache_type; 196 const char *cert_file; 197 const char *key_file; 198 const char *dcert_file; 199 const char *dkey_file; 200 const char *eccert_file; 201 const char *eckey_file; 202 const char *CAfile; 203 const char *CApath; 204 const char *fpt_dgst; /* Fingerprint digest algorithm */ 205 } TLS_CLIENT_INIT_PROPS; 206 207 typedef struct { 208 TLS_APPL_STATE *ctx; 209 VSTREAM *stream; 210 int log_level; 211 int timeout; 212 int tls_level; /* Security level */ 213 const char *nexthop; /* destination domain */ 214 const char *host; /* MX hostname */ 215 const char *namaddr; /* nam[addr] for logging */ 216 const char *serverid; /* Session cache key */ 217 const char *protocols; /* Enabled protocols */ 218 const char *cipher_grade; /* Minimum cipher grade */ 219 const char *cipher_exclusions; /* Ciphers to exclude */ 220 const ARGV *matchargv; /* Cert match patterns */ 221 const char *fpt_dgst; /* Fingerprint digest algorithm */ 222 } TLS_CLIENT_START_PROPS; 223 224 extern TLS_APPL_STATE *tls_client_init(const TLS_CLIENT_INIT_PROPS *); 225 extern TLS_SESS_STATE *tls_client_start(const TLS_CLIENT_START_PROPS *); 226 227 #define tls_client_stop(ctx, stream, timeout, failure, TLScontext) \ 228 tls_session_stop(ctx, (stream), (timeout), (failure), (TLScontext)) 229 230 #define TLS_CLIENT_INIT(props, a1, a2, a3, a4, a5, a6, a7, a8, a9, \ 231 a10, a11, a12) \ 232 tls_client_init((((props)->a1), ((props)->a2), ((props)->a3), \ 233 ((props)->a4), ((props)->a5), ((props)->a6), ((props)->a7), \ 234 ((props)->a8), ((props)->a9), ((props)->a10), ((props)->a11), \ 235 ((props)->a12), (props))) 236 237 #define TLS_CLIENT_START(props, a1, a2, a3, a4, a5, a6, a7, a8, a9, \ 238 a10, a11, a12, a13, a14) \ 239 tls_client_start((((props)->a1), ((props)->a2), ((props)->a3), \ 240 ((props)->a4), ((props)->a5), ((props)->a6), ((props)->a7), \ 241 ((props)->a8), ((props)->a9), ((props)->a10), ((props)->a11), \ 242 ((props)->a12), ((props)->a13), ((props)->a14), (props))) 243 244 /* 245 * tls_server.c 246 */ 247 typedef struct { 248 int log_level; 249 int verifydepth; 250 const char *cache_type; 251 long scache_timeout; 252 int set_sessid; 253 const char *cert_file; 254 const char *key_file; 255 const char *dcert_file; 256 const char *dkey_file; 257 const char *eccert_file; 258 const char *eckey_file; 259 const char *CAfile; 260 const char *CApath; 261 const char *protocols; 262 const char *eecdh_grade; 263 const char *dh1024_param_file; 264 const char *dh512_param_file; 265 int ask_ccert; 266 const char *fpt_dgst; /* Fingerprint digest algorithm */ 267 } TLS_SERVER_INIT_PROPS; 268 269 typedef struct { 270 TLS_APPL_STATE *ctx; /* TLS application context */ 271 VSTREAM *stream; /* Client stream */ 272 int log_level; /* TLS log level */ 273 int timeout; /* TLS handshake timeout */ 274 int requirecert; /* Insist on client cert? */ 275 const char *serverid; /* Server instance (salt cache key) */ 276 const char *namaddr; /* Client nam[addr] for logging */ 277 const char *cipher_grade; 278 const char *cipher_exclusions; 279 const char *fpt_dgst; /* Fingerprint digest algorithm */ 280 } TLS_SERVER_START_PROPS; 281 282 extern TLS_APPL_STATE *tls_server_init(const TLS_SERVER_INIT_PROPS *); 283 extern TLS_SESS_STATE *tls_server_start(const TLS_SERVER_START_PROPS *props); 284 285 #define tls_server_stop(ctx, stream, timeout, failure, TLScontext) \ 286 tls_session_stop(ctx, (stream), (timeout), (failure), (TLScontext)) 287 288 #define TLS_SERVER_INIT(props, a1, a2, a3, a4, a5, a6, a7, a8, a9, \ 289 a10, a11, a12, a13, a14, a15, a16, a17, a18, a19) \ 290 tls_server_init((((props)->a1), ((props)->a2), ((props)->a3), \ 291 ((props)->a4), ((props)->a5), ((props)->a6), ((props)->a7), \ 292 ((props)->a8), ((props)->a9), ((props)->a10), ((props)->a11), \ 293 ((props)->a12), ((props)->a13), ((props)->a14), ((props)->a15), \ 294 ((props)->a16), ((props)->a17), ((props)->a18), ((props)->a19), (props))) 295 296 #define TLS_SERVER_START(props, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10) \ 297 tls_server_start((((props)->a1), ((props)->a2), ((props)->a3), \ 298 ((props)->a4), ((props)->a5), ((props)->a6), ((props)->a7), \ 299 ((props)->a8), ((props)->a9), ((props)->a10), (props))) 300 301 /* 302 * tls_session.c 303 */ 304 extern void tls_session_stop(TLS_APPL_STATE *, VSTREAM *, int, int, TLS_SESS_STATE *); 305 306 #ifdef TLS_INTERNAL 307 308 #include <vstring.h> 309 310 extern VSTRING *tls_session_passivate(SSL_SESSION *); 311 extern SSL_SESSION *tls_session_activate(const char *, int); 312 313 /* 314 * tls_stream.c. 315 */ 316 extern void tls_stream_start(VSTREAM *, TLS_SESS_STATE *); 317 extern void tls_stream_stop(VSTREAM *); 318 319 /* 320 * tls_bio_ops.c: a generic multi-personality driver that retries SSL 321 * operations until they are satisfied or until a hard error happens. 322 * Because of its ugly multi-personality user interface we invoke it via 323 * not-so-ugly single-personality wrappers. 324 */ 325 extern int tls_bio(int, int, TLS_SESS_STATE *, 326 int (*) (SSL *), /* handshake */ 327 int (*) (SSL *, void *, int), /* read */ 328 int (*) (SSL *, const void *, int), /* write */ 329 void *, int); 330 331 #define tls_bio_connect(fd, timeout, context) \ 332 tls_bio((fd), (timeout), (context), SSL_connect, \ 333 NULL, NULL, NULL, 0) 334 #define tls_bio_accept(fd, timeout, context) \ 335 tls_bio((fd), (timeout), (context), SSL_accept, \ 336 NULL, NULL, NULL, 0) 337 #define tls_bio_shutdown(fd, timeout, context) \ 338 tls_bio((fd), (timeout), (context), SSL_shutdown, \ 339 NULL, NULL, NULL, 0) 340 #define tls_bio_read(fd, buf, len, timeout, context) \ 341 tls_bio((fd), (timeout), (context), NULL, \ 342 SSL_read, NULL, (buf), (len)) 343 #define tls_bio_write(fd, buf, len, timeout, context) \ 344 tls_bio((fd), (timeout), (context), NULL, \ 345 NULL, SSL_write, (buf), (len)) 346 347 /* 348 * tls_dh.c 349 */ 350 extern void tls_set_dh_from_file(const char *, int); 351 extern DH *tls_tmp_dh_cb(SSL *, int, int); 352 extern int tls_set_eecdh_curve(SSL_CTX *, const char *); 353 354 /* 355 * tls_rsa.c 356 */ 357 extern RSA *tls_tmp_rsa_cb(SSL *, int, int); 358 359 /* 360 * tls_verify.c 361 */ 362 extern char *tls_peer_CN(X509 *, const TLS_SESS_STATE *); 363 extern char *tls_issuer_CN(X509 *, const TLS_SESS_STATE *); 364 extern const char *tls_dns_name(const GENERAL_NAME *, const TLS_SESS_STATE *); 365 extern char *tls_fingerprint(X509 *, const char *); 366 extern int tls_verify_certificate_callback(int, X509_STORE_CTX *); 367 368 /* 369 * tls_certkey.c 370 */ 371 extern int tls_set_ca_certificate_info(SSL_CTX *, const char *, const char *); 372 extern int tls_set_my_certificate_key_info(SSL_CTX *, 373 /* RSA */ const char *, const char *, 374 /* DSA */ const char *, const char *, 375 /* ECDSA */ const char *, const char *); 376 377 /* 378 * tls_misc.c 379 */ 380 extern int TLScontext_index; 381 382 extern TLS_APPL_STATE *tls_alloc_app_context(SSL_CTX *); 383 extern TLS_SESS_STATE *tls_alloc_sess_context(int, const char *); 384 extern void tls_free_context(TLS_SESS_STATE *); 385 extern void tls_check_version(void); 386 extern long tls_bug_bits(void); 387 extern void tls_print_errors(void); 388 extern void tls_info_callback(const SSL *, int, int); 389 extern long tls_bio_dump_cb(BIO *, int, const char *, int, long, long); 390 391 /* 392 * tls_seed.c 393 */ 394 extern void tls_int_seed(void); 395 extern int tls_ext_seed(int); 396 397 #endif /* TLS_INTERNAL */ 398 399 /* LICENSE 400 /* .ad 401 /* .fi 402 /* The Secure Mailer license must be distributed with this software. 403 /* AUTHOR(S) 404 /* Wietse Venema 405 /* IBM T.J. Watson Research 406 /* P.O. Box 704 407 /* Yorktown Heights, NY 10598, USA 408 /* 409 /* Victor Duchovni 410 /* Morgan Stanley 411 /*--*/ 412 413 #endif /* USE_TLS */ 414 #endif /* _TLS_H_INCLUDED_ */ 415