Merge branch 'hans/crypto/cuddle_docs'

* hans/crypto/cuddle_docs:
  crypto: Remove old comment
  crypto: Restore 'error' as result of failed aead decryption
  crypto: Update types of hash algorithms
  crypto: Cuddle error types and documentation of them
  crypto: Note about key lengths for cipher_info/1
  crypto: Update CipherModes for PR/2186
  crypto: Declare *_info return map and other review-comments
  crypto: Declare *_info return map and other review-comments
  crypto: Document hash_info/1 and cipher_info/1
  crypto: Rename block_crypto_with/without to match stream_cipher names
  crypto: New types (block_cipher)

2 files changed, 220 insertions, 70 deletions

diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 83e10c4c78..8a4fad67de 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -192,7 +192,16 @@
   <datatypes>
     <datatype_title>Ciphers</datatype_title>
     <datatype>
+      <name name="cipher"/>
       <name name="stream_cipher"/>
+      <name name="block_cipher"/>
+      <desc>
+	<p>Ciphers known byt the CRYPTO application. Note that this list might be reduced if the
+	underlying libcrypto does not support all of them.</p>
+      </desc>
+    </datatype>
+
+    <datatype>
       <name name="stream_cipher_iv"/>
       <name name="stream_cipher_no_iv"/>
       <desc>
@@ -204,7 +213,7 @@
     </datatype>
 
     <datatype>
-      <name name="block_cipher_with_iv"/>
+      <name name="block_cipher_iv"/>
       <name name="cbc_cipher"/>
       <name name="cfb_cipher"/>
       <desc>
@@ -228,7 +237,7 @@
     </datatype>
 
     <datatype>
-      <name name="block_cipher_without_iv"/>
+      <name name="block_cipher_no_iv"/>
       <name name="ecb_cipher"/>
       <desc>
 	<p>Block ciphers without initialization vector for
@@ -248,20 +257,16 @@
       </desc>
     </datatype>
 
-    <datatype_title>Digests</datatype_title>
+    <datatype_title>Digests and hash</datatype_title>
     <datatype>
-      <name name="sha1"/>
-      <name name="sha2"/>
-      <name name="sha3"/>
-      <name name="blake2"/>
+      <name name="hash_algorithm"/>
       <desc>
       </desc>
     </datatype>
 
     <datatype>
-      <name name="compatibility_only_hash"/>
+      <name name="hmac_hash_algorithm"/>
       <desc>
-	<p>The <c>compatibility_only_hash()</c> algorithms are recommended only for compatibility with existing applications.</p>
       </desc>
     </datatype>
 
@@ -283,6 +288,17 @@
       </desc>
     </datatype>
 
+    <datatype>
+      <name name="sha1"/>
+      <name name="sha2"/>
+      <name name="sha3"/>
+      <name name="blake2"/>
+      <name name="compatibility_only_hash"/>
+      <desc>
+	<p>The <c>compatibility_only_hash()</c> algorithms are recommended only for compatibility with existing applications.</p>
+      </desc>
+    </datatype>
+
     <datatype_title>Elliptic Curves</datatype_title>
     <datatype>
       <name name="ec_named_curve"/>
@@ -537,6 +553,52 @@
       </desc>
     </datatype>
 
