update FAQ
[openssl.git] / ssl / ssl.h
index 2f70067b14571c0c3f0d766eb741e9ef5024ff47..2eccca29e0c22a649bf02633a095409d19b152e0 100644 (file)
--- a/ssl/ssl.h
+++ b/ssl/ssl.h
@@ -433,6 +433,58 @@ typedef struct {
        custom_srv_ext_second_cb_fn fn2; 
        void *arg;
 } custom_srv_ext_record;
+
+/* Callbacks and structures for handling Supplemental Data:
+ *   srv_supp_data_first_cb_fn  - server sends Supplemental Data
+ *   srv_supp_data_second_cb_fn - server receives Supplemental Data
+ *   cli_supp_data_first_cb_fn  - client receives Supplemental Data
+ *   cli_supp_data_second_cb_fn - client sends Supplemental Data
+ *
+ *   All these functions return nonzero on success.  Zero will terminate
+ *   the handshake (and return a specific TLS Fatal alert, if the function
+ *   declaration has an "al" parameter).  -1 for the "sending" functions
+ *   will result in no supplemental data entry being added to the
+ *   supplemental data message for the provided supplemental data type.
+ *
+ *   "supp_data_type" is a Supplemental Data Type from 0-65535.
+ *   "in" is a pointer to TLS "supplemental_data_entry" being provided to the cb.
+ *   "out" is used by the callback to return a pointer to "supplemental data"
+ *     which OpenSSL will later copy into the TLS handshake.  The contents
+ *     of this buffer should not be changed until the handshake is complete.
+ *   "inlen" and "outlen" are Supplemental Data lengths from 0-65535.
+ *   "al" is a TLS "AlertDescription" from 0-255 which WILL be sent as a
+ *     fatal TLS alert, if the callback returns zero.
+ */
+typedef int (*srv_supp_data_first_cb_fn)(SSL *s, unsigned short supp_data_type,
+            const unsigned char **out,
+            unsigned short *outlen, void *arg);
+typedef int (*srv_supp_data_second_cb_fn)(SSL *s, unsigned short supp_data_type,
+            const unsigned char *in,
+            unsigned short inlen, int *al,
+            void *arg);
+
+typedef int (*cli_supp_data_first_cb_fn)(SSL *s, unsigned short supp_data_type,
+            const unsigned char *in,
+            unsigned short inlen, int *al,
+            void *arg);
+typedef int (*cli_supp_data_second_cb_fn)(SSL *s, unsigned short supp_data_type,
+            const unsigned char **out,
+            unsigned short *outlen, void *arg);
+
+typedef struct {
+       unsigned short supp_data_type;
+       srv_supp_data_first_cb_fn fn1;
+       srv_supp_data_second_cb_fn fn2;
+       void *arg;
+} srv_supp_data_record;
+
+typedef struct {
+       unsigned short supp_data_type;
+       cli_supp_data_first_cb_fn fn1;
+       cli_supp_data_second_cb_fn fn2;
+       void *arg;
+} cli_supp_data_record;
+
 #endif
 
 #ifndef OPENSSL_NO_SSL_INTERN
@@ -596,13 +648,6 @@ struct ssl_session_st
 #endif
 #ifndef OPENSSL_NO_SRP
        char *srp_username;
-#endif
-#ifndef OPENSSL_NO_TLSEXT
-       /* Used by client: the proof for this session.
-        * We store it outside the sess_cert structure, since the proof
-        * is received before the certificate. */
-       unsigned char *audit_proof;
-       size_t audit_proof_length;
 #endif
        };
 
