doc/man3/PKCS8_encrypt.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 PKCS8_decrypt, PKCS8_decrypt_ex, PKCS8_encrypt, PKCS8_encrypt_ex,
   6 PKCS8_set0_pbe, PKCS8_set0_pbe_ex - PKCS8 encrypt/decrypt functions
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/x509.h>
  11
  12  PKCS8_PRIV_KEY_INFO *PKCS8_decrypt(const X509_SIG *p8, const char *pass,
  13                                     int passlen);
  14  PKCS8_PRIV_KEY_INFO *PKCS8_decrypt_ex(const X509_SIG *p8, const char *pass,
  15                                        int passlen, OSSL_LIB_CTX *ctx,
  16                                        const char *propq);
  17  X509_SIG *PKCS8_encrypt(int pbe_nid, const EVP_CIPHER *cipher,
  18                          const char *pass, int passlen, unsigned char *salt,
  19                          int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8);
  20  X509_SIG *PKCS8_encrypt_ex(int pbe_nid, const EVP_CIPHER *cipher,
  21                             const char *pass, int passlen, unsigned char *salt,
  22                             int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8,
  23                             OSSL_LIB_CTX *ctx, const char *propq);
  24  X509_SIG *PKCS8_set0_pbe(const char *pass, int passlen,
  25                          PKCS8_PRIV_KEY_INFO *p8inf, X509_ALGOR *pbe);
  26  X509_SIG *PKCS8_set0_pbe_ex(const char *pass, int passlen,
  27                              PKCS8_PRIV_KEY_INFO *p8inf, X509_ALGOR *pbe,
  28                              OSSL_LIB_CTX *ctx);
  29
  30 =head1 DESCRIPTION
  31
  32 PKCS8_encrypt() and PKCS8_encrypt_ex() perform encryption of an object I<p8> using
  33 the password I<pass> of length I<passlen>, salt I<salt> of length I<saltlen>
  34 and iteration count I<iter>.
  35 The resulting B<X509_SIG> contains the encoded algorithm parameters and encrypted
  36 key.
  37
  38 PKCS8_decrypt() and PKCS8_decrypt_ex() perform decryption of an B<X509_SIG> in
  39 I<p8> using the password I<pass> of length I<passlen> along with algorithm
  40 parameters obtained from the I<p8>.
  41
  42 PKCS8_set0_pbe() and PKCS8_set0_pbe_ex() perform encryption of the I<p8inf>
  43 using the password I<pass> of length I<passlen> and parameters I<pbe>.
  44
  45 Functions ending in _ex() allow for a library context I<ctx> and property query
  46 I<propq> to be used to select algorithm implementations.
  47
  48 =head1 RETURN VALUES
  49
  50 PKCS8_encrypt(), PKCS8_encrypt_ex(), PKCS8_set0_pbe() and PKCS8_set0_pbe_ex()
  51 return an encrypted key in a B<X509_SIG> structure or NULL if an error occurs.
  52
  53 PKCS8_decrypt() and PKCS8_decrypt_ex() return a B<PKCS8_PRIV_KEY_INFO> or NULL
  54 if an error occurs.
  55
  56 =head1 CONFORMING TO
  57
  58 IETF RFC 7292 (L<https://tools.ietf.org/html/rfc7292>)
  59
  60 =head1 SEE ALSO
  61
  62 L<crypto(7)>
  63
  64 =head1 HISTORY
  65
  66 PKCS8_decrypt_ex(), PKCS8_encrypt_ex() and PKCS8_set0_pbe_ex() were added in
  67 OpenSSL 3.0.
  68
  69 =head1 COPYRIGHT
  70
  71 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
  72
  73 Licensed under the Apache License 2.0 (the "License").  You may not use
  74 this file except in compliance with the License.  You can obtain a copy
  75 in the file LICENSE in the source distribution or at
  76 L<https://www.openssl.org/source/license.html>.
  77
  78 =cut