lib/libcrypto/man/BIO_f_cipher.3

   1 .\"     $OpenBSD: BIO_f_cipher.3,v 1.6 2016/12/06 14:45:08 schwarze Exp $
   2 .\"     OpenSSL 186bb907 Apr 13 11:05:13 2015 -0700
   3 .\"
   4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
   5 .\" Copyright (c) 2000, 2003, 2015, 2016 The OpenSSL Project.
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\"
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\"
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in
  17 .\"    the documentation and/or other materials provided with the
  18 .\"    distribution.
  19 .\"
  20 .\" 3. All advertising materials mentioning features or use of this
  21 .\"    software must display the following acknowledgment:
  22 .\"    "This product includes software developed by the OpenSSL Project
  23 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  24 .\"
  25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  26 .\"    endorse or promote products derived from this software without
  27 .\"    prior written permission. For written permission, please contact
  28 .\"    openssl-core@openssl.org.
  29 .\"
  30 .\" 5. Products derived from this software may not be called "OpenSSL"
  31 .\"    nor may "OpenSSL" appear in their names without prior written
  32 .\"    permission of the OpenSSL Project.
  33 .\"
  34 .\" 6. Redistributions of any form whatsoever must retain the following
  35 .\"    acknowledgment:
  36 .\"    "This product includes software developed by the OpenSSL Project
  37 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  38 .\"
  39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  42 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  51 .\"
  52 .Dd $Mdocdate: December 6 2016 $
  53 .Dt BIO_F_CIPHER 3
  54 .Os
  55 .Sh NAME
  56 .Nm BIO_f_cipher ,
  57 .Nm BIO_set_cipher ,
  58 .Nm BIO_get_cipher_status ,
  59 .Nm BIO_get_cipher_ctx
  60 .Nd cipher BIO filter
  61 .Sh SYNOPSIS
  62 .In openssl/bio.h
  63 .In openssl/evp.h
  64 .Ft BIO_METHOD *
  65 .Fo BIO_f_cipher
  66 .Fa void
  67 .Fc
  68 .Ft void
  69 .Fo BIO_set_cipher
  70 .Fa "BIO *b"
  71 .Fa "const EVP_CIPHER *cipher"
  72 .Fa "unsigned char *key"
  73 .Fa "unsigned char *iv"
  74 .Fa "int enc"
  75 .Fc
  76 .Ft int
  77 .Fo BIO_get_cipher_status
  78 .Fa "BIO *b"
  79 .Fc
  80 .Ft int
  81 .Fo BIO_get_cipher_ctx
  82 .Fa "BIO *b"
  83 .Fa "EVP_CIPHER_CTX **pctx"
  84 .Fc
  85 .Sh DESCRIPTION
  86 .Fn BIO_f_cipher
  87 returns the cipher BIO method.
  88 This is a filter BIO that encrypts any data written through it,
  89 and decrypts any data read from it.
  90 It is a BIO wrapper for the cipher routines
  91 .Xr EVP_CipherInit 3 ,
  92 .Xr EVP_CipherUpdate 3 ,
  93 and
  94 .Xr EVP_CipherFinal 3 .
  95 .Pp
  96 Cipher BIOs do not support
  97 .Xr BIO_gets 3
  98 or
  99 .Xr BIO_puts 3 .
 100 .Pp
 101 .Xr BIO_flush 3
 102 on an encryption BIO that is being written through
 103 is used to signal that no more data is to be encrypted:
 104 this is used to flush and possibly pad the final block through the BIO.
 105 .Pp
 106 .Fn BIO_set_cipher
 107 sets the cipher of BIO
 108 .Fa b
 109 to
 110 .Fa cipher
 111 using key
 112 .Fa key
 113 and IV
 114 .Fa iv .
 115 .Fa enc
 116 should be set to 1 for encryption and zero for decryption.
 117 .Pp
 118 When reading from an encryption BIO, the final block is automatically
 119 decrypted and checked when EOF is detected.
 120 .Fn BIO_get_cipher_status
 121 is a
 122 .Xr BIO_ctrl 3
 123 macro which can be called to determine
 124 whether the decryption operation was successful.
 125 .Pp
 126 .Fn BIO_get_cipher_ctx
 127 is a
 128 .Xr BIO_ctrl 3
 129 macro which retrieves the internal BIO cipher context.
 130 The retrieved context can be used in conjunction
 131 with the standard cipher routines to set it up.
 132 This is useful when
 133 .Fn BIO_set_cipher
 134 is not flexible enough for the applications needs.
 135 .Pp
 136 When encrypting,
 137 .Xr BIO_flush 3
 138 must be called to flush the final block through the BIO.
 139 If it is not, then the final block will fail a subsequent decrypt.
 140 .Pp
 141 When decrypting, an error on the final block is signalled
 142 by a zero return value from the read operation.
 143 A successful decrypt followed by EOF
 144 will also return zero for the final read.
 145 .Fn BIO_get_cipher_status
 146 should be called to determine if the decrypt was successful.
 147 .Pp
 148 As always, if
 149 .Xr BIO_gets 3
 150 or
 151 .Xr BIO_puts 3
 152 support is needed, then it can be achieved
 153 by preceding the cipher BIO with a buffering BIO.
 154 .Sh RETURN VALUES
 155 .Fn BIO_f_cipher
 156 returns the cipher BIO method.
 157 .Pp
 158 .Fn BIO_get_cipher_status
 159 returns 1 for a successful decrypt and 0 for failure.
 160 .Pp
 161 .Fn BIO_get_cipher_ctx
 162 currently always returns 1.
 163 .Sh SEE ALSO
 164 .Xr BIO_new 3