lib/libcrypto/man/PKCS7_sign_add_signer.3

   1 .\"     $OpenBSD: PKCS7_sign_add_signer.3,v 1.7 2017/01/06 18:21:55 schwarze Exp $
   2 .\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
   3 .\"
   4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
   5 .\" Copyright (c) 2007, 2008, 2009, 2015 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: January 6 2017 $
  53 .Dt PKCS7_SIGN_ADD_SIGNER 3
  54 .Os
  55 .Sh NAME
  56 .Nm PKCS7_sign_add_signer
  57 .Nd add a signer PKCS7 signed data structure
  58 .Sh SYNOPSIS
  59 .In openssl/pkcs7.h
  60 .Ft PKCS7_SIGNER_INFO *
  61 .Fo PKCS7_sign_add_signer
  62 .Fa "PKCS7 *p7"
  63 .Fa "X509 *signcert"
  64 .Fa "EVP_PKEY *pkey"
  65 .Fa "const EVP_MD *md"
  66 .Fa "int flags"
  67 .Fc
  68 .Sh DESCRIPTION
  69 .Fn PKCS7_sign_add_signer
  70 adds a signer with certificate
  71 .Fa signcert
  72 and private key
  73 .Fa pkey
  74 using message digest
  75 .Fa md
  76 to a
  77 .Vt PKCS7
  78 signed data structure
  79 .Fa p7 .
  80 .Pp
  81 The
  82 .Vt PKCS7
  83 structure should be obtained from an initial call to
  84 .Xr PKCS7_sign 3
  85 with the flag
  86 .Dv PKCS7_PARTIAL
  87 set or, in the case or re-signing, a valid
  88 .Vt PKCS7
  89 signed data structure.
  90 .Pp
  91 If the
  92 .Fa md
  93 parameter is
  94 .Dv NULL ,
  95 then the default digest for the public key algorithm will be used.
  96 .Pp
  97 Unless the
  98 .Dv PKCS7_REUSE_DIGEST
  99 flag is set, the returned
 100 .Dv PKCS7
 101 structure is not complete and must be
 102 finalized either by streaming (if applicable) or by a call to
 103 .Fn PKCS7_final .
 104 .Pp
 105 The main purpose of this function is to provide finer control over a
 106 PKCS#7 signed data structure where the simpler
 107 .Xr PKCS7_sign 3
 108 function defaults are not appropriate, for example if multiple
 109 signers or non default digest algorithms are needed.
 110 .Pp
 111 Any of the following flags (OR'ed together) can be passed in the
 112 .Fa flags
 113 parameter.
 114 .Pp
 115 If
 116 .Dv PKCS7_REUSE_DIGEST
 117 is set, then an attempt is made to copy the content digest value from the
 118 .Vt PKCS7
 119 structure: to add a signer to an existing structure.
 120 An error occurs if a matching digest value cannot be found to copy.
 121 The returned
 122 .Vt PKCS7
 123 structure will be valid and finalized when this flag is set.
 124 .Pp
 125 If
 126 .Dv PKCS7_PARTIAL
 127 is set in addition to
 128 .Dv PKCS7_REUSE_DIGEST ,
 129 then the
 130 .Dv PKCS7_SIGNER_INO
 131 structure will not be finalized, so additional attributes can be added.
 132 In this case an explicit call to
 133 .Fn PKCS7_SIGNER_INFO_sign
 134 is needed to finalize it.
 135 .Pp
 136 If
 137 .Dv PKCS7_NOCERTS
 138 is set, the signer's certificate will not be included in the
 139 .Vt PKCS7
 140 structure, though the signer's certificate must still be supplied in the
 141 .Fa signcert
 142 parameter.
 143 This can reduce the size of the signature if the signers certificate can
 144 be obtained by other means: for example a previously signed message.
 145 .Pp
 146 The signedData structure includes several PKCS#7 authenticatedAttributes
 147 including the signing time, the PKCS#7 content type and the supported
 148 list of ciphers in an SMIMECapabilities attribute.
 149 If
 150 .Dv PKCS7_NOATTR
 151 is set, then no authenticatedAttributes will be used.
 152 If
 153 .Dv PKCS7_NOSMIMECAP
 154 is set, then just the SMIMECapabilities are omitted.
 155 .Pp
 156 If present, the SMIMECapabilities attribute indicates support for the
 157 following algorithms: triple DES, 128-bit RC2, 64-bit RC2, DES
 158 and 40-bit RC2.
 159 If any of these algorithms is disabled, then it will not be included.
 160 .Pp
 161 .Fn PKCS7_sign_add_signer
 162 returns an internal pointer to the
 163 .Vt PKCS7_SIGNER_INFO
 164 structure just added, which can be used to set additional attributes
 165 before it is finalized.
 166 .Sh RETURN VALUES
 167 .Fn PKCS7_sign_add_signer
 168 returns an internal pointer to the
 169 .Vt PKCS7_SIGNER_INFO
 170 structure just added or
 171 .Dv NULL
 172 if an error occurs.
 173 .Sh SEE ALSO
 174 .Xr ERR_get_error 3 ,
 175 .Xr PKCS7_new 3 ,
 176 .Xr PKCS7_sign 3
 177 .Sh HISTORY
 178 .Fn PKCS7_sign_add_signer
 179 was added to OpenSSL 1.0.0.