crypto/external/bsd/openssl/lib/libcrypto/man/CMS_add1_signer.3

   1 .\"     $NetBSD: CMS_add1_signer.3,v 1.3 2015/06/12 17:01:13 christos Exp $
   2 .\"
   3 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
   4 .\"
   5 .\" Standard preamble:
   6 .\" ========================================================================
   7 .de Sp \" Vertical space (when we can't use .PP)
   8 .if t .sp .5v
   9 .if n .sp
  10 ..
  11 .de Vb \" Begin verbatim text
  12 .ft CW
  13 .nf
  14 .ne \\$1
  15 ..
  16 .de Ve \" End verbatim text
  17 .ft R
  18 .fi
  19 ..
  20 .\" Set up some character translations and predefined strings.  \*(-- will
  21 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  22 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  23 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  24 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  25 .\" nothing in troff, for use with C<>.
  26 .tr \(*W-
  27 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  28 .ie n \{\
  29 .    ds -- \(*W-
  30 .    ds PI pi
  31 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  32 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  33 .    ds L" ""
  34 .    ds R" ""
  35 .    ds C` ""
  36 .    ds C' ""
  37 'br\}
  38 .el\{\
  39 .    ds -- \|\(em\|
  40 .    ds PI \(*p
  41 .    ds L" ``
  42 .    ds R" ''
  43 .    ds C`
  44 .    ds C'
  45 'br\}
  46 .\"
  47 .\" Escape single quotes in literal strings from groff's Unicode transform.
  48 .ie \n(.g .ds Aq \(aq
  49 .el       .ds Aq '
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .\"
  56 .\" Avoid warning from groff about undefined register 'F'.
  57 .de IX
  58 ..
  59 .nr rF 0
  60 .if \n(.g .if rF .nr rF 1
  61 .if (\n(rF:(\n(.g==0)) \{
  62 .    if \nF \{
  63 .        de IX
  64 .        tm Index:\\$1\t\\n%\t"\\$2"
  65 ..
  66 .        if !\nF==2 \{
  67 .            nr % 0
  68 .            nr F 2
  69 .        \}
  70 .    \}
  71 .\}
  72 .rr rF
  73 .\"
  74 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  75 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  76 .    \" fudge factors for nroff and troff
  77 .if n \{\
  78 .    ds #H 0
  79 .    ds #V .8m
  80 .    ds #F .3m
  81 .    ds #[ \f1
  82 .    ds #] \fP
  83 .\}
  84 .if t \{\
  85 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  86 .    ds #V .6m
  87 .    ds #F 0
  88 .    ds #[ \&
  89 .    ds #] \&
  90 .\}
  91 .    \" simple accents for nroff and troff
  92 .if n \{\
  93 .    ds ' \&
  94 .    ds ` \&
  95 .    ds ^ \&
  96 .    ds , \&
  97 .    ds ~ ~
  98 .    ds /
  99 .\}
 100 .if t \{\
 101 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 102 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 103 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 104 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 105 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 106 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 107 .\}
 108 .    \" troff and (daisy-wheel) nroff accents
 109 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 110 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 111 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 112 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 113 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 114 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 115 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 116 .ds ae a\h'-(\w'a'u*4/10)'e
 117 .ds Ae A\h'-(\w'A'u*4/10)'E
 118 .    \" corrections for vroff
 119 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 120 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 121 .    \" for low resolution devices (crt and lpr)
 122 .if \n(.H>23 .if \n(.V>19 \
 123 \{\
 124 .    ds : e
 125 .    ds 8 ss
 126 .    ds o a
 127 .    ds d- d\h'-1'\(ga
 128 .    ds D- D\h'-1'\(hy
 129 .    ds th \o'bp'
 130 .    ds Th \o'LP'
 131 .    ds ae ae
 132 .    ds Ae AE
 133 .\}
 134 .rm #[ #] #H #V #F C
 135 .\" ========================================================================
 136 .\"
 137 .IX Title "CMS_add1_signer 3"
 138 .TH CMS_add1_signer 3 "2015-01-13" "1.0.1n" "OpenSSL"
 139 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 140 .\" way too many mistakes in technical documents.
 141 .if n .ad l
 142 .nh
 143 .SH "NAME"
 144 .Vb 1
 145 \& CMS_add1_signer, CMS_SignerInfo_sign \- add a signer to a CMS_ContentInfo signed data structure.
 146 .Ve
 147 .SH "LIBRARY"
 148 libcrypto, -lcrypto
 149 .SH "SYNOPSIS"
 150 .IX Header "SYNOPSIS"
 151 .Vb 1
 152 \& #include <openssl/cms.h>
 153 \&
 154 \& CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags);
 155 \&
 156 \& int CMS_SignerInfo_sign(CMS_SignerInfo *si);
 157 .Ve
 158 .SH "DESCRIPTION"
 159 .IX Header "DESCRIPTION"
 160 \&\fICMS_add1_signer()\fR adds a signer with certificate \fBsigncert\fR and private
 161 key \fBpkey\fR using message digest \fBmd\fR to CMS_ContentInfo SignedData
 162 structure \fBcms\fR.
 163 .PP
 164 The CMS_ContentInfo structure should be obtained from an initial call to
 165 \&\fICMS_sign()\fR with the flag \fB\s-1CMS_PARTIAL\s0\fR set or in the case or re-signing a
 166 valid CMS_ContentInfo SignedData structure.
 167 .PP
 168 If the \fBmd\fR parameter is \fB\s-1NULL\s0\fR then the default digest for the public
 169 key algorithm will be used.
 170 .PP
 171 Unless the \fB\s-1CMS_REUSE_DIGEST\s0\fR flag is set the returned CMS_ContentInfo
 172 structure is not complete and must be finalized either by streaming (if
 173 applicable) or a call to \fICMS_final()\fR.
 174 .PP
 175 The \fICMS_SignerInfo_sign()\fR function will explicitly sign a CMS_SignerInfo
 176 structure, its main use is when \fB\s-1CMS_REUSE_DIGEST\s0\fR and \fB\s-1CMS_PARTIAL\s0\fR flags
 177 are both set.
 178 .SH "NOTES"
 179 .IX Header "NOTES"
 180 The main purpose of \fICMS_add1_signer()\fR is to provide finer control
 181 over a \s-1CMS\s0 signed data structure where the simpler \fICMS_sign()\fR function defaults
 182 are not appropriate. For example if multiple signers or non default digest
 183 algorithms are needed. New attributes can also be added using the returned
 184 CMS_SignerInfo structure and the \s-1CMS\s0 attribute utility functions or the
 185 \&\s-1CMS\s0 signed receipt request functions.
 186 .PP
 187 Any of the following flags (ored together) can be passed in the \fBflags\fR
 188 parameter.
 189 .PP
 190 If \fB\s-1CMS_REUSE_DIGEST\s0\fR is set then an attempt is made to copy the content
 191 digest value from the CMS_ContentInfo structure: to add a signer to an existing
 192 structure.  An error occurs if a matching digest value cannot be found to copy.
 193 The returned CMS_ContentInfo structure will be valid and finalized when this
 194 flag is set.
 195 .PP
 196 If \fB\s-1CMS_PARTIAL\s0\fR is set in addition to \fB\s-1CMS_REUSE_DIGEST\s0\fR then the
 197 CMS_SignerInfo structure will not be finalized so additional attributes
 198 can be added. In this case an explicit call to \fICMS_SignerInfo_sign()\fR is
 199 needed to finalize it.
 200 .PP
 201 If \fB\s-1CMS_NOCERTS\s0\fR is set the signer's certificate will not be included in the
 202 CMS_ContentInfo structure, the signer's certificate must still be supplied in
 203 the \fBsigncert\fR parameter though. This can reduce the size of the signature if
 204 the signers certificate can be obtained by other means: for example a
 205 previously signed message.
 206 .PP
 207 The SignedData structure includes several \s-1CMS\s0 signedAttributes including the
 208 signing time, the \s-1CMS\s0 content type and the supported list of ciphers in an
 209 SMIMECapabilities attribute. If \fB\s-1CMS_NOATTR\s0\fR is set then no signedAttributes
 210 will be used. If \fB\s-1CMS_NOSMIMECAP\s0\fR is set then just the SMIMECapabilities are
 211 omitted.
 212 .PP
 213 OpenSSL will by default identify signing certificates using issuer name
 214 and serial number. If \fB\s-1CMS_USE_KEYID\s0\fR is set it will use the subject key
 215 identifier value instead. An error occurs if the signing certificate does not
 216 have a subject key identifier extension.
 217 .PP
 218 If present the SMIMECapabilities attribute indicates support for the following
 219 algorithms in preference order: 256 bit \s-1AES,\s0 Gost R3411\-94, Gost 28147\-89, 192
 220 bit \s-1AES, 128\s0 bit \s-1AES,\s0 triple \s-1DES, 128\s0 bit \s-1RC2, 64\s0 bit \s-1RC2, DES\s0 and 40 bit \s-1RC2.\s0
 221 If any of these algorithms is not available then it will not be included: for example the \s-1GOST\s0 algorithms will not be included if the \s-1GOST ENGINE\s0 is
 222 not loaded.
 223 .PP
 224 \&\fICMS_add1_signer()\fR returns an internal pointer to the CMS_SignerInfo
 225 structure just added, this can be used to set additional attributes
 226 before it is finalized.
 227 .SH "RETURN VALUES"
 228 .IX Header "RETURN VALUES"
 229 \&\fICMS_add1_signer()\fR returns an internal pointer to the CMS_SignerInfo
 230 structure just added or \s-1NULL\s0 if an error occurs.
 231 .SH "SEE ALSO"
 232 .IX Header "SEE ALSO"
 233 \&\fIERR_get_error\fR\|(3), \fICMS_sign\fR\|(3),
 234 \&\fICMS_final\fR\|(3),
 235 .SH "HISTORY"
 236 .IX Header "HISTORY"
 237 \&\fICMS_add1_signer()\fR was added to OpenSSL 0.9.8