| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | OSSL_CRMF_pbm_new,
|
|---|
| 6 | OSSL_CRMF_pbmp_new
|
|---|
| 7 | - functions for producing Password-Based MAC (PBM)
|
|---|
| 8 |
|
|---|
| 9 | =head1 SYNOPSIS
|
|---|
| 10 |
|
|---|
| 11 | #include <openssl/crmf.h>
|
|---|
| 12 |
|
|---|
| 13 | int OSSL_CRMF_pbm_new(OSSL_LIB_CTX *libctx, const char *propq,
|
|---|
| 14 | const OSSL_CRMF_PBMPARAMETER *pbmp,
|
|---|
| 15 | const unsigned char *msg, size_t msglen,
|
|---|
| 16 | const unsigned char *sec, size_t seclen,
|
|---|
| 17 | unsigned char **mac, size_t *maclen);
|
|---|
| 18 |
|
|---|
| 19 | OSSL_CRMF_PBMPARAMETER *OSSL_CRMF_pbmp_new(OSSL_LIB_CTX *libctx, size_t saltlen,
|
|---|
| 20 | int owfnid, size_t itercnt,
|
|---|
| 21 | int macnid);
|
|---|
| 22 |
|
|---|
| 23 | =head1 DESCRIPTION
|
|---|
| 24 |
|
|---|
| 25 | OSSL_CRMF_pbm_new() generates a PBM (Password-Based MAC) based on given PBM
|
|---|
| 26 | parameters I<pbmp>, message I<msg>, and secret I<sec>, along with the respective
|
|---|
| 27 | lengths I<msglen> and I<seclen>.
|
|---|
| 28 | The optional library context I<libctx> and I<propq> parameters may be used
|
|---|
| 29 | to influence the selection of the MAC algorithm referenced in the I<pbmp>;
|
|---|
| 30 | see L<crypto(7)/ALGORITHM FETCHING> for further information.
|
|---|
| 31 | On success writes the address of the newly
|
|---|
| 32 | allocated MAC via the I<mac> reference parameter and writes the length via the
|
|---|
| 33 | I<maclen> reference parameter unless it its NULL.
|
|---|
| 34 |
|
|---|
| 35 | OSSL_CRMF_pbmp_new() initializes and returns a new B<PBMParameter> structure
|
|---|
| 36 | with a new random salt of given length I<saltlen>,
|
|---|
| 37 | OWF (one-way function) NID I<owfnid>, OWF iteration count I<itercnt>,
|
|---|
| 38 | and MAC NID I<macnid>.
|
|---|
| 39 | The library context I<libctx> parameter may be used to select the provider
|
|---|
| 40 | for the random number generation (DRBG) and may be NULL for the default.
|
|---|
| 41 |
|
|---|
| 42 | =head1 NOTES
|
|---|
| 43 |
|
|---|
| 44 | The algorithms for the OWF (one-way function) and for the MAC (message
|
|---|
| 45 | authentication code) may be any with a NID defined in F<< <openssl/objects.h> >>.
|
|---|
| 46 | As specified by RFC 4210, these should include NID_hmac_sha1.
|
|---|
| 47 |
|
|---|
| 48 | RFC 4210 recommends that the salt SHOULD be at least 8 bytes (64 bits) long,
|
|---|
| 49 | where 16 bytes is common.
|
|---|
| 50 |
|
|---|
| 51 | The iteration count must be at least 100, as stipulated by RFC 4211, and is
|
|---|
| 52 | limited to at most 100000 to avoid DoS through manipulated or otherwise
|
|---|
| 53 | malformed input.
|
|---|
| 54 |
|
|---|
| 55 | =head1 RETURN VALUES
|
|---|
| 56 |
|
|---|
| 57 | OSSL_CRMF_pbm_new() returns 1 on success, 0 on error.
|
|---|
| 58 |
|
|---|
| 59 | OSSL_CRMF_pbmp_new() returns a new and initialized OSSL_CRMF_PBMPARAMETER
|
|---|
| 60 | structure, or NULL on error.
|
|---|
| 61 |
|
|---|
| 62 | =head1 EXAMPLES
|
|---|
| 63 |
|
|---|
| 64 | OSSL_CRMF_PBMPARAMETER *pbm = NULL;
|
|---|
| 65 | unsigned char *msg = "Hello";
|
|---|
| 66 | unsigned char *sec = "SeCrEt";
|
|---|
| 67 | unsigned char *mac = NULL;
|
|---|
| 68 | size_t maclen;
|
|---|
| 69 |
|
|---|
| 70 | if ((pbm = OSSL_CRMF_pbmp_new(16, NID_sha256, 500, NID_hmac_sha1) == NULL))
|
|---|
| 71 | goto err;
|
|---|
| 72 | if (!OSSL_CRMF_pbm_new(pbm, msg, 5, sec, 6, &mac, &maclen))
|
|---|
| 73 | goto err;
|
|---|
| 74 |
|
|---|
| 75 | =head1 SEE ALSO
|
|---|
| 76 |
|
|---|
| 77 | RFC 4211 section 4.4
|
|---|
| 78 |
|
|---|
| 79 | =head1 HISTORY
|
|---|
| 80 |
|
|---|
| 81 | The OpenSSL CRMF support was added in OpenSSL 3.0.
|
|---|
| 82 |
|
|---|
| 83 | =head1 COPYRIGHT
|
|---|
| 84 |
|
|---|
| 85 | Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 86 |
|
|---|
| 87 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 88 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 89 | in the file LICENSE in the source distribution or at
|
|---|
| 90 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 91 |
|
|---|
| 92 | =cut
|
|---|
