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