+    <datatype_title>Error types</datatype_title>
+
+    <datatype>
+      <name name="run_time_error"/>
+      <desc>
+	<p>The exception <c>error:badarg</c> signifies that one or more arguments are of wrong data type,
+	or are otherwise badly formed.
+	</p>
+	<p>The exception <c>error:notsup</c> signifies that the algorithm is known but is not supported
+	by current underlying libcrypto or explicitly disabled when building that.
+	</p>
+	<p>For a list of supported algorithms, see <seealso marker="#supports-0">supports/0</seealso>.
+	</p>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="descriptive_error"/>
+      <desc>
+	<p>This is a more developed variant of the older
+	<seealso marker="#type-run_time_error">run_time_error()</seealso>.
+	</p>
+	<p>It is like the older type an exception of the <c>error</c> class. In addition they contain
+	a descriptive text in English. That text is targeted to a developer. Examples are "Bad key size"
+	or "Cipher id is not an atom".
+	</p>
+	<p>The exceptions are:</p>
+	<taglist>
+	  <tag><c>{badarg, Description::string()}</c></tag>
+	  <item><p>Signifies that one or more arguments are of wrong data type or are otherwise badly formed.</p>
+	  </item>
+
+	  <tag><c>{notsup, Description::string()}</c></tag>
+	  <item><p>Signifies that the algorithm is known but is not supported by current underlying libcrypto
+	  or explicitly disabled when building that one.</p>
+	  </item>
+
+	  <tag><c>{error, Description::string()}</c></tag>
+	  <item><p>An error condition that should not occur, for example a memory allocation failed or
+	  the underlying cryptolib returned an error code, for example "Can't initialize context, step 1".
+	  Thoose text usually needs searching the C-code to be understood.</p>
+	  </item>
+	</taglist>
+      </desc>
+    </datatype>
+
   </datatypes>
 
   <!--================ FUNCTIONS ================-->
@@ -568,17 +630,18 @@
     </func>
 
     <func>
-      <name since="OTP R16B01">block_encrypt(Type, Key, Ivec, PlainText) -> CipherText</name>
-      <name since="OTP R16B01">block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) -> {CipherText, CipherTag}</name>
-      <name since="OTP R16B01">block_encrypt(aes_gcm | aes_ccm, Key, Ivec, {AAD, PlainText, TagLength}) -> {CipherText, CipherTag}</name>
+      <name since="OTP R16B01">block_encrypt(Type, Key, Ivec, PlainText) -> CipherText | Error</name>
+      <name since="OTP R16B01">block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) -> {CipherText, CipherTag} | Error</name>
+      <name since="OTP R16B01">block_encrypt(aes_gcm | aes_ccm, Key, Ivec, {AAD, PlainText, TagLength}) -> {CipherText, CipherTag} | Error </name>
       <fsummary>Encrypt <c>PlainText</c> according to <c>Type</c> block cipher</fsummary>
       <type>
-	<v>Type = <seealso marker="#type-block_cipher_with_iv">block_cipher_with_iv()</seealso></v>
+	<v>Type = <seealso marker="#type-block_cipher_iv">block_cipher_iv()</seealso></v>
 	<v>AeadType = <seealso marker="#type-aead_cipher">aead_cipher()</seealso></v>
 	<v>Key = <seealso marker="#type-key">key()</seealso> | <seealso marker="#type-des3_key">des3_key()</seealso></v>
         <v>PlainText = iodata()</v>
         <v>AAD = IVec = CipherText = CipherTag = binary()</v>
         <v>TagLength = 1..16</v>
+	<v>Error = <seealso marker="#type-run_time_error">run_time_error()</seealso></v>
       </type>
       <desc>
         <p>Encrypt <c>PlainText</c> according to <c>Type</c> block cipher.
@@ -595,15 +658,17 @@
     </func>
 
     <func>
-      <name since="OTP R16B01">block_decrypt(Type, Key, Ivec, CipherText) -> PlainText</name>
-      <name since="OTP R16B01">block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) -> PlainText | error</name>
+      <name since="OTP R16B01">block_decrypt(Type, Key, Ivec, CipherText) -> PlainText | Error</name>
+      <name since="OTP R16B01">block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) -> PlainText | Error</name>
       <fsummary>Decrypt <c>CipherText</c> according to <c>Type</c> block cipher</fsummary>
       <type>
-	<v>Type = <seealso marker="#type-block_cipher_with_iv">block_cipher_with_iv()</seealso></v>
+	<v>Type = <seealso marker="#type-block_cipher_iv">block_cipher_iv()</seealso></v>
 	<v>AeadType = <seealso marker="#type-aead_cipher">aead_cipher()</seealso></v>
 	<v>Key = <seealso marker="#type-key">key()</seealso> | <seealso marker="#type-des3_key">des3_key()</seealso></v>
         <v>PlainText = iodata()</v>
         <v>AAD = IVec = CipherText = CipherTag = binary()</v>
