Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PKCS7_ADD_ATTRIBUTE(3) FreeBSD Library Functions Manual	PKCS7_ADD_ATTRIBUTE(3)

NAME
     PKCS7_add_attribute, PKCS7_set_attributes,	PKCS7_get_attribute,
     PKCS7_add_signed_attribute, PKCS7_set_signed_attributes,
     PKCS7_get_signed_attribute, PKCS7_add_attrib_content_type,
     PKCS7_add1_attrib_digest, PKCS7_add0_attrib_signing_time,
     PKCS7_add_attrib_smimecap -- attributes of	SignerInfo objects

SYNOPSIS
     #include <openssl/pkcs7.h>

     int
     PKCS7_add_attribute(PKCS7_SIGNER_INFO *si,	int nid, int attrtype,
	 void *value);

     int
     PKCS7_set_attributes(PKCS7_SIGNER_INFO *si,
	 STACK_OF(X509_ATTRIBUTE) *sk);

     ASN1_TYPE *
     PKCS7_get_attribute(PKCS7_SIGNER_INFO *si,	int nid);

     int
     PKCS7_add_signed_attribute(PKCS7_SIGNER_INFO *si, int nid,	int attrtype,
	 void *value);

     int
     PKCS7_set_signed_attributes(PKCS7_SIGNER_INFO *si,
	 STACK_OF(X509_ATTRIBUTE) *sk);

     ASN1_TYPE *
     PKCS7_get_signed_attribute(PKCS7_SIGNER_INFO *si, int nid);

     int
     PKCS7_add_attrib_content_type(PKCS7_SIGNER_INFO *si, ASN1_OBJECT *coid);

     int
     PKCS7_add1_attrib_digest(PKCS7_SIGNER_INFO	*si, const unsigned char *md,
	 int mdlen);

     int
     PKCS7_add0_attrib_signing_time(PKCS7_SIGNER_INFO *si, ASN1_TIME *t);

     int
     PKCS7_add_attrib_smimecap(PKCS7_SIGNER_INFO *si,
	 STACK_OF(X509_ALGOR) *cap);

DESCRIPTION
     PKCS7_add_attribute() appends a new attribute of type nid to the
     unauthenticatedAttributes list of si, and it adds a new ASN.1 ANY object
     of	type attrtype with the given value to the new attribute.  Ownership of
     the value is transferred into the new attribute object, so	the calling
     code must not free(3) the value.  If the list already contains an unau-
     thenticated attribute of type nid before the call,	the new	attribute re-
     places the	old one	instead	of being appended to the end of	the list.

     PKCS7_set_attributes() frees the unauthenticatedAttributes	list of	si and
     all the attributes	contained in it	and replaces it	with a deep copy of
     sk.

     PKCS7_get_attribute() retrieves the first ASN.1 ANY member	of the attri-
     bute of type nid from the unauthenticatedAttributes list of si.

     The behaviour of PKCS7_add_signed_attribute(),
     PKCS7_set_signed_attributes(), and	PKCS7_get_signed_attribute() is	iden-
     tical except that they operate on the list	of authenticatedAttributes.

     The normal	way to use PKCS7_add_signed_attribute()	is to first create a
     SignedInfo	object with PKCS7_sign(3) using	the PKCS7_PARTIAL or
     PKCS7_STREAM flag,	retrieve the PKCS7_SIGNER_INFO object with
     PKCS7_get_signer_info(3) or add an	additional one with
     PKCS7_sign_add_signer(3), call PKCS7_add_signed_attribute() for each de-
     sired additional attribute, then do the signing with PKCS7_final(3) or
     with another finalizing function.

     The four remaining	functions are wrappers around
     PKCS7_add_signed_attribute().

     PKCS7_add_attrib_content_type() sets the NID_pkcs9_contentType attribute
     to	coid, which specifies the content type of the ContentInfo value	to be
     signed.  This attribute is	mandatory and automatically added by
     PKCS7_sign(3) and PKCS7_sign_add_signer(3)	unless the PKCS7_NOATTR	flag
     is	present.  Objects suitable as coid arguments can for example be	ob-
     tained with OBJ_nid2obj(3).  If coid is NULL, the content type defaults
     to	NID_pkcs7_data.

     PKCS7_add1_attrib_digest()	sets or	replaces the NID_pkcs9_messageDigest
     attribute,	which is the message digest of the contents octets of the DER-
     encoding of the content field of the ContentInfo value being signed, to a
     copy of md, which is assumed to be	mdlen bytes long.  If mdlen is -1,
     then strlen(md) is	used instead of	mdlen.	This attribute is mandatory
     and automatically added by	PKCS7_dataFinal(3) and PKCS7_final(3).

     PKCS7_add0_attrib_signing_time() sets or replaces the optional
     NID_pkcs9_signingTime attribute to	t, specifying the time at which	the
     signer performed the signing process.  Ownership of t is transferred into
     the new attribute object, so the calling code must	not free(3) t.	If t
     is	NULL, a	new ASN1_TIME structure	is allocated.  This attribute is auto-
     matically added by	PKCS7_dataFinal(3) and PKCS7_final(3).

     PKCS7_add_attrib_smimecap() sets or replaces the optional
     NID_SMIMECapabilities attribute, indicating algorithms the	sender is pre-
     pared to handle.  The cap pointer is not stored in	the new	attribute ob-
     ject and can be passed to sk_X509_ALGOR_pop_free()	after the call.	 This
     attribute is automatically	added by PKCS7_sign(3) and
     PKCS7_sign_add_signer(3) unless the PKCS7_NOATTR or PKCS7_NOSMIMECAP flag
     is	present.

