diff options
Diffstat (limited to 'src/lib/libcrypto/man/CMS_sign.3')
| -rw-r--r-- | src/lib/libcrypto/man/CMS_sign.3 | 199 | 
1 files changed, 0 insertions, 199 deletions
| diff --git a/src/lib/libcrypto/man/CMS_sign.3 b/src/lib/libcrypto/man/CMS_sign.3 deleted file mode 100644 index af75a20d6b..0000000000 --- a/src/lib/libcrypto/man/CMS_sign.3 +++ /dev/null | |||
| @@ -1,199 +0,0 @@ | |||
| 1 | .Dd $Mdocdate: November 11 2015 $ | ||
| 2 | .Dt CMS_SIGN 3 | ||
| 3 | .Os | ||
| 4 | .Sh NAME | ||
| 5 | .Nm CMS_sign | ||
| 6 | .Nd create a CMS SignedData structure | ||
| 7 | .Sh SYNOPSIS | ||
| 8 | .In openssl/cms.h | ||
| 9 | .Ft CMS_ContentInfo * | ||
| 10 | .Fo CMS_sign | ||
| 11 | .Fa "X509 *signcert" | ||
| 12 | .Fa "EVP_PKEY *pkey" | ||
| 13 | .Fa "STACK_OF(X509) *certs" | ||
| 14 | .Fa "BIO *data" | ||
| 15 | .Fa "unsigned int flags" | ||
| 16 | .Fc | ||
| 17 | .Sh DESCRIPTION | ||
| 18 | .Fn CMS_sign | ||
| 19 | creates and returns a CMS SignedData structure. | ||
| 20 | .Fa signcert | ||
| 21 | is the certificate to sign with, | ||
| 22 | .Fa pkey | ||
| 23 | is the corresponding private key. | ||
| 24 | .Fa certs | ||
| 25 | is an optional additional set of certificates to include in the CMS | ||
| 26 | structure (for example any intermediate CAs in the chain). | ||
| 27 | Any or all of these parameters can be | ||
| 28 | .Dv NULL , | ||
| 29 | see | ||
| 30 | .Sx NOTES | ||
| 31 | below. | ||
| 32 | .Pp | ||
| 33 | The data to be signed is read from | ||
| 34 | .Fa data . | ||
| 35 | .Pp | ||
| 36 | .Fa flags | ||
| 37 | is an optional set of flags. | ||
| 38 | .Sh NOTES | ||
| 39 | Any of the following flags (OR'ed together) can be passed in the | ||
| 40 | .Fa flags | ||
| 41 | parameter. | ||
| 42 | .Pp | ||
| 43 | Many S/MIME clients expect the signed content to include valid MIME | ||
| 44 | headers. | ||
| 45 | If the | ||
| 46 | .Dv CMS_TEXT | ||
| 47 | flag is set, MIME headers for type | ||
| 48 | .Sy text/plain | ||
| 49 | are prepended to the data. | ||
| 50 | .Pp | ||
| 51 | If | ||
| 52 | .Dv CMS_NOCERTS | ||
| 53 | is set, the signer's certificate will not be included in the | ||
| 54 | .Vt CMS_ContentInfo | ||
| 55 | structure, the signer's certificate must still be supplied in the | ||
| 56 | .Fa signcert | ||
| 57 | parameter though. | ||
| 58 | This can reduce the size of the signature if the signers certificate can | ||
| 59 | be obtained by other means: for example a previously signed message. | ||
| 60 | .Pp | ||
| 61 | The data being signed is included in the | ||
| 62 | .Vt CMS_ContentInfo | ||
| 63 | structure, unless | ||
| 64 | .Dv CMS_DETACHED | ||
| 65 | is set, in which case it is omitted. | ||
| 66 | This is used for | ||
| 67 | .Vt CMS_ContentInfo | ||
| 68 | detached signatures which are used in S/MIME plaintext signed | ||
| 69 | messages for example. | ||
| 70 | .Pp | ||
| 71 | Normally the supplied content is translated into MIME canonical format | ||
| 72 | (as required by the S/MIME specifications); if | ||
| 73 | .Dv CMS_BINARY | ||
| 74 | is set, no translation occurs. | ||
| 75 | This option should be used if the supplied data is in binary format; | ||
| 76 | otherwise the translation will corrupt it. | ||
| 77 | .Pp | ||
| 78 | The SignedData structure includes several CMS signedAttributes including | ||
| 79 | the signing time, the CMS content type and the supported list of ciphers | ||
| 80 | in an SMIMECapabilities attribute. | ||
| 81 | If | ||
| 82 | .Dv CMS_NOATTR | ||
| 83 | is set, then no signedAttributes will be used. | ||
| 84 | If | ||
| 85 | .Dv CMS_NOSMIMECAP | ||
| 86 | is set, then just the SMIMECapabilities are omitted. | ||
| 87 | .Pp | ||
| 88 | If present, the SMIMECapabilities attribute indicates support for the | ||
| 89 | following algorithms in preference order: 256 bit AES, Gost R3411-94, | ||
| 90 | Gost 28147-89, 192 bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit | ||
| 91 | RC2, DES and 40 bit RC2. | ||
| 92 | If any of these algorithms is not available, then it will not be | ||
| 93 | included: for example the GOST algorithms will not be included if | ||
| 94 | the GOST ENGINE is not loaded. | ||
| 95 | .Pp | ||
| 96 | OpenSSL will by default identify signing certificates using issuer name | ||
| 97 | and serial number. | ||
| 98 | If | ||
| 99 | .Dv CMS_USE_KEYID | ||
| 100 | is set, it will use the subject key identifier value instead. | ||
| 101 | An error occurs if the signing certificate does not have a subject key | ||
| 102 | identifier extension. | ||
| 103 | .Pp | ||
| 104 | If the flag | ||
| 105 | .Dv CMS_STREAM | ||
| 106 | is set, then the returned | ||
| 107 | .Vt CMS_ContentInfo | ||
| 108 | structure is just initialized ready to perform the signing operation. | ||
| 109 | The signing is however | ||
| 110 | .Em not | ||
| 111 | performed and the data to be signed is not read from the | ||
| 112 | .Fa data | ||
| 113 | parameter. | ||
| 114 | Signing is deferred until after the data has been written. | ||
| 115 | In this way, data can be signed in a single pass. | ||
| 116 | .Pp | ||
| 117 | If the | ||
| 118 | .Dv CMS_PARTIAL | ||
| 119 | flag is set, a partial | ||
| 120 | .Vt CMS_ContentInfo | ||
| 121 | structure is output to which additional signers and capabilities can be | ||
| 122 | added before finalization. | ||
| 123 | .Pp | ||
| 124 | If the flag | ||
| 125 | .Dv CMS_STREAM | ||
| 126 | is set, the returned | ||
| 127 | .Vt CMS_ContentInfo | ||
| 128 | structure is | ||
| 129 | .Em not | ||
| 130 | complete and outputting its contents via a function that does not | ||
| 131 | properly finalize the | ||
| 132 | .Vt CMS_ContentInfo | ||
| 133 | structure will give unpredictable results. | ||
| 134 | .Pp | ||
| 135 | Several functions including | ||
| 136 | .Xr SMIME_write_CMS 3 , | ||
| 137 | .Xr i2d_CMS_bio_stream 3 , | ||
| 138 | .Xr PEM_write_bio_CMS_stream 3 | ||
| 139 | finalize the structure. | ||
| 140 | Alternatively finalization can be performed by obtaining the streaming | ||
| 141 | ASN1 | ||
| 142 | .Vt BIO | ||
| 143 | directly using | ||
| 144 | .Xr BIO_new_CMS 3 . | ||
| 145 | .Pp | ||
| 146 | If a signer is specified, it will use the default digest for the signing | ||
| 147 | algorithm. | ||
| 148 | This is SHA1 for both RSA and DSA keys. | ||
| 149 | .Pp | ||
| 150 | If | ||
| 151 | .Fa signcert | ||
| 152 | and | ||
| 153 | .Fa pkey | ||
| 154 | are | ||
| 155 | .Dv NULL , | ||
| 156 | then a certificates only CMS structure is output. | ||
| 157 | .Pp | ||
| 158 | The function | ||
| 159 | .Fn CMS_sign | ||
| 160 | is a basic CMS signing function whose output will be suitable for many | ||
| 161 | purposes. | ||
| 162 | For finer control of the output format the | ||
| 163 | .Fa certs , | ||
| 164 | .Fa signcert | ||
| 165 | and | ||
| 166 | .Fa pkey | ||
| 167 | parameters can all be | ||
| 168 | .Dv NULL | ||
| 169 | and the | ||
| 170 | .Dv CMS_PARTIAL | ||
| 171 | flag set. | ||
| 172 | Then one or more signers can be added using the function | ||
| 173 | .Xr CMS_sign_add1_signer 3 , | ||
| 174 | non default digests can be used and custom attributes added. | ||
| 175 | .Xr CMS_final 3 | ||
| 176 | must then be called to finalize the structure if streaming is not | ||
| 177 | enabled. | ||
| 178 | .Sh RETURN VALUES | ||
| 179 | .Fn CMS_sign | ||
| 180 | returns either a valid | ||
| 181 | .Vt CMS_ContentInfo | ||
| 182 | structure or | ||
| 183 | .Dv NULL | ||
| 184 | if an error occurred. | ||
| 185 | The error can be obtained from | ||
| 186 | .Xr ERR_get_error 3 . | ||
| 187 | .Sh SEE ALSO | ||
| 188 | .Xr CMS_verify 3 , | ||
| 189 | .Xr ERR_get_error 3 | ||
| 190 | .Sh HISTORY | ||
| 191 | .Fn CMS_sign | ||
| 192 | was added to OpenSSL 0.9.8. | ||
| 193 | .Pp | ||
| 194 | The | ||
| 195 | .Dv CMS_STREAM | ||
| 196 | flag is only supported for detached data in OpenSSL 0.9.8. | ||
| 197 | It is supported for embedded data in OpenSSL 1.0.0 and later. | ||
| 198 | .Sh BUGS | ||
| 199 | Some attributes such as counter signatures are not supported. | ||
