Currently, the stack silently ignores DTLS frames with an unexpected CID.
However, in a system which performs CID-based demultiplexing before passing
datagrams to the Mbed TLS stack, unexpected CIDs are a sign of something not
working properly, and users might want to know about it.
This commit introduces an SSL error code MBEDTLS_ERR_SSL_UNEXPECTED_CID
which the stack can return in response to an unexpected CID. It will
conditionally be put to use in subsequent commits.
mbedtls_ssl_context contains pointers in_buf, in_hdr, in_len, ...
which point to various parts of the header of an incoming TLS or
DTLS record; similarly, there are pointers out_buf, ... for
outgoing records.
This commit adds fields in_cid and out_cid which point to where
the CID of incoming/outgoing records should reside, if present,
namely prior to where the record length resides.
Quoting https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-04:
The DTLSInnerPlaintext value is then encrypted and the CID added to
produce the final DTLSCiphertext.
struct {
ContentType special_type = tls12_cid; /* 25 */
ProtocolVersion version;
uint16 epoch;
uint48 sequence_number;
opaque cid[cid_length]; // New field
uint16 length;
opaque enc_content[DTLSCiphertext.length];
} DTLSCiphertext;
For outgoing records, out_cid is set in ssl_update_out_pointers()
based on the settings in the current outgoing transform.
For incoming records, ssl_update_in_pointers() sets in_cid as if no
CID was present, and it is the responsibility of ssl_parse_record_header()
to update the field (as well as in_len, in_msg and in_iv) when parsing
records that do contain a CID. This will be done in a subsequent commit.
Finally, the code around the invocations of ssl_decrypt_buf()
and ssl_encrypt_buf() is adapted to transfer the CID from the
input/output buffer to the CID field in the internal record
structure (which is what ssl_{encrypt/decrypt}_buf() uses).
Note that mbedtls_ssl_in_hdr_len() doesn't need change because
it infers the header length as in_iv - in_hdr, which will account
for the CID for records using such.
Using the Connection ID extension increases the maximum record expansion
because
- the real record content type is added to the plaintext
- the plaintext may be padded with an arbitrary number of
zero bytes, in order to prevent leakage of information
through package length analysis. Currently, we always
pad the plaintext in a minimal way so that its length
is a multiple of 16 Bytes.
This commit adapts the various parts of the library to account
for that additional source of record expansion.
Context:
The CID draft does not require that the length of CIDs used for incoming
records must not change in the course of a connection. Since the record
header does not contain a length field for the CID, this means that if
CIDs of varying lengths are used, the CID length must be inferred from
other aspects of the record header (such as the epoch) and/or by means
outside of the protocol, e.g. by coding its length in the CID itself.
Inferring the CID length from the record's epoch is theoretically possible
in DTLS 1.2, but it requires the information about the epoch to be present
even if the epoch is no longer used: That's because one should silently drop
records from old epochs, but not the entire datagrams to which they belong
(there might be entire flights in a single datagram, including a change of
epoch); however, in order to do so, one needs to parse the record's content
length, the position of which is only known once the CID length for the epoch
is known. In conclusion, it puts a significant burden on the implementation
to infer the CID length from the record epoch, which moreover mangles record
processing with the high-level logic of the protocol (determining which epochs
are in use in which flights, when they are changed, etc. -- this would normally
determine when we drop epochs).
Moreover, with DTLS 1.3, CIDs are no longer uniquely associated to epochs,
but every epoch may use a set of CIDs of varying lengths -- in that case,
it's even theoretically impossible to do record header parsing based on
the epoch configuration only.
We must therefore seek a way for standalone record header parsing, which
means that we must either (a) fix the CID lengths for incoming records,
or (b) allow the application-code to configure a callback to implement
an application-specific CID parsing which would somehow infer the length
of the CID from the CID itself.
Supporting multiple lengths for incoming CIDs significantly increases
complexity while, on the other hand, the restriction to a fixed CID length
for incoming CIDs (which the application controls - in contrast to the
lengths of the CIDs used when writing messages to the peer) doesn't
appear to severely limit the usefulness of the CID extension.
Therefore, the initial implementation of the CID feature will require
a fixed length for incoming CIDs, which is what this commit enforces,
in the following way:
In order to avoid a change of API in case support for variable lengths
CIDs shall be added at some point, we keep mbedtls_ssl_set_cid(), which
includes a CID length parameter, but add a new API mbedtls_ssl_conf_cid_len()
which applies to an SSL configuration, and which fixes the CID length that
any call to mbetls_ssl_set_cid() which applies to an SSL context that is bound
to the given SSL configuration must use.
While this creates a slight redundancy of parameters, it allows to
potentially add an API like mbedtls_ssl_conf_cid_len_cb() later which
could allow users to register a callback which dynamically infers the
length of a CID at record header parsing time, without changing the
rest of the API.
The function mbedtls_ssl_hdr_len() returns the length of the record
header (so far: always 13 Bytes for DTLS, and always 5 Bytes for TLS).
With the introduction of the CID extension, the lengths of record
headers depends on whether the records are incoming or outgoing,
and also on the current transform.
Preparing for this, this commit splits mbedtls_ssl_hdr_len() in two
-- so far unmodified -- functions mbedtls_ssl_in_hdr_len() and
mbedtls_ssl_out_hdr_len() and replaces the uses of mbedtls_ssl_hdr_len()
according to whether they are about incoming or outgoing records.
There is no need to change the signature of mbedtls_ssl_{in/out}_hdr_len()
in preparation for its dependency on the currently active transform,
since the SSL context is passed as an argument, and the currently
active transform is referenced from that.
This commit adds a static array `cid` to the internal structure
`mbedtls_record` representing encrypted and decrypted TLS records.
The expected evolution of state of this field is as follows:
- When handling an incoming record, the caller of `mbedtls_decrypt_buf()`
has to make sure the CID array field in `mbedtls_record` has been
properly set. Concretely, it will be copied from the CID from the record
header during record parsing.
- During decryption in `mbedtls_decrypt_buf()`, the transforms
incoming CID is compared to the CID in the `mbedtls_record`
structure representing the record to be decrypted.
- For an outgoing TLS record, the caller of `mbedtls_encrypt_buf()`
clears the CID in the `mbedtls_record` structure.
- During encryption in `mbedtls_encrypt_buf()`, the CID field in
`mbedtls_record` will be copied from the out-CID in the transform.
These will be copied from the CID fields in mbedtls_ssl_handshake_params
(outgoing CID) and mbedtls_ssl_context (incoming CID) when the transformation
is set up at the end of the handshake.
* mbedtls_ssl_context gets fields indicating whether the CID extension
should be negotiated in the next handshake, and, if yes, which CID
the user wishes the peer to use.
This information does not belong to mbedtls_ssl_handshake_params
because (a) it is configured prior to the handshake, and (b) it
applies to all subsequent handshakes.
* mbedtls_ssl_handshake_params gets fields indicating the state of CID
negotiation during the handshake. Specifically, it indicates if the
use of the CID extension has been negotiated, and if so, which CID
the peer wishes us to use for outgoing messages.
* origin/pr/2403: (24 commits)
crypto: Update to Mbed Crypto 8907b019e7
Create seedfile before running tests
crypto: Update to Mbed Crypto 81f9539037
ssl_cli.c : add explicit casting to unsigned char
Generating visualc files - let Mbed TLS take precedence over crypto
Add a link to the seedfile for out-of-tree cmake builds
Adjust visual studio file generation to always use the crypto submodule
all.sh: unparallelize mingw tests
all.sh - disable parallelization for shared target tests
config.pl: disable PSA_ITS_FILE and PSA_CRYPTO_STORAGE for baremetal
all.sh: unset crypto storage define in a psa full config cmake asan test
all.sh: unset FS_IO-dependent defines for tests that do not have it
curves.pl - change test script to not depend on the implementation
Export the submodule flag to sub-cmakes
Disable MBEDTLS_ECP_RESTARTABLE in full config
Export the submodule flag to sub-makes
Force the usage of crypto submodule
Fix crypto submodule usage in Makefile
Documentation rewording
Typo fixes in documentation
...
* origin/pr/2410:
Update change log
Document the default value for the maximum fragment length
Improve clarity of mbedtls_ssl_conf_max_frag_len documentation
Reword ssl_conf_max_frag_len documentation
Fix typos and miswording in the mbedtls_ssl_conf_max_frag_len documentation comment
Reword ssl_conf_max_frag_len documentation to clarify its necessity
Previously it was disabled as too experimental, which no longer holds. Also,
this option introduces new APIs, so it's not only about an internal
alternative (as the comment in config.pl used to state) - people who request a
full config should get all of the available APIs.
Adapt all.sh: now all builds with full config will also test this option, and
builds with the default config will test without it. Just to be sure, let's
have a build with full config minus this option.
Update documentation of MBEDTLS_USE_PSA_CRYPTO to reflect the status of the
new APIs it enables in Mbed TLS and why they're still opt-in.
Also enable it in scripts/config.pl full, as well as two storage options that
were only blacklisted from full config because they depended on
MBEDTLS_PSA_CRYPTO_C.
* origin/pr/2530: (27 commits)
Style fix
Fix test data
Update test data
Add some negative test cases
Fix minor issues
Add ChangeLog entry about listing all SAN
Check that SAN is not malformed when parsing
Documentation fixes
Fix ChangeLog entry
Fail in case critical crt policy not supported
Update SAN parsing documentation
change the type of hardware_module_name member
Change mbedtls_x509_subject_alternative_name
Add length checking in certificate policy parsing
Rephrase x509_crt extension member description
Rephrase changeLog entries
Remove redundant memset()
Propogate error when parsing SubjectAltNames
Tidy up style in x509_info_subject_alt_name
Print unparseable SubjectAlternativeNames
...
* origin/pr/2538:
Remove unneeded whitespaces
Fix mingw CI failures
Initialize psa_crypto in ssl test
Fix missing tls version test failures
Fix typo
Fix ChangeLog entry location
Add changeLog entry
Add test for export keys functionality
Add function to retrieve the tls_prf type
Add tests for the public tls_prf API
Add public API for tls_prf
Add eap-tls key derivation in the examples.
Add ChangeLog entry
Add an extra key export function
Have the temporary buffer allocated dynamically
Zeroize secret data in the exit point
Add a single exit point in key derivation function
Add an additional function `mbedtls_ssl_export_keys_ext_t()`
for exporting key, that adds additional information such as
the used `tls_prf` and the random bytes.
1) Fix typo in `mbedtls_x509_parse_subject_alt_name()` documentation.
2) Add a not in `mbedtls_x509_parse_subject_alt_name()` documentation,
stating that the lifetime of the target structure is restricted
by the lifetime ofthe parsed certificate.
Make `mbedtls_x509_subject_alternative_name` to be a single item
rather than a list. Adapt the subject alternative name parsing function,
to receive a signle `mbedtls_x509_buf` item from the subject_alt_names
sequence of the certificate.
The documentation for some new structures and members was only a C style
comment and wasn't picked up by doxygen. This commit adds the missing
asterisks.
