mirror of https://github.com/openssl/openssl.git
Implementation of the RFC 9579, PBMAC1 in PKCS#12 - documentation
Reviewed-by: Paul Dale <ppzgs1@gmail.com> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/24577)
This commit is contained in:
Dmitry Belyavskiy
parent
fe79159be0
commit
38aa61e5a7
|
|
@ -62,6 +62,8 @@ PKCS#12 output (export) options:
|
|||
[B<-certpbe> I<cipher>]
|
||||
[B<-descert>]
|
||||
[B<-macalg> I<digest>]
|
||||
[B<-pbmac1_pbkdf2>]
|
||||
[B<-pbmac1_pbkdf2_md> I<digest>]
|
||||
[B<-iter> I<count>]
|
||||
[B<-noiter>]
|
||||
[B<-nomaciter>]
|
||||
|
|
@ -345,6 +347,15 @@ then both, the private key and the certificates are encrypted using triple DES.
|
|||
|
||||
Specify the MAC digest algorithm. If not included SHA256 will be used.
|
||||
|
||||
=item B<-pbmac1_pbkdf2>
|
||||
|
||||
Use PBMAC1 with PBKDF2 for MAC protection of the PKCS#12 file.
|
||||
|
||||
=item B<-pbmac1_pbkdf2_md> I<digest>
|
||||
|
||||
Specify the PBKDF2 KDF digest algorithm. If not specified, SHA256 will be used.
|
||||
Unless C<-pbmac1_pbkdf2> is specified, this parameter is ignored.
|
||||
|
||||
=item B<-iter> I<count>
|
||||
|
||||
This option specifies the iteration count for the encryption key and MAC. The
|
||||
|
|
|
|||
|
|
@ -0,0 +1,46 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
PBMAC1_get1_pbkdf2_param - Function to manipulate a PBMAC1
|
||||
MAC structure
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/x509.h>
|
||||
|
||||
PBKDF2PARAM *PBMAC1_get1_pbkdf2_param(const X509_ALGOR *macalg);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
PBMAC1_get1_pbkdf2_param() retrieves a B<PBKDF2PARAM> structure from an
|
||||
I<X509_ALGOR> structure.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
PBMAC1_get1_pbkdf2_param() returns NULL in case when PBMAC1 uses an algorithm
|
||||
apart from B<PBKDF2> or when passed incorrect parameters and a pointer to
|
||||
B<PBKDF2PARAM> structure otherwise.
|
||||
|
||||
=head1 CONFORMING TO
|
||||
|
||||
IETF RFC 9579 (L<https://tools.ietf.org/html/rfc9579>)
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<openssl-pkcs12(1)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The I<PBMAC1_get1_pbkdf2_param> function was added in OpenSSL 3.4.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2021-2024 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the Apache License 2.0 (the "License"). You may not use
|
||||
this file except in compliance with the License. You can obtain a copy
|
||||
in the file LICENSE in the source distribution or at
|
||||
L<https://www.openssl.org/source/license.html>.
|
||||
|
||||
=cut
|
||||
|
|
@ -3,7 +3,8 @@
|
|||
=head1 NAME
|
||||
|
||||
PKCS12_gen_mac, PKCS12_setup_mac, PKCS12_set_mac,
|
||||
PKCS12_verify_mac - Functions to create and manipulate a PKCS#12 structure
|
||||
PKCS12_set_pbmac1_pbkdf2, PKCS12_verify_mac, PKCS12_get0_mac -
|
||||
Functions to create and manipulate a PKCS#12 MAC structure
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
|
|
@ -15,9 +16,19 @@ PKCS12_verify_mac - Functions to create and manipulate a PKCS#12 structure
|
|||
int PKCS12_set_mac(PKCS12 *p12, const char *pass, int passlen,
|
||||
unsigned char *salt, int saltlen, int iter,
|
||||
const EVP_MD *md_type);
|
||||
int PKCS12_set_pbmac1_pbkdf2(PKCS12 *p12, const char *pass, int passlen,
|
||||
unsigned char *salt, int saltlen, int iter,
|
||||
const EVP_MD *md_type,
|
||||
const char *prf_md_name);
|
||||
int PKCS12_setup_mac(PKCS12 *p12, int iter, unsigned char *salt,
|
||||
int saltlen, const EVP_MD *md_type);
|
||||
|
||||
void PKCS12_get0_mac(const ASN1_OCTET_STRING **pmac,
|
||||
const X509_ALGOR **pmacalg,
|
||||
const ASN1_OCTET_STRING **psalt,
|
||||
const ASN1_INTEGER **piter,
|
||||
const PKCS12 *p12);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
PKCS12_gen_mac() generates an HMAC over the entire PKCS#12 object using the
|
||||
|
|
@ -31,10 +42,15 @@ PKCS12_setup_mac() sets the MAC part of the PKCS#12 structure with the supplied
|
|||
parameters.
|
||||
|
||||
PKCS12_set_mac() sets the MAC and MAC parameters into the PKCS#12 object.
|
||||
PKCS12_set_pbmac1_pbkdf2() sets the MAC and MAC parameters into the PKCS#12
|
||||
object when B<PBMAC1> with PBKDF2 is used for protection of the PKCS#12 object.
|
||||
|
||||
I<pass> is the passphrase to use in the HMAC. I<salt> is the salt value to use,
|
||||
I<iter> is the iteration count and I<md_type> is the message digest
|
||||
function to use.
|
||||
I<iter> is the iteration count and I<md_type> is the message digest function to
|
||||
use. I<prf_md_name> specifies the digest used for the PBKDF2 in PBMAC1 KDF.
|
||||
|
||||
PKCS12_get0_mac() retrieves any included MAC value, B<X509_ALGOR> object,
|
||||
I<salt>, and I<iter> count from the PKCS12 object.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
|
|
@ -43,17 +59,18 @@ If I<salt> is NULL then a suitable salt will be generated and used.
|
|||
If I<iter> is 1 then an iteration count will be omitted from the PKCS#12
|
||||
structure.
|
||||
|
||||
PKCS12_gen_mac(), PKCS12_verify_mac() and PKCS12_set_mac() make assumptions
|
||||
regarding the encoding of the given passphrase. See L<passphrase-encoding(7)>
|
||||
for more information.
|
||||
PKCS12_gen_mac(), PKCS12_verify_mac(), PKCS12_set_mac() and
|
||||
PKCS12_set_pbmac1_pbkdf2() make assumptions regarding the encoding of the
|
||||
given passphrase. See L<passphrase-encoding(7)> for more information.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
All functions return 1 on success and 0 if an error occurred.
|
||||
All functions returning an integer return 1 on success and 0 if an error occurred.
|
||||
|
||||
=head1 CONFORMING TO
|
||||
|
||||
IETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>)
|
||||
IETF RFC 9579 (L<https://tools.ietf.org/html/rfc9579>)
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
|
|
@ -62,9 +79,13 @@ L<EVP_KDF-PKCS12KDF(7)>,
|
|||
L<PKCS12_create(3)>,
|
||||
L<passphrase-encoding(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The I<PKCS12_set_pbmac1_pbkdf2> function was added in OpenSSL 3.4.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.
|
||||
Copyright 2021-2024 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the Apache License 2.0 (the "License"). You may not use
|
||||
this file except in compliance with the License. You can obtain a copy
|
||||
|
|
|
|||
|
|
@ -218,6 +218,9 @@ PBEPARAM_free,
|
|||
PBEPARAM_new,
|
||||
PBKDF2PARAM_free,
|
||||
PBKDF2PARAM_new,
|
||||
PBMAC1PARAM_free,
|
||||
PBMAC1PARAM_it,
|
||||
PBMAC1PARAM_new,
|
||||
PKCS12_BAGS_free,
|
||||
PKCS12_BAGS_new,
|
||||
PKCS12_MAC_DATA_free,
|
||||
|
|
|
|||
|
|
@ -115,6 +115,7 @@ d2i_OTHERNAME,
|
|||
d2i_PBE2PARAM,
|
||||
d2i_PBEPARAM,
|
||||
d2i_PBKDF2PARAM,
|
||||
d2i_PBMAC1PARAM,
|
||||
d2i_PKCS12,
|
||||
d2i_PKCS12_BAGS,
|
||||
d2i_PKCS12_MAC_DATA,
|
||||
|
|
@ -300,6 +301,7 @@ i2d_OTHERNAME,
|
|||
i2d_PBE2PARAM,
|
||||
i2d_PBEPARAM,
|
||||
i2d_PBKDF2PARAM,
|
||||
i2d_PBMAC1PARAM,
|
||||
i2d_PKCS12,
|
||||
i2d_PKCS12_BAGS,
|
||||
i2d_PKCS12_MAC_DATA,
|
||||
|
|
|
|||
|
|
@ -749,7 +749,6 @@ PKCS12_MAC_DATA_it(3)
|
|||
PKCS12_PBE_add(3)
|
||||
PKCS12_SAFEBAGS_it(3)
|
||||
PKCS12_SAFEBAG_it(3)
|
||||
PKCS12_get0_mac(3)
|
||||
PKCS12_get_attr(3)
|
||||
PKCS12_it(3)
|
||||
PKCS12_item_pack_safebag(3)
|
||||
|
|
|
|||
|
|
@ -1027,7 +1027,6 @@ PKCS12_add_safe(3)
|
|||
PKCS12_add_safes(3)
|
||||
PKCS12_decrypt_skey(3)
|
||||
PKCS12_gen_mac(3)
|
||||
PKCS12_get0_mac(3)
|
||||
PKCS12_get_attr(3)
|
||||
PKCS12_get_attr_gen(3)
|
||||
PKCS12_get_friendlyname(3)
|
||||
|
|
|
|||
Loading…
Reference in New Issue