1OSSL_CRMF_PBMP_NEW(3ossl)           OpenSSL          OSSL_CRMF_PBMP_NEW(3ossl)
2
3
4

NAME

6       OSSL_CRMF_pbm_new, OSSL_CRMF_pbmp_new - functions for producing
7       Password-Based MAC (PBM)
8

SYNOPSIS

10        #include <openssl/crmf.h>
11
12        int OSSL_CRMF_pbm_new(OSSL_LIB_CTX *libctx, const char *propq,
13                              const OSSL_CRMF_PBMPARAMETER *pbmp,
14                              const unsigned char *msg, size_t msglen,
15                              const unsigned char *sec, size_t seclen,
16                              unsigned char **mac, size_t *maclen);
17
18        OSSL_CRMF_PBMPARAMETER *OSSL_CRMF_pbmp_new(OSSL_LIB_CTX *libctx, size_t saltlen,
19                                                   int owfnid, size_t itercnt,
20                                                   int macnid);
21

DESCRIPTION

23       OSSL_CRMF_pbm_new() generates a PBM (Password-Based MAC) based on given
24       PBM parameters pbmp, message msg, and secret sec, along with the
25       respective lengths msglen and seclen.  The optional library context
26       libctx and propq parameters may be used to influence the selection of
27       the MAC algorithm referenced in the pbmp; see "ALGORITHM FETCHING" in
28       crypto(7) for further information.  On success writes the address of
29       the newly allocated MAC via the mac reference parameter and writes the
30       length via the maclen reference parameter unless it its NULL.
31
32       OSSL_CRMF_pbmp_new() initializes and returns a new PBMParameter
33       structure with a new random salt of given length saltlen, OWF (one-way
34       function) NID owfnid, OWF iteration count itercnt, and MAC NID macnid.
35       The library context libctx parameter may be used to select the provider
36       for the random number generation (DRBG) and may be NULL for the
37       default.
38

NOTES

40       The algorithms for the OWF (one-way function) and for the MAC (message
41       authentication code) may be any with a NID defined in
42       <openssl/objects.h>.  As specified by RFC 4210, these should include
43       NID_hmac_sha1.
44
45       RFC 4210 recommends that the salt SHOULD be at least 8 bytes (64 bits)
46       long, where 16 bytes is common.
47
48       The iteration count must be at least 100, as stipulated by RFC 4211,
49       and is limited to at most 100000 to avoid DoS through manipulated or
50       otherwise malformed input.
51

RETURN VALUES

53       OSSL_CRMF_pbm_new() returns 1 on success, 0 on error.
54
55       OSSL_CRMF_pbmp_new() returns a new and initialized
56       OSSL_CRMF_PBMPARAMETER structure, or NULL on error.
57

EXAMPLES

59        OSSL_CRMF_PBMPARAMETER *pbm = NULL;
60        unsigned char *msg = "Hello";
61        unsigned char *sec = "SeCrEt";
62        unsigned char *mac = NULL;
63        size_t maclen;
64
65        if ((pbm = OSSL_CRMF_pbmp_new(16, NID_sha256, 500, NID_hmac_sha1) == NULL))
66            goto err;
67        if (!OSSL_CRMF_pbm_new(pbm, msg, 5, sec, 6, &mac, &maclen))
68            goto err;
69

SEE ALSO

71       RFC 4211 section 4.4
72

HISTORY

74       The OpenSSL CRMF support was added in OpenSSL 3.0.
75

77       Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved.
78
79       Licensed under the Apache License 2.0 (the "License").  You may not use
80       this file except in compliance with the License.  You can obtain a copy
81       in the file LICENSE in the source distribution or at
82       <https://www.openssl.org/source/license.html>.
83
84
85
863.0.5                             2022-11-01         OSSL_CRMF_PBMP_NEW(3ossl)
Impressum