@@ -707,6 +752,12 @@ struct ssl_session_st
  * TLS only.)  "Released" buffers are put onto a free-list in the context
  * or just freed (depending on the context's setting for freelist_max_len). */
 #define SSL_MODE_RELEASE_BUFFERS 0x00000010L
+/* Send the current time in the Random fields of the ClientHello and
+ * ServerHello records for compatibility with hypothetical implementations
+ * that require it.
+ */
+#define SSL_MODE_SEND_CLIENTHELLO_TIME 0x00000020L
+#define SSL_MODE_SEND_SERVERHELLO_TIME 0x00000040L
 
 /* Cert related flags */
 /* Many implementations ignore some aspects of the TLS standards such as
@@ -757,6 +808,12 @@ struct ssl_session_st
 #define SSL_CONF_FLAG_CLIENT           0x4
 #define SSL_CONF_FLAG_SERVER           0x8
 #define SSL_CONF_FLAG_SHOW_ERRORS      0x10
+#define SSL_CONF_FLAG_CERTIFICATE      0x20
+/* Configuration value types */
+#define SSL_CONF_TYPE_UNKNOWN          0x0
+#define SSL_CONF_TYPE_STRING           0x1
+#define SSL_CONF_TYPE_FILE             0x2
+#define SSL_CONF_TYPE_DIR              0x3
 
 /* Note: SSL[_CTX]_set_{options,mode} use |= op on the previous value,
  * they cannot be used to clear bits. */
@@ -1138,14 +1195,17 @@ struct ssl_ctx_st
        size_t tlsext_ellipticcurvelist_length;
        unsigned char *tlsext_ellipticcurvelist;
 # endif /* OPENSSL_NO_EC */
-       int (*tlsext_authz_server_audit_proof_cb)(SSL *s, void *arg);
-       void *tlsext_authz_server_audit_proof_cb_arg;
-
        /* Arrays containing the callbacks for custom TLS Extensions. */
        custom_cli_ext_record *custom_cli_ext_records;
        size_t custom_cli_ext_records_count;
        custom_srv_ext_record *custom_srv_ext_records;
        size_t custom_srv_ext_records_count;
+
+       /* Arrays containing the callbacks for Supplemental Data. */
+       cli_supp_data_record *cli_supp_data_records;
+       size_t cli_supp_data_records_count;
+       srv_supp_data_record *srv_supp_data_records;
+       size_t srv_supp_data_records_count;
        };
 
 #endif
@@ -1214,19 +1274,20 @@ void SSL_CTX_set_next_proto_select_cb(SSL_CTX *s,
                                                 const unsigned char *in,
                                                 unsigned int inlen, void *arg),
                                      void *arg);
+void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data,
+                                   unsigned *len);
+#endif
 
+#ifndef OPENSSL_NO_TLSEXT
 int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
                          const unsigned char *in, unsigned int inlen,
                          const unsigned char *client, unsigned int client_len);
-void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data,
-                                   unsigned *len);
+#endif
 
 #define OPENSSL_NPN_UNSUPPORTED        0
 #define OPENSSL_NPN_NEGOTIATED 1
 #define OPENSSL_NPN_NO_OVERLAP 2
 
