Make more use of OSSL_PARAM for digests
authorRichard Levitte <levitte@openssl.org>
Tue, 16 Jul 2019 03:59:50 +0000 (05:59 +0200)
committerRichard Levitte <levitte@openssl.org>
Mon, 12 Aug 2019 11:35:18 +0000 (13:35 +0200)
A lot of the different numbers associated with digests are really
algorithm parameters.  block size, digest length, that sort of
thing.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9391)

crypto/include/internal/evp_int.h
doc/man7/provider-digest.pod
include/openssl/core_names.h
include/openssl/core_numbers.h

index 9d87898..cdb5aab 100644 (file)
@@ -212,10 +212,9 @@ struct evp_md_st {
     OSSL_OP_digest_digest_fn *digest;
     OSSL_OP_digest_freectx_fn *freectx;
     OSSL_OP_digest_dupctx_fn *dupctx;
-    OSSL_OP_digest_size_fn *size;
-    OSSL_OP_digest_block_size_fn *dblock_size;
-    OSSL_OP_digest_set_params_fn *set_params;
     OSSL_OP_digest_get_params_fn *get_params;
+    OSSL_OP_digest_ctx_set_params_fn *ctx_set_params;
+    OSSL_OP_digest_ctx_get_params_fn *ctx_get_params;
 
 } /* EVP_MD */ ;
 
index f6c3286..0842842 100644 (file)
@@ -31,10 +31,11 @@ provider-digest - The digest library E<lt>-E<gt> provider functions
                       unsigned char *out, size_t *outl, size_t outsz);
 
  /* Digest parameters */
- size_t OP_digest_size(void);
- size_t OP_digest_block_size(void);
- int OP_digest_set_params(void *dctx, const OSSL_PARAM params[]);
- int OP_digest_get_params(void *dctx, OSSL_PARAM params[]);
+ int OP_digest_get_params(OSSL_PARAM params[]);
+
+ /* Digest context parameters */
+ int OP_digest_ctx_set_params(void *dctx, const OSSL_PARAM params[]);
+ int OP_digest_ctx_get_params(void *dctx, OSSL_PARAM params[]);
 
 =head1 DESCRIPTION
 
@@ -129,18 +130,72 @@ exceed B<outsz> bytes.
 
 =head2 Digest Parameters
 
-OP_digest_size() should return the size of the digest.
+OP_digest_get_params() gets details of the algorithm implementation
+and stores them in B<params>.
+See L<OSSL_PARAM(3)> for further details on the parameters structure.
+
+Parameters currently recognised by built-in digests with this function
+are as follows. Not all parametes are relevant to, or are understood
+by all digests:
+
+=over 4
+
+=item B<OSSL_DIGEST_PARAM_BLOCK_SIZE> (int)
+
+The digest block size.
+
+=item B<OSSL_DIGEST_PARAM_SIZE> (int)
+
+The digest output size.
+
+=item B<OSSL_DIGEST_PARAM_FLAGS> (unsigned long)
+
+Diverse flags that describe exceptional behaviour for the digest:
+
+=over 4
+
+=item B<EVP_MD_FLAG_ONESHOT>
+
+This digest method can only handle one block of input.
+
+=item B<EVP_MD_FLAG_XOF>
+
+This digest method is an extensible-output function (XOF) and supports
+setting the B<OSSL_DIGEST_PARAM_XOFLEN> parameter.
+
+=item B<EVP_MD_FLAG_DIGALGID_NULL>
+
+When setting up a DigestAlgorithmIdentifier, this flag will have the
+parameter set to NULL by default.  Use this for PKCS#1.  I<Note: if
+combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.>
+
+=item B<EVP_MD_FLAG_DIGALGID_ABSENT>
+
+When setting up a DigestAlgorithmIdentifier, this flag will have the
+parameter be left absent by default.  I<Note: if combined with
+EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
+
+=item B<EVP_MD_FLAG_DIGALGID_CUSTOM>
+
+Custom DigestAlgorithmIdentifier handling via ctrl, with
+B<EVP_MD_FLAG_DIGALGID_ABSENT> as default.  I<Note: if combined with
+EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
+Currently unused.
+
+=back
+
+=back
 
-OP_digest_block_size() should return the size of the block size of the
-underlying digest algorithm.
+=head2 Digest Context Parameters
 
-OP_digest_set_params() set digest parameters associated with the given provider
-side digest context B<dctx> to B<params>.
+OP_digest_ctx_set_params() sets digest parameters associated with the
+given provider side digest context B<dctx> to B<params>.
 Any parameter settings are additional to any that were previously set.
 See L<OSSL_PARAM(3)> for further details on the parameters structure.
 