+	<v>Error = BadTag | <seealso marker="#type-run_time_error">run_time_error()</seealso></v>
+	<v>BadTag = error</v>
       </type>
       <desc>
         <p>Decrypt <c>CipherText</c> according to <c>Type</c> block cipher.
@@ -844,6 +909,39 @@
     </func>
 
     <func>
+      <name name="hash_info" arity="1" since="OTP 22.0"/>
+      <fsummary>Information about supported hash algorithms.</fsummary>
+      <desc>
+	<p>Provides a map with information about block_size, size and possibly other properties of the
+	hash algorithm in question.
+	</p>
+	<p>For a list of supported hash algorithms, see <seealso marker="#supports-0">supports/0</seealso>.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="cipher_info" arity="1" since="OTP 22.0"/>
+      <fsummary>Information about supported ciphers.</fsummary>
+      <desc>
+	<p>Provides a map with information about block_size, key_length, iv_length and possibly other properties of the
+	cipher algorithm in question.
+	</p>
+        <note>
+	  <p>The ciphers <c>aes_cbc</c>, <c>aes_cfb8</c>, <c>aes_cfb128</c>, <c>aes_ctr</c>, 
+	  <c>aes_ecb</c>, <c>aes_gcm</c> and <c>aes_ccm</c>
+	  has no keylength in the <c>Type</c> as opposed to for example <c>aes_128_ctr</c>. They adapt to the length of
+	  the key provided in the encrypt and decrypt function. Therefor it is impossible to return a valid keylength
+	  in the map.</p>
+	  <p>Always use a <c>Type</c> with an explicit key length,
+	  </p>
+	</note>
+	<p>For a list of supported cipher algorithms, see <seealso marker="#supports-0">supports/0</seealso>.
+	</p>
+      </desc>
+    </func>
+
+    <func>
       <name name="mod_pow" arity="3" since="OTP R16B01"/>
       <fsummary>Computes the function: N^P mod M</fsummary>
       <desc>
@@ -1289,8 +1387,8 @@ FloatValue = rand:uniform().     % again
       <desc>
         <p> Can be used to determine which crypto algorithms that are supported
 	by the underlying libcrypto library</p>
-	<p>Note: the <c>rsa_opts</c> entry is in an experimental state and may change or be removed without notice.
-	No guarantee for the accuarcy of the rsa option's value list should be assumed.
+	<p>See <seealso marker="#hash_info-1">hash_info/1</seealso> and <seealso marker="#cipher_info-1">cipher_info/1</seealso>
+	for information about the hash and cipher algorithms.
 	</p>
       </desc>
     </func>
diff --git a/lib/crypto/src/crypto.erl b/lib/crypto/src/crypto.erl
index 503c347c56..a5e60fbe75 100644
--- a/lib/crypto/src/crypto.erl
+++ b/lib/crypto/src/crypto.erl
@@ -277,7 +277,13 @@
 -type edwards_curve_ed() :: ed25519 | ed448 .
 
 %%% 
--type block_cipher_with_iv() :: cbc_cipher()
+-type cipher() :: block_cipher()
+                | stream_cipher()
+                | aead_cipher() .
+
+-type block_cipher() :: block_cipher_iv() | block_cipher_no_iv() .
+
+-type block_cipher_iv() :: cbc_cipher()
                               | cfb_cipher()
                               | aes_ige256
                               | blowfish_ofb64
@@ -310,7 +316,7 @@
                    | des3_cfb .
 
 
--type block_cipher_without_iv() :: ecb_cipher() .
+-type block_cipher_no_iv() :: ecb_cipher() .
 -type ecb_cipher()  :: des_ecb | blowfish_ecb | aes_ecb .
 
 -type key() :: iodata().
@@ -330,6 +336,20 @@
 
 -type crypto_integer() :: binary() | integer().
 
+%%%
+%% Exceptions
+%%   error:badarg
+%%   error:notsup
+-type run_time_error() :: no_return().
+
+%% Exceptions
+%%   error:{badarg,Reason::term()}
+%%   error:{notsup,Reason::term()}
+%%   error:{error,Reason::term()}
+-type descriptive_error() :: no_return() .
+
+
+%%--------------------------------------------------------------------
 -compile(no_native).
 -on_load(on_load/0).
 -define(CRYPTO_NIF_VSN,302).
