mbedtls/docs/3.0-migration-guide.d/key-export.md

37 lines
1.5 KiB
Markdown
Raw Normal View History

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()
```
Those APIs have been removed and replaced by the new API
`mbedtls_ssl_set_export_keys_cb()`. This API differs from
the previous key export API in the following ways:
- It is no longer bound to an SSL configuration, but to an
SSL context. This allows users to more easily identify the
connection an exported key belongs to.
- 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.
- The callback now specifies a void return type, rather than
returning an error code. It is the responsibility of the application
to handle failures in the key export callback, for example by
shutting down the TLS connection.
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.