style improve

- Better comments
- Better naming

mbedtls/src/ecp/mod.rs

@@ -309,10 +309,6 @@ impl EcPoint {
         Mpi::copy(&self.inner.Y)
     }
 
-    pub fn z(&self) -> Result<Mpi> {
-        Mpi::copy(&self.inner.Z)
-    }
-
     pub fn is_zero(&self) -> Result<bool> {
         /*
         mbedtls_ecp_is_zero takes arg as non-const for no particular reason
@@ -373,9 +369,14 @@ Please use `mul_with_rng` instead."
     ///
     /// This function will return an error if:
     ///
-    /// * `k` is not a valid private key, or `self` is not a valid public key.
+    /// * `k` is not a valid private key, determined by mbedtls function [`mbedtls_ecp_check_privkey`]
+    /// * `self` is not a valid public key, determined by mbedtls function [`mbedtls_ecp_check_pubkey`]
     /// * Memory allocation fails.
-    /// * Any other kind of failure occurs during the execution of the underlying `mbedtls_ecp_mul` function.
+    /// * Any other kind of failure occurs during the execution of the underlying [`mbedtls_ecp_mul`] function.
+    ///
+    /// [`mbedtls_ecp_check_pubkey`]: https://github.com/fortanix/rust-mbedtls/blob/main/mbedtls-sys/vendor/include/mbedtls/ecp.h#L1115-L1143
+    /// [`mbedtls_ecp_check_privkey`]: https://github.com/fortanix/rust-mbedtls/blob/main/mbedtls-sys/vendor/include/mbedtls/ecp.h#L1145-L1165
+    /// [`mbedtls_ecp_mul`]: https://github.com/fortanix/rust-mbedtls/blob/main/mbedtls-sys/vendor/include/mbedtls/ecp.h#L933-L971
     pub fn mul_with_rng<F: crate::rng::Random>(&self, group: &mut EcGroup, k: &Mpi, rng: &mut F) -> Result<EcPoint> {
         // Note: mbedtls_ecp_mul performs point validation itself so we skip that here
 
@@ -433,7 +434,12 @@ Please use `mul_with_rng` instead."
         }
     }
 
-    /// This function compares two points in const time.
+    /// This function checks equalness of two points in const time.
+    ///
+    /// The implementation is based on C mbedtls function [`mbedtls_ecp_point_cmp`].
+    /// This new implementation ensures there is no shortcut when any of `x, y ,z` fields of two points is not equal.
+    ///
+    /// [`mbedtls_ecp_point_cmp`]: https://github.com/fortanix/rust-mbedtls/blob/main/mbedtls-sys/vendor/library/ecp.c#L809-L825
     pub fn eq_const_time(&self, other: &EcPoint) -> bool {
         unsafe {
             let x = mpi_cmp_mpi(&self.inner.X, &other.inner.X) == 0;

mbedtls/src/pk/mod.rs

@@ -308,7 +308,7 @@ impl Pk {
     #[deprecated(
         since = "0.12.3",
         note = "This function does not accept an RNG so it's vulnerable to side channel attacks.
-Please use `private_from_ec_components_with_rng` instead."
+Please use `private_from_ec_scalar_with_rng` instead."
     )]
     pub fn private_from_ec_components(mut curve: EcGroup, private_key: Mpi) -> Result<Pk> {
         let mut ret = Self::init();
@@ -348,10 +348,10 @@ Please use `private_from_ec_components_with_rng` instead."
     ///
     /// This function will return an error if:
     ///
-    /// * Fails to genearte `EcPoint` from given EcGroup in `curve`.
+    /// * Fails to generate `EcPoint` from given EcGroup in `curve`.
     /// * The underlying C `mbedtls_pk_setup` function fails to set up the `Pk` context.
-    /// * The `EcPoint::mul` function fails to generate the public key point.
-    pub fn private_from_ec_components_with_rng<F: Random>(mut curve: EcGroup, private_key: Mpi, rng: &mut F) -> Result<Pk> {
+    /// * The `EcPoint::mul_with_rng` function fails to generate the public key point.
+    pub fn private_from_ec_scalar_with_rng<F: Random>(mut curve: EcGroup, private_key: Mpi, rng: &mut F) -> Result<Pk> {
         let mut ret = Self::init();
         let curve_generator = curve.generator()?;
         let public_point = curve_generator.mul_with_rng(&mut curve, &private_key, rng)?;
@@ -1205,7 +1205,7 @@ iy6KC991zzvaWY/Ys+q/84Afqa+0qJKQnPuy/7F5GkVdQA/lfbhi
 
         assert_eq!(pem1, pem2);
 
-        let mut key_from_components = Pk::private_from_ec_components_with_rng(
+        let mut key_from_components = Pk::private_from_ec_scalar_with_rng(
             secp256r1.clone(),
             key1.ec_private().unwrap(),
             &mut crate::test_support::rand::test_rng(),