diff --git a/pk/mirage_crypto_pk.mli b/pk/mirage_crypto_pk.mli index 9304c37d..ba3f4188 100644 --- a/pk/mirage_crypto_pk.mli +++ b/pk/mirage_crypto_pk.mli @@ -62,7 +62,7 @@ module Rsa : sig val priv : e:Z.t -> d:Z.t -> n:Z.t -> p:Z.t -> q:Z.t -> dp:Z.t -> dq:Z.t -> q':Z.t -> (priv, [> `Msg of string ]) result (** [priv ~e ~d ~n ~p ~q ~dp ~dq ~q'] validates the private key: [e, n] must - be a valid {!pub}, [p] and [q] valid prime numbers [> 0], [odd], + be a valid {!type-pub}, [p] and [q] valid prime numbers [> 0], [odd], probabilistically prime, [p <> q], [n = p * q], [e] probabilistically prime and coprime to both [p] and [q], [q' = q ^ -1 mod p], [1 < d < n], [dp = d mod (p - 1)], [dq = d mod (q - 1)], @@ -76,12 +76,12 @@ module Rsa : sig val priv_of_primes : e:Z.t -> p:Z.t -> q:Z.t -> (priv, [> `Msg of string ]) result - (** [priv_of_primes ~e ~p ~q] is the {{!priv}private key} derived from the + (** [priv_of_primes ~e ~p ~q] is the {{!type-priv}private key} derived from the minimal description [(e, p, q)]. *) val priv_of_exp : ?g:Mirage_crypto_rng.g -> ?attempts:int -> e:Z.t -> d:Z.t -> n:Z.t -> unit -> (priv, [> `Msg of string ]) result - (** [priv_of_exp ?g ?attempts ~e ~d n] is the unique {{!priv}private key} + (** [priv_of_exp ?g ?attempts ~e ~d n] is the unique {{!type-priv}private key} characterized by the public ([e]) and private ([d]) exponents, and modulus [n]. This operation uses a probabilistic process that can fail to recover the key. @@ -139,8 +139,8 @@ module Rsa : sig (** {1 Key generation} *) val generate : ?g:Mirage_crypto_rng.g -> ?e:Z.t -> bits:bits -> unit -> priv - (** [generate ~g ~e ~bits ()] is a new {{!priv}private key}. The new key is - guaranteed to be well formed, see {!priv}. + (** [generate ~g ~e ~bits ()] is a new {{!type-priv}private key}. The new key is + guaranteed to be well formed, see {!val-priv}. [e] defaults to [2^16+1]. @@ -156,7 +156,7 @@ module Rsa : sig (** {b PKCS v1.5} operations, as defined by {b PKCS #1 v1.5}. For the operations that only add the raw padding, the key size must be at - least 11 bytes larger than the message. For full {{!sign}signing}, the + least 11 bytes larger than the message. For full {{!PKCS1.sign}signing}, the minimal key size varies according to the hash algorithm. In this case, the key size is [priv_bits key / 8], rounded up. *) module PKCS1 : sig @@ -261,7 +261,7 @@ module Rsa : sig val sign : ?g:Mirage_crypto_rng.g -> ?crt_hardening:bool -> ?mask:mask -> ?slen:int -> key:priv -> Cstruct.t or_digest -> Cstruct.t - (** [sign ~g ~crt_hardening ~mask ~slen ~key message] the {!p PSS}-padded + (** [sign ~g ~crt_hardening ~mask ~slen ~key message] the [PSS]-padded digest of [message], signed with the [key]. [crt_hardening] defaults to [false]. @@ -314,7 +314,7 @@ module Dsa : sig (priv, [> `Msg of string ]) result (** [priv ~fips ~p ~q ~gg ~x ~y ()] constructs a private DSA key from the given numbers. Will result in an error if parameters are ill-formed: same as - {!pub}, and additionally [0 < x < q] and [y = g ^ x mod p]. Note that no + {!val-pub}, and additionally [0 < x < q] and [y = g ^ x mod p]. Note that no time masking is done on the modular exponentiation. *) type pub = private { @@ -323,7 +323,7 @@ module Dsa : sig gg : Z.t ; y : Z.t ; } - (** Public key, a subset of {{!priv}private key}. + (** Public key, a subset of {{!type-priv}private key}. {e [Sexplib] convertible}. *) @@ -348,7 +348,7 @@ module Dsa : sig (** Extract the public component from a private key. *) val generate : ?g:Mirage_crypto_rng.g -> keysize -> priv - (** [generate g size] is a fresh {{!priv}private} key. The domain parameters + (** [generate g size] is a fresh {{!type-priv}private} key. The domain parameters are derived using a modified FIPS.186-4 probabilistic process, but the derivation can not be validated. Note that no time masking is done for the modular exponentiations. @@ -451,7 +451,7 @@ module Dh : sig val gen_key : ?g:Mirage_crypto_rng.g -> ?bits:bits -> group -> secret * Cstruct.t (** Generate a random {!secret} and the corresponding public key. [bits] is the exact bit-size of {!secret} and defaults to a value - dependent on the {!group}'s [p]. + dependent on the {!type-group}'s [p]. {b Note} The process might diverge when [bits] is extremely small. *) @@ -464,7 +464,7 @@ module Dh : sig [1 < public < p-1] && [public <> gg]. *) val gen_group : ?g:Mirage_crypto_rng.g -> bits:bits -> unit -> group - (** [gen_group ~g ~bits ()] generates a random {!group} with modulus size + (** [gen_group ~g ~bits ()] generates a random {!type-group} with modulus size [bits]. Uses a safe prime [p = 2q + 1] (with [q] prime) for the modulus and [2] for the generator, such that [2^q = 1 mod p]. Runtime is on the order of a minute for 1024 bits. @@ -473,7 +473,7 @@ module Dh : sig {b Note} The process might diverge if there are no suitable groups. This happens with extremely small [bits] values. *) - (** A small catalog of standardized {!group}s. *) + (** A small catalog of standardized {!type-group}s. *) module Group : sig (** From RFC 2409: *) @@ -522,7 +522,7 @@ module Z_extra : sig 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. + {{!Z.t}[t]} in big-endian. If [~bits] is not given, the operation considers the entire [cs], otherwise the initial [min ~bits (bit-length cs)] bits of [cs]. diff --git a/rng/mirage_crypto_rng.mli b/rng/mirage_crypto_rng.mli index 029b770a..0dd9f909 100644 --- a/rng/mirage_crypto_rng.mli +++ b/rng/mirage_crypto_rng.mli @@ -73,7 +73,7 @@ exception Unseeded_generator (** Thrown when using an uninitialized {{!g}generator}. *) exception No_default_generator -(** Thrown when {!set_generator} has not been called. *) +(** Thrown when {!set_default_generator} has not been called. *) (** Entropy sources and collection *) module Entropy : sig @@ -214,7 +214,7 @@ val default_generator : unit -> g (** [default_generator ()] is the default generator. Functions in this module use this generator when not explicitly supplied one. - @raise No_default_generator if {!set_generator} has not been called. *) + @raise No_default_generator if {!set_default_generator} has not been called. *) val set_default_generator : g -> unit (** [set_default_generator g] sets the default generator to [g]. This function diff --git a/src/mirage_crypto.mli b/src/mirage_crypto.mli index 22eb2ab8..2cc4857d 100644 --- a/src/mirage_crypto.mli +++ b/src/mirage_crypto.mli @@ -29,7 +29,7 @@ module Uncommon : sig @raise Division_by_zero when [y < 1]. *) - (** Addons to {!Cstruct}. *) + (** Addons to the {!Cstruct} interface. *) module Cs : sig val (<+>) : Cstruct.t -> Cstruct.t -> Cstruct.t @@ -70,9 +70,9 @@ end (** Hashes. - Each algorithm is contained in its own {{!hashing_modules}module}, with - high-level operations accessible through {{!hashing_funs}functions} that - dispatch on {{!hash}code} value. *) + Each algorithm is contained in its own {{!Hash.S}module}, with + high-level operations accessible through functions that + dispatch on {{!Hash.hash}code} value. *) module Hash : sig type digest = Cstruct.t @@ -88,7 +88,7 @@ module Hash : sig {- [let iter_pair : 'a * 'a -> 'a iter = fun (x, y) f = f x; f y]} {- [let iter_list : 'a list -> 'a iter = fun xs f -> List.iter f xs]}} *) - (** {1:hashing_modules Hashing algorithms} *) + (** {1 Hashing algorithms} *) (** A single hash algorithm. *) module type S = sig @@ -158,7 +158,7 @@ module Hash : sig (** [digesti iter = feedi empty iter |> get] *) val hmaci : key:Cstruct.t -> Cstruct.t iter -> digest - (** See {{!hmac}[hmac]}. *) + (** See {{!val-hmac}[hmac]}. *) end module MD5 : S @@ -182,7 +182,7 @@ module Hash : sig This is the most convenient way to go from a code to a module. *) - (** {1:hashing_funs Hash functions} *) + (** {1 Hash functions} *) val digest : [< hash ] -> Cstruct.t -> digest (** [digest algorithm bytes] is [algorithm] applied to [bytes]. *)