@@ -368,10 +388,7 @@ stop() ->
                                       | {curves,  Curves}
                                       | {rsa_opts, RSAopts},
                              Hashs :: [sha1() | sha2() | sha3() | blake2() | ripemd160 | compatibility_only_hash()],
-                             Ciphers :: [stream_cipher()
-                                         | block_cipher_with_iv() | block_cipher_without_iv()
-                                         | aead_cipher()
-                                        ],
+                             Ciphers :: [cipher()],
                              PKs :: [rsa | dss | ecdsa | dh | ecdh | ec_gf2m],
                              Macs :: [hmac | cmac | poly1305],
                              Curves :: [ec_named_curve() | edwards_curve_dh() | edwards_curve_ed()],
@@ -405,14 +422,18 @@ enable_fips_mode(_) -> ?nif_stub.
 %%%
 %%%================================================================
 
--define(HASH_HASH_ALGORITHM, sha1() | sha2() | sha3() | blake2() | ripemd160 | compatibility_only_hash() ).
-
--spec hash_info(Type) -> map() when Type :: ?HASH_HASH_ALGORITHM.
+-type hash_algorithm() :: sha1() | sha2() | sha3() | blake2() | ripemd160 | compatibility_only_hash() .
 
+-spec hash_info(Type) -> Result | run_time_error()
+                             when Type :: hash_algorithm(),
+                                  Result :: #{size := integer(),
+                                              block_size := integer(),
+                                              type := integer()
+                                             } .
 hash_info(Type) ->
     notsup_to_error(hash_info_nif(Type)).
 
--spec hash(Type, Data) -> Digest when Type :: ?HASH_HASH_ALGORITHM,
+-spec hash(Type, Data) -> Digest when Type :: hash_algorithm(),
                                       Data :: iodata(),
                                       Digest :: binary().
 hash(Type, Data) ->
@@ -422,7 +443,7 @@ hash(Type, Data) ->
 
 -opaque hash_state() :: reference().
 
--spec hash_init(Type) -> State when Type :: ?HASH_HASH_ALGORITHM,
+-spec hash_init(Type) -> State when Type :: hash_algorithm(),
                                     State :: hash_state().
 hash_init(Type) -> 
     notsup_to_error(hash_init_nif(Type)).
@@ -448,12 +469,12 @@ hash_final(Context) ->
 
 %%%---- HMAC
 
--define(HMAC_HASH_ALGORITHM,  sha1() | sha2() | sha3() | compatibility_only_hash()).
+-type hmac_hash_algorithm() ::  sha1() | sha2() | sha3() | compatibility_only_hash().
 
 %%%---- hmac/3,4 
 
 -spec hmac(Type, Key, Data) -> 
-                  Mac when Type :: ?HMAC_HASH_ALGORITHM,
+                  Mac when Type :: hmac_hash_algorithm(),
                            Key :: iodata(),
                            Data :: iodata(),
                            Mac :: binary() .
@@ -462,7 +483,7 @@ hmac(Type, Key, Data) ->
     hmac(Type, Key, Data1, undefined, erlang:byte_size(Data1), max_bytes()).
 
 -spec hmac(Type, Key, Data, MacLength) -> 
-                  Mac when Type :: ?HMAC_HASH_ALGORITHM,
+                  Mac when Type :: hmac_hash_algorithm(),
                            Key :: iodata(),
                            Data :: iodata(),
                            MacLength :: integer(),
@@ -477,7 +498,7 @@ hmac(Type, Key, Data, MacLength) ->
 -opaque hmac_state() :: binary().
 
 -spec hmac_init(Type, Key) ->
-                       State when Type :: ?HMAC_HASH_ALGORITHM,
+                       State when Type :: hmac_hash_algorithm(),
                                   Key :: iodata(),
                                   State :: hmac_state() .
 hmac_init(Type, Key) ->
@@ -547,9 +568,30 @@ poly1305(Key, Data) ->
                 error(E)
         end).
 
