Add an in_progress error return code

Ref: WebAssembly/wasi-crypto#26

witx/proposal_common.witx

@@ -126,6 +126,13 @@
     ;;;
     ;;; Non-generic options are required and must be given by building an `options` set and giving that object to functions instantiating that algorithm.
     $parameters_missing
+
+    ;;; A requested computation is not done yet, and additional calls to the function are required.
+    ;;;
+    ;;; Some functions, such as functions generating key pairs and password stretching functions, can take a long time to complete.
+    ;;;
+    ;;; In order to avoid a host call to be blocked for too long, these functions can return prematurely, requiring additional calls with the same parameters until they complete.
+    $in_progress
   )
 )
 

witx/proposal_signatures.witx

@@ -11,6 +11,9 @@
   ;;;
   ;;; The function may also return `unsupported_algorithm` if the algorithm is not supported by the host.
   ;;;
+  ;;; Finally, if generating that type of key pair is an expensive operation, the function may return `in_progress`.
+  ;;; In that case, the guest should retry with the same parameters until the function completes.
+  ;;;
   ;;; Example usage:
   ;;;
   ;;; ```rust

witx/proposal_symmetric.md

@@ -802,7 +802,7 @@ ctx.symmetric_options_set_guest_buffer(options_handle, "memory", &mut memory)?;
 ctx.symmetric_options_set_u64(options_handle, "opslimit", 5)?;
 ctx.symmetric_options_set_u64(options_handle, "parallelism", 8)?;
 
-let state_handle = ctx.symmetric_state_open("Argon2id", None, Some(options))?;
+let state_handle = ctx.symmetric_state_open("ARGON2-ID-13", None, Some(options))?;
 ctx.symmtric_state_absorb(state_handle, b"password")?;
 
 let pw_str_handle = ctx.symmetric_state_squeeze_tag(state_handle)?;

witx/proposal_symmetric.witx

@@ -248,7 +248,7 @@
   ;;; ctx.symmetric_options_set_u64(options_handle, "opslimit", 5)?;
   ;;; ctx.symmetric_options_set_u64(options_handle, "parallelism", 8)?;
   ;;;
-  ;;; let state_handle = ctx.symmetric_state_open("Argon2id", None, Some(options))?;
+  ;;; let state_handle = ctx.symmetric_state_open("ARGON2-ID-13", None, Some(options))?;
   ;;; ctx.symmtric_state_absorb(state_handle, b"password")?;
   ;;;
   ;;; let pw_str_handle = ctx.symmetric_state_squeeze_tag(state_handle)?;
@@ -380,6 +380,9 @@
   ;;; - **Stateful hash objects, permutation-based constructions:** squeeze.
   ;;;
   ;;; Other kinds of algorithms may return `invalid_operation` instead.
+  ;;;
+  ;;; For password-stretching functions, the function may return `in_progress`.
+  ;;; In that case, the guest should retry with the same parameters until the function completes.
   (@interface func (export "symmetric_state_squeeze")
     (param $handle $symmetric_state)
     (param $out (@witx pointer u8))
@@ -394,6 +397,9 @@
   ;;; - **Password-hashing functions:** returns a standard string containing all the required parameters for password verification.
   ;;;
   ;;; Other kinds of algorithms may return `invalid_operation` instead.
+  ;;;
+  ;;; For password-stretching functions, the function may return `in_progress`.
+  ;;; In that case, the guest should retry with the same parameters until the function completes.
   (@interface func (export "symmetric_state_squeeze_tag")
     (param $handle $symmetric_state)
     (result $error $crypto_errno)

witx/wasi_ephemeral_crypto.md

@@ -802,7 +802,7 @@ ctx.symmetric_options_set_guest_buffer(options_handle, "memory", &mut memory)?;
 ctx.symmetric_options_set_u64(options_handle, "opslimit", 5)?;
 ctx.symmetric_options_set_u64(options_handle, "parallelism", 8)?;
 
-let state_handle = ctx.symmetric_state_open("Argon2id", None, Some(options))?;
+let state_handle = ctx.symmetric_state_open("ARGON2-ID-13", None, Some(options))?;
 ctx.symmtric_state_absorb(state_handle, b"password")?;
 
 let pw_str_handle = ctx.symmetric_state_squeeze_tag(state_handle)?;