PKCS5_PBE_keyivgen.pod 8.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187
  1. =pod
  2. =head1 NAME
  3. PKCS5_PBE_keyivgen, PKCS5_PBE_keyivgen_ex, PKCS5_pbe2_set, PKCS5_pbe2_set_iv,
  4. PKCS5_pbe2_set_iv_ex, PKCS5_pbe_set, PKCS5_pbe_set_ex, PKCS5_pbe2_set_scrypt,
  5. PKCS5_pbe_set0_algor, PKCS5_pbe_set0_algor_ex,
  6. PKCS5_v2_PBE_keyivgen, PKCS5_v2_PBE_keyivgen_ex,
  7. PKCS5_v2_scrypt_keyivgen, PKCS5_v2_scrypt_keyivgen_ex,
  8. PKCS5_pbkdf2_set, PKCS5_pbkdf2_set_ex, EVP_PBE_scrypt, EVP_PBE_scrypt_ex
  9. - PKCS#5 Password based encryption routines
  10. =head1 SYNOPSIS
  11. #include <openssl/evp.h>
  12. int PKCS5_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
  13. ASN1_TYPE *param, const EVP_CIPHER *cipher,
  14. const EVP_MD *md, int en_de);
  15. int PKCS5_PBE_keyivgen_ex(EVP_CIPHER_CTX *cctx, const char *pass, int passlen,
  16. ASN1_TYPE *param, const EVP_CIPHER *cipher,
  17. const EVP_MD *md, int en_de, OSSL_LIB_CTX *libctx,
  18. const char *propq);
  19. int PKCS5_v2_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
  20. ASN1_TYPE *param, const EVP_CIPHER *cipher,
  21. const EVP_MD *md, int en_de);
  22. int PKCS5_v2_PBE_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass, int passlen,
  23. ASN1_TYPE *param, const EVP_CIPHER *cipher,
  24. const EVP_MD *md, int en_de,
  25. OSSL_LIB_CTX *libctx, const char *propq);
  26. int EVP_PBE_scrypt(const char *pass, size_t passlen,
  27. const unsigned char *salt, size_t saltlen,
  28. uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
  29. unsigned char *key, size_t keylen);
  30. int EVP_PBE_scrypt_ex(const char *pass, size_t passlen,
  31. const unsigned char *salt, size_t saltlen,
  32. uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem,
  33. unsigned char *key, size_t keylen,
  34. OSSL_LIB_CTX *ctx, const char *propq);
  35. int PKCS5_v2_scrypt_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass,
  36. int passlen, ASN1_TYPE *param,
  37. const EVP_CIPHER *c, const EVP_MD *md, int en_de);
  38. int PKCS5_v2_scrypt_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass,
  39. int passlen, ASN1_TYPE *param,
  40. const EVP_CIPHER *c, const EVP_MD *md, int en_de,
  41. OSSL_LIB_CTX *libctx, const char *propq);
  42. #include <openssl/x509.h>
  43. int PKCS5_pbe_set0_algor(X509_ALGOR *algor, int alg, int iter,
  44. const unsigned char *salt, int saltlen);
  45. int PKCS5_pbe_set0_algor_ex(X509_ALGOR *algor, int alg, int iter,
  46. const unsigned char *salt, int saltlen,
  47. OSSL_LIB_CTX *libctx);
  48. X509_ALGOR *PKCS5_pbe_set(int alg, int iter,
  49. const unsigned char *salt, int saltlen);
  50. X509_ALGOR *PKCS5_pbe_set_ex(int alg, int iter,
  51. const unsigned char *salt, int saltlen,
  52. OSSL_LIB_CTX *libctx);
  53. X509_ALGOR *PKCS5_pbe2_set(const EVP_CIPHER *cipher, int iter,
  54. unsigned char *salt, int saltlen);
  55. X509_ALGOR *PKCS5_pbe2_set_iv(const EVP_CIPHER *cipher, int iter,
  56. unsigned char *salt, int saltlen,
  57. unsigned char *aiv, int prf_nid);
  58. X509_ALGOR *PKCS5_pbe2_set_iv_ex(const EVP_CIPHER *cipher, int iter,
  59. unsigned char *salt, int saltlen,
  60. unsigned char *aiv, int prf_nid,
  61. OSSL_LIB_CTX *libctx);
  62. X509_ALGOR *PKCS5_pbe2_set_scrypt(const EVP_CIPHER *cipher,
  63. const unsigned char *salt, int saltlen,
  64. unsigned char *aiv, uint64_t N, uint64_t r,
  65. uint64_t p);
  66. X509_ALGOR *PKCS5_pbkdf2_set(int iter, unsigned char *salt, int saltlen,
  67. int prf_nid, int keylen);
  68. X509_ALGOR *PKCS5_pbkdf2_set_ex(int iter, unsigned char *salt, int saltlen,
  69. int prf_nid, int keylen,
  70. OSSL_LIB_CTX *libctx);
  71. =head1 DESCRIPTION
  72. =head2 Key Derivation
  73. PKCS5_PBE_keyivgen() and PKCS5_PBE_keyivgen_ex() take a password I<pass> of
  74. length I<passlen>, parameters I<param> and a message digest function I<md_type>
  75. and performs a key derivation according to PKCS#5 PBES1. The resulting key is
  76. then used to initialise the cipher context I<ctx> with a cipher I<cipher> for
  77. encryption (I<en_de>=1) or decryption (I<en_de>=0).
  78. I<pass> is an optional parameter and can be NULL. If I<passlen> is -1, then the
  79. function will calculate the length of I<pass> using strlen().
  80. PKCS5_v2_PBE_keyivgen() and PKCS5_v2_PBE_keyivgen_ex() are similar to the above
  81. but instead use PKCS#5 PBES2 as the encryption algorithm using the supplied
  82. parameters.
  83. PKCS5_v2_scrypt_keyivgen() and PKCS5_v2_scrypt_keyivgen_ex() use SCRYPT as the
  84. key derivation part of the encryption algorithm.
  85. I<salt> is the salt used in the derivation of length I<saltlen>. If the
  86. I<salt> is NULL, then I<saltlen> must be 0. The function will not
  87. attempt to calculate the length of the I<salt> because it is not assumed to
  88. be NULL terminated.
  89. I<iter> is the iteration count and its value should be greater than or
  90. equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any
  91. I<iter> less than 1 is treated as a single iteration.
  92. I<digest> is the message digest function used in the derivation.
  93. Functions ending in _ex() take optional parameters I<libctx> and I<propq> which
  94. are used to select appropriate algorithm implementations.
  95. =head2 Algorithm Identifier Creation
  96. PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(),
  97. PKCS5_pbe2_set_iv_ex() and PKCS5_pbe2_set_scrypt() generate an B<X509_ALGOR>
  98. object which represents an AlgorithmIdentifier containing the algorithm OID and
  99. associated parameters for the PBE algorithm.
  100. PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() generate an B<X509_ALGOR>
  101. object which represents an AlgorithmIdentifier containing the algorithm OID and
  102. associated parameters for the PBKDF2 algorithm.
  103. PKCS5_pbe_set0_algor() and PKCS5_pbe_set0_algor_ex() set the PBE algorithm OID and
  104. parameters into the supplied B<X509_ALGOR>.
  105. If I<salt> is NULL, then I<saltlen> specifies the size in bytes of the random salt to
  106. generate. If I<saltlen> is 0 then a default size is used.
  107. For PBE related functions such as PKCS5_pbe_set_ex() the default salt length is 8 bytes.
  108. For PBE2 related functions that use PBKDF2 such as PKCS5_pbkdf2_set(),
  109. PKCS5_pbe2_set_scrypt() and PKCS5_pbe2_set() the default salt length is 16 bytes.
  110. =head1 NOTES
  111. The *_keyivgen() functions are typically used in PKCS#12 to encrypt objects.
  112. These functions make no assumption regarding the given password.
  113. It will simply be treated as a byte sequence.
  114. =head1 RETURN VALUES
  115. PKCS5_PBE_keyivgen(), PKCS5_v2_PBE_keyivgen(),
  116. PKCS5_v2_PBE_keyivgen_ex(), PKCS5_v2_scrypt_keyivgen(),
  117. PKCS5_v2_scrypt_keyivgen_ex(), PKCS5_pbe_set0_algor() and
  118. PKCS5_pbe_set0_algor_ex() return 1 for success and 0 if an error occurs.
  119. PKCS5_pbe_set(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set(), PKCS5_pbe2_set_iv(),
  120. PKCS5_pbe2_set_iv_ex(), PKCS5_pbe2_set_scrypt(),
  121. PKCS5_pbkdf2_set() and PKCS5_pbkdf2_set_ex() return an B<X509_ALGOR> object or
  122. NULL if an error occurs.
  123. =head1 CONFORMING TO
  124. IETF RFC 8018 (L<https://tools.ietf.org/html/rfc8018>)
  125. =head1 SEE ALSO
  126. L<EVP_PBE_CipherInit_ex(3)>,
  127. L<PKCS12_pbe_crypt_ex(3)>,
  128. L<passphrase-encoding(7)>
  129. =head1 HISTORY
  130. PKCS5_v2_PBE_keyivgen_ex(), EVP_PBE_scrypt_ex(), PKCS5_v2_scrypt_keyivgen_ex(),
  131. PKCS5_pbe_set0_algor_ex(), PKCS5_pbe_set_ex(), PKCS5_pbe2_set_iv_ex() and
  132. PKCS5_pbkdf2_set_ex() were added in OpenSSL 3.0.
  133. From OpenSSL 3.0 the PBKDF1 algorithm used in PKCS5_PBE_keyivgen() and
  134. PKCS5_PBE_keyivgen_ex() has been moved to the legacy provider as an EVP_KDF.
  135. In OpenSSL 3.2 the default salt length changed from 8 bytes to 16 bytes for PBE2
  136. related functions such as PKCS5_pbe2_set().
  137. This is required for PBKDF2 FIPS compliance.
  138. =head1 COPYRIGHT
  139. Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.
  140. Licensed under the Apache License 2.0 (the "License"). You may not use
  141. this file except in compliance with the License. You can obtain a copy
  142. in the file LICENSE in the source distribution or at
  143. L<https://www.openssl.org/source/license.html>.
  144. =cut