From 3254ebd02478248960a3f041565ab86567fde759 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 11 Jun 2025 23:16:32 +0000 Subject: Since the function SMIME_write_ASN1(3) is no longer public, move the descriptions of CMS_REUSE_DIGEST, PKCS7_REUSE_DIGEST, SMIME_BINARY, and SMIME_CRLFEOL and some improved wordings from that former page to SMIME_write_CMS(3) and SMIME_write_PKCS7(3), with some further polishing. Feedback and OK tb@. --- src/lib/libcrypto/man/SMIME_write_CMS.3 | 109 ++++++++++++++++++++---- src/lib/libcrypto/man/SMIME_write_PKCS7.3 | 135 +++++++++++++++++++----------- 2 files changed, 181 insertions(+), 63 deletions(-) (limited to 'src/lib') diff --git a/src/lib/libcrypto/man/SMIME_write_CMS.3 b/src/lib/libcrypto/man/SMIME_write_CMS.3 index 1a691fc29a..5f4c43bb7c 100644 --- a/src/lib/libcrypto/man/SMIME_write_CMS.3 +++ b/src/lib/libcrypto/man/SMIME_write_CMS.3 @@ -1,7 +1,24 @@ -.\" $OpenBSD: SMIME_write_CMS.3,v 1.8 2025/06/11 14:23:14 schwarze Exp $ +.\" $OpenBSD: SMIME_write_CMS.3,v 1.9 2025/06/11 23:16:32 schwarze Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" -.\" This file was written by Dr. Stephen Henson . +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021, 2025 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" The original file was written by Dr. Stephen Henson . .\" Copyright (c) 2008 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -66,21 +83,35 @@ .Fc .Sh DESCRIPTION .Fn SMIME_write_CMS -adds the appropriate MIME headers to the -.Fa cms -structure to produce an S/MIME message and writes it to -.Fa out . +generates an S/MIME message on +.Fa out +by writing MIME 1.0 headers +followed by a BER- and base64-encoded serialization of +.Fa cms . +The BER encoding uses the DER format except as described for +.Dv CMS_STREAM +below. If streaming is enabled, the content must be supplied in the .Fa data argument. .Pp -The following +The .Fa flags -can be passed: +can be the logical OR of zero or more of the following bits: .Bl -tag -width Ds .It Dv CMS_DETACHED -Use cleartext signing. -This option only makes sense if +Use cleartext signing and generate a +.Qq multipart/signed +S/MIME message. +The content is read from +.Fa data . +If +.Fa data +is a +.Dv NULL +pointer, this flag is ignored. +.Pp +This flag is only supported if .Fa cms is of the type .Vt SignedData @@ -95,13 +126,46 @@ is not set, the data must be read twice: once to compute the signature in .Xr CMS_sign 3 and once to output the S/MIME message. -.It Dv CMS_TEXT -Add MIME headers for type text/plain to the content. -This only makes sense if +.Pp +If +.Dv CMS_DETACHED +is ignored or not specified, the smime-type is chosen according to +.Xr CMS_get0_type 3 : +.Bl -tag -width Ds +.It Dv NID_pkcs7_enveloped +.Qq enveloped-data +.It Dv NID_pkcs7_signed +.Bl -tag -width Msigned-receiptM -compact +.It Qq signed-receipt +if +.Xr CMS_get0_eContentType 3 +is +.Dv NID_id_smime_ct_receipt +.It Qq signed-data +if +.Fa cms +specifies any digest algorithm +.It Qq certs-only +otherwise +.El +.It Dv NID_id_smime_ct_compressedData +.Qq compressed-data +.El +.It Dv CMS_REUSE_DIGEST +Skip the calls to +.Xr CMS_dataInit 3 +and +.Xr CMS_dataFinal 3 . +This flag has no effect unless .Dv CMS_DETACHED is also set. .It Dv CMS_STREAM -Perform streaming. +Perform streaming by reading the content from +.Fa data . +This only works if +.Dv CMS_DETACHED +is not specified. +.Pp This flag should only be set if .Dv CMS_STREAM was also passed to the function that created @@ -112,6 +176,23 @@ constructed encoding except in the case of .Vt SignedData with detached content where the content is absent and DER format is used. +.It Dv CMS_TEXT +Prepend the line +.Qq Content-Type: text/plain +to the content. +This only makes sense if +.Dv CMS_DETACHED +is also set. +It is ignored if the flag +.Dv SMIME_BINARY +is also set. +.It Dv SMIME_BINARY +If specified, this flag is passed through to +.Xr SMIME_crlf_copy 3 . +.It Dv SMIME_CRLFEOL +End MIME header lines with pairs of carriage return and newline characters. +By default, no carriage return characters are written +and header lines are ended with newline characters only. .El .Sh RETURN VALUES .Fn SMIME_write_CMS diff --git a/src/lib/libcrypto/man/SMIME_write_PKCS7.3 b/src/lib/libcrypto/man/SMIME_write_PKCS7.3 index 72200c0b1b..5e344d9c63 100644 --- a/src/lib/libcrypto/man/SMIME_write_PKCS7.3 +++ b/src/lib/libcrypto/man/SMIME_write_PKCS7.3 @@ -1,10 +1,10 @@ -.\" $OpenBSD: SMIME_write_PKCS7.3,v 1.11 2025/06/11 14:23:14 schwarze Exp $ +.\" $OpenBSD: SMIME_write_PKCS7.3,v 1.12 2025/06/11 23:16:32 schwarze Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" .\" This file is a derived work. .\" The changes are covered by the following Copyright and license: .\" -.\" Copyright (c) 2021 Ingo Schwarze +.\" Copyright (c) 2021, 2025 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -84,48 +84,81 @@ .Fc .Sh DESCRIPTION .Fn SMIME_write_PKCS7 -adds the appropriate MIME headers to a PKCS#7 structure to produce an -S/MIME message. -.Pp +generates an S/MIME message on .Fa out -is the -.Vt BIO -to write the data to. -.Fa p7 -is the appropriate -.Vt PKCS7 -structure. +by writing MIME 1.0 headers +followed by a BER- and base64-encoded serialization of +.Fa p7 . +The BER encoding uses the DER format except as described for +.Dv PKCS7_STREAM +below. If streaming is enabled, then the content must be supplied in the .Fa data argument. -.Fa flags -is an optional set of flags. .Pp -The following flags can be passed in the +The .Fa flags -parameter. -.Pp +can be the logical OR of zero or more of the following bits: +.Bl -tag -width Ds +.It Dv PKCS7_DETACHED +Use cleartext signing and generate a +.Qq multipart/signed +S/MIME message. +The content is read from +.Fa data . If -.Dv PKCS7_DETACHED -is set, then cleartext signing will be used. -This option only makes sense for signedData where +.Fa data +is a +.Dv NULL +pointer, this flag is ignored. +.Pp +This flag is only supported for signedData where .Dv PKCS7_DETACHED is also set when .Xr PKCS7_sign 3 -is also called. +is called. .Pp -If the -.Dv PKCS7_TEXT -flag is set, MIME headers for type -.Sy text/plain -are added to the content. -This only makes sense if +If +.Dv PKCS7_STREAM +is not set, the data must be read twice: once to compute the +signature in +.Xr PKCS7_sign 3 +and once to output the S/MIME message. +.Pp +If +.Dv PKCS7_DETACHED +is ignored or not specified, the smime-type is chosen according to the type of +.Fa p7 : +.Bl -tag -width Ds +.It Dv NID_pkcs7_enveloped +.Qq enveloped-data +.It Dv NID_pkcs7_signed +.Bl -tag -width Msigned-dataM -compact +.It Qq signed-data +if +.Fa p7 +specifies any digest algorithm +.It Qq certs-only +otherwise +.El +.It Dv NID_id_smime_ct_compressedData +.Qq compressed-data +.El +.It Dv PKCS7_REUSE_DIGEST +Skip the calls to +.Xr PKCS7_dataInit 3 +and +.Xr PKCS7_dataFinal 3 . +This flag has no effect unless .Dv PKCS7_DETACHED is also set. +.It Dv PKCS7_STREAM +Perform streaming by reading the content from +.Fa data . +This only works if +.Dv PKCS7_DETACHED +is not specified. .Pp -If the -.Dv PKCS7_STREAM -flag is set, streaming is performed. This flag should only be set if .Dv PKCS7_STREAM was also set in the previous call to @@ -133,13 +166,28 @@ was also set in the previous call to or .Xr PKCS7_encrypt 3 . .Pp -The bit -.Dv SMIME_OLDMIME -is inverted before passing on the -.Fa flags -to -.Xr SMIME_write_ASN1 3 . -Consequently, if this bit is set in the +The content is output in BER format using indefinite length constructed +encoding except in the case of signed data with detached content +where the content is absent and DER format is used. +.It Dv PKCS7_TEXT +Prepend the line +.Qq Content-Type: text/plain +to the content. +This only makes sense if +.Dv PKCS7_DETACHED +is also set. +It is ignored if the flag +.Dv SMIME_BINARY +is also set. +.It Dv SMIME_BINARY +If specified, this flag is passed through to +.Xr SMIME_crlf_copy 3 . +.It Dv SMIME_CRLFEOL +End MIME header lines with pairs of carriage return and newline characters. +By default, no carriage return characters are written +and header lines are ended with newline characters only. +.It Dv SMIME_OLDMIME +If this bit is set in the .Fa flags argument, .Qq application/pkcs7-mime @@ -151,18 +199,7 @@ Otherwise, or .Qq application/x-pkcs7-signature is used. -.Pp -If cleartext signing is being used and -.Dv PKCS7_STREAM -is not set, then the data must be read twice: once to compute the -signature in -.Xr PKCS7_sign 3 -and once to output the S/MIME message. -.Pp -If streaming is performed, the content is output in BER format using -indefinite length constructed encoding except in the case of signed -data with detached content where the content is absent and DER -format is used. +.El .Sh RETURN VALUES .Fn SMIME_write_PKCS7 is intended to return 1 on success or 0 on failure. -- cgit v1.2.3-55-g6feb