-OP_digest_get_params() gets details of currently set parameters values associated
-with the give provider side digest context B<dctx> and stores them in B<params>.
+OP_digest_ctx_get_params() gets details of currently set parameters
+values associated with the give provider side digest context B<dctx>
+and stores them in B<params>.
 See L<OSSL_PARAM(3)> for further details on the parameters structure.
 
 Parameters currently recognised by built-in digests are as follows. Not all
index d1ba624..bf57d15 100644 (file)
@@ -55,6 +55,9 @@ extern "C" {
 #define OSSL_DIGEST_PARAM_SSL3_MS   "ssl3-ms"
 #define OSSL_DIGEST_PARAM_PAD_TYPE  "pad_type"
 #define OSSL_DIGEST_PARAM_MICALG    "micalg"
+#define OSSL_DIGEST_PARAM_BLOCK_SIZE "blocksize" /* OSSL_PARAM_INTEGER */
+#define OSSL_DIGEST_PARAM_SIZE      "size" /* OSSL_PARAM_INTEGER */
+#define OSSL_DIGEST_PARAM_FLAGS     "flags" /* OSSL_PARAM_UNSIGNED_INTEGER */
 
 /* PKEY parameters */
 /* Diffie-Hellman Parameters */
index f4c4a61..e4d3f5d 100644 (file)
@@ -136,19 +136,18 @@ OSSL_CORE_MAKE_FUNC(const OSSL_ITEM *,provider_get_reason_strings,
 
 /* Digests */
 
-# define OSSL_OP_DIGEST                     1
-
-# define OSSL_FUNC_DIGEST_NEWCTX            1
-# define OSSL_FUNC_DIGEST_INIT              2
-# define OSSL_FUNC_DIGEST_UPDATE            3
-# define OSSL_FUNC_DIGEST_FINAL             4
-# define OSSL_FUNC_DIGEST_DIGEST            5
-# define OSSL_FUNC_DIGEST_FREECTX           6
-# define OSSL_FUNC_DIGEST_DUPCTX            7
-# define OSSL_FUNC_DIGEST_SIZE              8
-# define OSSL_FUNC_DIGEST_BLOCK_SIZE        9
-# define OSSL_FUNC_DIGEST_SET_PARAMS        10
-# define OSSL_FUNC_DIGEST_GET_PARAMS        11
+# define OSSL_OP_DIGEST                              1
+
+# define OSSL_FUNC_DIGEST_NEWCTX                     1
+# define OSSL_FUNC_DIGEST_INIT                       2
+# define OSSL_FUNC_DIGEST_UPDATE                     3
+# define OSSL_FUNC_DIGEST_FINAL                      4
+# define OSSL_FUNC_DIGEST_DIGEST                     5
+# define OSSL_FUNC_DIGEST_FREECTX                    6
+# define OSSL_FUNC_DIGEST_DUPCTX                     7
+# define OSSL_FUNC_DIGEST_GET_PARAMS                 8
+# define OSSL_FUNC_DIGEST_CTX_SET_PARAMS             9
+# define OSSL_FUNC_DIGEST_CTX_GET_PARAMS            10
 
 OSSL_CORE_MAKE_FUNC(void *, OP_digest_newctx, (void *provctx))
 OSSL_CORE_MAKE_FUNC(int, OP_digest_init, (void *dctx))
@@ -164,12 +163,11 @@ OSSL_CORE_MAKE_FUNC(int, OP_digest_digest,
 OSSL_CORE_MAKE_FUNC(void, OP_digest_freectx, (void *dctx))
 OSSL_CORE_MAKE_FUNC(void *, OP_digest_dupctx, (void *dctx))
 
-OSSL_CORE_MAKE_FUNC(size_t, OP_digest_size, (void))
-OSSL_CORE_MAKE_FUNC(size_t, OP_digest_block_size, (void))
-OSSL_CORE_MAKE_FUNC(int, OP_digest_set_params,
-                    (void *dctx, const OSSL_PARAM params[]))
-OSSL_CORE_MAKE_FUNC(int, OP_digest_get_params,
-                    (void *dctx, OSSL_PARAM params[]))
+OSSL_CORE_MAKE_FUNC(int, OP_digest_get_params, (OSSL_PARAM params[]))
+OSSL_CORE_MAKE_FUNC(int, OP_digest_ctx_set_params,
+                    (void *vctx, const OSSL_PARAM params[]))
+OSSL_CORE_MAKE_FUNC(int, OP_digest_ctx_get_params,
+                    (void *vctx, OSSL_PARAM params[]))
 
 /* Symmetric Ciphers */