-#endif
-
 int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char* protos,
                            unsigned protos_len);
 int SSL_set_alpn_protos(SSL *ssl, const unsigned char* protos,
@@ -1291,6 +1352,31 @@ int SSL_CTX_set_custom_cli_ext(SSL_CTX *ctx, unsigned short ext_type,
 int SSL_CTX_set_custom_srv_ext(SSL_CTX *ctx, unsigned short ext_type,
                               custom_srv_ext_first_cb_fn fn1, 
                               custom_srv_ext_second_cb_fn fn2, void *arg);
+
+/* Register callbacks to handle Supplemental Data as client or server.
+ *
+ * For SSL_CTX_set_srv_supp_data, a NULL srv_supp_data_first_cb_fn results in no supplemental data
+ * being sent by the server for that TLS extension.
+ * A NULL srv_supp_data_second_cb_fn results in no supplemental data
+ * being received by the server for that TLS extension.
+ *
+ * For SSL_CTX_set_cli_supp_data, a NULL cli_supp_data_first_cb_fn results in no supplemental data
+ * being received by the client for that TLS extension.
+ * A NULL cli_supp_data_second_cb_fn results in no supplemental data
+ * being sent by the client for that TLS extension.
+ *
+ * Returns nonzero on success.  You cannot register twice for the same supp_data_type.
+ */
+int SSL_CTX_set_srv_supp_data(SSL_CTX *ctx,
+                             unsigned short supp_data_type,
+                             srv_supp_data_first_cb_fn fn1,
+                             srv_supp_data_second_cb_fn fn2, void *arg);
+
+int SSL_CTX_set_cli_supp_data(SSL_CTX *ctx,
+                             unsigned short supp_data_type,
+                             cli_supp_data_first_cb_fn fn1,
+                             cli_supp_data_second_cb_fn fn2, void *arg);
+
 #endif
 
 #define SSL_NOTHING    1
@@ -1812,9 +1898,6 @@ DECLARE_PEM_rw(SSL_SESSION, SSL_SESSION)
 #define SSL_CTRL_GET_TLS_EXT_HEARTBEAT_PENDING         86
 #define SSL_CTRL_SET_TLS_EXT_HEARTBEAT_NO_REQUESTS     87
 #endif
-/* Callback for verifying audit proofs (client only) */
-#define SSL_CTRL_SET_TLSEXT_AUTHZ_SERVER_AUDIT_PROOF_CB 95
-#define SSL_CTRL_SET_TLSEXT_AUTHZ_SERVER_AUDIT_PROOF_CB_ARG 96
 #endif /* OPENSSL_NO_TLSEXT */
 
 #define DTLS_CTRL_GET_TIMEOUT          73
@@ -1853,6 +1936,9 @@ DECLARE_PEM_rw(SSL_SESSION, SSL_SESSION)
 #define SSL_CTRL_GET_RAW_CIPHERLIST            110
 #define SSL_CTRL_GET_EC_POINT_FORMATS          111
 
+#define SSL_CTRL_GET_CHAIN_CERTS               115
+#define SSL_CTRL_SELECT_CURRENT_CERT           116
+
 #define DTLSv1_get_timeout(ssl, arg) \
        SSL_ctrl(ssl,DTLS_CTRL_GET_TIMEOUT,0, (void *)arg)
 #define DTLSv1_handle_timeout(ssl) \
@@ -1902,8 +1988,14 @@ DECLARE_PEM_rw(SSL_SESSION, SSL_SESSION)
        SSL_CTX_ctrl(ctx,SSL_CTRL_CHAIN_CERT,0,(char *)x509)
 #define SSL_CTX_add1_chain_cert(ctx,x509) \
        SSL_CTX_ctrl(ctx,SSL_CTRL_CHAIN_CERT,1,(char *)x509)
+#define SSL_CTX_get0_chain_certs(ctx,px509) \
+       SSL_CTX_ctrl(ctx,SSL_CTRL_GET_CHAIN_CERTS,0,px509)
+#define SSL_CTX_clear_chain_certs(ctx) \
+       SSL_CTX_set0_chain(ctx,NULL)
 #define SSL_CTX_build_cert_chain(ctx, flags) \
        SSL_CTX_ctrl(ctx,SSL_CTRL_BUILD_CERT_CHAIN, flags, NULL)
+#define SSL_CTX_select_current_cert(ctx,x509) \
+       SSL_CTX_ctrl(ctx,SSL_CTRL_SELECT_CURRENT_CERT,0,(char *)x509)
 
 #define SSL_CTX_set0_verify_cert_store(ctx,st) \
        SSL_CTX_ctrl(ctx,SSL_CTRL_SET_VERIFY_CERT_STORE,0,(char *)st)
@@ -1922,8 +2014,15 @@ DECLARE_PEM_rw(SSL_SESSION, SSL_SESSION)
        SSL_ctrl(ctx,SSL_CTRL_CHAIN_CERT,0,(char *)x509)
 #define SSL_add1_chain_cert(ctx,x509) \
        SSL_ctrl(ctx,SSL_CTRL_CHAIN_CERT,1,(char *)x509)
+#define SSL_get0_chain_certs(ctx,px509) \
+       SSL_ctrl(ctx,SSL_CTRL_GET_CHAIN_CERTS,0,px509)
+#define SSL_clear_chain_certs(ctx) \
+       SSL_set0_chain(ctx,NULL)
 #define SSL_build_cert_chain(s, flags) \
        SSL_ctrl(s,SSL_CTRL_BUILD_CERT_CHAIN, flags, NULL)
+#define SSL_select_current_cert(ctx,x509) \
+       SSL_ctrl(ctx,SSL_CTRL_SELECT_CURRENT_CERT,0,(char *)x509)
+
 #define SSL_set0_verify_cert_store(s,st) \
        SSL_ctrl(s,SSL_CTRL_SET_VERIFY_CERT_STORE,0,(char *)st)
 #define SSL_set1_verify_cert_store(s,st) \
@@ -2052,17 +2151,6 @@ int      SSL_use_certificate(SSL *ssl, X509 *x);
 int    SSL_use_certificate_ASN1(SSL *ssl, const unsigned char *d, int len);
 
 #ifndef OPENSSL_NO_TLSEXT
-/* Set authz data for the current active cert. */
-int    SSL_CTX_use_authz(SSL_CTX *ctx, unsigned char *authz, size_t authz_length);
-int    SSL_use_authz(SSL *ssl, unsigned char *authz, size_t authz_length);
-/* Get the authz of type 'type' associated with the current active cert. */
-const unsigned char *SSL_CTX_get_authz_data(SSL_CTX *ctx, unsigned char type,
-                                           size_t *data_length);
-#ifndef OPENSSL_NO_STDIO
-int    SSL_CTX_use_authz_file(SSL_CTX *ctx, const char *file);
-int    SSL_use_authz_file(SSL *ssl, const char *file);
-#endif
-
 /* Set serverinfo data for the current active cert. */
 int    SSL_CTX_use_serverinfo(SSL_CTX *ctx, const unsigned char *serverinfo,
                               size_t serverinfo_length);
@@ -2116,10 +2204,6 @@ int      SSL_SESSION_print_fp(FILE *fp,const SSL_SESSION *ses);
 #ifndef OPENSSL_NO_BIO
 int    SSL_SESSION_print(BIO *fp,const SSL_SESSION *ses);
 #endif
-#ifndef OPENSSL_NO_TLSEXT
-unsigned char *SSL_SESSION_get_tlsext_authz_server_audit_proof(SSL_SESSION *s,
-       size_t *proof_length);
-#endif
 void   SSL_SESSION_free(SSL_SESSION *ses);
 int    i2d_SSL_SESSION(SSL_SESSION *in,unsigned char **pp);
 int    SSL_set_session(SSL *to, SSL_SESSION *session);
@@ -2177,6 +2261,9 @@ int SSL_set_trust(SSL *s, int trust);
 int SSL_CTX_set1_param(SSL_CTX *ctx, X509_VERIFY_PARAM *vpm);
 int SSL_set1_param(SSL *ssl, X509_VERIFY_PARAM *vpm);
 
+X509_VERIFY_PARAM *SSL_CTX_get0_param(SSL_CTX *ctx);
+X509_VERIFY_PARAM *SSL_get0_param(SSL *ssl);
+
 #ifndef OPENSSL_NO_SRP
 int SSL_CTX_set_srp_username(SSL_CTX *ctx,char *name);
 int SSL_CTX_set_srp_password(SSL_CTX *ctx,char *password);
@@ -2293,7 +2380,10 @@ STACK_OF(X509_NAME) *SSL_dup_CA_list(STACK_OF(X509_NAME) *sk);
 SSL *SSL_dup(SSL *ssl);
 
 X509 *SSL_get_certificate(const SSL *ssl);
-/* EVP_PKEY */ struct evp_pkey_st *SSL_get_privatekey(SSL *ssl);
+/* EVP_PKEY */ struct evp_pkey_st *SSL_get_privatekey(const SSL *ssl);
+
+X509 *SSL_CTX_get0_certificate(const SSL_CTX *ctx);
+EVP_PKEY *SSL_CTX_get0_privatekey(const SSL_CTX *ctx);
 
 void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx,int mode);
 int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx);
