mbedtls/programs
Jaeden Amero 67ea2c5e6d Merge branch 'development-psa-proposed' into development
Resolve conflicts by performing the following.

- Take the upstream Mbed TLS ChangeLog verbatim.
- Reject changes to Makefiles and CMake that are related to using Mbed
  Crypto as a submodule. It doesn't make sense to use Mbed Crypto as a
  submodule of itself.
- Reject README changes, as Mbed Crypto has its own, different README.
- Reject PSA-related changes to config.h. We don't want to disable the
  availability of the PSA Crypto API by default in the Mbed Crypto
  config.h.
- Don't inadvertently revert dead code removal in
  mbedtls_cipher_write_tag() which was added in f2a7529403 ("Fix
  double return statement in cipher.c")
- Where Mbed Crypto already had some MBEDTLS_USE_PSA_CRYPTO code (from
  past companion PRs) take the latest version from Mbed TLS which
  includes integration with MBEDTLS_CHECK_PARAMS.
- Update the version of the shared library files to match what's
  currently present in Mbed TLS.
- Reject removal of testing with PSA from config full tests.
- Resolve conflicts in test tests/suites/helpers.function, where both
  Mbed Crypto and Mbed TLS both added documentation for TEST_ASSERT.
  Combine text from both documentation efforts.
- Reject adding a submodule of ourselves.
- Reject addition of submodule tests in all.sh.
- Reject addition of submodule to library path in
  tests/scripts/run-test-suites.pl.
- Avoid using USE_CRYPTO_SUBMODULE=1 in
  component_test_use_psa_crypto_full_cmake_asan() in all.sh.
2019-02-14 15:58:43 +00:00
..
aes Merge development commit 8e76332 into development-psa 2019-01-31 08:20:20 -05:00
hash Merge development commit 8e76332 into development-psa 2019-01-31 08:20:20 -05:00
pkey Merge development commit 8e76332 into development-psa 2019-01-31 08:20:20 -05:00
psa Run generate_psa_constants.py before building psa_constant_names with cmake 2019-02-07 13:08:34 +00:00
random Merge development commit 8e76332 into development-psa 2019-01-31 08:20:20 -05:00
ssl Documentation fixes 2019-02-05 05:06:35 -05:00
test Merge development commit 8e76332 into development-psa 2019-01-31 08:20:20 -05:00
util Merge development commit 8e76332 into development-psa 2019-01-31 08:20:20 -05:00
x509 Merge development commit 8e76332 into development-psa 2019-01-31 08:20:20 -05:00
.gitignore psa: programs: Add cipher example 2018-09-12 16:50:07 +03:00
CMakeLists.txt psa: programs: Add cipher example 2018-09-12 16:50:07 +03:00
Makefile Add dependency to Makefile 2019-02-06 16:24:43 +00:00
README.md Add test/zeroize.c 2018-08-10 11:48:52 +02:00
wince_main.c Change main license to Apache 2.0 2015-09-04 14:21:07 +02:00

Mbed TLS sample programs

This subdirectory mostly contains sample programs that illustrate specific features of the library, as well as a few test and support programs.

Symmetric cryptography (AES) examples

  • aes/aescrypt2.c: file encryption and authentication with a key derived from a low-entropy secret, demonstrating the low-level AES interface, the digest interface and HMAC.
    Warning: this program illustrates how to use low-level functions in the library. It should not be taken as an example of how to build a secure encryption mechanism. To derive a key from a low-entropy secret such as a password, use a standard key stretching mechanism such as PBKDF2 (provided by the pkcs5 module). To encrypt and authenticate data, use a standard mode such as GCM or CCM (both available as library module).

  • aes/crypt_and_hash.c: file encryption and authentication, demonstrating the generic cipher interface and the generic hash interface.

Hash (digest) examples

Public-key cryptography examples

Generic public-key cryptography (pk) examples

  • pkey/gen_key.c: generates a key for any of the supported public-key algorithms (RSA or ECC) and writes it to a file that can be used by the other pk sample programs.

  • pkey/key_app.c: loads a PEM or DER public key or private key file and dumps its content.

  • pkey/key_app_writer.c: loads a PEM or DER public key or private key file and writes it to a new PEM or DER file.

  • pkey/pk_encrypt.c, pkey/pk_decrypt.c: loads a PEM or DER public/private key file and uses the key to encrypt/decrypt a short string through the generic public-key interface.

  • pkey/pk_sign.c, pkey/pk_verify.c: loads a PEM or DER private/public key file and uses the key to sign/verify a short string.

ECDSA and RSA signature examples

Diffie-Hellman key exchange examples

  • pkey/dh_client.c, pkey/dh_server.c: secure channel demonstrators (client, server). This pair of programs illustrates how to set up a secure channel using RSA for authentication and Diffie-Hellman to generate a shared AES session key.

  • pkey/ecdh_curve25519.c: demonstration of a elliptic curve Diffie-Hellman (ECDH) key agreement.

Bignum (mpi) usage examples

Random number generator (RNG) examples

  • random/gen_entropy.c: shows how to use the default entropy sources to generate random data.
    Note: most applications should only use the entropy generator to seed a cryptographic pseudorandom generator, as illustrated by random/gen_random_ctr_drbg.c.

  • random/gen_random_ctr_drbg.c: shows how to use the default entropy sources to seed a pseudorandom generator, and how to use the resulting random generator to generate random data.

  • random/gen_random_havege.c: demonstrates the HAVEGE entropy collector.

SSL/TLS examples

SSL/TLS sample applications

  • ssl/dtls_client.c: a simple DTLS client program, which sends one datagram to the server and reads one datagram in response.

  • ssl/dtls_server.c: a simple DTLS server program, which expects one datagram from the client and writes one datagram in response. This program supports DTLS cookies for hello verification.

  • ssl/mini_client.c: a minimalistic SSL client, which sends a short string and disconnects. This is primarily intended as a benchmark; for a better example of a typical TLS client, see ssl/ssl_client1.c.

  • ssl/ssl_client1.c: a simple HTTPS client that sends a fixed request and displays the response.

  • ssl/ssl_fork_server.c: a simple HTTPS server using one process per client to send a fixed response. This program requires a Unix/POSIX environment implementing the fork system call.

  • ssl/ssl_mail_client.c: a simple SMTP-over-TLS or SMTP-STARTTLS client. This client sends an email with fixed content.

  • ssl/ssl_pthread_server.c: a simple HTTPS server using one thread per client to send a fixed response. This program requires the pthread library.

  • ssl/ssl_server.c: a simple HTTPS server that sends a fixed response. It serves a single client at a time.

SSL/TLS feature demonstrators

Note: unlike most of the other programs under the programs/ directory, these two programs are not intended as a basis for writing an application. They combine most of the features supported by the library, and most applications require only a few features. To write a new application, we recommended that you start with ssl_client1.c or ssl_server.c, and then look inside ssl/ssl_client2.c or ssl/ssl_server2.c to see how to use the specific features that your application needs.

  • ssl/ssl_client2.c: an HTTPS client that sends a fixed request and displays the response, with options to select TLS protocol features and Mbed TLS library features.

  • ssl/ssl_server2.c: an HTTPS server that sends a fixed response, with options to select TLS protocol features and Mbed TLS library features.

In addition to providing options for testing client-side features, the ssl_client2 program has options that allow you to trigger certain behaviors in the server. For example, there are options to select ciphersuites, or to force a renegotiation. These options are useful for testing the corresponding features in a TLS server. Likewise, ssl_server2 has options to activate certain behaviors that are useful for testing a TLS client.

Test utilities

  • test/benchmark.c: benchmark for cryptographic algorithms.

  • test/selftest.c: runs the self-test function in each library module.

  • test/ssl_cert_test.c: demonstrates how to verify X.509 certificates, and (for RSA keys only) how to check that each certificate matches the corresponding private key. This program requires some test data which is not provided.

  • test/udp_proxy.c: a UDP proxy that can inject certain failures (delay, duplicate, drop). Useful for testing DTLS.

  • test/zeroize.c: a test program for mbedtls_platform_zeroize, used by tests/scripts/test_zeroize.gdb.

Development utilities

  • util/pem2der.c: a PEM to DER converter. Mbed TLS can read PEM files directly, but this utility can be useful for interacting with other tools or with minimal Mbed TLS builds that lack PEM support.

  • util/strerror.c: prints the error description corresponding to an integer status returned by an Mbed TLS function.

X.509 certificate examples

  • x509/cert_app.c: connects to a TLS server and verifies its certificate chain.

  • x509/cert_req.c: generates a certificate signing request (CSR) for a private key.

  • x509/cert_write.c: signs a certificate signing request, or self-signs a certificate.

  • x509/crl_app.c: loads and dumps a certificate revocation list (CRL).

  • x509/req_app.c: loads and dumps a certificate signing request (CSR).