--spec cipher_info(Type) -> map() when Type :: block_cipher_with_iv()
-                                           | aead_cipher()
-                                           | block_cipher_without_iv().
+%%%---- Cipher info
+%%%----------------------------------------------------------------
+-spec cipher_info(Type) -> Result | run_time_error()
+                               when Type :: cipher(),
+                                    Result :: #{key_length := integer(),
+                                                iv_length := integer(),
+                                                block_size := integer(),
+                                                mode := CipherModes,
+                                                type := undefined | integer()
+                                               },
+                                    CipherModes :: undefined
+                                                 | cbc_mode
+                                                 | ccm_mode
+                                                 | cfb_mode
+                                                 | ctr_mode
+                                                 | ecb_mode
+                                                 | gcm_mode
+                                                 | ige_mode
+                                                 | ocb_mode
+                                                 | ofb_mode
+                                                 | wrap_mode
+                                                 | xts_mode
+                                                   .
+
 %% These ciphers are not available via the EVP interface on older cryptolibs.
 cipher_info(aes_ctr) ->
     #{block_size => 1,iv_length => 16,key_length => 32,mode => ctr_mode,type => undefined};
@@ -567,11 +609,12 @@ cipher_info(Type) ->
 
 %%%---- Block ciphers
 %%%----------------------------------------------------------------
--spec block_encrypt(Type::block_cipher_with_iv(), Key::key()|des3_key(), Ivec::binary(), PlainText::iodata()) -> binary();
+-spec block_encrypt(Type::block_cipher_iv(), Key::key()|des3_key(), Ivec::binary(), PlainText::iodata()) ->
+                           binary() | run_time_error();
                    (Type::aead_cipher(),  Key::iodata(), Ivec::binary(), {AAD::binary(), PlainText::iodata()}) ->
-                           {binary(), binary()};
+                           {binary(), binary()} | run_time_error();
                    (aes_gcm | aes_ccm, Key::iodata(), Ivec::binary(), {AAD::binary(), PlainText::iodata(), TagLength::1..16}) ->
-                           {binary(), binary()}.
+                           {binary(), binary()} | run_time_error().
 
 
 block_encrypt(Type, Key, Ivec, Data) ->
@@ -596,16 +639,19 @@ do_block_encrypt(Type, Key, Ivec, PlainText) ->
     ?COMPAT(crypto_one_shot(Type, Key, Ivec, PlainText, true)).
 
 
--spec block_encrypt(Type::block_cipher_without_iv(), Key::key(), PlainText::iodata()) -> binary().
+-spec block_encrypt(Type::block_cipher_no_iv(), Key::key(), PlainText::iodata()) ->
+                           binary() | run_time_error().
 
 block_encrypt(Type, Key, PlainText) ->
     ?COMPAT(crypto_one_shot(Type, Key, <<>>, PlainText, true)).
 
 %%%----------------------------------------------------------------
 %%%----------------------------------------------------------------
--spec block_decrypt(Type::block_cipher_with_iv(), Key::key()|des3_key(), Ivec::binary(), Data::iodata()) -> binary();
+-spec block_decrypt(Type::block_cipher_iv(), Key::key()|des3_key(), Ivec::binary(), Data::iodata()) ->
+                           binary() | run_time_error();
 		   (Type::aead_cipher(), Key::iodata(), Ivec::binary(),
-		    {AAD::binary(), Data::iodata(), Tag::binary()}) -> binary() | error.
+		    {AAD::binary(), Data::iodata(), Tag::binary()}) ->
+                           binary() | error | run_time_error() .
 
 block_decrypt(Type, Key, Ivec, Data) ->
     do_block_decrypt(alias(Type), Key, Ivec, Data).
@@ -622,7 +668,8 @@ do_block_decrypt(Type, Key, Ivec, Data) ->
     ?COMPAT(crypto_one_shot(Type, Key, Ivec, Data, false)).
 
 
