$NetBSD: PKCS5_PBE_keyivgen.3,v 1.5 2024/09/08 13:08:28 christos Exp $

-*- mode: troff; coding: utf-8 -*-
Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)

Standard preamble:
========================================================================
..

..

.. \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
. ds C` "" . ds C' "" 'br\} . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.

If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.

Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF ========================================================================

Title "PKCS5_PBE_keyivgen 3" For nroff, turn off justification. Always turn off hyphenation; it makes
way too many mistakes in technical documents.
PKCS5_PBE_keyivgen, PKCS5_PBE_keyivgen_ex, PKCS5_pbe2_set, PKCS5_pbe2_set_iv, PKCS5_pbe2_set_iv_ex, PKCS5_pbe_set, PKCS5_pbe_set_ex, PKCS5_pbe2_set_scrypt, PKCS5_pbe_set0_algor, PKCS5_pbe_set0_algor_ex, PKCS5_v2_PBE_keyivgen, PKCS5_v2_PBE_keyivgen_ex, PKCS5_v2_scrypt_keyivgen, PKCS5_v2_scrypt_keyivgen_ex, PKCS5_pbkdf2_set, PKCS5_pbkdf2_set_ex, EVP_PBE_scrypt, EVP_PBE_scrypt_ex \- PKCS#5 Password based encryption routines Header "SYNOPSIS" .Vb 1 #include <openssl/evp.h> \& int PKCS5_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen, ASN1_TYPE *param, const EVP_CIPHER *cipher, const EVP_MD *md, int en_de); int PKCS5_PBE_keyivgen_ex(EVP_CIPHER_CTX *cctx, const char *pass, int passlen, ASN1_TYPE *param, const EVP_CIPHER *cipher, const EVP_MD *md, int en_de, OSSL_LIB_CTX *libctx, const char *propq); int PKCS5_v2_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen, ASN1_TYPE *param, const EVP_CIPHER *cipher, const EVP_MD *md, int en_de); int PKCS5_v2_PBE_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass, int passlen, ASN1_TYPE *param, const EVP_CIPHER *cipher, const EVP_MD *md, int en_de, OSSL_LIB_CTX *libctx, const char *propq); int EVP_PBE_scrypt(const char *pass, size_t passlen, const unsigned char *salt, size_t saltlen, uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem, unsigned char *key, size_t keylen); int EVP_PBE_scrypt_ex(const char *pass, size_t passlen, const unsigned char *salt, size_t saltlen, uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem, unsigned char *key, size_t keylen, OSSL_LIB_CTX *ctx, const char *propq); int PKCS5_v2_scrypt_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen, ASN1_TYPE *param, const EVP_CIPHER *c, const EVP_MD *md, int en_de); int PKCS5_v2_scrypt_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass, int passlen, ASN1_TYPE *param, const EVP_CIPHER *c, const EVP_MD *md, int en_de, OSSL_LIB_CTX *libctx, const char *propq); \& #include <openssl/x509.h> \& int PKCS5_pbe_set0_algor(X509_ALGOR *algor, int alg, int iter, const unsigned char *salt, int saltlen); int PKCS5_pbe_set0_algor_ex(X509_ALGOR *algor, int alg, int iter, const unsigned char *salt, int saltlen, OSSL_LIB_CTX *libctx); \& X509_ALGOR *PKCS5_pbe_set(int alg, int iter, const unsigned char *salt, int saltlen); X509_ALGOR *PKCS5_pbe_set_ex(int alg, int iter, const unsigned char *salt, int saltlen, OSSL_LIB_CTX *libctx); \& X509_ALGOR *PKCS5_pbe2_set(const EVP_CIPHER *cipher, int iter, unsigned char *salt, int saltlen); X509_ALGOR *PKCS5_pbe2_set_iv(const EVP_CIPHER *cipher, int iter, unsigned char *salt, int saltlen, unsigned char *aiv, int prf_nid); X509_ALGOR *PKCS5_pbe2_set_iv_ex(const EVP_CIPHER *cipher, int iter, unsigned char *salt, int saltlen, unsigned char *aiv, int prf_nid, OSSL_LIB_CTX *libctx); X509_ALGOR *PKCS5_pbe2_set_scrypt(const EVP_CIPHER *cipher, const unsigned char *salt, int saltlen, unsigned char *aiv, uint64_t N, uint64_t r, uint64_t p); \& X509_ALGOR *PKCS5_pbkdf2_set(int iter, unsigned char *salt, int saltlen, int prf_nid, int keylen); X509_ALGOR *PKCS5_pbkdf2_set_ex(int iter, unsigned char *salt, int saltlen, int prf_nid, int keylen, OSSL_LIB_CTX *libctx); .Ve Header "DESCRIPTION" Subsection "Key Derivation" \fBPKCS5_PBE_keyivgen() and PKCS5_PBE_keyivgen_ex() take a password pass of length passlen, parameters param and a message digest function md_type and performs a key derivation according to PKCS#5 PBES1. The resulting key is then used to initialise the cipher context ctx with a cipher cipher for encryption (en_de=1) or decryption (en_de=0).

\fIpass is an optional parameter and can be NULL. If passlen is -1, then the function will calculate the length of pass using strlen().

\fBPKCS5_v2_PBE_keyivgen() and PKCS5_v2_PBE_keyivgen_ex() are similar to the above but instead use PKCS#5 PBES2 as the encryption algorithm using the supplied parameters.

\fBPKCS5_v2_scrypt_keyivgen() and PKCS5_v2_scrypt_keyivgen_ex() use SCRYPT as the key derivation part of the encryption algorithm.

\fIsalt is the salt used in the derivation of length saltlen. If the \fIsalt is NULL, then saltlen must be 0. The function will not attempt to calculate the length of the salt because it is not assumed to be NULL terminated.

\fIiter is the iteration count and its value should be greater than or equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any \fIiter less than 1 is treated as a single iteration.

\fIdigest is the message digest function used in the derivation.

Functions ending in _ex() take optional parameters libctx and propq which are used to select appropriate algorithm implementations.

Subsection "Algorithm Identifier Creation" \fBPKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(), \fBPKCS5_pbe2_set_iv_ex() and PKCS5_pbe2_set_scrypt() generate an X509_ALGOR object which represents an AlgorithmIdentifier containing the algorithm OID and associated parameters for the PBE algorithm.

\fBPKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() generate an X509_ALGOR object which represents an AlgorithmIdentifier containing the algorithm OID and associated parameters for the PBKDF2 algorithm.

\fBPKCS5_pbe_set0_algor() and PKCS5_pbe_set0_algor_ex() set the PBE algorithm OID and parameters into the supplied X509_ALGOR.

Header "NOTES" The *_keyivgen() functions are typically used in PKCS#12 to encrypt objects.

These functions make no assumption regarding the given password. It will simply be treated as a byte sequence.

Header "RETURN VALUES" \fBPKCS5_PBE_keyivgen(), PKCS5_v2_PBE_keyivgen(), \fBPKCS5_v2_PBE_keyivgen_ex(), PKCS5_v2_scrypt_keyivgen(), \fBPKCS5_v2_scrypt_keyivgen_ex(), PKCS5_pbe_set0_algor() and \fBPKCS5_pbe_set0_algor_ex() return 1 for success and 0 if an error occurs.

\fBPKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(), \fBPKCS5_pbe2_set_iv_ex(), PKCS5_pbe2_set_scrypt(), \fBPKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() return an X509_ALGOR object or NULL if an error occurs.

Header "CONFORMING TO" IETF RFC 8018 (<https://tools.ietf.org/html/rfc8018>) Header "SEE ALSO" \fBEVP_PBE_CipherInit_ex\|(3), \fBPKCS12_pbe_crypt_ex\|(3), \fBpassphrase-encoding\|(7) Header "HISTORY" \fBPKCS5_v2_PBE_keyivgen_ex(), EVP_PBE_scrypt_ex(), PKCS5_v2_scrypt_keyivgen_ex(), \fBPKCS5_pbe_set0_algor_ex(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set_iv_ex() and \fBPKCS5_pbkdf2_set_ex() were added in OpenSSL 3.0.

From OpenSSL 3.0 the PBKDF1 algorithm used in PKCS5_PBE_keyivgen() and \fBPKCS5_PBE_keyivgen_ex() has been moved to the legacy provider as an EVP_KDF.

Header "COPYRIGHT" Copyright 2021 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 <https://www.openssl.org/source/license.html>.