external/ibm-public/postfix/dist/src/tls/tls.h

   1 /*      $NetBSD$        */
   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_ */