rsa: write documentation of new functions for parse/writing RSA priv/pub keys

Signed-off-by: Valerio Setti <valerio.setti@nordicsemi.no>

library/rsa.c

@@ -688,9 +688,6 @@ static int asn1_get_nonzero_mpi(unsigned char **p,
     return 0;
 }
 
-/*
- * Parse a PKCS#1 encoded private RSA key
- */
 int mbedtls_rsa_key_parse(mbedtls_rsa_context *rsa, const unsigned char *key, size_t keylen)
 {
     int ret, version;
@@ -837,17 +834,18 @@ cleanup:
     return ret;
 }
 
+int mbedtls_rsa_pubkey_parse(mbedtls_rsa_context *rsa, unsigned char **p,
+                             const unsigned char *end)
+{
+    int ret = MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED;
+    size_t len;
+
     /*
      *  RSAPublicKey ::= SEQUENCE {
      *      modulus           INTEGER,  -- n
      *      publicExponent    INTEGER   -- e
      *  }
      */
-int mbedtls_rsa_pubkey_parse(mbedtls_rsa_context *rsa, unsigned char **p,
-                             const unsigned char *end)
-{
-    int ret = MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED;
-    size_t len;
 
     if ((ret = mbedtls_asn1_get_tag(p, end, &len,
                                     MBEDTLS_ASN1_CONSTRUCTED | MBEDTLS_ASN1_SEQUENCE)) != 0) {

library/rsa_internal.h

@@ -17,44 +17,77 @@
 #include "mbedtls/rsa.h"
 
 /**
- * \brief
+ * \brief           Parse a PKCS#1 (ASN.1) encoded private RSA key.
  *
- * \param rsa
+ * \param rsa       The RSA context where parsed data will be stored.
- * \param key
+ * \param key       The buffer that contains the key.
- * \param keylen
+ * \param keylen    The length of the key buffer in bytes.
- * \return int
+ *
+ * \return          0 in success
+ * \return          MBEDTLS_ERR_ASN1_xxx in case of ASN.1 parsing errors.
+ * \return          MBEDTLS_ERR_RSA_BAD_INPUT_DATA in case of invalid version.
  */
 int mbedtls_rsa_key_parse(mbedtls_rsa_context *rsa, const unsigned char *key, size_t keylen);
 
 /**
- * \brief
+ * \brief           Parse a PKCS#1 (ASN.1) encoded public RSA key.
  *
- * \param rsa
+ * \param rsa       The RSA context where parsed data will be stored.
- * \param p
+ * \param p         Beginning of the buffer containing the key to be parsed.
- * \param end
+ *                  On successful return, the referenced pointer will be
- * \return int
+ *                  updated in order to point to the end of the parsed data.
+ * \param end       End of the buffer containing the key to be parsed.
+ *
+ * \return          0 on success.
+ * \return          MBEDTLS_ERR_ASN1_xxx in case of ASN.1 parsing errors.
+ * \return          MBEDTLS_ERR_RSA_BAD_INPUT_DATA in case of importing or
+ *                  priv/pub validation errors.
  */
 int mbedtls_rsa_pubkey_parse(mbedtls_rsa_context *rsa, unsigned char **p,
                              const unsigned char *end);
 
 /**
- * \brief
+ * \brief           Write a PKCS#1 (ASN.1) encoded private RSA key.
  *
- * \param p
+ * \param rsa       The RSA context which contains the data to be written.
- * \param start
+ * \param start     Beginning of the buffer that will be filled with the
- * \param rsa
+ *                  private key.
- * \return int
+ * \param p         End of the buffer that will be filled with the private key.
+ *                  On successful return, the referenced pointer will be
+ *                  updated in order to point to the beginning of written data.
+ *
+ * \return          On success, the number of bytes written to the output buffer
+ *                  (i.e. a value > 0).
+ * \return          MBEDTLS_ERR_RSA_BAD_INPUT_DATA is the RSA context does not
+ *                  cointain valid.
+ * \return          MBEDTLS_ERR_ASN1_xxx in case of failure while writing to the
+ *                  output buffer.
+ *
+ * \note            The output buffer is filled backward, i.e. starting from its
+ *                  end and moving toward its start.
  */
 int mbedtls_rsa_key_write(const mbedtls_rsa_context *rsa, unsigned char *start,
                           unsigned char **p);
 
 /**
- * \brief
+ * \brief           Parse a PKCS#1 (ASN.1) encoded public RSA key.
  *
- * \param p
+ * \param rsa       The RSA context which contains the data to be written.
- * \param start
+ * \param start     Beginning of the buffer that will be filled with the
- * \param rsa
+ *                  private key.
- * \return int
+ * \param p         End of the buffer that will be filled with the private key.
+ *                  On successful return, the referenced pointer will be
+ *                  updated in order to point to the beginning of written data.
+ *
+ * \return          On success, the number of bytes written to the output buffer
+ *                  (i.e. a value > 0).
+ * \return          MBEDTLS_ERR_RSA_BAD_INPUT_DATA is the RSA context does not
+ *                  cointain valid.
+ * \return          MBEDTLS_ERR_ASN1_xxx in case of failure while writing to the
+ *                  output buffer.
+ *
+ * \note            The output buffer is filled backward, i.e. starting from its
+ *                  end and moving toward its start.
  */
 int mbedtls_rsa_pubkey_write(const mbedtls_rsa_context *rsa, unsigned char *start,
                              unsigned char **p);