--spec block_decrypt(Type::block_cipher_without_iv(), Key::key(), Data::iodata()) -> binary().
+-spec block_decrypt(Type::block_cipher_no_iv(), Key::key(), Data::iodata()) ->
+                           binary() | run_time_error().
 
 block_decrypt(Type, Key, Data) ->
     ?COMPAT(crypto_one_shot(Type, Key, <<>>, Data, false)).
@@ -642,7 +689,7 @@ block_decrypt(Type, Key, Data) ->
                           | chacha20 .
 
 %%%---- stream_init
--spec stream_init(Type, Key, IVec) -> State | no_return()
+-spec stream_init(Type, Key, IVec) -> State | run_time_error()
                                           when Type :: stream_cipher_iv(),
                                                Key :: iodata(),
                                                IVec ::binary(),
@@ -655,7 +702,7 @@ stream_init(Type, Key, IVec) when is_binary(IVec) ->
     {Type, {Ref,flg_undefined}}.
 
 
--spec stream_init(Type, Key) -> State | no_return()
+-spec stream_init(Type, Key) -> State | run_time_error()
                                     when Type :: stream_cipher_no_iv(),
                                          Key :: iodata(),
                                          State :: stream_state() .
@@ -667,7 +714,7 @@ stream_init(rc4 = Type, Key) ->
     {Type, {Ref,flg_undefined}}.
 
 %%%---- stream_encrypt
--spec stream_encrypt(State, PlainText) -> {NewState, CipherText} | no_return()
+-spec stream_encrypt(State, PlainText) -> {NewState, CipherText} | run_time_error()
                                               when State :: stream_state(),
                                                    PlainText :: iodata(),
                                                    NewState :: stream_state(),
@@ -676,7 +723,7 @@ stream_encrypt(State, Data) ->
     crypto_stream_emulate(State, Data, true).
 
 %%%---- stream_decrypt
--spec stream_decrypt(State, CipherText) -> {NewState, PlainText} | no_return()
+-spec stream_decrypt(State, CipherText) -> {NewState, PlainText} | run_time_error()
                                               when State :: stream_state(),
                                                    CipherText :: iodata(),
                                                    NewState :: stream_state(),
@@ -735,8 +782,8 @@ next_iv(Type, Data, _Ivec) ->
 %%% Create and initialize a new state for encryption or decryption
 %%% 
 
--spec crypto_init(Cipher, Key, EncryptFlag) -> State | ng_crypto_error()
-                                                   when Cipher :: block_cipher_without_iv()
+-spec crypto_init(Cipher, Key, EncryptFlag) -> State | descriptive_error()
+                                                   when Cipher :: block_cipher_no_iv()
                                                                 | stream_cipher_no_iv(),
                                                         Key :: iodata(),
                                                         EncryptFlag :: boolean(),
@@ -746,9 +793,9 @@ crypto_init(Cipher, Key, EncryptFlag) ->
     ng_crypto_init_nif(alias(Cipher), iolist_to_binary(Key), <<>>, EncryptFlag).
 
 
--spec crypto_init(Cipher, Key, IV, EncryptFlag) -> State | ng_crypto_error()
+-spec crypto_init(Cipher, Key, IV, EncryptFlag) -> State | descriptive_error()
                                                        when Cipher :: stream_cipher_iv()
-                                                                    | block_cipher_with_iv(),
+                                                                    | block_cipher_iv(),
                                                             Key :: iodata(),
                                                             IV :: iodata(),
                                                             EncryptFlag :: boolean(),
@@ -759,9 +806,9 @@ crypto_init(Cipher, Key, IV, EncryptFlag) ->
 
 
 %%%----------------------------------------------------------------
--spec crypto_init_dyn_iv(Cipher, Key, EncryptFlag) -> State | ng_crypto_error()
+-spec crypto_init_dyn_iv(Cipher, Key, EncryptFlag) -> State | descriptive_error()
                                                           when Cipher :: stream_cipher_iv()
-                                                                       | block_cipher_with_iv(),
+                                                                       | block_cipher_iv(),
                                                                Key :: iodata(),
                                                                EncryptFlag :: boolean(),
                                                                State :: crypto_state() .
@@ -776,7 +823,7 @@ crypto_init_dyn_iv(Cipher, Key, EncryptFlag) ->
 %%% blocksize.
 %%% 
 
