From ceb7b1209c52ff875fe8754030bc09a0d97ac360 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 18 Jan 2018 23:27:47 +0100 Subject: [PATCH 1/7] Readme with a short description of each sample program --- README.md | 2 +- programs/README.md | 123 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+), 1 deletion(-) create mode 100644 programs/README.md diff --git a/README.md b/README.md index 4270e8069..a9934871c 100644 --- a/README.md +++ b/README.md @@ -138,7 +138,7 @@ The solution file `mbedTLS.sln` contains all the basic projects needed to build Example programs ---------------- -We've included example programs for a lot of different features and uses in `programs/`. Most programs only focus on a single feature or usage scenario, so keep that in mind when copying parts of the code. +We've included example programs for a lot of different features and uses in [`programs/`](programs/README.md). Most programs only focus on a single feature or usage scenario, so keep that in mind when copying parts of the code. Tests ----- diff --git a/programs/README.md b/programs/README.md new file mode 100644 index 000000000..fec8a60e4 --- /dev/null +++ b/programs/README.md @@ -0,0 +1,123 @@ +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`](aes/aescrypt2.c): file encryption and authentication, demonstrating the low-level AES interface and HMAC. + Warning: this program illustrates how to roll your own block cipher mode. Most applications should not do this and should instead use the standard library functions (e.g. `mbedtls_aes_crypt_cbc`). + +* [`aes/crypt_and_hash.c`](aes/crypt_and_hash.c): file encryption and authentication, demonstrating the generic cipher interface and the generic hash interface. + +## Hash (digest) examples + +* [`hash/generic_sum.c`](hash/generic_sum.c): file hash calculator and verifier, demonstrating the message digest (`md`) interface. + +* [`hash/hello.c`](hash/hello.c): hello-world program for MD5. + +## Public-key cryptography examples + +### Generic public-key cryptography (`pk`) examples + +* [`pkey/gen_key.c`](pkey/gen_key.c): generate a key for any of the supported public-key algorithms (RSA or ECC) and write it to a file that can be used by the other pk sample programs. + +* [`pkey/key_app.c`](pkey/key_app.c): Load a PEM or DER public key or private key file and dump its content. + +* [`pkey/key_app_writer.c`](pkey/key_app_writer.c): Load a PEM or DER public key or private key file and write it to a new PEM or DER file. + +* [`pkey/pk_encrypt.c`](pkey/pk_encrypt.c), [`pkey/pk_decrypt.c`](pkey/pk_decrypt.c): Load a PEM or DER public/private key file and use the key to encrypt/decrypt a short string through the generic public-key interface. + +* [`pkey/pk_sign.c`](pkey/pk_sign.c), [`pkey/pk_verify.c`](pkey/pk_verify.c): Load a PEM or DER private/public key file and use the key to sign/verify a short string. + +### ECDSA and RSA signature examples + +* [`pkey/ecdsa.c`](pkey/ecdsa.c): generate an ECDSA key, sign a fixed message and verify the signature. + +* [`pkey/rsa_encrypt.c`](pkey/rsa_encrypt.c), [`pkey/rsa_decrypt.c`](pkey/rsa_decrypt.c): load an RSA public/private key and use it to encrypt/decrypt a short string through the low-level RSA interface. + +* [`pkey/rsa_genkey.c`](pkey/rsa_genkey.c): generate an RSA key and write it to a file that can be used with the other RSA sample programs. + +* [`pkey/rsa_sign.c`](pkey/rsa_sign.c), [`pkey/rsa_verify.c`](pkey/rsa_verify.c): load an RSA private/public key and use it to sign/verify a short string with the RSA PKCS#1 v1.5 algorithm. + +* [`pkey/rsa_sign_pss.c`](pkey/rsa_sign_pss.c), [`pkey/rsa_verify_pss.c`](pkey/rsa_verify_pss.c): load an RSA private/public key and use it to sign/verify a short string with the RSASSA-PSS algorithm. + +### Diffie-Hellman key exchange examples + +* [`pkey/dh_client.c`](pkey/dh_client.c), [`pkey/dh_server.c`](pkey/dh_server.c): secure channel demonstrator (client, server). Illustrates how to set up a secure channel using RSA for authentication and Diffie-Hellman to set up a shared AES session key. + +* [`pkey/ecdh_curve25519.c`](pkey/ecdh_curve25519.c): demonstration of a elliptic curve Diffie-Hellman (ECDH) key agreement. + +### Bignum (`mpi`) usage examples + +* [`pkey/dh_genprime.c`](pkey/dh_genprime.c): illustrates the bignum (`mpi`) interface by generating Diffie-Hellman parameters. + +* [`pkey/mpi_demo.c`](pkey/mpi_demo.c): demonstrates operations on big integers. + +## Random number generator (RNG) examples + +* [`random/gen_entropy.c`](random/gen_entropy.c): illustrates using the default entropy sources to generate random data. + Note: most applications should use the entropy generator only to seed a cryptographic pseudorandom generator, as illustrated by `random/gen_random_ctr_drbg.c`. + +* [`random/gen_random_ctr_drbg.c`](random/gen_random_ctr_drbg.c): illustrates using the default entropy sources to seed a pseudorandom generator, and using the resulting random generator to generate random data. + +* [`random/gen_random_havege.c`](random/gen_random_havege.c): illustrates the HAVEGE entropy collector. + +## SSL/TLS examples + +### SSL/TLS sample applications + +* [`ssl/dtls_client.c`](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`](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`](ssl/mini_client.c): a minimalistic SSL client which sends a short string and disconnects. This is intended more as a benchmark; for a better example of a typical TLS client, see `ssl/ssl_client1.c`. + +* [`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`](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`](ssl/ssl_mail_client.c): a simple SMTP-over-TLS or SMTP-STARTTLS client. This client sends an email with a fixed content. + +* [`ssl/ssl_pthread_server.c`](ssl/ssl_pthread_server.c): a simple HTTPS server using one thread per client to send a fixed response. This program requires a the pthread library. + +* [`ssl/ssl_server.c`](ssl/ssl_server.c): a simple HTTPS server that sends a fixed response. This server 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 to start writing an application. They combine most of the features supported by the library, and most applications require only a few features. It is recommended to start with `ssl_client1.c` or `ssl_server.c`, and to 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`](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`](ssl/ssl_server2.c): an HTTPS server that sends a fixed response, with options to select TLS protocol features and Mbed TLS library features. + +These programs have options to trigger certain behaviors (e.g. reconnection, renegotiation) so the `ssl_server2` program can be useful to test features in your TLS client and the `ssl_client2` program can be useful to test features in your TLS server. + +## Test utilities + +* [`test/benchmark.c`](test/benchmark.c): benchmark for cryptographic algorithms. + +* [`test/selftest.c`](test/selftest.c): runs the self-test functions in all the library modules. + +* [`test/ssl_cert_test.c`](test/ssl_cert_test.c): verify some X.509 certificates, and verify that each certificate matches the corresponding private key (supported for RSA keys only). + +* [`test/udp_proxy.c`](test/udp_proxy.c): a UDP proxy that can inject certain failures (delay, duplicate, drop). Useful to test DTLS. + +## Development utilities + +* [`util/pem2der.c`](util/pem2der.c): a PEM to DER converter. Mbed TLS can read PEM files directly, but this utility can be useful to interact with other tools or with minimal Mbed TLS builds that lack PEM support. + +* [`util/strerror.c`](util/strerror.c): print the error description corresponding to an integer status returned by an Mbed TLS function. + +## X.509 certificate examples + +* [`x509/cert_app.c`](x509/cert_app.c): connect to a TLS server and verify its certificate chain. + +* [`x509/cert_req.c`](x509/cert_req.c): generate a certificate signing request (CSR) for a private key. + +* [`x509/cert_write.c`](x509/cert_write.c): sign a certificate signing request, or self-sign a certificate. + +* [`x509/crl_app.c`](x509/crl_app.c): load and dump a certificate revocation list (CRL). + +* [`x509/req_app.c`](x509/req_app.c): load and dump a certificate signing request (CSR). + From 6b9cbb86855541cc7975fb3551fbe1def4682687 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 30 Jul 2018 20:06:19 +0200 Subject: [PATCH 2/7] Copyediting --- programs/README.md | 58 +++++++++++++++++++++++----------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/programs/README.md b/programs/README.md index fec8a60e4..31b7e2a2f 100644 --- a/programs/README.md +++ b/programs/README.md @@ -20,15 +20,15 @@ This subdirectory mostly contains sample programs that illustrate specific featu ### Generic public-key cryptography (`pk`) examples -* [`pkey/gen_key.c`](pkey/gen_key.c): generate a key for any of the supported public-key algorithms (RSA or ECC) and write it to a file that can be used by the other pk sample programs. +* [`pkey/gen_key.c`](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`](pkey/key_app.c): Load a PEM or DER public key or private key file and dump its content. +* [`pkey/key_app.c`](pkey/key_app.c): loads a PEM or DER public key or private key file and dumps its content. -* [`pkey/key_app_writer.c`](pkey/key_app_writer.c): Load a PEM or DER public key or private key file and write it to a new PEM or DER file. +* [`pkey/key_app_writer.c`](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_encrypt.c), [`pkey/pk_decrypt.c`](pkey/pk_decrypt.c): Load a PEM or DER public/private key file and use the key to encrypt/decrypt a short string through the generic public-key interface. +* [`pkey/pk_encrypt.c`](pkey/pk_encrypt.c), [`pkey/pk_decrypt.c`](pkey/pk_decrypt.c): load a PEM or DER public/private key file and use the key to encrypt/decrypt a short string through the generic public-key interface. -* [`pkey/pk_sign.c`](pkey/pk_sign.c), [`pkey/pk_verify.c`](pkey/pk_verify.c): Load a PEM or DER private/public key file and use the key to sign/verify a short string. +* [`pkey/pk_sign.c`](pkey/pk_sign.c), [`pkey/pk_verify.c`](pkey/pk_verify.c): load a PEM or DER private/public key file and use the key to sign/verify a short string. ### ECDSA and RSA signature examples @@ -44,80 +44,80 @@ This subdirectory mostly contains sample programs that illustrate specific featu ### Diffie-Hellman key exchange examples -* [`pkey/dh_client.c`](pkey/dh_client.c), [`pkey/dh_server.c`](pkey/dh_server.c): secure channel demonstrator (client, server). Illustrates how to set up a secure channel using RSA for authentication and Diffie-Hellman to set up a shared AES session key. +* [`pkey/dh_client.c`](pkey/dh_client.c), [`pkey/dh_server.c`](pkey/dh_server.c): secure channel demonstrators (client, server). 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`](pkey/ecdh_curve25519.c): demonstration of a elliptic curve Diffie-Hellman (ECDH) key agreement. ### Bignum (`mpi`) usage examples -* [`pkey/dh_genprime.c`](pkey/dh_genprime.c): illustrates the bignum (`mpi`) interface by generating Diffie-Hellman parameters. +* [`pkey/dh_genprime.c`](pkey/dh_genprime.c): shows how to use the bignum (`mpi`) interface to generate Diffie-Hellman parameters. * [`pkey/mpi_demo.c`](pkey/mpi_demo.c): demonstrates operations on big integers. ## Random number generator (RNG) examples -* [`random/gen_entropy.c`](random/gen_entropy.c): illustrates using the default entropy sources to generate random data. - Note: most applications should use the entropy generator only to seed a cryptographic pseudorandom generator, as illustrated by `random/gen_random_ctr_drbg.c`. +* [`random/gen_entropy.c`](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`](random/gen_random_ctr_drbg.c): illustrates using the default entropy sources to seed a pseudorandom generator, and using the resulting random generator to generate random data. +* [`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 using the resulting random generator to generate random data. -* [`random/gen_random_havege.c`](random/gen_random_havege.c): illustrates the HAVEGE entropy collector. +* [`random/gen_random_havege.c`](random/gen_random_havege.c): demonstrates the HAVEGE entropy collector. ## SSL/TLS examples ### SSL/TLS sample applications -* [`ssl/dtls_client.c`](ssl/dtls_client.c): a simple DTLS client program which sends one datagram to the server and reads one datagram in response. +* [`ssl/dtls_client.c`](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`](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/dtls_server.c`](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`](ssl/mini_client.c): a minimalistic SSL client which sends a short string and disconnects. This is intended more as a benchmark; for a better example of a typical TLS client, see `ssl/ssl_client1.c`. +* [`ssl/mini_client.c`](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`](ssl/ssl_client1.c): a simple HTTPS client that sends a fixed request and displays the response. * [`ssl/ssl_fork_server.c`](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`](ssl/ssl_mail_client.c): a simple SMTP-over-TLS or SMTP-STARTTLS client. This client sends an email with a fixed content. +* [`ssl/ssl_mail_client.c`](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`](ssl/ssl_pthread_server.c): a simple HTTPS server using one thread per client to send a fixed response. This program requires a the pthread library. +* [`ssl/ssl_pthread_server.c`](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`](ssl/ssl_server.c): a simple HTTPS server that sends a fixed response. This server serves a single client at a time. +* [`ssl/ssl_server.c`](ssl/ssl_server.c): a simple HTTPS server that sends a fixed response. This server accepts 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 to start writing an application. They combine most of the features supported by the library, and most applications require only a few features. It is recommended to start with `ssl_client1.c` or `ssl_server.c`, and to look inside `ssl/ssl_client2.c` or `ssl/ssl_server2.c` to see how to use the specific features that your application needs. +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`](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`](ssl/ssl_server2.c): an HTTPS server that sends a fixed response, with options to select TLS protocol features and Mbed TLS library features. -These programs have options to trigger certain behaviors (e.g. reconnection, renegotiation) so the `ssl_server2` program can be useful to test features in your TLS client and the `ssl_client2` program can be useful to test features in your TLS server. +In addition to providing options for testing client-side features, the `ssl_client2` program has options to exercise certain behaviors in the server (for example, to select ciphersuites, or to force a renegotiation), which are useful to test the corresponding features in a TLS server. Likewise, `ssl_server2` has options to activate certain behaviors that are useful to test a TLS client. ## Test utilities * [`test/benchmark.c`](test/benchmark.c): benchmark for cryptographic algorithms. -* [`test/selftest.c`](test/selftest.c): runs the self-test functions in all the library modules. +* [`test/selftest.c`](test/selftest.c): runs the self-test function in each library module. -* [`test/ssl_cert_test.c`](test/ssl_cert_test.c): verify some X.509 certificates, and verify that each certificate matches the corresponding private key (supported for RSA keys only). +* [`test/ssl_cert_test.c`](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`](test/udp_proxy.c): a UDP proxy that can inject certain failures (delay, duplicate, drop). Useful to test DTLS. +* [`test/udp_proxy.c`](test/udp_proxy.c): a UDP proxy that can inject certain failures (delay, duplicate, drop). Useful for testing DTLS. ## Development utilities -* [`util/pem2der.c`](util/pem2der.c): a PEM to DER converter. Mbed TLS can read PEM files directly, but this utility can be useful to interact with other tools or with minimal Mbed TLS builds that lack PEM support. +* [`util/pem2der.c`](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`](util/strerror.c): print the error description corresponding to an integer status returned by an Mbed TLS function. +* [`util/strerror.c`](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`](x509/cert_app.c): connect to a TLS server and verify its certificate chain. +* [`x509/cert_app.c`](x509/cert_app.c): connects to a TLS server and verifies its certificate chain. -* [`x509/cert_req.c`](x509/cert_req.c): generate a certificate signing request (CSR) for a private key. +* [`x509/cert_req.c`](x509/cert_req.c): generates a certificate signing request (CSR) for a private key. -* [`x509/cert_write.c`](x509/cert_write.c): sign a certificate signing request, or self-sign a certificate. +* [`x509/cert_write.c`](x509/cert_write.c): signs a certificate signing request, or self-sign a certificate. -* [`x509/crl_app.c`](x509/crl_app.c): load and dump a certificate revocation list (CRL). +* [`x509/crl_app.c`](x509/crl_app.c): loads and dumps a certificate revocation list (CRL). -* [`x509/req_app.c`](x509/req_app.c): load and dump a certificate signing request (CSR). +* [`x509/req_app.c`](x509/req_app.c): loads and dumps a certificate signing request (CSR). From c2e5cdd536c16f460555e00cf90ec51512db79ae Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 30 Jul 2018 20:11:05 +0200 Subject: [PATCH 3/7] Explain aescrypt2 better and warn that it doesn't do things properly --- programs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/programs/README.md b/programs/README.md index 31b7e2a2f..7075ae2dd 100644 --- a/programs/README.md +++ b/programs/README.md @@ -5,8 +5,8 @@ This subdirectory mostly contains sample programs that illustrate specific featu ## Symmetric cryptography (AES) examples -* [`aes/aescrypt2.c`](aes/aescrypt2.c): file encryption and authentication, demonstrating the low-level AES interface and HMAC. - Warning: this program illustrates how to roll your own block cipher mode. Most applications should not do this and should instead use the standard library functions (e.g. `mbedtls_aes_crypt_cbc`). +* [`aes/aescrypt2.c`](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`](aes/crypt_and_hash.c): file encryption and authentication, demonstrating the generic cipher interface and the generic hash interface. From 27a046058a660f9c177587071d10ddd9446a53d9 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 6 Aug 2018 20:09:16 +0200 Subject: [PATCH 4/7] Unify the grammar of descriptions Use "program: does this and then does that" throughout. --- programs/README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/programs/README.md b/programs/README.md index 7075ae2dd..f9e961f88 100644 --- a/programs/README.md +++ b/programs/README.md @@ -26,25 +26,25 @@ This subdirectory mostly contains sample programs that illustrate specific featu * [`pkey/key_app_writer.c`](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_encrypt.c), [`pkey/pk_decrypt.c`](pkey/pk_decrypt.c): load a PEM or DER public/private key file and use the key to encrypt/decrypt a short string through the generic public-key interface. +* [`pkey/pk_encrypt.c`](pkey/pk_encrypt.c), [`pkey/pk_decrypt.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_sign.c), [`pkey/pk_verify.c`](pkey/pk_verify.c): load a PEM or DER private/public key file and use the key to sign/verify a short string. +* [`pkey/pk_sign.c`](pkey/pk_sign.c), [`pkey/pk_verify.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 -* [`pkey/ecdsa.c`](pkey/ecdsa.c): generate an ECDSA key, sign a fixed message and verify the signature. +* [`pkey/ecdsa.c`](pkey/ecdsa.c): generates an ECDSA key, sign a fixed message and verify the signature. -* [`pkey/rsa_encrypt.c`](pkey/rsa_encrypt.c), [`pkey/rsa_decrypt.c`](pkey/rsa_decrypt.c): load an RSA public/private key and use it to encrypt/decrypt a short string through the low-level RSA interface. +* [`pkey/rsa_encrypt.c`](pkey/rsa_encrypt.c), [`pkey/rsa_decrypt.c`](pkey/rsa_decrypt.c): loads an RSA public/private key and uses it to encrypt/decrypt a short string through the low-level RSA interface. -* [`pkey/rsa_genkey.c`](pkey/rsa_genkey.c): generate an RSA key and write it to a file that can be used with the other RSA sample programs. +* [`pkey/rsa_genkey.c`](pkey/rsa_genkey.c): generates an RSA key and writes it to a file that can be used with the other RSA sample programs. -* [`pkey/rsa_sign.c`](pkey/rsa_sign.c), [`pkey/rsa_verify.c`](pkey/rsa_verify.c): load an RSA private/public key and use it to sign/verify a short string with the RSA PKCS#1 v1.5 algorithm. +* [`pkey/rsa_sign.c`](pkey/rsa_sign.c), [`pkey/rsa_verify.c`](pkey/rsa_verify.c): loads an RSA private/public key and uses it to sign/verify a short string with the RSA PKCS#1 v1.5 algorithm. -* [`pkey/rsa_sign_pss.c`](pkey/rsa_sign_pss.c), [`pkey/rsa_verify_pss.c`](pkey/rsa_verify_pss.c): load an RSA private/public key and use it to sign/verify a short string with the RSASSA-PSS algorithm. +* [`pkey/rsa_sign_pss.c`](pkey/rsa_sign_pss.c), [`pkey/rsa_verify_pss.c`](pkey/rsa_verify_pss.c): loads an RSA private/public key and use it to sign/verify a short string with the RSASSA-PSS algorithm. ### Diffie-Hellman key exchange examples -* [`pkey/dh_client.c`](pkey/dh_client.c), [`pkey/dh_server.c`](pkey/dh_server.c): secure channel demonstrators (client, server). Illustrates how to set up a secure channel using RSA for authentication and Diffie-Hellman to generate a shared AES session key. +* [`pkey/dh_client.c`](pkey/dh_client.c), [`pkey/dh_server.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`](pkey/ecdh_curve25519.c): demonstration of a elliptic curve Diffie-Hellman (ECDH) key agreement. @@ -115,7 +115,7 @@ In addition to providing options for testing client-side features, the `ssl_clie * [`x509/cert_req.c`](x509/cert_req.c): generates a certificate signing request (CSR) for a private key. -* [`x509/cert_write.c`](x509/cert_write.c): signs a certificate signing request, or self-sign a certificate. +* [`x509/cert_write.c`](x509/cert_write.c): signs a certificate signing request, or self-signs a certificate. * [`x509/crl_app.c`](x509/crl_app.c): loads and dumps a certificate revocation list (CRL). From aa22030e21c7b2af27ee5095d823402af1e9072a Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 6 Aug 2018 20:19:50 +0200 Subject: [PATCH 5/7] Further wording improvements --- programs/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/programs/README.md b/programs/README.md index f9e961f88..ef20993e9 100644 --- a/programs/README.md +++ b/programs/README.md @@ -59,7 +59,7 @@ This subdirectory mostly contains sample programs that illustrate specific featu * [`random/gen_entropy.c`](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`](random/gen_random_ctr_drbg.c): shows how to use the default entropy sources to seed a pseudorandom generator, and using the resulting random generator to generate random data. +* [`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`](random/gen_random_havege.c): demonstrates the HAVEGE entropy collector. @@ -81,7 +81,7 @@ This subdirectory mostly contains sample programs that illustrate specific featu * [`ssl/ssl_pthread_server.c`](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`](ssl/ssl_server.c): a simple HTTPS server that sends a fixed response. This server accepts a single client at a time. +* [`ssl/ssl_server.c`](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 @@ -91,7 +91,7 @@ Note: unlike most of the other programs under the `programs/` directory, these t * [`ssl/ssl_server2.c`](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 to exercise certain behaviors in the server (for example, to select ciphersuites, or to force a renegotiation), which are useful to test the corresponding features in a TLS server. Likewise, `ssl_server2` has options to activate certain behaviors that are useful to test a TLS client. +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 From 0b54419bc8c7274bb66cbd5fe320eb82506ba29c Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 10 Aug 2018 11:32:11 +0200 Subject: [PATCH 6/7] More grammar alignment --- programs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/programs/README.md b/programs/README.md index ef20993e9..d8e4cd62b 100644 --- a/programs/README.md +++ b/programs/README.md @@ -32,7 +32,7 @@ This subdirectory mostly contains sample programs that illustrate specific featu ### ECDSA and RSA signature examples -* [`pkey/ecdsa.c`](pkey/ecdsa.c): generates an ECDSA key, sign a fixed message and verify the signature. +* [`pkey/ecdsa.c`](pkey/ecdsa.c): generates an ECDSA key, signs a fixed message and verifies the signature. * [`pkey/rsa_encrypt.c`](pkey/rsa_encrypt.c), [`pkey/rsa_decrypt.c`](pkey/rsa_decrypt.c): loads an RSA public/private key and uses it to encrypt/decrypt a short string through the low-level RSA interface. @@ -40,7 +40,7 @@ This subdirectory mostly contains sample programs that illustrate specific featu * [`pkey/rsa_sign.c`](pkey/rsa_sign.c), [`pkey/rsa_verify.c`](pkey/rsa_verify.c): loads an RSA private/public key and uses it to sign/verify a short string with the RSA PKCS#1 v1.5 algorithm. -* [`pkey/rsa_sign_pss.c`](pkey/rsa_sign_pss.c), [`pkey/rsa_verify_pss.c`](pkey/rsa_verify_pss.c): loads an RSA private/public key and use it to sign/verify a short string with the RSASSA-PSS algorithm. +* [`pkey/rsa_sign_pss.c`](pkey/rsa_sign_pss.c), [`pkey/rsa_verify_pss.c`](pkey/rsa_verify_pss.c): loads an RSA private/public key and uses it to sign/verify a short string with the RSASSA-PSS algorithm. ### Diffie-Hellman key exchange examples From ffbdc614493e9688ece2c11ab87fadff8aab9dde Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 10 Aug 2018 11:48:52 +0200 Subject: [PATCH 7/7] Add test/zeroize.c --- programs/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/programs/README.md b/programs/README.md index d8e4cd62b..eb25a7f69 100644 --- a/programs/README.md +++ b/programs/README.md @@ -103,6 +103,8 @@ In addition to providing options for testing client-side features, the `ssl_clie * [`test/udp_proxy.c`](test/udp_proxy.c): a UDP proxy that can inject certain failures (delay, duplicate, drop). Useful for testing DTLS. +* [`test/zeroize.c`](test/zeroize.c): a test program for `mbedtls_platform_zeroize`, used by [`tests/scripts/test_zeroize.gdb`](tests/scripts/test_zeroize.gdb). + ## Development utilities * [`util/pem2der.c`](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.