diff --git a/docs/3.0-migration-guide.d/key-export.md b/docs/3.0-migration-guide.d/key-export.md new file mode 100644 index 000000000..43781a2fb --- /dev/null +++ b/docs/3.0-migration-guide.d/key-export.md @@ -0,0 +1,28 @@ +SSL key export interface change +------------------------------- + +This affects users of the SSL key export APIs: +``` + mbedtls_ssl_conf_export_keys_cb() + mbedtls_ssl_conf_export_keys_ext_cb() +``` + +The API `mbedtls_ssl_conf_export_keys_ext_cb()` has been removed, +and the function type of key export callback passed to +`mbedtls_ssl_conf_export_keys_cb()` has changed, as follows: +- It no longer exports raw keys and IV. +- A secret type parameter has been added to identify which key + is being exported. For TLS 1.2, only the master secret is + exported, but upcoming TLS 1.3 support will add other kinds of keys. + +For users which do not rely on raw keys and IV, adjusting to the new +callback type should be straightforward - see the example programs +programs/ssl/ssl_client2 and programs/ssl/ssl_server2 for callbacks +for NSSKeylog, EAP-TLS and DTLS-SRTP. + +Users which require access to the raw keys used to secure application +traffic may derive those by hand based on the master secret and the +handshake transcript hashes which can be obtained from the raw data +on the wire. Such users are also encouraged to reach out to the +Mbed TLS team on the mailing list, to let the team know about their +use case.