Describe X509 constification and ASN1_STRING changes

In a CHANGES.md entry and in ossl-guide-migration, to
cover the constification of the X509 related functions and
the change to ASN1_STRING to be opaque.

Fixes: #30060

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Norbert Pocs <norbertp@openssl.org>
MergeDate: Fri Feb 27 18:45:47 2026
(Merged from https://github.com/openssl/openssl/pull/30165)

CHANGES.md

@@ -248,9 +248,17 @@ OpenSSL 4.0
 
    *Alexandr Nedvedicky*
 
- * The `X509_verify()` function now takes a `const X509 *` argument
+ * Many functions accepting X509 \* arguments, or returning values
+   from a const X509 \* have been changed to take / return const
+   arguments. The most visible changes are places where pointer values
+   are returned from a const X509 \* object. In many places where
+   these were non const values being returned from a const object,
+   these pointer values have now been made const. The goal of this
+   change is to enable future improvements in X.509 certificate
+   handling. For full details see the relevant section in
+   ossl-migration-guide(7).
 
-   * Bob Beck *
+   *Bob Beck*
 
  * The crypto-mdebug-backtrace configuration option has been entirely removed.
    The option has been a no-op since 1.0.2.

doc/man7/ossl-guide-migration.pod

@@ -48,6 +48,134 @@ an ASN1_BIT_STRING type, instead of direct flag and structure manipulation.
 
 =head2 Upgrading from OpenSSL 3.x
 
+=head3 The B<ASN1_STRING> type is now opaque
+
+B<ASN1_STRING> is the basis for many types in OpenSSL. Since OpenSSL 1.1.1
+accessor functions have been available to access and create B<ASN1_STRING>
+values of various types. See ASN1_STRING_type_new(3),
+ASN1_STRING_get0_data(3), ASN1_STRING_set(3) and ASN1_STRING_length(3).
+
+If your code uses direct access to B<ASN1_STRING> structure members you will
+need to convert it to allocate the correct type B<ASN1_STRING>, and use accessors.
+
+If your code has in the past used an B<ASN1_STRING> as a stack allocated
+object, you will need to allocate it from the heap with
+ASN1_STRING_new(3) or ASN1_STRING_type_new(3).
+
+The flags member of B<ASN1_STRING> has become inaccessible, and the definitions
+of the flags are no longer public. This includes the public definition
+of the flags:
+
+B<ASN1_STRING_FLAG_NDEF>
+B<ASN1_STRING_FLAG_CONT>
+B<ASN1_STRING_FLAG_MSTRING>
+B<ASN1_STRING_FLAG_EMBED>
+B<ASN1_STRING_FLAG_BITS_LEFT>
+
+For the first four values, these were internal use flags which were never
+user settable in a way that would not cause things to break.
+
+The final flag was used to indicate that an B<ASN1_BIT_STRING> has a
+value of unused bits left - Most applications do not touch this.  You
+should not use ASN1_STRING_set() to set the value of an
+B<ASN1_BIT_STRING> that may have unused bits on the end.  To ensure
+the number of unused bits is correctly set in an B<ASN1_BIT_STRING>
+type, use the functions ASN1_BIT_STRING_set_bit(3) or
+ASN1_BIT_STRING_set1(3) to set the value of an B<ASN1_BIT_STRING>, and
+ensure that the number of unused bits is correctly set. The function
+ASN1_BIT_STRING_get_length(3) may be used to retrieve the length in
+bytes, and the number of unused bits of an B<ASN1_BIT_STRING>.
+
+=head3 Constification of B<X509> functions
+
+A large number of public API functions that access an B<X509> * object have
+been constified. This change has been made to allow for future improvements
+to the B<X509> layer to reduce the number of memory allocations and copies
+that are made. These changes can impact code which uses these functions if
+a returned pointer value which was not const in previous versions of OpenSSL
+has now been made const. When such a value is assigned to a non-const pointer
+variable you will get a compiler warning. .
+
+The returned values being const is an indication that you may not mutate these
+values safely.
+
+Typically, you will need to change any variables holding these values
+to be const. If for some reason you need to mutate the returned object, you should
+make a copy of the returned const object into a mutable non-const object,
+bearing in mind that your copy has no effect on the original B<X509> object itself.
+
+The following functions have had arguments / return values related to B<X509>
+constified. For full details see their relevant manual pages.
+
+NAME_CONSTRAINTS_check
+NAME_CONSTRAINTS_check_CN
+X509_add_cert
+X509_add_ext
+X509_alias_get0
+X509_build_chain
+X509_chain_check_suiteb
+X509_check_ca
+X509_check_email
+X509_check_host
+X509_check_ip
+X509_check_ip_asc
+X509_check_issued
+X509_check_purpose
+X509_check_trust
+X509_CRL_get0_by_cert
+X509_find_by_issuer_and_serial
+X509_find_by_subject
+X509_get_ext
+X509_get_extended_key_usage
+X509_get_extension_flags
+X509_get_key_usage
+X509_get_pathlen
+X509_get_proxy_pathlen
+X509_get_pubkey
+X509_get_pubkey_parameters
+X509_get_signature_info
+X509_get0_authority_issuer
+X509_get0_authority_key_id
+X509_get0_authority_serial
+X509_get0_pubkey
+X509_get0_reject_objects
+X509_get0_subject_key_id
+X509_get0_subject_key_id
+X509_get0_trust_objects
+X509_get1_email
+X509_get1_ocsp
+X509_issuer_and_serial_hash
+X509_issuer_name_hash
+X509_issuer_name_hash_old
+X509_keyid_get0
+X509_load_http
+X509_OBJECT_get0_X509
+X509_OBJECT_set1_X509
+X509_print_ex_fp
+X509_print_fp
+X509_REQ_get1_email
+X509_REQ_to_X509
+X509_self_signed
+X509_STORE_add_cert
+X509_STORE_CTX_get_current_cert
+X509_STORE_CTX_get0_cert
+X509_STORE_CTX_get0_current_issuer
+X509_STORE_CTX_get1_issuer
+X509_STORE_CTX_init
+X509_STORE_CTX_set_cert
+X509_subject_name_hash
+X509_subject_name_hash_old
+X509_to_X509_REQ
+X509_TRUST_add
+X509v3_addr_validate_resource_set
+X509v3_asid_validate_resource_set
+
+The following two functions we "un-constified" As they were documented as returning
+an explicitly mutable pointer from within an B<X509> object:
+
+X509_getm_notAfter
+X509_getm_notBefore
+
 =head3 Removal of atexit() usage
 
 libcrypto no longer arms OPENSSL_cleanup() function as atexit(3) handler.