X509_ADD_CERT(3ossl)

💖 X509_add_cert, X509_add_certs — X509 certificate list addition functions 💖

okay bestie, welcome to X509_ADD_CERT(3ossl) — yes that's the manual page name, we're in the OpenSSL docs, section 3ossl, and today we're talking about adding certs to lists. riveting? no. essential? absolutely. let's go 🦋

---

✨ SYNOPSIS ✨

#include <openssl/x509.h>

int X509_add_cert(STACK_OF(X509) *sk, X509 *cert, int flags);
int X509_add_certs(STACK_OF(X509) *sk, STACK_OF(X509) *certs, int flags);

---

🌸 DESCRIPTION 🌸

so X509_add_cert() takes a certificate cert and adds it to the given list sk. and listen — if you pass NULL as the cert argument, that's an error, no cap. don't do it. 🙈

then we have X509_add_certs(), which is the group-chat version: it adds a whole list of certificates certs to the given list sk. the certs argument is allowed to be NULL, and if it is, nothing happens at all — it's giving "no effect", truly nothing. also important: it does not modify the list certs itself. but — and this is the plot twist — if the X509_ADD_FLAG_UP_REF flag (we'll get to it, hold on) is set, then the reference counters of those of its members that actually got added to sk get increased. so like, the members are being touched, just not the list itself. 💅

both of these functions have a flags parameter, and that's the lil control panel for all the details of the operation. let's break it down:

• X509_ADD_FLAG_DEFAULT — this one equals 0, and it means... no special semantics. literally just vibes. the default-est default to ever default. ✨
• X509_ADD_FLAG_UP_REF — set this and the reference counts of those certificates that were added successfully get increased. (successfully is doing a lot of work in that sentence, keep it in mind, we come back to it in NOTES 👀)
• X509_ADD_FLAG_PREPEND — set this and the certificates get prepended to sk. by default they're appended to sk. and in both cases the original order of the added certificates is preserved. so nobody's getting shuffled, we respect the queue. 🎀
• X509_ADD_FLAG_NO_DUP — set this and any certificates already contained in sk get ignored. how do we know they're already there? that's determined using X509_cmp(3). no dupes on this list, we're not doing that. 🚫
• X509_ADD_FLAG_NO_SS — set this and certificates that are marked self-signed get ignored. and how do we know they're self-signed? that's determined using X509_self_signed(3). bye self-signed girlies, not today. 👋

---

🔥 RETURN VALUES 🔥

both functions return 1 for success and 0 for failure. that's it, that's the whole system. binary. slay. 💀

---

🫶 NOTES 🫶

okay real talk, this part matters:

if you use X509_add_certs() with the flags X509_ADD_FLAG_NO_DUP or X509_ADD_FLAG_NO_SS, it is advisable to also use X509_ADD_FLAG_UP_REF, because otherwise, likely not for all members of the certs list is the ownership transferred to the list of certificates sk. (that's the manpage talking, and it's saying: some of them won't get their ownership handed over, and you'd be leaving refcounts in a weird spot. messy. don't.) 😭

also, care should be taken in case the certs argument equals sk. like, same list? adding a list to itself? take care. be careful. that's the warning. 🧚

---

🌈 SEE ALSO 🌈

• X509_cmp(3)
• X509_self_signed(3)

---

⭐ HISTORY ⭐

the functions X509_add_cert() and X509_add_certs() were added in OpenSSL 3.0. glow-up era. 👑

---

💜 COPYRIGHT 💜

Copyright 2019-2025 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 🫶 this was version 3.5.9, dated 2026-09-29, and honestly? iconic of it. go forth and add your certs responsibly. periodt. 💖✨🎀