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