X509_CMP_TIME(3ossl)

✨ X509_CMP_TIME 💅

okay bestie, so this is a page from the OpenSSL manual — specifically the third section, the library-calls girlies. And it's all about the X509 time functions: X509_cmp_time, X509_cmp_current_time, X509_cmp_timeframe, X509_time_adj, X509_time_adj_ex, and X509_gmtime_adj. Yes that's six whole functions in one page, she's an overachiever, we love her for it. 🎀

---

🌸 SYNOPSIS 🌸

here's the receipts, exactly as written, no editing, no notes:

int X509_cmp_time(const ASN1_TIME *asn1_time, time_t *in_tm);
int X509_cmp_current_time(const ASN1_TIME *asn1_time);
int X509_cmp_timeframe(const X509_VERIFY_PARAM *vpm,
                       const ASN1_TIME *start, const ASN1_TIME *end);
ASN1_TIME *X509_time_adj(ASN1_TIME *asn1_time, long offset_sec, time_t *in_tm);
ASN1_TIME *X509_time_adj_ex(ASN1_TIME *asn1_time, int offset_day, long
                            offset_sec, time_t *in_tm);
ASN1_TIME *X509_gmtime_adj(ASN1_TIME *asn1_time, long offset_sec);

---

🦋 DESCRIPTION 🦋

okay so, three of these compare, three of these adjust. let's go one by one because there's lore here.

• X509_cmp_time() — compares the ASN1_TIME sitting in asn1_time against the time living in in_tm.
• X509_cmp_current_time() — compares the ASN1_TIME in asn1_time against the current time, expressed as a time_t.
• X509_cmp_timeframe() — compares the given time period against the reference time that's included in the verification parameters vpm — but only if vpm is not NULL and it contains X509_V_FLAG_USE_CHECK_TIME. otherwise? the current time gets used as the reference time instead. lowkey a whole conditional situation, but she's consistent. ✨

---

now the adjusting girlies:

• X509_time_adj_ex() — sets the ASN1_TIME structure asn1_time to the time that is offset_day and offset_sec after in_tm. two offsets, day AND sec, she's doing both, icon behaviour.
• X509_time_adj() — sets the ASN1_TIME structure asn1_time to the time offset_sec after in_tm. but bestie, listen: this method can only handle second offsets up to the capacity of long. so the newer X509_time_adj_ex() API should be preferred. ngl, the old one is giving legacy 💀

🫶 for both of those methods: if asn1_time is NULL, a new ASN1_TIME structure gets allocated and returned. you don't have to bring your own, she'll make one.

🫶 and in all of the methods on this page: if in_tm is NULL, the current time — expressed as time_t — is used. convenient fr fr.

asn1_time must satisfy the ASN1_TIME format mandated by RFC 5280, i.e., its format must be either YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ. no other shapes, she has a type. no cap.

• X509_gmtime_adj() — sets the ASN1_TIME structure asn1_time to the time offset_sec after the current time. it's literally equivalent to calling X509_time_adj() with the last parameter as NULL. same vibe, shorter name.

---

💀 BUGS 💀

🚨 okay this one's important and it's a little cursed: unlike many standard comparison functions, X509_cmp_time() and X509_cmp_current_time() return 0 on error. not -1, not 1, zero. so if you're out here treating the return value like a normal comparison result, the error case is gonna blend right in. watch out bestie, that's a trap 🙈

---

🔥 RETURN VALUES 🔥

let's do the receipts, one function at a time.

X509_cmp_time() and X509_cmp_current_time():

• return -1 if asn1_time is earlier than, or equal to, in_tm (resp. current time)
• return 1 otherwise
• and return 0 on error (yes, again, the bug note, it haunts us 😭)

X509_cmp_timeframe():

• returns 0 if vpm is not NULL and the verification parameters do not contain X509_V_FLAG_USE_CHECK_TIME but do contain X509_V_FLAG_NO_CHECK_TIME
• otherwise:
  • returns 1 if the end time is not NULL and the reference time (which has been determined as stated above 👆) is past the end time
  • returns -1 if the start time is not NULL and the reference time is before
  • else returns 0 to indicate that the reference time is in range — which implies that the end time is not before the start time if both are present

X509_time_adj(), X509_time_adj_ex() and X509_gmtime_adj():

• return a pointer to the updated ASN1_TIME structure
• and NULL on error. that's it, that's the contract. 💅

---

⭐ HISTORY ⭐

• X509_cmp_timeframe() was added in OpenSSL 3.0. so if you're on something older, that one's not coming to the party, sorry babes. 🎀

---

👑 COPYRIGHT 👑

Copyright 2017-2018 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 <https://www.openssl.org/source/license.html>.

---

and that's the whole page, bestie, you ate that 🍓 go forth and compare your timestamps responsibly ✨💖🦋

this was version 3.5.9, dated 2026-09-29, from the OpenSSL manual, section 3ossl — mwah, signing off 💅🌈