documentation updates

entropy/mirage_crypto_entropy.mli

@@ -46,4 +46,4 @@ val initialize :
   ?g:'a -> (module Mirage_crypto_rng.Generator with type g = 'a) -> t Lwt.t
 (** [initialize ~g rng_module] sets the default generator to the [rng_module]
     and sets up periodic entropy feeding for that rng. This function raises if
-    called a second time. *)
+    it is called a second time. *)

pk/mirage_crypto_pk.mli

@@ -1,16 +1,8 @@
 (** {1 Public-key cryptography} *)
 
-(** {b RSA} public-key cryptography.
-
-Keys are taken to be trusted material, and their properties are not checked.
-
-Messages are checked not to exceed the key size, and this is signalled via
-exceptions.
-
-Private-key operations are optionally protected through RSA blinding. *)
-
 type bits = int
 
+(** {b RSA} public-key cryptography algorithm. *)
 module Rsa : sig
 
   (** {1 Keys}
@@ -20,7 +12,12 @@ module Rsa : sig
       the client to ensure the trustworthiness of keys.
 
       The two anchoring points provided are {{!generate}[generate]} and
-      {{!well_formed}[well_formed]}. *)
+      {{!well_formed}[well_formed]}.
+
+      Messages are checked not to exceed the key size, and this is signalled via
+      the {!Insufficient_key} exception.
+
+      Private-key operations are optionally protected through RSA blinding. *)
 
   exception Insufficient_key
   (** Raised if the key is too small to transform the given message, i.e. if the
@@ -143,8 +140,8 @@ module Rsa : sig
       result is correct. This is to counter Chinese remainder theorem attacks to
       factorize primes. If the computed signature is incorrect, it is again
       computed in the classical way (c ^ d mod n) without the Chinese remainder
-      theorem optimization. The deterministic PKCS1 signing, which is at danger,
-      uses [true] as default.
+      theorem optimization. The deterministic {{!PKCS1.sign}PKCS1 signing},
+      which is at danger, uses [true] as default.
 
       [~mask] defaults to [`Yes].
 
@@ -234,6 +231,8 @@ module Rsa : sig
         @raise Invalid_argument if message is a [`Digest] of the wrong size.  *)
   end
 
+  (** {1 OAEP padded modes} *)
+
   (** {b OAEP}-padded encryption, as defined by {b PKCS #1 v2.1}.
 
       The same hash function is used for padding and MGF. MGF is {b MGF1} as
@@ -258,6 +257,8 @@ module Rsa : sig
         defaults to [false]. *)
   end
 
+  (** {1 PSS signing} *)
+
   (** {b PSS}-based signing, as defined by {b PKCS #1 v2.1}.
 
       The same hash function is used for padding, MGF and computing message
@@ -269,7 +270,7 @@ module Rsa : sig
 
     val sign : ?g:Mirage_crypto_rng.g -> ?rsa_crt_hardening:bool ->
       ?mask:mask -> ?slen:int -> key:priv -> Cstruct.t or_digest -> Cstruct.t
-    (** [sign ~g ~rsa_crt_hardening ~mask ~slen ~key message] the {p PSS}-padded
+    (** [sign ~g ~rsa_crt_hardening ~mask ~slen ~key message] the {!p PSS}-padded
         digest of [message], signed with the [key]. [rsa_crt_hardening] defaults
         to [false].
 
@@ -492,7 +493,10 @@ module Dh : sig
 
 end
 
+(** {b Z} Convert Z to big endian Cstruct.t and generate random Z values. *)
 module Z_extra : sig
+  (** {1 Conversion to and from Cstruct.t} *)
+
   val of_cstruct_be : ?bits:bits -> Cstruct.t -> Z.t
   (** [of_cstruct_be ~bits cs] interprets the bit pattern of [cs] as a
       {{!t}[t]} in big-endian.

rng/mirage_crypto_rng.ml

@@ -68,5 +68,3 @@ let block g =
 
 let strict g =
   let Generator (_, s, _) = get g in s
-
-type buffer = Cstruct.t

rng/mirage_crypto_rng.mli

@@ -9,7 +9,7 @@
        facility to convert such modules into actual {{!g}generators}, and
        functions that operate on this representation.}
     {- A global generator instance, the default is {{!Null}Null}, used
-       when one is not explicitly supplied.}
+       when one is not explicitly supplied.}}
 *)
 
 (** {1 Usage notes} *)
@@ -162,25 +162,11 @@ val strict : g option -> bool
 {[let rec f1 ?g ~n i =
   if i < 1 then [] else Rng.generate ?g n :: f1 ?g ~n (i - 1)]}
 
-    Generating a [Z.t] smaller than [10] and an [int64] in the range [\[3, 7\]]:
-{[let f2 ?g () = Rng.(Z.gen ?g ~$10, Int64.gen_r 3L 8L)]}
+    Generating a [Z.t] smaller than [10]:
+{[let f2 ?g () = Mirage_crypto_pk.Z_extra.gen ?g Z.(~$10)]}
 
     Creating a local Fortuna instance and using it as a key-derivation function:
 {[let f3 secret =
   let g = Rng.(create ~seed:secret (module Generators.Fortuna)) in
   Rng.generate ~g 32]}
-
-    Generating a 17-bit prime with two leading bits set:
-{[let p = Rng.prime ~msb:2 17]}
-
-    Fisher-Yates shuffle:
-{[let f4 ?g arr =
-  let n = Array.length arr in
-  arr |> Array.iter @@ fun i ->
-    let j = Rng.Int.gen_r ?g i n in
-    let (a, b) = (arr.(i), arr.(j)) in
-    arr.(i) <- b ; arr.(j) <- a ]}
-      *)
-
-type buffer = Cstruct.t
-(** Type definition to satisfy MirageOS RANDOM signature *)
+*)

