Replace "a RSA" with "an RSA"

Fixes openssl#19771

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19787)

(cherry picked from commit a63fa5f711f1f97e623348656b42717d6904ee3e)
(cherry picked from commit f3e9308fe1b692c424feaa256fbecce958cef1f4)

10 files changed, 213 insertions, 11 deletions

diff --git a/CHANGES.md b/CHANGES.md
index 83bb306362..86f1430843 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -19230,7 +19230,7 @@ ndif
    *Ralf S. Engelschall*
 
  * Incorporated the popular no-RSA/DSA-only patches
-   which allow to compile a RSA-free SSLeay.
+   which allow to compile an RSA-free SSLeay.
 
    *Andrew Cooke / Interrader Ldt., Ralf S. Engelschall*
 
diff --git a/crypto/rsa/rsa_mp.c b/crypto/rsa/rsa_mp.c
index b785344cf0..f827c0a2f8 100644
--- a/crypto/rsa/rsa_mp.c
+++ b/crypto/rsa/rsa_mp.c
@@ -21,7 +21,7 @@ void ossl_rsa_multip_info_free_ex(RSA_PRIME_INFO *pinfo)
 
 void ossl_rsa_multip_info_free(RSA_PRIME_INFO *pinfo)
 {
-    /* free a RSA_PRIME_INFO structure */
+    /* free an RSA_PRIME_INFO structure */
     BN_clear_free(pinfo->r);
     BN_clear_free(pinfo->d);
     BN_clear_free(pinfo->t);
@@ -32,7 +32,7 @@ RSA_PRIME_INFO *ossl_rsa_multip_info_new(void)
 {
     RSA_PRIME_INFO *pinfo;
 
-    /* create a RSA_PRIME_INFO structure */
+    /* create an RSA_PRIME_INFO structure */
     if ((pinfo = OPENSSL_zalloc(sizeof(RSA_PRIME_INFO))) == NULL) {
         ERR_raise(ERR_LIB_RSA, ERR_R_MALLOC_FAILURE);
         return NULL;
diff --git a/demos/encode/rsa_encode.c b/demos/encode/rsa_encode.c
new file mode 100644
index 0000000000..2bf6d13e6f
--- /dev/null
+++ b/demos/encode/rsa_encode.c
@@ -0,0 +1,202 @@
+/*-
+ * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
+ *
+ * Licensed under the Apache License 2.0 (the "License").  You may not use
+ * this file except in compliance with the License.  You can obtain a copy
+ * in the file LICENSE in the source distribution or at
+ * https://www.openssl.org/source/license.html
+ */
+#include <string.h>
+#include <openssl/decoder.h>
+#include <openssl/encoder.h>
+#include <openssl/evp.h>
+
+/*
+ * Example showing the encoding and decoding of RSA public and private keys. A
+ * PEM-encoded RSA key is read in from stdin, decoded, and then re-encoded and
+ * output for demonstration purposes. Both public and private keys are accepted.
+ *
+ * This can be used to load RSA keys from a file or save RSA keys to a file.
+ */
+
+/* A property query used for selecting algorithm implementations. */
+static const char *propq = NULL;
+
+/*
+ * Load a PEM-encoded RSA key from a file, optionally decrypting it with a
+ * supplied passphrase.
+ */
+static EVP_PKEY *load_key(OSSL_LIB_CTX *libctx, FILE *f, const char *passphrase)
+{
+    int rv = 0;
+    EVP_PKEY *pkey = NULL;
+    OSSL_DECODER_CTX *dctx = NULL;
+    int selection = 0;
+
+    /*
+     * Create PEM decoder context expecting an RSA key.
+     *
+     * For raw (non-PEM-encoded) keys, change "PEM" to "DER".
+     *
+     * The selection argument here specifies whether we are willing to accept a
+     * public key, private key, or either. If it is set to zero, either will be
+     * accepted. If set to EVP_PKEY_KEYPAIR, a private key will be required, and
+     * if set to EVP_PKEY_PUBLIC_KEY, a public key will be required.
+     */
+    dctx = OSSL_DECODER_CTX_new_for_pkey(&pkey, "PEM", NULL, "RSA",
+                                         selection,
+                                         libctx, propq);
+    if (dctx == NULL) {
+        fprintf(stderr, "OSSL_DECODER_CTX_new_for_pkey() failed\n");
+        goto cleanup;
+    }
+
+    /*
+     * Set passphrase if provided; needed to decrypt encrypted PEM files.
+     * If the input is not encrypted, any passphrase provided is ignored.
+     *
+     * Alternative methods for specifying passphrases exist, such as a callback
+     * (see OSSL_DECODER_CTX_set_passphrase_cb(3)), which may be more useful for
+     * interactive applications which do not know if a passphrase should be
+     * prompted for in advance, or for GUI applications.
+     */
+    if (passphrase != NULL) {
+        if (OSSL_DECODER_CTX_set_passphrase(dctx,
+                                            (const unsigned char *)passphrase,
+                                            strlen(passphrase)) == 0) {
+            fprintf(stderr, "OSSL_DECODER_CTX_set_passphrase() failed\n");
+            goto cleanup;
+        }
+    }
+
+    /* Do the decode, reading from file. */
+    if (OSSL_DECODER_from_fp(dctx, f) == 0) {
+        fprintf(stderr, "OSSL_DECODER_from_fp() failed\n");
+        goto cleanup;
+    }
+
+    rv = 1;
+cleanup:
+    OSSL_DECODER_CTX_free(dctx);
+
+    /*
+     * pkey is created by OSSL_DECODER_CTX_new_for_pkey, but we
+     * might fail subsequently, so ensure it's properly freed
+     * in this case.
+     */
+    if (rv == 0) {
+        EVP_PKEY_free(pkey);
+        pkey = NULL;
+    }
+
+    return pkey;
+}
+
+/*
+ * Store an RSA public or private key to a file using PEM encoding.
+ *
+ * If a passphrase is supplied, the file is encrypted, otherwise
+ * it is unencrypted.
+ */
+static int store_key(EVP_PKEY *pkey, FILE *f, const char *passphrase)
+{
+    int rv = 0;
+    int selection;
+    OSSL_ENCODER_CTX *ectx = NULL;
+
+    /*
+     * Create a PEM encoder context.
+     *
+     * For raw (non-PEM-encoded) output, change "PEM" to "DER".
+     *
+     * The selection argument controls whether the private key is exported
+     * (EVP_PKEY_KEYPAIR), or only the public key (EVP_PKEY_PUBLIC_KEY). The
+     * former will fail if we only have a public key.
+     *
+     * Note that unlike the decode API, you cannot specify zero here.
+     *
+     * Purely for the sake of demonstration, here we choose to export the whole
+     * key if a passphrase is provided and the public key otherwise.
+     */
+    selection = (passphrase != NULL)
+        ? EVP_PKEY_KEYPAIR
+        : EVP_PKEY_PUBLIC_KEY;
+
+    ectx = OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "PEM", NULL, propq);
+    if (ectx == NULL) {
+        fprintf(stderr, "OSSL_ENCODER_CTX_new_for_pkey() failed\n");
+        goto cleanup;
+    }
+
+    /*
+     * Set passphrase if provided; the encoded output will then be encrypted
+     * using the passphrase.
+     *
+     * Alternative methods for specifying passphrases exist, such as a callback
+     * (see OSSL_ENCODER_CTX_set_passphrase_cb(3), just as for OSSL_DECODER_CTX;
+     * however you are less likely to need them as you presumably know whether
+     * encryption is desired in advance.
+     *
+     * Note that specifying a passphrase alone is not enough to cause the
+     * key to be encrypted. You must set both a cipher and a passphrase.
+     */
+    if (passphrase != NULL) {
+        /* Set cipher. AES-128-CBC is a reasonable default. */
+        if (OSSL_ENCODER_CTX_set_cipher(ectx, "AES-128-CBC", propq) == 0) {
+            fprintf(stderr, "OSSL_ENCODER_CTX_set_cipher() failed\n");
+            goto cleanup;
+        }
+
+        /* Set passphrase. */
+        if (OSSL_ENCODER_CTX_set_passphrase(ectx,
+                                            (const unsigned char *)passphrase,
+                                            strlen(passphrase)) == 0) {
+            fprintf(stderr, "OSSL_ENCODER_CTX_set_passphrase() failed\n");
+            goto cleanup;
+        }
+    }
+
+    /* Do the encode, writing to the given file. */
+    if (OSSL_ENCODER_to_fp(ectx, f) == 0) {
+        fprintf(stderr, "OSSL_ENCODER_to_fp() failed\n");
+        goto cleanup;
+    }
+
+    rv = 1;
+cleanup:
+    OSSL_ENCODER_CTX_free(ectx);
+    return rv;
+}
+
+int main(int argc, char **argv)
+{
+    int rv = 1;
+    OSSL_LIB_CTX *libctx = NULL;
+    EVP_PKEY *pkey = NULL;
+    const char *passphrase_in = NULL, *passphrase_out = NULL;
+
+    /* usage: rsa_encode <passphrase-in> <passphrase-out> */
+    if (argc > 1 && argv[1][0])
+        passphrase_in = argv[1];
+
+    if (argc > 2 && argv[2][0])
+        passphrase_out = argv[2];
+
+    /* Decode PEM key from stdin and then PEM encode it to stdout. */
+    pkey = load_key(libctx, stdin, passphrase_in);
+    if (pkey == NULL) {
+        fprintf(stderr, "Failed to decode key\n");
+        goto cleanup;
+    }
+
+    if (store_key(pkey, stdout, passphrase_out) == 0) {
+        fprintf(stderr, "Failed to encode key\n");
+        goto cleanup;
+    }
+
+    rv = 0;
+cleanup:
+    EVP_PKEY_free(pkey);
+    OSSL_LIB_CTX_free(libctx);
+    return rv;
+}
diff --git a/doc/HOWTO/certificates.txt b/doc/HOWTO/certificates.txt
index cfd2bdabb1..78ab97b419 100644
--- a/doc/HOWTO/certificates.txt
+++ b/doc/HOWTO/certificates.txt
@@ -30,7 +30,7 @@ keys, so before you create a certificate or a certificate request, you
 need to create a private key.
 
 Private keys are generated with 'openssl genrsa -out privkey.pem' if
-you want a RSA private key, or if you want a DSA private key:
+you want an RSA private key, or if you want a DSA private key:
 'openssl dsaparam -out dsaparam.pem 2048; openssl gendsa -out privkey.pem dsaparam.pem'.
 
 The private keys created by these commands are not passphrase protected;
diff --git a/doc/HOWTO/keys.txt b/doc/HOWTO/keys.txt
index 9f0967cf55..c4a74c54fc 100644
--- a/doc/HOWTO/keys.txt
+++ b/doc/HOWTO/keys.txt
@@ -14,9 +14,9 @@ algorithms.  The most popular ones associated with certificates are
 RSA and DSA, and this HOWTO will show how to generate each of them.
 
 
-2. To generate a RSA key
+2. To generate an RSA key
 
-A RSA key can be used both for encryption and for signing.
+An RSA key can be used both for encryption and for signing.
 
 Generating a key for the RSA algorithm is quite easy, all you have to
 do is the following:
diff --git a/doc/man3/SSL_CTX_set_cipher_list.pod b/doc/man3/SSL_CTX_set_cipher_list.pod
index 29e4a424f7..71f399400c 100644
--- a/doc/man3/SSL_CTX_set_cipher_list.pod
+++ b/doc/man3/SSL_CTX_set_cipher_list.pod
@@ -80,7 +80,7 @@ additional restrictions apply. All ciphers have additional requirements.
 ADH ciphers don't need a certificate, but DH-parameters must have been set.
 All other ciphers need a corresponding certificate and key.
 
-A RSA cipher can only be chosen, when a RSA certificate is available.
+An RSA cipher can only be chosen, when an RSA certificate is available.
 RSA ciphers using DHE need a certificate and key and additional DH-parameters
 (see L<SSL_CTX_set_tmp_dh_callback(3)>).
 
diff --git a/doc/man3/SSL_CTX_use_certificate.pod b/doc/man3/SSL_CTX_use_certificate.pod
index 1bad97454a..ca1827dada 100644
--- a/doc/man3/SSL_CTX_use_certificate.pod
+++ b/doc/man3/SSL_CTX_use_certificate.pod
@@ -130,7 +130,7 @@ RSA key found to B<ssl>.
 SSL_CTX_check_private_key() checks the consistency of a private key with
 the corresponding certificate loaded into B<ctx>. If more than one
 key/certificate pair (RSA/DSA) is installed, the last item installed will
-be checked. If e.g. the last item was a RSA certificate or key, the RSA
+be checked. If e.g. the last item was an RSA certificate or key, the RSA
 key/certificate pair will be checked. SSL_check_private_key() performs
 the same check for B<ssl>. If no key/certificate was explicitly added for
 this B<ssl>, the last item added into B<ctx> will be checked.
diff --git a/doc/man3/SSL_CTX_use_serverinfo.pod b/doc/man3/SSL_CTX_use_serverinfo.pod
index ece8744d55..ebdb5c6f7c 100644
--- a/doc/man3/SSL_CTX_use_serverinfo.pod
+++ b/doc/man3/SSL_CTX_use_serverinfo.pod
@@ -59,7 +59,7 @@ SSL_SERVERINFOV2 data or "BEGIN SERVERINFO FOR " for SSL_SERVERINFOV1 data.
 
 If more than one certificate (RSA/DSA) is installed using
 SSL_CTX_use_certificate(), the serverinfo extension will be loaded into the
-last certificate installed.  If e.g. the last item was a RSA certificate, the
+last certificate installed.  If e.g. the last item was an RSA certificate, the
 loaded serverinfo extension data will be loaded for that certificate.  To
 use the serverinfo extension for multiple certificates,
 SSL_CTX_use_serverinfo() needs to be called multiple times, once B<after>
diff --git a/test/keymgmt_internal_test.c b/test/keymgmt_internal_test.c
index bd95d4c984..ce2e458f8c 100644
--- a/test/keymgmt_internal_test.c
+++ b/test/keymgmt_internal_test.c
@@ -227,7 +227,7 @@ static int test_pass_rsa(FIXTURE *fixture)
     while (dup_pk == NULL) {
         ret = 0;
         km = km3;
-        /* Check that we can't export an RSA key into a RSA-PSS keymanager */
+        /* Check that we can't export an RSA key into an RSA-PSS keymanager */
         if (!TEST_ptr_null(provkey2 = evp_pkey_export_to_provider(pk, NULL,
                                                                   &km,
                                                                   NULL)))
diff --git a/test/sslapitest.c b/test/sslapitest.c
index 19adc96b73..83f1bc3fbf 100644
--- a/test/sslapitest.c
+++ b/test/sslapitest.c
@@ -399,7 +399,7 @@ static int test_keylog(void)
      * Now we want to test that our output data was vaguely sensible. We
      * do that by using strtok and confirming that we have more or less the
      * data we expect. For both client and server, we expect to see one master
-     * secret. The client should also see a RSA key exchange.
+     * secret. The client should also see an RSA key exchange.
      */
     expected.rsa_key_exchange_count = 1;
     expected.master_secret_count = 1;