doc/man3/X509_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 X509_chain_up_ref,
   6 X509_new, X509_free, X509_up_ref - X509 certificate ASN1 allocation functions
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/x509.h>
  11
  12  X509 *X509_new(void);
  13  void X509_free(X509 *a);
  14  int X509_up_ref(X509 *a);
  15  STACK_OF(X509) *X509_chain_up_ref(STACK_OF(X509) *x);
  16
  17 =head1 DESCRIPTION
  18
  19 The X509 ASN1 allocation routines, allocate and free an
  20 X509 structure, which represents an X509 certificate.
  21
  22 X509_new() allocates and initializes a X509 structure with reference count
  23 B<1>.
  24
  25 X509_free() decrements the reference count of B<X509> structure B<a> and
  26 frees it up if the reference count is zero. If B<a> is NULL nothing is done.
  27
  28 X509_up_ref() increments the reference count of B<a>.
  29
  30 X509_chain_up_ref() increases the reference count of all certificates in
  31 chain B<x> and returns a copy of the stack.
  32
  33 =head1 NOTES
  34
  35 The function X509_up_ref() if useful if a certificate structure is being
  36 used by several different operations each of which will free it up after
  37 use: this avoids the need to duplicate the entire certificate structure.
  38
  39 The function X509_chain_up_ref() doesn't just up the reference count of
  40 each certificate it also returns a copy of the stack, using sk_X509_dup(),
  41 but it serves a similar purpose: the returned chain persists after the
  42 original has been freed.
  43
  44 =head1 RETURN VALUES
  45
  46 If the allocation fails, X509_new() returns B<NULL> and sets an error
  47 code that can be obtained by L<ERR_get_error(3)>.
  48 Otherwise it returns a pointer to the newly allocated structure.
  49
  50 X509_up_ref() returns 1 for success and 0 for failure.
  51
  52 X509_chain_up_ref() returns a copy of the stack or B<NULL> if an error
  53 occurred.
  54
  55 =head1 SEE ALSO
  56
  57 L<d2i_X509(3)>,
  58 L<ERR_get_error(3)>,
  59 L<X509_CRL_get0_by_serial(3)>,
  60 L<X509_get0_signature(3)>,
  61 L<X509_get_ext_d2i(3)>,
  62 L<X509_get_extension_flags(3)>,
  63 L<X509_get_pubkey(3)>,
  64 L<X509_get_subject_name(3)>,
  65 L<X509_get_version(3)>,
  66 L<X509_NAME_add_entry_by_txt(3)>,
  67 L<X509_NAME_ENTRY_get_object(3)>,
  68 L<X509_NAME_get_index_by_NID(3)>,
  69 L<X509_NAME_print_ex(3)>,
  70 L<X509_sign(3)>,
  71 L<X509V3_get_d2i(3)>,
  72 L<X509_verify_cert(3)>
  73
  74 =head1 COPYRIGHT
  75
  76 Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
  77
  78 Licensed under the Apache License 2.0 (the "License").  You may not use
  79 this file except in compliance with the License.  You can obtain a copy
  80 in the file LICENSE in the source distribution or at
  81 L<https://www.openssl.org/source/license.html>.
  82
  83 =cut