NAME

X509_new, X509_dup, X509_free, X509_up_ref, X509_chain_up_ref — X.509 certificate object

SYNOPSIS

#include <openssl/x509.h> X509 *
X509_new(void); X509 *
X509_dup(X509 *a); void
X509_free(X509 *a); int
X509_up_ref(X509 *a); STACK_OF(X509) *
X509_chain_up_ref(STACK_OF(X509) *chain);

DESCRIPTION

X509_new() allocates and initializes an empty X509 object with reference count 1. It represents an ASN.1 Certificate structure defined in RFC 5280 section 4.1. It can hold a public key together with information about the person, organization, device, or function the associated private key belongs to. X509_dup() creates a deep copy of a using ASN1_item_dup(3), setting the reference count of the copy to 1. X509_free() decrements the reference count of the X509 structure a and frees it up if the reference count reaches 0. If a is a NULL pointer, no action occurs. X509_up_ref() increments the reference count of a by 1. This function is useful if a certificate structure is being used by several different operations each of which will free it up after use: this avoids the need to duplicate the entire certificate structure. X509_chain_up_ref() performs a shallow copy of the given chain using sk_X509_dup() and increments the reference count of each contained certificate by 1. Its purpose is similar to X509_up_ref(): The returned chain persists after the original is freed.

RETURN VALUES

X509_new() and X509_dup() return a pointer to the newly allocated object or NULL if an error occurs; an error code can be obtained by ERR_get_error(3). X509_up_ref() returns 1 for success or 0 for failure. X509_chain_up_ref() returns the copy of the chain or NULL if an error occurs.

SEE ALSO

AUTHORITY_KEYID_new(3), BASIC_CONSTRAINTS_new(3), crypto(3), d2i_X509(3), PKCS8_PRIV_KEY_INFO_new(3), X509_ALGOR_new(3), X509_ATTRIBUTE_new(3), X509_check_ca(3), X509_check_host(3), X509_check_issued(3), X509_check_private_key(3), X509_check_purpose(3), X509_check_trust(3), X509_CINF_new(3), X509_cmp(3), X509_CRL_new(3), X509_digest(3), X509_EXTENSION_new(3), X509_find_by_subject(3), X509_get0_notBefore(3), X509_get0_signature(3), X509_get1_email(3), X509_get_ex_new_index(3), X509_get_pubkey(3), X509_get_serialNumber(3), X509_get_subject_name(3), X509_get_version(3), X509_INFO_new(3), X509_LOOKUP_hash_dir(3), X509_LOOKUP_new(3), X509_NAME_new(3), X509_policy_check(3), X509_policy_tree_level_count(3), X509_print_ex(3), X509_PUBKEY_new(3), X509_PURPOSE_set(3), X509_REQ_new(3), X509_SIG_new(3), X509_sign(3), X509_STORE_CTX_new(3), X509_STORE_get_by_subject(3), X509_STORE_new(3), X509_TRUST_set(3)

STANDARDS

RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile

HISTORY

X509_new() and X509_free() appeared in SSLeay 0.4 or earlier. X509_dup() first appeared in SSLeay 0.4.4. These functions have been available since OpenBSD 2.4. X509_up_ref() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 6.1. X509_chain_up_ref() first appeared in OpenSSL 1.0.2 and has been available since OpenBSD 6.3.

BUGS

The X.509 public key infrastructure and its data types contain too many design bugs to list them. For lots of examples, see the classic X.509 Style Guide that Peter Gutmann published in 2000.