@@ -2428,6 +2518,7 @@ int SSL_cache_hit(SSL *s);
 int SSL_is_server(SSL *s);
 
 SSL_CONF_CTX *SSL_CONF_CTX_new(void);
+int SSL_CONF_CTX_finish(SSL_CONF_CTX *cctx);
 void SSL_CONF_CTX_free(SSL_CONF_CTX *cctx);
 unsigned int SSL_CONF_CTX_set_flags(SSL_CONF_CTX *cctx, unsigned int flags);
 unsigned int SSL_CONF_CTX_clear_flags(SSL_CONF_CTX *cctx, unsigned int flags);
@@ -2438,6 +2529,7 @@ void SSL_CONF_CTX_set_ssl_ctx(SSL_CONF_CTX *cctx, SSL_CTX *ctx);
 
 int SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value);
 int SSL_CONF_cmd_argv(SSL_CONF_CTX *cctx, int *pargc, char ***pargv);
+int SSL_CONF_cmd_value_type(SSL_CONF_CTX *cctx, const char *cmd);
 
 #ifndef OPENSSL_NO_SSL_TRACE
 void SSL_trace(int write_p, int version, int content_type,
@@ -2456,7 +2548,7 @@ void ERR_load_SSL_strings(void);
 /* Function codes. */
 #define SSL_F_AUTHZ_FIND_DATA                           330
 #define SSL_F_AUTHZ_VALIDATE                            323
-#define SSL_F_CHECK_SUITEB_CIPHER_LIST                  335
+#define SSL_F_CHECK_SUITEB_CIPHER_LIST                  331
 #define SSL_F_CLIENT_CERTIFICATE                        100
 #define SSL_F_CLIENT_FINISHED                           167
 #define SSL_F_CLIENT_HELLO                              101
@@ -2622,8 +2714,9 @@ void ERR_load_SSL_strings(void);
 #define SSL_F_SSL_DO_HANDSHAKE                          180
 #define SSL_F_SSL_GET_NEW_SESSION                       181
 #define SSL_F_SSL_GET_PREV_SESSION                      217
-#define SSL_F_SSL_GET_SERVER_CERT_INDEX                         331
-#define SSL_F_SSL_GET_SERVER_SEND_PKEY                  182
+#define SSL_F_SSL_GET_SERVER_CERT_INDEX                         322
+#define SSL_F_SSL_GET_SERVER_SEND_CERT                  182
+#define SSL_F_SSL_GET_SERVER_SEND_PKEY                  319
 #define SSL_F_SSL_GET_SIGN_PKEY                                 183
 #define SSL_F_SSL_INIT_WBIO_BUFFER                      184
 #define SSL_F_SSL_LOAD_CLIENT_CA_FILE                   185
@@ -2640,8 +2733,8 @@ void ERR_load_SSL_strings(void);
 #define SSL_F_SSL_READ                                  223
 #define SSL_F_SSL_RSA_PRIVATE_DECRYPT                   187
 #define SSL_F_SSL_RSA_PUBLIC_ENCRYPT                    188
-#define SSL_F_SSL_SCAN_CLIENTHELLO_TLSEXT               319
-#define SSL_F_SSL_SCAN_SERVERHELLO_TLSEXT               320
+#define SSL_F_SSL_SCAN_CLIENTHELLO_TLSEXT               320
+#define SSL_F_SSL_SCAN_SERVERHELLO_TLSEXT               321
 #define SSL_F_SSL_SESSION_NEW                           189
 #define SSL_F_SSL_SESSION_PRINT_FP                      190
 #define SSL_F_SSL_SESSION_SET1_ID_CONTEXT               312
@@ -2682,11 +2775,13 @@ void ERR_load_SSL_strings(void);
 #define SSL_F_TLS1_CHECK_SERVERHELLO_TLSEXT             274
 #define SSL_F_TLS1_ENC                                  210
 #define SSL_F_TLS1_EXPORT_KEYING_MATERIAL               314
+#define SSL_F_TLS1_GET_CLIENT_SUPPLEMENTAL_DATA                 335
 #define SSL_F_TLS1_GET_SERVER_SUPPLEMENTAL_DATA                 326
 #define SSL_F_TLS1_HEARTBEAT                            315
 #define SSL_F_TLS1_PREPARE_CLIENTHELLO_TLSEXT           275
 #define SSL_F_TLS1_PREPARE_SERVERHELLO_TLSEXT           276
 #define SSL_F_TLS1_PRF                                  284
+#define SSL_F_TLS1_SEND_CLIENT_SUPPLEMENTAL_DATA        338
 #define SSL_F_TLS1_SEND_SERVER_SUPPLEMENTAL_DATA        327
 #define SSL_F_TLS1_SETUP_KEY_BLOCK                      211
 #define SSL_F_WRITE_PENDING                             212
@@ -2699,6 +2794,7 @@ void ERR_load_SSL_strings(void);
 #define SSL_R_BAD_AUTHENTICATION_TYPE                   102
 #define SSL_R_BAD_CHANGE_CIPHER_SPEC                    103
 #define SSL_R_BAD_CHECKSUM                              104
+#define SSL_R_BAD_DATA                                  390
 #define SSL_R_BAD_DATA_RETURNED_BY_CALLBACK             106
 #define SSL_R_BAD_DECOMPRESSION                                 107
 #define SSL_R_BAD_DH_G_LENGTH                           108
@@ -2793,7 +2889,7 @@ void ERR_load_SSL_strings(void);
 #define SSL_R_INVALID_COMPRESSION_ALGORITHM             341
 #define SSL_R_INVALID_NULL_CMD_NAME                     385
 #define SSL_R_INVALID_PURPOSE                           278
-#define SSL_R_INVALID_SERVERINFO_DATA                   389
+#define SSL_R_INVALID_SERVERINFO_DATA                   388
 #define SSL_R_INVALID_SRP_USERNAME                      357
 #define SSL_R_INVALID_STATUS_RESPONSE                   328
 #define SSL_R_INVALID_TICKET_KEYS_LENGTH                325
@@ -2849,6 +2945,7 @@ void ERR_load_SSL_strings(void);
 #define SSL_R_NO_COMPRESSION_SPECIFIED                  187
 #define SSL_R_NO_GOST_CERTIFICATE_SENT_BY_PEER          330
 #define SSL_R_NO_METHOD_SPECIFIED                       188
+#define SSL_R_NO_PEM_EXTENSIONS                                 389
 #define SSL_R_NO_PRIVATEKEY                             189
 #define SSL_R_NO_PRIVATE_KEY_ASSIGNED                   190
 #define SSL_R_NO_PROTOCOLS_AVAILABLE                    191
@@ -2876,6 +2973,8 @@ void ERR_load_SSL_strings(void);
 #define SSL_R_PEER_ERROR_NO_CERTIFICATE                         202
 #define SSL_R_PEER_ERROR_NO_CIPHER                      203
 #define SSL_R_PEER_ERROR_UNSUPPORTED_CERTIFICATE_TYPE   204
+#define SSL_R_PEM_NAME_BAD_PREFIX                       391
+#define SSL_R_PEM_NAME_TOO_SHORT                        392
 #define SSL_R_PRE_MAC_LENGTH_TOO_LONG                   205
 #define SSL_R_PROBLEMS_MAPPING_CIPHER_FUNCTIONS                 206
 #define SSL_R_PROTOCOL_IS_SHUTDOWN                      207
@@ -2959,7 +3058,7 @@ void ERR_load_SSL_strings(void);
 #define SSL_R_TLS_INVALID_ECPOINTFORMAT_LIST            157
 #define SSL_R_TLS_PEER_DID_NOT_RESPOND_WITH_CERTIFICATE_LIST 233
 #define SSL_R_TLS_RSA_ENCRYPTED_VALUE_LENGTH_IS_WRONG   234
-#define SSL_R_TOO_MANY_EMPTY_FRAGMENTS                  388
+#define SSL_R_TOO_MANY_EMPTY_FRAGMENTS                  393
 #define SSL_R_TRIED_TO_USE_UNSUPPORTED_CIPHER           235
 #define SSL_R_UNABLE_TO_DECODE_DH_CERTS                         236
 #define SSL_R_UNABLE_TO_DECODE_ECDH_CERTS               313