lib/libcrypto/man/evp.3

   1 .\"     $OpenBSD: evp.3,v 1.4 2016/12/06 15:15:26 schwarze Exp $
   2 .\"     OpenSSL a9c85cea Nov 11 09:33:55 2016 +0100
   3 .\"
   4 .\" This file was written by Ulf Moeller <ulf@openssl.org>,
   5 .\" Matt Caswell <matt@openssl.org>, Geoff Thorpe <geoff@openssl.org>,
   6 .\" and Dr. Stephen Henson <steve@openssl.org>.
   7 .\" Copyright (c) 2000, 2002, 2006, 2013, 2016 The OpenSSL Project.
   8 .\" All rights reserved.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\"
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\"
  17 .\" 2. Redistributions in binary form must reproduce the above copyright
  18 .\"    notice, this list of conditions and the following disclaimer in
  19 .\"    the documentation and/or other materials provided with the
  20 .\"    distribution.
  21 .\"
  22 .\" 3. All advertising materials mentioning features or use of this
  23 .\"    software must display the following acknowledgment:
  24 .\"    "This product includes software developed by the OpenSSL Project
  25 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  26 .\"
  27 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  28 .\"    endorse or promote products derived from this software without
  29 .\"    prior written permission. For written permission, please contact
  30 .\"    openssl-core@openssl.org.
  31 .\"
  32 .\" 5. Products derived from this software may not be called "OpenSSL"
  33 .\"    nor may "OpenSSL" appear in their names without prior written
  34 .\"    permission of the OpenSSL Project.
  35 .\"
  36 .\" 6. Redistributions of any form whatsoever must retain the following
  37 .\"    acknowledgment:
  38 .\"    "This product includes software developed by the OpenSSL Project
  39 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  40 .\"
  41 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  42 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  43 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  44 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  45 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  46 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  47 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  48 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  49 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  50 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  51 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  52 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  53 .\"
  54 .Dd $Mdocdate: December 6 2016 $
  55 .Dt EVP 3
  56 .Os
  57 .Sh NAME
  58 .Nm evp
  59 .Nd high level cryptographic functions
  60 .Sh SYNOPSIS
  61 .In openssl/evp.h
  62 .Sh DESCRIPTION
  63 The EVP library provides a high level interface to cryptographic
  64 functions.
  65 .Pp
  66 .Xr EVP_SealInit 3
  67 and
  68 .Xr EVP_OpenInit 3
  69 provide public key encryption and decryption to implement digital
  70 "envelopes".
  71 .Pp
  72 The
  73 .Xr EVP_DigestSignInit 3
  74 and
  75 .Xr EVP_DigestVerifyInit 3
  76 functions implement digital signatures and Message Authentication Codes
  77 (MACs).
  78 Also see the older
  79 .Xr EVP_SignInit 3
  80 and
  81 .Xr EVP_VerifyInit 3
  82 functions.
  83 .Pp
  84 Symmetric encryption is available with the
  85 .Xr EVP_EncryptInit 3
  86 functions.
  87 The
  88 .Xr EVP_DigestInit 3
  89 functions provide message digests.
  90 .Pp
  91 Authenticated encryption with additional data (AEAD) is available with
  92 the
  93 .Xr EVP_AEAD_CTX_init 3
  94 functions.
  95 .Pp
  96 The
  97 .Fn EVP_PKEY_*
  98 functions provide a high level interface to asymmetric algorithms.
  99 To create a new
 100 .Vt EVP_PKEY ,
 101 see
 102 .Xr EVP_PKEY_new 3 .
 103 .Vt EVP_PKEY Ns s
 104 can be associated with a private key of a particular algorithm
 105 by using the functions described in the
 106 .Xr EVP_PKEY_set1_RSA 3
 107 page, or new keys can be generated using
 108 .Xr EVP_PKEY_keygen 3 .
 109 .Vt EVP_PKEY Ns s
 110 can be compared using
 111 .Xr EVP_PKEY_cmp 3
 112 or printed using
 113 .Xr EVP_PKEY_print_private 3 .
 114 .Pp
 115 The
 116 .Fn EVP_PKEY_*
 117 functions support the full range of asymmetric algorithm operations:
 118 .Bl -bullet
 119 .It
 120 For key agreement, see
 121 .Xr EVP_PKEY_derive 3 .
 122 .It
 123 For signing and verifying, see
 124 .Xr EVP_PKEY_sign 3 ,
 125 .Xr EVP_PKEY_verify 3 ,
 126 and
 127 .Xr EVP_PKEY_verify_recover 3 .
 128 However, note that these functions do not perform a digest of the
 129 data to be signed.
 130 Therefore normally you would use the
 131 .Xr EVP_DigestSignInit 3
 132 functions for this purpose.
 133 .It
 134 For encryption and decryption see
 135 .Xr EVP_PKEY_encrypt 3
 136 and
 137 .Xr EVP_PKEY_decrypt 3 ,
 138 respectively.
 139 However, note that these functions perform encryption and decryption only.
 140 As public key encryption is an expensive operation, normally you
 141 would wrap an encrypted message in a digital envelope using the
 142 .Xr EVP_SealInit 3
 143 and
 144 .Xr EVP_OpenInit 3
 145 functions.
 146 .El
 147 .Pp
 148 The
 149 .Xr EVP_BytesToKey 3
 150 function provides some limited support for password based encryption.
 151 Careful selection of the parameters will provide a PKCS#5 PBKDF1
 152 compatible implementation.
 153 However, new applications should typically not use this (preferring, for
 154 example, PBKDF2 from PCKS#5).
 155 .Pp
 156 Algorithms are loaded with
 157 .Xr OpenSSL_add_all_algorithms 3 .
 158 .Pp
 159 All the symmetric algorithms (ciphers), digests and asymmetric
 160 algorithms (public key algorithms) can be replaced by
 161 .Xr engine 3
 162 modules providing alternative implementations.
 163 If
 164 .Vt ENGINE
 165 implementations of ciphers or digests are registered as defaults,
 166 then the various EVP functions will automatically use those
 167 implementations in preference to built in software implementations.
 168 For more information, consult the
 169 .Xr engine 3
 170 manual page.
 171 .Pp
 172 Although low level algorithm specific functions exist for many
 173 algorithms, their use is discouraged.
 174 They cannot be used with an
 175 .Vt ENGINE ,
 176 and
 177 .Vt ENGINE
 178 versions of new algorithms cannot be accessed using the low level
 179 functions.
 180 Using them also makes code harder to adapt to new algorithms, some
 181 options are not cleanly supported at the low level, and some
 182 operations are more efficient using the high level interfaces.
 183 .Sh SEE ALSO
 184 .Xr engine 3 ,
 185 .Xr EVP_AEAD_CTX_init 3 ,
 186 .Xr EVP_BytesToKey 3 ,
 187 .Xr EVP_DigestInit 3 ,
 188 .Xr EVP_DigestSignInit 3 ,
 189 .Xr EVP_EncryptInit 3 ,
 190 .Xr EVP_OpenInit 3 ,
 191 .Xr EVP_PKEY_decrypt 3 ,
 192 .Xr EVP_PKEY_derive 3 ,
 193 .Xr EVP_PKEY_encrypt 3 ,
 194 .Xr EVP_PKEY_keygen 3 ,
 195 .Xr EVP_PKEY_new 3 ,
 196 .Xr EVP_PKEY_print_private 3 ,
 197 .Xr EVP_PKEY_set1_RSA 3 ,
 198 .Xr EVP_PKEY_sign 3 ,
 199 .Xr EVP_PKEY_verify 3 ,
 200 .Xr EVP_PKEY_verify_recover 3 ,
 201 .Xr EVP_SealInit 3 ,
 202 .Xr EVP_SignInit 3 ,
 203 .Xr EVP_VerifyInit 3 ,
 204 .Xr OpenSSL_add_all_algorithms 3