1.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.35)
| 1.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
|
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v
7.if n .sp
8..
9.de Vb \" Begin verbatim text
10.ft CW
11.nf
12.ne \\$1
13..
14.de Ve \" End verbatim text
15.ft R
16.fi
17..
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26.ie n \{\
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
35'br\}
36.el\{\
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
41. ds C`
42. ds C'
43'br\}
44.\"
45.\" Escape single quotes in literal strings from groff's Unicode transform.
46.ie \n(.g .ds Aq \(aq
47.el .ds Aq '
48.\"
49.\" If the F register is >0, we'll generate index entries on stderr for
50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51.\" entries marked with X<> in POD. Of course, you'll have to process the
52.\" output yourself in some meaningful fashion.
53.\"
54.\" Avoid warning from groff about undefined register 'F'.
55.de IX
56..
57.if !\nF .nr F 0
58.if \nF>0 \{\
59. de IX
60. tm Index:\\$1\t\\n%\t"\\$2"
61..
62. if !\nF==2 \{\
63. nr % 0
64. nr F 2
65. \}
66.\}
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
71.if n \{\
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
77.\}
78.if t \{\
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
84.\}
85. \" simple accents for nroff and troff
86.if n \{\
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
93.\}
94.if t \{\
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101.\}
102. \" troff and (daisy-wheel) nroff accents
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
112. \" corrections for vroff
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115. \" for low resolution devices (crt and lpr)
116.if \n(.H>23 .if \n(.V>19 \
117\{\
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
127.\}
128.rm #[ #] #H #V #F C
129.\" ========================================================================
130.\"
131.IX Title "EVP_DigestSignInit 3"
| 2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v
7.if n .sp
8..
9.de Vb \" Begin verbatim text
10.ft CW
11.nf
12.ne \\$1
13..
14.de Ve \" End verbatim text
15.ft R
16.fi
17..
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26.ie n \{\
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
35'br\}
36.el\{\
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
41. ds C`
42. ds C'
43'br\}
44.\"
45.\" Escape single quotes in literal strings from groff's Unicode transform.
46.ie \n(.g .ds Aq \(aq
47.el .ds Aq '
48.\"
49.\" If the F register is >0, we'll generate index entries on stderr for
50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51.\" entries marked with X<> in POD. Of course, you'll have to process the
52.\" output yourself in some meaningful fashion.
53.\"
54.\" Avoid warning from groff about undefined register 'F'.
55.de IX
56..
57.if !\nF .nr F 0
58.if \nF>0 \{\
59. de IX
60. tm Index:\\$1\t\\n%\t"\\$2"
61..
62. if !\nF==2 \{\
63. nr % 0
64. nr F 2
65. \}
66.\}
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
71.if n \{\
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
77.\}
78.if t \{\
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
84.\}
85. \" simple accents for nroff and troff
86.if n \{\
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
93.\}
94.if t \{\
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101.\}
102. \" troff and (daisy-wheel) nroff accents
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
112. \" corrections for vroff
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115. \" for low resolution devices (crt and lpr)
116.if \n(.H>23 .if \n(.V>19 \
117\{\
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
127.\}
128.rm #[ #] #H #V #F C
129.\" ========================================================================
130.\"
131.IX Title "EVP_DigestSignInit 3"
|
132.TH EVP_DigestSignInit 3 "2018-03-27" "1.0.2o" "OpenSSL"
| 132.TH EVP_DigestSignInit 3 "2018-08-14" "1.0.2p" "OpenSSL"
|
133.\" For nroff, turn off justification. Always turn off hyphenation; it makes
134.\" way too many mistakes in technical documents.
135.if n .ad l
136.nh
137.SH "NAME"
138EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal \- EVP signing functions
139.SH "SYNOPSIS"
140.IX Header "SYNOPSIS"
141.Vb 1
142\& #include <openssl/evp.h>
143\&
144\& int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
145\& const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
146\& int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
147\& int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen);
148.Ve
149.SH "DESCRIPTION"
150.IX Header "DESCRIPTION"
151The \s-1EVP\s0 signature routines are a high level interface to digital signatures.
152.PP
153\&\fIEVP_DigestSignInit()\fR sets up signing context \fBctx\fR to use digest \fBtype\fR from
| 133.\" For nroff, turn off justification. Always turn off hyphenation; it makes
134.\" way too many mistakes in technical documents.
135.if n .ad l
136.nh
137.SH "NAME"
138EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal \- EVP signing functions
139.SH "SYNOPSIS"
140.IX Header "SYNOPSIS"
141.Vb 1
142\& #include <openssl/evp.h>
143\&
144\& int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
145\& const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
146\& int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
147\& int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen);
148.Ve
149.SH "DESCRIPTION"
150.IX Header "DESCRIPTION"
151The \s-1EVP\s0 signature routines are a high level interface to digital signatures.
152.PP
153\&\fIEVP_DigestSignInit()\fR sets up signing context \fBctx\fR to use digest \fBtype\fR from
|
154\&\s-1ENGINE \s0\fBimpl\fR and private key \fBpkey\fR. \fBctx\fR must be initialized with
| 154\&\s-1ENGINE\s0 \fBimpl\fR and private key \fBpkey\fR. \fBctx\fR must be initialized with
|
155\&\fIEVP_MD_CTX_init()\fR before calling this function. If \fBpctx\fR is not \s-1NULL\s0 the
156\&\s-1EVP_PKEY_CTX\s0 of the signing operation will be written to \fB*pctx\fR: this can
157be used to set alternative signing options.
158.PP
159\&\fIEVP_DigestSignUpdate()\fR hashes \fBcnt\fR bytes of data at \fBd\fR into the
160signature context \fBctx\fR. This function can be called several times on the
161same \fBctx\fR to include additional data. This function is currently implemented
162usig a macro.
163.PP
164\&\fIEVP_DigestSignFinal()\fR signs the data in \fBctx\fR places the signature in \fBsig\fR.
165If \fBsig\fR is \fB\s-1NULL\s0\fR then the maximum size of the output buffer is written to
166the \fBsiglen\fR parameter. If \fBsig\fR is not \fB\s-1NULL\s0\fR then before the call the
167\&\fBsiglen\fR parameter should contain the length of the \fBsig\fR buffer, if the
168call is successful the signature is written to \fBsig\fR and the amount of data
169written to \fBsiglen\fR.
170.SH "RETURN VALUES"
171.IX Header "RETURN VALUES"
172\&\fIEVP_DigestSignInit()\fR \fIEVP_DigestSignUpdate()\fR and \fIEVP_DigestSignaFinal()\fR return
1731 for success and 0 or a negative value for failure. In particular a return
174value of \-2 indicates the operation is not supported by the public key
175algorithm.
176.PP
177The error codes can be obtained from \fIERR_get_error\fR\|(3).
178.SH "NOTES"
179.IX Header "NOTES"
180The \fB\s-1EVP\s0\fR interface to digital signatures should almost always be used in
181preference to the low level interfaces. This is because the code then becomes
182transparent to the algorithm used and much more flexible.
183.PP
184In previous versions of OpenSSL there was a link between message digest types
185and public key algorithms. This meant that \*(L"clone\*(R" digests such as \fIEVP_dss1()\fR
186needed to be used to sign using \s-1SHA1\s0 and \s-1DSA.\s0 This is no longer necessary and
187the use of clone digest is now discouraged.
188.PP
189For some key types and parameters the random number generator must be seeded
190or the operation will fail.
191.PP
192The call to \fIEVP_DigestSignFinal()\fR internally finalizes a copy of the digest
193context. This means that calls to \fIEVP_DigestSignUpdate()\fR and
194\&\fIEVP_DigestSignFinal()\fR can be called later to digest and sign additional data.
195.PP
196Since only a copy of the digest context is ever finalized the context must
197be cleaned up after use by calling \fIEVP_MD_CTX_cleanup()\fR or a memory leak
198will occur.
199.PP
200The use of \fIEVP_PKEY_size()\fR with these functions is discouraged because some
201signature operations may have a signature length which depends on the
202parameters set. As a result \fIEVP_PKEY_size()\fR would have to return a value
203which indicates the maximum possible signature for any set of parameters.
204.SH "SEE ALSO"
205.IX Header "SEE ALSO"
206\&\fIEVP_DigestVerifyInit\fR\|(3),
207\&\fIEVP_DigestInit\fR\|(3), \fIerr\fR\|(3),
208\&\fIevp\fR\|(3), \fIhmac\fR\|(3), \fImd2\fR\|(3),
209\&\fImd5\fR\|(3), \fImdc2\fR\|(3), \fIripemd\fR\|(3),
210\&\fIsha\fR\|(3), \fIdgst\fR\|(1)
211.SH "HISTORY"
212.IX Header "HISTORY"
213\&\fIEVP_DigestSignInit()\fR, \fIEVP_DigestSignUpdate()\fR and \fIEVP_DigestSignFinal()\fR
214were first added to OpenSSL 1.0.0.
| 155\&\fIEVP_MD_CTX_init()\fR before calling this function. If \fBpctx\fR is not \s-1NULL\s0 the
156\&\s-1EVP_PKEY_CTX\s0 of the signing operation will be written to \fB*pctx\fR: this can
157be used to set alternative signing options.
158.PP
159\&\fIEVP_DigestSignUpdate()\fR hashes \fBcnt\fR bytes of data at \fBd\fR into the
160signature context \fBctx\fR. This function can be called several times on the
161same \fBctx\fR to include additional data. This function is currently implemented
162usig a macro.
163.PP
164\&\fIEVP_DigestSignFinal()\fR signs the data in \fBctx\fR places the signature in \fBsig\fR.
165If \fBsig\fR is \fB\s-1NULL\s0\fR then the maximum size of the output buffer is written to
166the \fBsiglen\fR parameter. If \fBsig\fR is not \fB\s-1NULL\s0\fR then before the call the
167\&\fBsiglen\fR parameter should contain the length of the \fBsig\fR buffer, if the
168call is successful the signature is written to \fBsig\fR and the amount of data
169written to \fBsiglen\fR.
170.SH "RETURN VALUES"
171.IX Header "RETURN VALUES"
172\&\fIEVP_DigestSignInit()\fR \fIEVP_DigestSignUpdate()\fR and \fIEVP_DigestSignaFinal()\fR return
1731 for success and 0 or a negative value for failure. In particular a return
174value of \-2 indicates the operation is not supported by the public key
175algorithm.
176.PP
177The error codes can be obtained from \fIERR_get_error\fR\|(3).
178.SH "NOTES"
179.IX Header "NOTES"
180The \fB\s-1EVP\s0\fR interface to digital signatures should almost always be used in
181preference to the low level interfaces. This is because the code then becomes
182transparent to the algorithm used and much more flexible.
183.PP
184In previous versions of OpenSSL there was a link between message digest types
185and public key algorithms. This meant that \*(L"clone\*(R" digests such as \fIEVP_dss1()\fR
186needed to be used to sign using \s-1SHA1\s0 and \s-1DSA.\s0 This is no longer necessary and
187the use of clone digest is now discouraged.
188.PP
189For some key types and parameters the random number generator must be seeded
190or the operation will fail.
191.PP
192The call to \fIEVP_DigestSignFinal()\fR internally finalizes a copy of the digest
193context. This means that calls to \fIEVP_DigestSignUpdate()\fR and
194\&\fIEVP_DigestSignFinal()\fR can be called later to digest and sign additional data.
195.PP
196Since only a copy of the digest context is ever finalized the context must
197be cleaned up after use by calling \fIEVP_MD_CTX_cleanup()\fR or a memory leak
198will occur.
199.PP
200The use of \fIEVP_PKEY_size()\fR with these functions is discouraged because some
201signature operations may have a signature length which depends on the
202parameters set. As a result \fIEVP_PKEY_size()\fR would have to return a value
203which indicates the maximum possible signature for any set of parameters.
204.SH "SEE ALSO"
205.IX Header "SEE ALSO"
206\&\fIEVP_DigestVerifyInit\fR\|(3),
207\&\fIEVP_DigestInit\fR\|(3), \fIerr\fR\|(3),
208\&\fIevp\fR\|(3), \fIhmac\fR\|(3), \fImd2\fR\|(3),
209\&\fImd5\fR\|(3), \fImdc2\fR\|(3), \fIripemd\fR\|(3),
210\&\fIsha\fR\|(3), \fIdgst\fR\|(1)
211.SH "HISTORY"
212.IX Header "HISTORY"
213\&\fIEVP_DigestSignInit()\fR, \fIEVP_DigestSignUpdate()\fR and \fIEVP_DigestSignFinal()\fR
214were first added to OpenSSL 1.0.0.
|