--spec crypto_update(State, Data) -> Result | ng_crypto_error()
+-spec crypto_update(State, Data) -> Result | descriptive_error()
                                         when State :: crypto_state(),
                                              Data :: iodata(),
                                              Result :: binary() .
@@ -790,7 +837,7 @@ crypto_update(State, Data0) ->
 
 
 %%%----------------------------------------------------------------
--spec crypto_update_dyn_iv(State, Data, IV) -> Result | ng_crypto_error()
+-spec crypto_update_dyn_iv(State, Data, IV) -> Result | descriptive_error()
                                                    when State :: crypto_state(),
                                                         Data :: iodata(),
                                                         IV :: iodata(),
@@ -810,15 +857,16 @@ crypto_update_dyn_iv(State, Data0, IV) ->
 %%% The size must be an integer multiple of the crypto's blocksize.
 %%% 
 
--spec crypto_one_shot(Cipher, Key, IV, Data, EncryptFlag) -> Result | ng_crypto_error()
-                                                                 when Cipher :: stream_cipher()
-                                                                              | block_cipher_with_iv()
-                                                                              | block_cipher_without_iv(),
-                                                                      Key :: iodata(),
-                                                                      IV :: iodata() | undefined,
-                                                                      Data :: iodata(),
-                                                                      EncryptFlag :: boolean(),
-                                                                      Result :: binary() .
+-spec crypto_one_shot(Cipher, Key, IV, Data, EncryptFlag) ->
+                             Result | descriptive_error()
+                                 when Cipher :: stream_cipher()
+                                              | block_cipher(),
+                                      Key :: iodata(),
+                                      IV :: iodata() | undefined,
+                                      Data :: iodata(),
+                                      EncryptFlag :: boolean(),
+                                      Result :: binary() .
+
 crypto_one_shot(Cipher, Key, undefined, Data, EncryptFlag) ->
     crypto_one_shot(Cipher, Key, <<>>, Data, EncryptFlag);
 
@@ -835,21 +883,25 @@ crypto_one_shot(Cipher, Key, IV, Data0, EncryptFlag) ->
 %%%----------------------------------------------------------------
 %%% NIFs
 
--type ng_crypto_error() :: no_return() .
+-spec ng_crypto_init_nif(atom(), binary(), binary()|undefined, boolean()|undefined ) ->
+                                crypto_state() | descriptive_error()
+                      ; (crypto_state(), <<>>, <<>>, boolean())
+                        -> crypto_state() | descriptive_error().
 
--spec ng_crypto_init_nif(atom(), binary(), binary()|undefined, boolean()|undefined ) -> crypto_state() | ng_crypto_error()
-                      ; (crypto_state(), <<>>, <<>>, boolean()) -> crypto_state() | ng_crypto_error().
 ng_crypto_init_nif(_Cipher, _Key, _IVec, _EncryptFlg) -> ?nif_stub.
 
 
--spec ng_crypto_update_nif(crypto_state(), binary()) -> binary() | ng_crypto_error() .
+-spec ng_crypto_update_nif(crypto_state(), binary()) ->
+                                  binary() | descriptive_error() .
 ng_crypto_update_nif(_State, _Data) -> ?nif_stub.
 
--spec ng_crypto_update_nif(crypto_state(), binary(), binary()) -> binary() | ng_crypto_error() .
+-spec ng_crypto_update_nif(crypto_state(), binary(), binary()) ->
+                                  binary() | descriptive_error() .
 ng_crypto_update_nif(_State, _Data, _IV) -> ?nif_stub.
 
 
--spec ng_crypto_one_shot_nif(atom(), binary(), binary(), binary(), boolean() ) -> binary() | ng_crypto_error().
+-spec ng_crypto_one_shot_nif(atom(), binary(), binary(), binary(), boolean() ) ->
+                                    binary() | descriptive_error().
 ng_crypto_one_shot_nif(_Cipher, _Key, _IVec, _Data, _EncryptFlg) -> ?nif_stub.
 
 %%%----------------------------------------------------------------