doc/man3/X509_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 X509_new, X509_new_ex,
   6 X509_free, X509_up_ref,
   7 X509_chain_up_ref,
   8 OSSL_STACK_OF_X509_free
   9 - X509 certificate ASN1 allocation and deallocation functions
  10
  11 =head1 SYNOPSIS
  12
  13  #include <openssl/x509.h>
  14
  15  X509 *X509_new(void);
  16  X509 *X509_new_ex(OSSL_LIB_CTX *libctx, const char *propq);
  17  void X509_free(X509 *a);
  18  int X509_up_ref(X509 *a);
  19  STACK_OF(X509) *X509_chain_up_ref(STACK_OF(X509) *x);
  20  void OSSL_STACK_OF_X509_free(STACK_OF(X509) *certs);
  21
  22 =head1 DESCRIPTION
  23
  24 The X509 ASN1 allocation routines, allocate and free an
  25 X509 structure, which represents an X509 certificate.
  26
  27 X509_new_ex() allocates and initializes a X509 structure with a
  28 library context of I<libctx>, property query of I<propq> and a reference
  29 count of B<1>. Many X509 functions such as X509_check_purpose(), and
  30 X509_verify() use this library context to select which providers supply the
  31 fetched algorithms (SHA1 is used internally). This created X509 object can then
  32 be used when loading binary data using d2i_X509().
  33
  34 X509_new() is similar to X509_new_ex() but sets the library context
  35 and property query to NULL. This results in the default (NULL) library context
  36 being used for any X509 operations requiring algorithm fetches.
  37
  38 X509_free() decrements the reference count of B<X509> structure B<a> and
  39 frees it up if the reference count is zero. If B<a> is NULL nothing is done.
  40
  41 X509_up_ref() increments the reference count of B<a>.
  42
  43 X509_chain_up_ref() increases the reference count of all certificates in
  44 chain B<x> and returns a copy of the stack, or an empty stack if B<a> is NULL.
  45
  46 OSSL_STACK_OF_X509_free() deallocates the given list of pointers to
  47 certificates after calling X509_free() on all its elements.
  48
  49 =head1 NOTES
  50
  51 The function X509_up_ref() if useful if a certificate structure is being
  52 used by several different operations each of which will free it up after
  53 use: this avoids the need to duplicate the entire certificate structure.
  54
  55 The function X509_chain_up_ref() doesn't just up the reference count of
  56 each certificate. It also returns a copy of the stack, using sk_X509_dup(),
  57 but it serves a similar purpose: the returned chain persists after the
  58 original has been freed.
  59
  60 =head1 RETURN VALUES
  61
  62 If the allocation fails, X509_new() returns NULL and sets an error
  63 code that can be obtained by L<ERR_get_error(3)>.
  64 Otherwise it returns a pointer to the newly allocated structure.
  65
  66 X509_up_ref() returns 1 for success and 0 for failure.
  67
  68 X509_chain_up_ref() returns a copy of the stack or NULL if an error occurred.
  69
  70 OSSL_STACK_OF_X509_free() has no return value.
  71
  72 =head1 SEE ALSO
  73
  74 L<d2i_X509(3)>,
  75 L<ERR_get_error(3)>,
  76 L<X509_CRL_get0_by_serial(3)>,
  77 L<X509_get0_signature(3)>,
  78 L<X509_get_ext_d2i(3)>,
  79 L<X509_get_extension_flags(3)>,
  80 L<X509_get_pubkey(3)>,
  81 L<X509_get_subject_name(3)>,
  82 L<X509_get_version(3)>,
  83 L<X509_NAME_add_entry_by_txt(3)>,
  84 L<X509_NAME_ENTRY_get_object(3)>,
  85 L<X509_NAME_get_index_by_NID(3)>,
  86 L<X509_NAME_print_ex(3)>,
  87 L<X509_sign(3)>,
  88 L<X509V3_get_d2i(3)>,
  89 L<X509_verify_cert(3)>
  90
  91 =head1 HISTORY
  92
  93 X509_new_ex() was added in OpenSSL 3.0.
  94
  95 OSSL_STACK_OF_X509_free() was added in OpenSSL 3.2.
  96
  97 =head1 COPYRIGHT
  98
  99 Copyright 2002-2021 The OpenSSL Project Authors. All Rights Reserved.
 100
 101 Licensed under the Apache License 2.0 (the "License").  You may not use
 102 this file except in compliance with the License.  You can obtain a copy
 103 in the file LICENSE in the source distribution or at
 104 L<https://www.openssl.org/source/license.html>.
 105
 106 =cut