From f1f0731ddf6cb31d62a2c0f406b009ae9817ed7f Mon Sep 17 00:00:00 2001 From: slontis Date: Wed, 8 Nov 2023 16:14:44 +1000 Subject: [PATCH] Add missing documentation for X509_ATTRIBUTE related functions. Partial fix for #8026 Reviewed-by: Tom Cosgrove Reviewed-by: Matt Caswell Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/22656) --- crypto/x509/x509_req.c | 2 +- doc/build.info | 24 +++ doc/man3/CMS_signed_get_attr.pod | 214 +++++++++++++++++++++++++ doc/man3/EVP_PKEY_get_attr.pod | 113 +++++++++++++ doc/man3/X509_ATTRIBUTE.pod | 263 +++++++++++++++++++++++++++++++ doc/man3/X509_REQ_get_attr.pod | 111 +++++++++++++ util/missingcrypto.txt | 58 ------- util/other.syms | 1 + 8 files changed, 727 insertions(+), 59 deletions(-) create mode 100644 doc/man3/CMS_signed_get_attr.pod create mode 100644 doc/man3/EVP_PKEY_get_attr.pod create mode 100644 doc/man3/X509_ATTRIBUTE.pod create mode 100644 doc/man3/X509_REQ_get_attr.pod diff --git a/crypto/x509/x509_req.c b/crypto/x509/x509_req.c index fa73b331a5..77de85dc5b 100644 --- a/crypto/x509/x509_req.c +++ b/crypto/x509/x509_req.c @@ -202,7 +202,7 @@ X509_ATTRIBUTE *X509_REQ_delete_attr(X509_REQ *req, int loc) if (req == NULL) { ERR_raise(ERR_LIB_X509, ERR_R_PASSED_NULL_PARAMETER); - return 0; + return NULL; } attr = X509at_delete_attr(req->req_info.attributes, loc); if (attr != NULL) diff --git a/doc/build.info b/doc/build.info index aec4ae616f..c88399a138 100644 --- a/doc/build.info +++ b/doc/build.info @@ -855,6 +855,10 @@ DEPEND[html/man3/CMS_sign_receipt.html]=man3/CMS_sign_receipt.pod GENERATE[html/man3/CMS_sign_receipt.html]=man3/CMS_sign_receipt.pod DEPEND[man/man3/CMS_sign_receipt.3]=man3/CMS_sign_receipt.pod GENERATE[man/man3/CMS_sign_receipt.3]=man3/CMS_sign_receipt.pod +DEPEND[html/man3/CMS_signed_get_attr.html]=man3/CMS_signed_get_attr.pod +GENERATE[html/man3/CMS_signed_get_attr.html]=man3/CMS_signed_get_attr.pod +DEPEND[man/man3/CMS_signed_get_attr.3]=man3/CMS_signed_get_attr.pod +GENERATE[man/man3/CMS_signed_get_attr.3]=man3/CMS_signed_get_attr.pod DEPEND[html/man3/CMS_uncompress.html]=man3/CMS_uncompress.pod GENERATE[html/man3/CMS_uncompress.html]=man3/CMS_uncompress.pod DEPEND[man/man3/CMS_uncompress.3]=man3/CMS_uncompress.pod @@ -1263,6 +1267,10 @@ DEPEND[html/man3/EVP_PKEY_fromdata.html]=man3/EVP_PKEY_fromdata.pod GENERATE[html/man3/EVP_PKEY_fromdata.html]=man3/EVP_PKEY_fromdata.pod DEPEND[man/man3/EVP_PKEY_fromdata.3]=man3/EVP_PKEY_fromdata.pod GENERATE[man/man3/EVP_PKEY_fromdata.3]=man3/EVP_PKEY_fromdata.pod +DEPEND[html/man3/EVP_PKEY_get_attr.html]=man3/EVP_PKEY_get_attr.pod +GENERATE[html/man3/EVP_PKEY_get_attr.html]=man3/EVP_PKEY_get_attr.pod +DEPEND[man/man3/EVP_PKEY_get_attr.3]=man3/EVP_PKEY_get_attr.pod +GENERATE[man/man3/EVP_PKEY_get_attr.3]=man3/EVP_PKEY_get_attr.pod DEPEND[html/man3/EVP_PKEY_get_default_digest_nid.html]=man3/EVP_PKEY_get_default_digest_nid.pod GENERATE[html/man3/EVP_PKEY_get_default_digest_nid.html]=man3/EVP_PKEY_get_default_digest_nid.pod DEPEND[man/man3/EVP_PKEY_get_default_digest_nid.3]=man3/EVP_PKEY_get_default_digest_nid.pod @@ -2787,6 +2795,10 @@ DEPEND[html/man3/X509_ALGOR_dup.html]=man3/X509_ALGOR_dup.pod GENERATE[html/man3/X509_ALGOR_dup.html]=man3/X509_ALGOR_dup.pod DEPEND[man/man3/X509_ALGOR_dup.3]=man3/X509_ALGOR_dup.pod GENERATE[man/man3/X509_ALGOR_dup.3]=man3/X509_ALGOR_dup.pod +DEPEND[html/man3/X509_ATTRIBUTE.html]=man3/X509_ATTRIBUTE.pod +GENERATE[html/man3/X509_ATTRIBUTE.html]=man3/X509_ATTRIBUTE.pod +DEPEND[man/man3/X509_ATTRIBUTE.3]=man3/X509_ATTRIBUTE.pod +GENERATE[man/man3/X509_ATTRIBUTE.3]=man3/X509_ATTRIBUTE.pod DEPEND[html/man3/X509_CRL_get0_by_serial.html]=man3/X509_CRL_get0_by_serial.pod GENERATE[html/man3/X509_CRL_get0_by_serial.html]=man3/X509_CRL_get0_by_serial.pod DEPEND[man/man3/X509_CRL_get0_by_serial.3]=man3/X509_CRL_get0_by_serial.pod @@ -2831,6 +2843,10 @@ DEPEND[html/man3/X509_PUBKEY_new.html]=man3/X509_PUBKEY_new.pod GENERATE[html/man3/X509_PUBKEY_new.html]=man3/X509_PUBKEY_new.pod DEPEND[man/man3/X509_PUBKEY_new.3]=man3/X509_PUBKEY_new.pod GENERATE[man/man3/X509_PUBKEY_new.3]=man3/X509_PUBKEY_new.pod +DEPEND[html/man3/X509_REQ_get_attr.html]=man3/X509_REQ_get_attr.pod +GENERATE[html/man3/X509_REQ_get_attr.html]=man3/X509_REQ_get_attr.pod +DEPEND[man/man3/X509_REQ_get_attr.3]=man3/X509_REQ_get_attr.pod +GENERATE[man/man3/X509_REQ_get_attr.3]=man3/X509_REQ_get_attr.pod DEPEND[html/man3/X509_REQ_get_extensions.html]=man3/X509_REQ_get_extensions.pod GENERATE[html/man3/X509_REQ_get_extensions.html]=man3/X509_REQ_get_extensions.pod DEPEND[man/man3/X509_REQ_get_extensions.3]=man3/X509_REQ_get_extensions.pod @@ -3121,6 +3137,7 @@ html/man3/CMS_get0_type.html \ html/man3/CMS_get1_ReceiptRequest.html \ html/man3/CMS_sign.html \ html/man3/CMS_sign_receipt.html \ +html/man3/CMS_signed_get_attr.html \ html/man3/CMS_uncompress.html \ html/man3/CMS_verify.html \ html/man3/CMS_verify_receipt.html \ @@ -3223,6 +3240,7 @@ html/man3/EVP_PKEY_digestsign_supports_digest.html \ html/man3/EVP_PKEY_encapsulate.html \ html/man3/EVP_PKEY_encrypt.html \ html/man3/EVP_PKEY_fromdata.html \ +html/man3/EVP_PKEY_get_attr.html \ html/man3/EVP_PKEY_get_default_digest_nid.html \ html/man3/EVP_PKEY_get_field_type.html \ html/man3/EVP_PKEY_get_group_name.html \ @@ -3604,6 +3622,7 @@ html/man3/UI_new.html \ html/man3/X509V3_get_d2i.html \ html/man3/X509V3_set_ctx.html \ html/man3/X509_ALGOR_dup.html \ +html/man3/X509_ATTRIBUTE.html \ html/man3/X509_CRL_get0_by_serial.html \ html/man3/X509_EXTENSION_set_object.html \ html/man3/X509_LOOKUP.html \ @@ -3615,6 +3634,7 @@ html/man3/X509_NAME_get0_der.html \ html/man3/X509_NAME_get_index_by_NID.html \ html/man3/X509_NAME_print_ex.html \ html/man3/X509_PUBKEY_new.html \ +html/man3/X509_REQ_get_attr.html \ html/man3/X509_REQ_get_extensions.html \ html/man3/X509_SIG_get0.html \ html/man3/X509_STORE_CTX_get_by_subject.html \ @@ -3760,6 +3780,7 @@ man/man3/CMS_get0_type.3 \ man/man3/CMS_get1_ReceiptRequest.3 \ man/man3/CMS_sign.3 \ man/man3/CMS_sign_receipt.3 \ +man/man3/CMS_signed_get_attr.3 \ man/man3/CMS_uncompress.3 \ man/man3/CMS_verify.3 \ man/man3/CMS_verify_receipt.3 \ @@ -3862,6 +3883,7 @@ man/man3/EVP_PKEY_digestsign_supports_digest.3 \ man/man3/EVP_PKEY_encapsulate.3 \ man/man3/EVP_PKEY_encrypt.3 \ man/man3/EVP_PKEY_fromdata.3 \ +man/man3/EVP_PKEY_get_attr.3 \ man/man3/EVP_PKEY_get_default_digest_nid.3 \ man/man3/EVP_PKEY_get_field_type.3 \ man/man3/EVP_PKEY_get_group_name.3 \ @@ -4243,6 +4265,7 @@ man/man3/UI_new.3 \ man/man3/X509V3_get_d2i.3 \ man/man3/X509V3_set_ctx.3 \ man/man3/X509_ALGOR_dup.3 \ +man/man3/X509_ATTRIBUTE.3 \ man/man3/X509_CRL_get0_by_serial.3 \ man/man3/X509_EXTENSION_set_object.3 \ man/man3/X509_LOOKUP.3 \ @@ -4254,6 +4277,7 @@ man/man3/X509_NAME_get0_der.3 \ man/man3/X509_NAME_get_index_by_NID.3 \ man/man3/X509_NAME_print_ex.3 \ man/man3/X509_PUBKEY_new.3 \ +man/man3/X509_REQ_get_attr.3 \ man/man3/X509_REQ_get_extensions.3 \ man/man3/X509_SIG_get0.3 \ man/man3/X509_STORE_CTX_get_by_subject.3 \ diff --git a/doc/man3/CMS_signed_get_attr.pod b/doc/man3/CMS_signed_get_attr.pod new file mode 100644 index 0000000000..833cfc441b --- /dev/null +++ b/doc/man3/CMS_signed_get_attr.pod @@ -0,0 +1,214 @@ +=pod + +=head1 NAME + +CMS_signed_get_attr_count, +CMS_signed_get_attr_by_NID, CMS_signed_get_attr_by_OBJ, CMS_signed_get_attr, +CMS_signed_delete_attr, +CMS_signed_add1_attr, CMS_signed_add1_attr_by_OBJ, +CMS_signed_add1_attr_by_NID, CMS_signed_add1_attr_by_txt, +CMS_signed_get0_data_by_OBJ, +CMS_unsigned_get_attr_count, +CMS_unsigned_get_attr_by_NID, CMS_unsigned_get_attr_by_OBJ, +CMS_unsigned_get_attr, CMS_unsigned_delete_attr, +CMS_unsigned_add1_attr, CMS_unsigned_add1_attr_by_OBJ, +CMS_unsigned_add1_attr_by_NID, CMS_unsigned_add1_attr_by_txt, +CMS_unsigned_get0_data_by_OBJ +- CMS signed and unsigned attribute functions + +=head1 SYNOPSIS + + #include + + int CMS_signed_get_attr_count(const CMS_SignerInfo *si); + int CMS_signed_get_attr_by_NID(const CMS_SignerInfo *si, int nid, + int lastpos); + int CMS_signed_get_attr_by_OBJ(const CMS_SignerInfo *si, const ASN1_OBJECT *obj, + int lastpos); + X509_ATTRIBUTE *CMS_signed_get_attr(const CMS_SignerInfo *si, int loc); + X509_ATTRIBUTE *CMS_signed_delete_attr(CMS_SignerInfo *si, int loc); + int CMS_signed_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr); + int CMS_signed_add1_attr_by_OBJ(CMS_SignerInfo *si, + const ASN1_OBJECT *obj, int type, + const void *bytes, int len); + int CMS_signed_add1_attr_by_NID(CMS_SignerInfo *si, + int nid, int type, + const void *bytes, int len); + int CMS_signed_add1_attr_by_txt(CMS_SignerInfo *si, + const char *attrname, int type, + const void *bytes, int len); + void *CMS_signed_get0_data_by_OBJ(const CMS_SignerInfo *si, + const ASN1_OBJECT *oid, + int lastpos, int type); + + int CMS_unsigned_get_attr_count(const CMS_SignerInfo *si); + int CMS_unsigned_get_attr_by_NID(const CMS_SignerInfo *si, int nid, + int lastpos); + int CMS_unsigned_get_attr_by_OBJ(const CMS_SignerInfo *si, + const ASN1_OBJECT *obj, int lastpos); + X509_ATTRIBUTE *CMS_unsigned_get_attr(const CMS_SignerInfo *si, int loc); + X509_ATTRIBUTE *CMS_unsigned_delete_attr(CMS_SignerInfo *si, int loc); + int CMS_unsigned_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr); + int CMS_unsigned_add1_attr_by_OBJ(CMS_SignerInfo *si, + const ASN1_OBJECT *obj, int type, + const void *bytes, int len); + int CMS_unsigned_add1_attr_by_NID(CMS_SignerInfo *si, + int nid, int type, + const void *bytes, int len); + int CMS_unsigned_add1_attr_by_txt(CMS_SignerInfo *si, + const char *attrname, int type, + const void *bytes, int len); + void *CMS_unsigned_get0_data_by_OBJ(CMS_SignerInfo *si, ASN1_OBJECT *oid, + int lastpos, int type); + +=head1 DESCRIPTION + +CMS_signerInfo contains separate attribute lists for signed and unsigned +attributes. Each CMS_signed_XXX() function is used for signed attributes, and +each CMS_unsigned_XXX() function is used for unsigned attributes. +Since the CMS_unsigned_XXX() functions work in the same way as the +CMS_signed_XXX() equivalents, only the CMS_signed_XXX() functions are +described below. + +CMS_signed_get_attr_by_OBJ() finds the location of the first matching object +I in the SignerInfo's I signed attribute list. The search starts at the +position after I. If the returned value is positive then it can be used +on the next call to CMS_signed_get_attr_by_OBJ() as the value of I in +order to iterate through the remaining attributes. I can be set to any +negative value on the first call, in order to start searching from the start of +the signed attribute list. + +CMS_signed_get_attr_by_NID() is similar to CMS_signed_get_attr_by_OBJ() except +that it passes the numerical identifier (NID) I associated with the object. +See for a list of NID_*. + +CMS_signed_get_attr() returns the B object at index I in the +I signed attribute list. I should be in the range from 0 to +CMS_signed_get_attr_count() - 1. + +CMS_signed_delete_attr() removes the B object at index I in +the I signed attribute list. An error occurs if the I attribute list +is NULL. + +CMS_signed_add1_attr() pushes a copy of the passed in B object +to the I signed attribute list. A new signed attribute list is created if +required. An error occurs if I is NULL. + +CMS_signed_add1_attr_by_OBJ() creates a new signed B using +X509_ATTRIBUTE_set1_object() and X509_ATTRIBUTE_set1_data() to assign a new +I with type I and data I of length I and then pushes it +to the I object's attribute list. + +CMS_signed_add1_attr_by_NID() is similar to CMS_signed_add1_attr_by_OBJ() except +that it passes the numerical identifier (NID) I associated with the object. +See for a list of NID_*. + +CMS_signed_add1_attr_by_txt() is similar to CMS_signed_add1_attr_by_OBJ() +except that it passes a name I associated with the object. +See for a list of SN_* names. + +CMS_signed_get0_data_by_OBJ() finds the first attribute in a I signed +attributes list that matches the I starting at index I +and returns the data retrieved from the found attributes first B +object. An error will occur if the attribute type I does not match the +type of the B object OR if I is either B or +B OR the attribute is not found. +If I is less than -1 then an error will occur if there are multiple +objects in the signed attribute list that match I. +If I is less than -2 then an error will occur if there is more than +one B object in the found signed attribute. + +Refer to L for information related to attributes. + +=head1 RETURN VALUES + +The CMS_unsigned_XXX() functions return values are similar to those of the +equivalent CMS_signed_XXX() functions. + +CMS_signed_get_attr_count() returns the number of signed attributes in the +SignerInfo I, or -1 if the signed attribute list is NULL. + +CMS_signed_get_attr_by_OBJ() returns -1 if either the signed attribute list of +I is empty OR if I is not found, otherwise it returns the location of +the I in the SignerInfo's I signed attribute list. + +CMS_signed_get_attr_by_NID() is similar to CMS_signed_get_attr_by_OBJ() except +that it returns -2 if the I is not known by OpenSSL. + +CMS_signed_get_attr() returns either a signed B or NULL on error. + +CMS_signed_delete_attr() returns either the removed signed B or +NULL if there is a error. + +CMS_signed_add1_attr(), CMS_signed_add1_attr_by_OBJ(), +CMS_signed_add1_attr_by_NID(), CMS_signed_add1_attr_by_txt(), +return 1 on success or 0 on error. + +CMS_signed_get0_data_by_OBJ() returns the data retrieved from the found +signed attributes first B object, or NULL if an error occurs. + +=head1 NOTES + +Some attributes are added automatically during the signing process. + +Calling CMS_SignerInfo_sign() adds the NID_pkcs9_signingTime signed +attribute. + +Calling CMS_final(), CMS_final_digest() or CMS_dataFinal() adds the +NID_pkcs9_messageDigest signed attribute. + +The NID_pkcs9_contentType signed attribute is always added if the +NID_pkcs9_signingTime attribute is added. + +Calling CMS_sign_ex(), CMS_sign_receipt() or CMS_add1_signer() may add +attributes depending on the flags parameter. See L for +more information. + +OpenSSL applies special rules for the following attribute NIDs: + +=over 4 + +=item CMS Signed Attributes + +NID_pkcs9_contentType +NID_pkcs9_messageDigest +NID_pkcs9_signingTime + +=item ESS Signed Attributes + +NID_id_smime_aa_signingCertificate +NID_id_smime_aa_signingCertificateV2 +NID_id_smime_aa_receiptRequest + +=item CMS Unsigned Attributes + +NID_pkcs9_countersignature + +=back + +CMS_signed_add1_attr(), CMS_signed_add1_attr_by_OBJ(), +CMS_signed_add1_attr_by_NID(), CMS_signed_add1_attr_by_txt() +and the equivalent CMS_unsigned_add1_attrXXX() functions allow +duplicate attributes to be added. The attribute rules are not checked +during these function calls, and are deferred until the sign or verify process +(i.e. during calls to any of CMS_sign_ex(), CMS_sign(), CMS_sign_receipt(), +CMS_add1_signer(), CMS_Final(), CMS_dataFinal(), CMS_final_digest(), +CMS_verify(), CMS_verify_receipt() or CMS_SignedData_verify()). + +For CMS attribute rules see RFC 5652 Section 11. +For ESS attribute rules see RFC 2634 Section 1.3.4 and RFC 5035 Section 5.4. + +=head1 SEE ALSO + +L + +=head1 COPYRIGHT + +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man3/EVP_PKEY_get_attr.pod b/doc/man3/EVP_PKEY_get_attr.pod new file mode 100644 index 0000000000..101677422c --- /dev/null +++ b/doc/man3/EVP_PKEY_get_attr.pod @@ -0,0 +1,113 @@ +=pod + +=head1 NAME + +EVP_PKEY_get_attr, +EVP_PKEY_get_attr_count, +EVP_PKEY_get_attr_by_NID, EVP_PKEY_get_attr_by_OBJ, +EVP_PKEY_delete_attr, +EVP_PKEY_add1_attr, +EVP_PKEY_add1_attr_by_OBJ, EVP_PKEY_add1_attr_by_NID, EVP_PKEY_add1_attr_by_txt +- EVP_PKEY B functions + +=head1 SYNOPSIS + + #include + + int EVP_PKEY_get_attr_count(const EVP_PKEY *key); + int EVP_PKEY_get_attr_by_NID(const EVP_PKEY *key, int nid, int lastpos); + int EVP_PKEY_get_attr_by_OBJ(const EVP_PKEY *key, const ASN1_OBJECT *obj, + int lastpos); + X509_ATTRIBUTE *EVP_PKEY_get_attr(const EVP_PKEY *key, int loc); + X509_ATTRIBUTE *EVP_PKEY_delete_attr(EVP_PKEY *key, int loc); + int EVP_PKEY_add1_attr(EVP_PKEY *key, X509_ATTRIBUTE *attr); + int EVP_PKEY_add1_attr_by_OBJ(EVP_PKEY *key, + const ASN1_OBJECT *obj, int type, + const unsigned char *bytes, int len); + int EVP_PKEY_add1_attr_by_NID(EVP_PKEY *key, + int nid, int type, + const unsigned char *bytes, int len); + int EVP_PKEY_add1_attr_by_txt(EVP_PKEY *key, + const char *attrname, int type, + const unsigned char *bytes, int len); + +=head1 DESCRIPTION + +These functions are used by B. + +EVP_PKEY_get_attr_by_OBJ() finds the location of the first matching object I +in the I attribute list. The search starts at the position after I. +If the returned value is positive then it can be used on the next call to +EVP_PKEY_get_attr_by_OBJ() as the value of I in order to iterate through +the remaining attributes. I can be set to any negative value on the +first call, in order to start searching from the start of the attribute list. + +EVP_PKEY_get_attr_by_NID() is similar to EVP_PKEY_get_attr_by_OBJ() except that +it passes the numerical identifier (NID) I associated with the object. +See for a list of NID_*. + +EVP_PKEY_get_attr() returns the B object at index I in the +I attribute list. I should be in the range from 0 to +EVP_PKEY_get_attr_count() - 1. + +EVP_PKEY_delete_attr() removes the B object at index I in +the I attribute list. + +EVP_PKEY_add1_attr() pushes a copy of the passed in B object +to the I attribute list. A new I attribute list is created if required. +An error occurs if either I is NULL, or the attribute already exists. + +EVP_PKEY_add1_attr_by_OBJ() creates a new B using +X509_ATTRIBUTE_set1_object() and X509_ATTRIBUTE_set1_data() to assign a new +I with type I and data I of length I and then pushes it +to the I object's attribute list. If I already exists in the attribute +list then an error occurs. + +EVP_PKEY_add1_attr_by_NID() is similar to EVP_PKEY_add1_attr_by_OBJ() except +that it passes the numerical identifier (NID) I associated with the object. +See for a list of NID_*. + +EVP_PKEY_add1_attr_by_txt() is similar to EVP_PKEY_add1_attr_by_OBJ() except +that it passes a name I associated with the object. +See for a list of SN_* names. + +=head1 RETURN VALUES + +EVP_PKEY_get_attr_count() returns the number of attributes in the I object +attribute list or -1 if the attribute list is NULL. + +EVP_PKEY_get_attr_by_OBJ() returns -1 if either the list is empty OR the object +is not found, otherwise it returns the location of the object in the list. + +EVP_PKEY_get_attr_by_NID() is similar to EVP_PKEY_get_attr_by_OBJ(), except that +it returns -2 if the I is not known by OpenSSL. + +EVP_PKEY_get_attr() returns either a B or NULL if there is a +error. + +EVP_PKEY_delete_attr() returns either the removed B or NULL if +there is a error. + +EVP_PKEY_add1_attr(), EVP_PKEY_add1_attr_by_OBJ(), EVP_PKEY_add1_attr_by_NID() +and EVP_PKEY_add1_attr_by_txt() return 1 on success or 0 otherwise. + +=head1 NOTES + +A B object's attribute list is initially NULL. All the above functions +listed will return an error unless EVP_PKEY_add1_attr() is called. +All functions listed assume that the I is not NULL. + +=head1 SEE ALSO + +L + +=head1 COPYRIGHT + +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man3/X509_ATTRIBUTE.pod b/doc/man3/X509_ATTRIBUTE.pod new file mode 100644 index 0000000000..1eacf3ee3d --- /dev/null +++ b/doc/man3/X509_ATTRIBUTE.pod @@ -0,0 +1,263 @@ +=pod + +=head1 NAME + +X509_ATTRIBUTE, X509at_get_attr, +X509at_get_attr_count, X509at_get_attr_by_NID, X509at_get_attr_by_OBJ, +X509at_delete_attr, +X509at_add1_attr, +X509at_add1_attr_by_OBJ, X509at_add1_attr_by_NID, X509at_add1_attr_by_txt, +X509at_get0_data_by_OBJ, +X509_ATTRIBUTE_create, X509_ATTRIBUTE_create_by_NID, +X509_ATTRIBUTE_create_by_OBJ, X509_ATTRIBUTE_create_by_txt, +X509_ATTRIBUTE_set1_object, X509_ATTRIBUTE_set1_data, +X509_ATTRIBUTE_count, +X509_ATTRIBUTE_get0_data, X509_ATTRIBUTE_get0_object, X509_ATTRIBUTE_get0_type +- X509 attribute functions + +=head1 SYNOPSIS + + #include + + typedef struct x509_attributes_st X509_ATTRIBUTE; + + int X509at_get_attr_count(const STACK_OF(X509_ATTRIBUTE) *x); + int X509at_get_attr_by_NID(const STACK_OF(X509_ATTRIBUTE) *x, int nid, + int lastpos); + int X509at_get_attr_by_OBJ(const STACK_OF(X509_ATTRIBUTE) *sk, + const ASN1_OBJECT *obj, int lastpos); + X509_ATTRIBUTE *X509at_get_attr(const STACK_OF(X509_ATTRIBUTE) *x, int loc); + X509_ATTRIBUTE *X509at_delete_attr(STACK_OF(X509_ATTRIBUTE) *x, int loc); + STACK_OF(X509_ATTRIBUTE) *X509at_add1_attr(STACK_OF(X509_ATTRIBUTE) **x, + X509_ATTRIBUTE *attr); + STACK_OF(X509_ATTRIBUTE) *X509at_add1_attr_by_OBJ(STACK_OF(X509_ATTRIBUTE) + **x, const ASN1_OBJECT *obj, + int type, + const unsigned char *bytes, + int len); + STACK_OF(X509_ATTRIBUTE) *X509at_add1_attr_by_NID(STACK_OF(X509_ATTRIBUTE) + **x, int nid, int type, + const unsigned char *bytes, + int len); + STACK_OF(X509_ATTRIBUTE) *X509at_add1_attr_by_txt(STACK_OF(X509_ATTRIBUTE) + **x, const char *attrname, + int type, + const unsigned char *bytes, + int len); + void *X509at_get0_data_by_OBJ(const STACK_OF(X509_ATTRIBUTE) *x, + const ASN1_OBJECT *obj, int lastpos, int type); + X509_ATTRIBUTE *X509_ATTRIBUTE_create(int nid, int atrtype, void *value); + X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_NID(X509_ATTRIBUTE **attr, int nid, + int atrtype, const void *data, + int len); + X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_OBJ(X509_ATTRIBUTE **attr, + const ASN1_OBJECT *obj, + int atrtype, const void *data, + int len); + X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_txt(X509_ATTRIBUTE **attr, + const char *atrname, int type, + const unsigned char *bytes, + int len); + int X509_ATTRIBUTE_set1_object(X509_ATTRIBUTE *attr, const ASN1_OBJECT *obj); + int X509_ATTRIBUTE_set1_data(X509_ATTRIBUTE *attr, int attrtype, + const void *data, int len); + void *X509_ATTRIBUTE_get0_data(X509_ATTRIBUTE *attr, int idx, int atrtype, + void *data); + int X509_ATTRIBUTE_count(const X509_ATTRIBUTE *attr); + ASN1_OBJECT *X509_ATTRIBUTE_get0_object(X509_ATTRIBUTE *attr); + ASN1_TYPE *X509_ATTRIBUTE_get0_type(X509_ATTRIBUTE *attr, int idx); + +=head1 DESCRIPTION + +B objects are used by many standards including X509, X509_REQ, +PKCS12, PKCS8, PKCS7 and CMS. + +The B object is used to represent the ASN.1 Attribute as defined +in RFC 5280, i.e. + + Attribute ::= SEQUENCE { + type AttributeType, + values SET OF AttributeValue } + + AttributeType ::= OBJECT IDENTIFIER + AttributeValue ::= ANY -- DEFINED BY AttributeType + +For example CMS defines the signing-time attribute as: + + id-signingTime OBJECT IDENTIFIER ::= { iso(1) member-body(2) + us(840) rsadsi(113549) pkcs(1) pkcs9(9) 5 } + + SigningTime ::= Time + + Time ::= CHOICE { + utcTime UTCTime, + generalizedTime GeneralizedTime } + +In OpenSSL B maps to an B object +and B maps to a list of B objects. + +The following functions are used for B objects. + +X509at_get_attr_by_OBJ() finds the location of the first matching object I +in a list of attributes I. The search starts at the position after I. +If the returned value is positive then it can be used on the next call to +X509at_get_attr_by_OBJ() as the value of I in order to iterate through +the remaining attributes. I can be set to any negative value on the +first call, in order to start searching from the start of the list. + +X509at_get_attr_by_NID() is similar to X509at_get_attr_by_OBJ() except that it +passes the numerical identifier (NID) I associated with the object. +See for a list of NID_*. + +X509at_get_attr() returns the B object at index I in the +list of attributes I. I should be in the range from 0 to +X509at_get_attr_count() - 1. + +X509at_delete_attr() removes the B object at index I in +the list of attributes I. + +X509at_add1_attr() pushes a copy of the passed in B object +to the list I. +Both I and I must be non NULL or an error will occur. +If I<*x> is NULL then a new list is created, otherwise it uses the +passed in list. An error will occur if an existing attribute (with the same +attribute type) already exists in the attribute list. + +X509at_add1_attr_by_OBJ() creates a new B using +X509_ATTRIBUTE_set1_object() and X509_ATTRIBUTE_set1_data() to assign a new +I with type I and data I of length I and then pushes it +to the attribute list I. Both I and I must be non NULL or an error +will occur. If I<*x> is NULL then a new attribute list is created. If I +already exists in the attribute list then an error occurs. + +X509at_add1_attr_by_NID() is similar to X509at_add1_attr_by_OBJ() except that it +passes the numerical identifier (NID) I associated with the object. +See for a list of NID_*. + +X509at_add1_attr_by_txt() is similar to X509at_add1_attr_by_OBJ() except that it +passes a name I associated with the object. +See for a list of SN_* names. + +X509_ATTRIBUTE_set1_object() assigns a B I +to the attribute I. If I contained an existing B then +it is freed. An error occurs if either I or I are NULL, or if +the passed in I cannot be duplicated. + +X509_ATTRIBUTE_set1_data() pushes a new B object onto the I +attributes list. The new object is assigned a copy of the data in I of +size I. +If I has flag I set then a table lookup using the +I attributes NID is used to set an B using +ASN1_STRING_set_by_NID(), and the passed in I must be in the format +required for that object type or an error will occur. +If I is not -1 then internally ASN1_STRING_type_new() is +used with the passed in I. +If I is 0 the call does nothing except return 1. + +X509_ATTRIBUTE_create() creates a new B using the I +to set the B OID and the I and I to set the +B. + +X509_ATTRIBUTE_create_by_OBJ() uses X509_ATTRIBUTE_set1_object() and +X509_ATTRIBUTE_set1_data() to assign a new I with type I and +data I of length I. If the passed in attribute I OR I<*attr> is +NULL then a new B will be returned, otherwise the passed in +B is used. Note that the ASN1_OBJECT I is pushed onto the +attributes existing list of objects, which could be an issue if the attributes + was different. + +X509_ATTRIBUTE_create_by_NID() is similar to X509_ATTRIBUTE_create_by_OBJ() +except that it passes the numerical identifier (NID) I associated with the +object. See for a list of NID_*. + +X509_ATTRIBUTE_create_by_txt() is similar to X509_ATTRIBUTE_create_by_OBJ() +except that it passes a name I associated with the +object. See for a list of SN_* names. + +X509_ATTRIBUTE_count() returns the number of B objects in an +attribute I. + +X509_ATTRIBUTE_get0_type() returns the B object at index I in +the attribute list I. I should be in the +range of 0 to X509_ATTRIBUTE_count() - 1 or an error will occur. + +X509_ATTRIBUTE_get0_data() returns the data of an B object at +index I in the attribute I. I is unused and can be set to NULL. +An error will occur if the attribute type I does not match the type of +the B object at index I OR if I is either +B or B OR if the I is not in the +range 0 to X509_ATTRIBUTE_count() - 1. + +X509at_get0_data_by_OBJ() finds the first attribute in an attribute list I +that matches the I starting at index I and returns the data +retrieved from the found attributes first B object. An error will +occur if the attribute type I does not match the type of the B +object OR if I is either B or B OR the +attribute is not found. +If I is less than -1 then an error will occur if there are multiple +objects in the list I that match I. +If I is less than -2 then an error will occur if there is more than +one B object in the found attribute. + +=head1 RETURN VALUES + +X509at_get_attr_count() returns the number of attributes in the list I or -1 +if I is NULL. + +X509at_get_attr_by_OBJ() returns -1 if either the list is empty OR the object +is not found, otherwise it returns the location of the object in the list. + +X509at_get_attr_by_NID() is similar to X509at_get_attr_by_OBJ(), except that +it returns -2 if the I is not known by OpenSSL. + +X509at_get_attr() returns either an B or NULL if there is a error. + +X509at_delete_attr() returns either the removed B or NULL if +there is a error. + +X509_ATTRIBUTE_count() returns -1 on error, otherwise it returns the number +of B elements. + +X509_ATTRIBUTE_get0_type() returns NULL on error, otherwise it returns a +B object. + +X509_ATTRIBUTE_get0_data() returns NULL if an error occurs, +otherwise it returns the data associated with an B object. + +X509_ATTRIBUTE_set1_object() and X509_ATTRIBUTE_set1_data() returns 1 on +success, or 0 otherwise. + +X509_ATTRIBUTE_create(), X509_ATTRIBUTE_create_by_OBJ(), +X509_ATTRIBUTE_create_by_NID() and X509_ATTRIBUTE_create_by_txt() return either +a B on success, or NULL if there is a error. + +X509at_add1_attr(), X509at_add1_attr_by_OBJ(), X509at_add1_attr_by_NID() and +X509at_add1_attr_by_txt() return NULL on error, otherwise they return a list +of B. + +X509at_get0_data_by_OBJ() returns the data retrieved from the found attributes +first B object, or NULL if an error occurs. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, + +=head1 COPYRIGHT + +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man3/X509_REQ_get_attr.pod b/doc/man3/X509_REQ_get_attr.pod new file mode 100644 index 0000000000..a85d8399b0 --- /dev/null +++ b/doc/man3/X509_REQ_get_attr.pod @@ -0,0 +1,111 @@ +=pod + +=head1 NAME + +X509_REQ_get_attr_count, +X509_REQ_get_attr_by_NID, X509_REQ_get_attr_by_OBJ, X509_REQ_get_attr, +X509_REQ_delete_attr, +X509_REQ_add1_attr, X509_REQ_add1_attr_by_OBJ, X509_REQ_add1_attr_by_NID, +X509_REQ_add1_attr_by_txt +- B support for signed certificate requests + +=head1 SYNOPSIS + + #include + + int X509_REQ_get_attr_count(const X509_REQ *req); + int X509_REQ_get_attr_by_NID(const X509_REQ *req, int nid, int lastpos); + int X509_REQ_get_attr_by_OBJ(const X509_REQ *req, const ASN1_OBJECT *obj, + int lastpos); + X509_ATTRIBUTE *X509_REQ_get_attr(const X509_REQ *req, int loc); + X509_ATTRIBUTE *X509_REQ_delete_attr(X509_REQ *req, int loc); + int X509_REQ_add1_attr(X509_REQ *req, X509_ATTRIBUTE *attr); + int X509_REQ_add1_attr_by_OBJ(X509_REQ *req, + const ASN1_OBJECT *obj, int type, + const unsigned char *bytes, int len); + int X509_REQ_add1_attr_by_NID(X509_REQ *req, + int nid, int type, + const unsigned char *bytes, int len); + int X509_REQ_add1_attr_by_txt(X509_REQ *req, + const char *attrname, int type, + const unsigned char *bytes, int len); + +=head1 DESCRIPTION + +X509_REQ_get_attr_by_OBJ() finds the location of the first matching object I +in the I attribute list. The search starts at the position after I. +If the returned value is positive then it can be used on the next call to +X509_REQ_get_attr_by_OBJ() as the value of I in order to iterate through +the remaining attributes. I can be set to any negative value on the +first call, in order to start searching from the start of the attribute list. + +X509_REQ_get_attr_by_NID() is similar to X509_REQ_get_attr_by_OBJ() except that +it passes the numerical identifier (NID) I associated with the object. +See for a list of NID_*. + +X509_REQ_get_attr() returns the B object at index I in the +I attribute list. I should be in the range from 0 to +X509_REQ_get_attr_count() - 1. + +X509_REQ_delete_attr() removes the B object at index I in +the I objects list of attributes. An error occurs if I is NULL. + +X509_REQ_add1_attr() pushes a copy of the passed in B I<>attr> +to the I object's attribute list. An error will occur if either the +attribute list is NULL or the attribute already exists. + +X509_REQ_add1_attr_by_OBJ() creates a new B using +X509_ATTRIBUTE_set1_object() and X509_ATTRIBUTE_set1_data() to assign a new +I with type I and data I of length I and then pushes it +to the I object's attribute list. I must be non NULL or an error +will occur. If I already exists in the attribute list then an error occurs. + +X509_REQ_add1_attr_by_NID() is similar to X509_REQ_add1_attr_by_OBJ() except +that it passes the numerical identifier (NID) I associated with the object. +See for a list of NID_*. + +X509_REQ_add1_attr_by_txt() is similar to X509_REQ_add1_attr_by_OBJ() except +that it passes a name I associated with the object. +See for a list of SN_* names. + +Refer to L for information related to attributes. + +=head1 RETURN VALUES + +X509_REQ_get_attr_count() returns the number of attributes in the I object +attribute list or -1 if the attribute list is NULL. + +X509_REQ_get_attr_by_OBJ() returns -1 if either the I object's attribute +list is empty OR I is not found, otherwise it returns the location of the +I in the attribute list. + +X509_REQ_get_attr_by_NID() is similar to X509_REQ_get_attr_by_OBJ(), except that +it returns -2 if the I is not known by OpenSSL. + +X509_REQ_get_attr() returns either an B or NULL on error. + +X509_REQ_delete_attr() returns either the removed B or NULL if +there is a error. + +X509_REQ_add1_attr(), X509_REQ_add1_attr_by_OBJ(), X509_REQ_add1_attr_by_NID() +and X509_REQ_add1_attr_by_txt() return 1 on success or 0 on error. + +=head1 NOTES + +Any functions that modify the attributes (add or delete) internally set a flag +to indicate the ASN.1 encoding has been modified. + +=head1 SEE ALSO + +L + +=head1 COPYRIGHT + +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt index d6906f6ddc..08231eddce 100644 --- a/util/missingcrypto.txt +++ b/util/missingcrypto.txt @@ -326,27 +326,7 @@ CMS_digest_verify(3) CMS_is_detached(3) CMS_set1_signers_certs(3) CMS_set_detached(3) -CMS_signed_add1_attr(3) -CMS_signed_add1_attr_by_NID(3) -CMS_signed_add1_attr_by_OBJ(3) -CMS_signed_add1_attr_by_txt(3) -CMS_signed_delete_attr(3) -CMS_signed_get0_data_by_OBJ(3) -CMS_signed_get_attr(3) -CMS_signed_get_attr_by_NID(3) -CMS_signed_get_attr_by_OBJ(3) -CMS_signed_get_attr_count(3) CMS_stream(3) -CMS_unsigned_add1_attr(3) -CMS_unsigned_add1_attr_by_NID(3) -CMS_unsigned_add1_attr_by_OBJ(3) -CMS_unsigned_add1_attr_by_txt(3) -CMS_unsigned_delete_attr(3) -CMS_unsigned_get0_data_by_OBJ(3) -CMS_unsigned_get_attr(3) -CMS_unsigned_get_attr_by_NID(3) -CMS_unsigned_get_attr_by_OBJ(3) -CMS_unsigned_get_attr_count(3) CONF_dump_bio(3) CONF_dump_fp(3) CONF_free(3) @@ -588,18 +568,9 @@ EVP_PKEY_CTX_hex2ctrl(3) EVP_PKEY_CTX_set0_keygen_info(3) EVP_PKEY_CTX_set_data(3) EVP_PKEY_CTX_str2ctrl(3) -EVP_PKEY_add1_attr(3) -EVP_PKEY_add1_attr_by_NID(3) -EVP_PKEY_add1_attr_by_OBJ(3) -EVP_PKEY_add1_attr_by_txt(3) EVP_PKEY_assign(3) EVP_PKEY_decrypt_old(3) -EVP_PKEY_delete_attr(3) EVP_PKEY_encrypt_old(3) -EVP_PKEY_get_attr(3) -EVP_PKEY_get_attr_by_NID(3) -EVP_PKEY_get_attr_by_OBJ(3) -EVP_PKEY_get_attr_count(3) EVP_PKEY_save_parameters(3) EVP_add_alg_module(3) EVP_add_cipher(3) @@ -1107,17 +1078,7 @@ X509V3_set_conf_lhash(3) X509V3_set_nconf(3) X509V3_string_free(3) X509_ALGORS_it(3) -X509_ATTRIBUTE_count(3) -X509_ATTRIBUTE_create(3) -X509_ATTRIBUTE_create_by_NID(3) -X509_ATTRIBUTE_create_by_OBJ(3) -X509_ATTRIBUTE_create_by_txt(3) -X509_ATTRIBUTE_get0_data(3) -X509_ATTRIBUTE_get0_object(3) -X509_ATTRIBUTE_get0_type(3) X509_ATTRIBUTE_it(3) -X509_ATTRIBUTE_set1_data(3) -X509_ATTRIBUTE_set1_object(3) X509_CERT_AUX_it(3) X509_CINF_it(3) X509_CRL_INFO_it(3) @@ -1169,17 +1130,8 @@ X509_PURPOSE_get_id(3) X509_PURPOSE_get_trust(3) X509_PURPOSE_set(3) X509_REQ_INFO_it(3) -X509_REQ_add1_attr(3) -X509_REQ_add1_attr_by_NID(3) -X509_REQ_add1_attr_by_OBJ(3) -X509_REQ_add1_attr_by_txt(3) -X509_REQ_delete_attr(3) X509_REQ_extension_nid(3) X509_REQ_get1_email(3) -X509_REQ_get_attr(3) -X509_REQ_get_attr_by_NID(3) -X509_REQ_get_attr_by_OBJ(3) -X509_REQ_get_attr_count(3) X509_REQ_get_extension_nids(3) X509_REQ_it(3) X509_REQ_print(3) @@ -1275,16 +1227,6 @@ X509_supported_extension(3) X509_to_X509_REQ(3) X509_trust_clear(3) X509_trusted(3) -X509at_add1_attr(3) -X509at_add1_attr_by_NID(3) -X509at_add1_attr_by_OBJ(3) -X509at_add1_attr_by_txt(3) -X509at_delete_attr(3) -X509at_get0_data_by_OBJ(3) -X509at_get_attr(3) -X509at_get_attr_by_NID(3) -X509at_get_attr_by_OBJ(3) -X509at_get_attr_count(3) X509v3_addr_add_inherit(3) X509v3_addr_add_prefix(3) X509v3_addr_add_range(3) diff --git a/util/other.syms b/util/other.syms index bf7eb8b22e..4a4cabb273 100644 --- a/util/other.syms +++ b/util/other.syms @@ -113,6 +113,7 @@ UI_METHOD datatype UI_STRING datatype UI_string_types datatype UI_string_types datatype +X509_ATTRIBUTE datatype X509_STORE_CTX_cert_crl_fn datatype X509_STORE_CTX_check_crl_fn datatype X509_STORE_CTX_check_issued_fn datatype