Fix style in crypto/store/loader_file.c

With added commenting to describe the individual decoders a little
more.

Reviewed-by: Andy Polyakov <appro@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3930)

diff --git a/crypto/store/loader_file.c b/crypto/store/loader_file.c
index 5b0ca9775618b000203c98bc6250ffffe29b8b82..570f12ba12aa42e197b2e479a7f5ecf42be094d1 100644 (file)
--- a/crypto/store/loader_file.c
+++ b/crypto/store/loader_file.c
@@ -30,8 +30,9 @@
 
 #include "e_os.h"
 
-/*
+/*-
  *  Password prompting
+ *  ------------------
  */
 
 static char *file_get_pass(const UI_METHOD *ui_method, char *pass,
@@ -83,6 +84,7 @@ struct pem_pass_data {
     void *data;
     const char *prompt_info;
 };
+
 static int file_fill_pem_pass_data(struct pem_pass_data *pass_data,
                                    const char *prompt_info,
                                    const UI_METHOD *ui_method, void *ui_data)
@@ -94,6 +96,8 @@ static int file_fill_pem_pass_data(struct pem_pass_data *pass_data,
     pass_data->prompt_info = prompt_info;
     return 1;
 }
+
+/* This is used anywhere a pem_password_cb is needed */
 static int file_get_pem_pass(char *buf, int num, int w, void *data)
 {
     struct pem_pass_data *pass_data = data;
@@ -103,8 +107,14 @@ static int file_get_pem_pass(char *buf, int num, int w, void *data)
     return pass == NULL ? 0 : strlen(pass);
 }
 
-/*
- *  The file scheme handlers
+/*-
+ *  The file scheme decoders
+ *  ------------------------
+ *
+ *  Each possible data type has its own decoder, which either operates
+ *  through a given PEM name, or attempts to decode to see if the blob
+ *  it's given is decodable for its data type.  The assumption is that
+ *  only the correct data type will match the content.
  */
 
 /*-
@@ -168,6 +178,11 @@ typedef struct file_handler_st {
     int repeatable;
 } FILE_HANDLER;
 
+/*
+ * PKCS#12 decoder.  It operates by decoding all of the blob content,
+ * extracting all the interesting data from it and storing them internally,
+ * then serving them one piece at a time.
+ */
 static OSSL_STORE_INFO *try_decode_PKCS12(const char *pem_name,
                                           const char *pem_header,
                                           const unsigned char *blob,
@@ -267,12 +282,14 @@ static OSSL_STORE_INFO *try_decode_PKCS12(const char *pem_name,
 
     return store_info;
 }
+
 static int eof_PKCS12(void *ctx_)
 {
     STACK_OF(OSSL_STORE_INFO) *ctx = ctx_;
 
     return ctx == NULL || sk_OSSL_STORE_INFO_num(ctx) == 0;
 }
+
 static void destroy_ctx_PKCS12(void **pctx)
 {
     STACK_OF(OSSL_STORE_INFO) *ctx = *pctx;
@@ -280,6 +297,7 @@ static void destroy_ctx_PKCS12(void **pctx)
     sk_OSSL_STORE_INFO_pop_free(ctx, OSSL_STORE_INFO_free);
     *pctx = NULL;
 }
+
 static FILE_HANDLER PKCS12_handler = {
     "PKCS12",
     try_decode_PKCS12,
@@ -288,6 +306,11 @@ static FILE_HANDLER PKCS12_handler = {
     1                            /* repeatable */
 };
 
+/*
+ * Encrypted PKCS#8 decoder.  It operates by just decrypting the given blob
+ * into a new blob, which is returned as an EMBEDDED STORE_INFO.  The whole
+ * decoding process will then start over with the new blob.
+ */
 static OSSL_STORE_INFO *try_decode_PKCS8Encrypted(const char *pem_name,
                                                   const char *pem_header,
                                                   const unsigned char *blob,
@@ -352,11 +375,17 @@ static OSSL_STORE_INFO *try_decode_PKCS8Encrypted(const char *pem_name,
     BUF_MEM_free(mem);
     return NULL;
 }
+
 static FILE_HANDLER PKCS8Encrypted_handler = {
     "PKCS8Encrypted",
     try_decode_PKCS8Encrypted
 };
 
+/*
+ * Private key decoder.  Decodes all sorts of private keys, both PKCS#8
+ * encoded ones and old style PEM ones (with the key type is encoded into
+ * the PEM name).
+ */
 int pem_check_suffix(const char *pem_str, const char *suffix);
 static OSSL_STORE_INFO *try_decode_PrivateKey(const char *pem_name,
                                               const char *pem_header,
@@ -425,11 +454,15 @@ static OSSL_STORE_INFO *try_decode_PrivateKey(const char *pem_name,
 
     return store_info;
 }
+
 static FILE_HANDLER PrivateKey_handler = {
     "PrivateKey",
     try_decode_PrivateKey
 };
 
+/*
+ * Public key decoder.  Only supports SubjectPublicKeyInfo formated keys.
+ */
 static OSSL_STORE_INFO *try_decode_PUBKEY(const char *pem_name,
                                           const char *pem_header,
                                           const unsigned char *blob,
@@ -455,11 +488,15 @@ static OSSL_STORE_INFO *try_decode_PUBKEY(const char *pem_name,
 
     return store_info;
 }
+
 static FILE_HANDLER PUBKEY_handler = {
     "PUBKEY",
     try_decode_PUBKEY
 };
 
+/*
+ * Key parameter decoder.
+ */
 static OSSL_STORE_INFO *try_decode_params(const char *pem_name,
                                           const char *pem_header,
                                           const unsigned char *blob,
@@ -534,11 +571,15 @@ static OSSL_STORE_INFO *try_decode_params(const char *pem_name,
 
     return store_info;
 }
+
 static FILE_HANDLER params_handler = {
     "params",
     try_decode_params
 };
 
+/*
+ * X.509 certificate decoder.
+ */
 static OSSL_STORE_INFO *try_decode_X509Certificate(const char *pem_name,
                                                    const char *pem_header,
                                                    const unsigned char *blob,
@@ -580,11 +621,15 @@ static OSSL_STORE_INFO *try_decode_X509Certificate(const char *pem_name,
 
     return store_info;
 }
+
 static FILE_HANDLER X509Certificate_handler = {
     "X509Certificate",
     try_decode_X509Certificate
 };
 
+/*
+ * X.509 CRL decoder.
+ */
 static OSSL_STORE_INFO *try_decode_X509CRL(const char *pem_name,
                                            const char *pem_header,
                                            const unsigned char *blob,
@@ -613,11 +658,15 @@ static OSSL_STORE_INFO *try_decode_X509CRL(const char *pem_name,
 
     return store_info;
 }
+
 static FILE_HANDLER X509CRL_handler = {
     "X509CRL",
     try_decode_X509CRL
 };
 
+/*
+ * To finish it all off, we collect all the handlers.
+ */
 static const FILE_HANDLER *file_handlers[] = {
     &PKCS12_handler,
     &PKCS8Encrypted_handler,
@@ -629,8 +678,9 @@ static const FILE_HANDLER *file_handlers[] = {
 };
 
 
-/*
+/*-
  *  The loader itself
+ *  -----------------
  */
 
 struct ossl_store_loader_ctx_st {