RETURN VALUES
     PKCS7_add_attribute(), PKCS7_set_attributes(),
     PKCS7_add_signed_attribute(), PKCS7_set_signed_attributes(),
     PKCS7_add_attrib_content_type(), PKCS7_add1_attrib_digest(),
     PKCS7_add0_attrib_signing_time(), and PKCS7_add_attrib_smimecap() return
     1 on success or 0 on failure.  The	most common reason for failure is lack
     of	memory.	 PKCS7_add_attribute() and PKCS7_add_signed_attribute()	also
     fail if nid is invalid, and PKCS7_add_attrib_content_type() if si already
     contains an authenticated attribute of type NID_pkcs9_contentType.

     PKCS7_get_attribute() and PKCS7_get_signed_attribute() return an internal
     pointer to	an ASN.1 ANY object or NULL on failure.	 They fail if nid is
     invalid, if the respective	list in	si contains no attribute of the	re-
     quested type, or if an invalid element is found in	the list before	find-
     ing the attribute of the requested	type.

SEE ALSO
     ASN1_TIME_new(3), ASN1_TYPE_new(3), OBJ_nid2obj(3), PKCS7_final(3),
     PKCS7_get_signer_info(3), PKCS7_new(3), PKCS7_sign(3),
     PKCS7_sign_add_signer(3), STACK_OF(3), X509_ALGOR_new(3),
     X509_ATTRIBUTE_new(3)

STANDARDS
     RFC 2315: PKCS #7:	Cryptographic Message Syntax Version 1.5, section 9.2:
     SignerInfo	type

     RFC 2985: PKCS #9:	Selected Object	Classes	and Attribute Types Version
     2.0, section 5.3: Attribute types for use in PKCS #7 data and section
     5.6: Attributes defined in	S/MIME

     RFC 8551: Secure/Multipurpose Internet Mail Extensions (S/MIME) Version
     4.0 Message Specification,	section	2.5.2: SMIMECapabilities Attribute

HISTORY
     PKCS7_add_attribute(), PKCS7_set_attributes(), PKCS7_get_attribute(),
     PKCS7_add_signed_attribute(), PKCS7_set_signed_attributes(), and
     PKCS7_get_signed_attribute() first	appeared in OpenSSL 0.9.1 and have
     been available since OpenBSD 2.6.

     PKCS7_add_attrib_smimecap() first appeared	in OpenSSL 0.9.5 and has been
     available since OpenBSD 2.7.

     PKCS7_add_attrib_content_type(), PKCS7_add1_attrib_digest(), and
     PKCS7_add0_attrib_signing_time() first appeared in	OpenSSL	1.0.0 and have
     been available since OpenBSD 4.9.

CAVEATS
     PKCS7_set_signed_attributes() does	not validate that sk contains the PKCS
     #9	content	type and message digest	attributes required by RFC 2315.  It
     succeeds even when	sk is empty, leaving si	in a state that	violates the
     standard.

     PKCS7_add0_attrib_signing_time() does not validate	t in any way.  In par-
     ticular, it may set the signing time to the future	or to the remote past.

BUGS
     A function	to remove individual attributes	from these lists does not ap-
     pear to exist.  A program desiring	to do that might have to manually it-
     erate the fields auth_attr	and unauth_attr	of si, which are both of type
     STACK_OF(X509_ATTRIBUTE), using the facilities described in STACK_OF(3)
     and OPENSSL_sk_new(3).

FreeBSD	13.0			 June 10, 2020			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | STANDARDS | HISTORY | CAVEATS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PKCS7_add_attribute&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help