src/mirage_crypto.mli

@@ -102,6 +102,8 @@ module Uncommon : sig
   val failwith : ('a, Format.formatter, unit, unit, unit, 'b) format6 -> 'a
 end
 
+(**/**)
+
 (** {1 Hashing} *)
 
 (** Hashes.
@@ -145,7 +147,7 @@ module Hash : sig
     (** [feed t msg] adds the information in [msg] to [t].
 
         [feed] is analogous to appending:
-        [feed (feed t msg1) msg2 = feed t (append msg1 msg2)]. *)
+        [feed (feed t msg1) msg2 = feed t (Cstruct.append msg1 msg2)]. *)
 
     val get : t -> digest
     (** [get t] is the digest corresponding to [t]. *)
@@ -164,7 +166,7 @@ module Hash : sig
         secret [key], generated using the standard HMAC construction over this
         hash algorithm. *)
 
-    (** {1:hashing_funs Functions over iterators}
+    (** {1 Functions over iterators}
 
         Functions that operate on arbitrary {{!iter}iterators}. They can serve
         as a basis for other, more specialized aggregate hashing operations.
@@ -173,7 +175,7 @@ module Hash : sig
 
     val feedi : t -> Cstruct.t iter -> t
     (** [feedi t iter =
-  (let r = ref t in iter (fun msg -> r := feed !r msg); !r)] *)
+        (let r = ref t in iter (fun msg -> r := feed !r msg); !r)] *)
 
     val digesti : Cstruct.t iter -> digest
     (** [digesti iter = feedi empty iter |> get] *)
@@ -195,18 +197,32 @@ module Hash : sig
   (** Algorithm codes. *)
 
   val hashes : hash list
+  (** [hashes] is a list of all implemented hash algorithms. *)
 
   val module_of   : [< hash ] -> (module S)
   (** [module_of hash] is the (first-class) module corresponding to the code
       [hash].
 
       This is the most convenient way to go from a code to a module. *)
 
+  (** {1:hashing_funs Hash functions} *)
+
   val digest      : [< hash ] -> Cstruct.t -> digest
+  (** [digest algorithm bytes] is [algorithm] applied to [bytes]. *)
+
   val digesti     : [< hash ] -> Cstruct.t iter -> digest
+  (** [digesti algorithm iter] is [algorithm] applied to [iter]. *)
+
   val mac         : [< hash ] -> key:Cstruct.t -> Cstruct.t -> digest
+  (** [mac algorithm ~key bytes] is the mac [algorithm] applied to [bytes]
+      under [key]. *)
+
   val maci        : [< hash ] -> key:Cstruct.t -> Cstruct.t iter -> digest
+  (** [maci algorithm ~key iter] is the mac [algorithm] applied to [iter] under
+      [key]. *)
+
   val digest_size : [< hash ] -> int
+  (** [digest_size algorithm] is the size of the [algorithm] in bytes. *)
 end
 
 
@@ -345,6 +361,7 @@ module Cipher_block : sig
       (** [decrypt] is [encrypt]. *)
 
       val add_ctr : ctr -> int64 -> ctr
+      (** [add_ctr ctr n] adds [n] to [ctr]. *)
 
       val next_ctr : ctr:ctr -> Cstruct.t -> ctr
       (** [next_ctr ~ctr msg] is the state of the counter after encrypting or
@@ -362,6 +379,7 @@ module Cipher_block : sig
           *)
 
       val ctr_of_cstruct : Cstruct.t -> ctr
+      (** [ctr_of_cstruct cs] converts the value of [cs] into a counter. *)
     end
 
     (** {e Galois/Counter Mode}. *)