doc/crypto/ASN1_INTEGER_get_int64.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN, - ASN.1 INTEGER and ENUMERATED utilities
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/asn1.h>
  10
  11  int ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a);
  12  int ASN1_INTEGER_get(ASN1_INTEGER *a, long v);
  13
  14  int ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r);
  15  long ASN1_INTEGER_set(const ASN1_INTEGER *a);
  16
  17  ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai);
  18  BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);
  19
  20  int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_INTEGER *a);
  21  long ASN1_ENUMERATED_get(ASN1_ENUMERATED *a);
  22
  23  int ASN1_ENUMERATED_set_int64(ASN1_INTEGER *a, int64_t r);
  24  int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);
  25
  26  ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(BIGNUM *bn, ASN1_ENUMERATED *ai);
  27  BIGNUM *ASN1_ENUMERATED_to_BN(ASN1_ENUMERATED *ai, BIGNUM *bn);
  28
  29 =head1 DESCRIPTION
  30
  31 These functions convert to and from B<ASN1_INTEGER> and B<ASN1_ENUMERATED>
  32 structures.
  33
  34 ASN1_INTEGER_get_int64() converts an B<ASN1_INTEGER> into an B<int64_t> type
  35 If successful it returns 1 and sets B<*pr> to the value of B<a>. If it fails
  36 (due to invalid type or the value being too big to fit into an B<int64_t> type)
  37 it returns 0.
  38
  39 ASN1_INTEGER_get() also returns the value of B<a> but it returns 0 if B<a> is
  40 NULL and -1 on error (which is ambiguous because -1 is a legitimate value for
  41 an B<ASN1_INTEGER>). New applications should use ASN1_INTEGER_get_int64()
  42 instead.
  43
  44 ASN1_INTEGER_set_int64() sets the value of B<ASN1_INTEGER> B<a> to the
  45 B<int64_t> value B<r>.
  46
  47 ASN1_INTEGER_set() sets the value of B<ASN1_INTEGER> B<a> to the B<long> value
  48 B<v>.
  49
  50 BN_to_ASN1_INTEGER() converts B<BIGNUM> B<bn> to an B<ASN1_INTEGER>. If B<ai>
  51 is NULL a new B<ASN1_INTEGER> structure is returned. If B<ai> is not NULL then
  52 the existing structure will be used instead.
  53
  54 ASN1_INTEGER_to_BN() converts ASN1_INTEGER B<ai> into a B<BIGNUM>. If B<bn> is
  55 NULL a new B<BIGNUM> structure is returned. If B<bn> is not NULL then the
  56 existing structure will be used instead.
  57
  58 ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_set_int64(),
  59 ASN1_ENUMERATED_set(), BN_to_ASN1_ENUMERATED() and ASN1_ENUMERATED_to_BN()
  60 behave in an identical way to their ASN1_INTEGER counterparts except they
  61 operate on an B<ASN1_ENUMERATED> value.
  62
  63 ASN1_ENUMERATED_get() returns the value of B<a> in a similar way to
  64 ASN1_INTEGER_get() but it returns B<0xffffffffL> if the value of B<a> will not
  65 fit in a long type. New applications should use ASN1_ENUMERATED_get_int64()
  66 instead.
  67
  68 =head1 NOTES
  69
  70 In general an B<ASN1_INTEGER> or B<ASN1_ENUMERATED> type can contain an
  71 integer of almost arbitrary size and so cannot always be represented by a C
  72 B<int64_t> type. However in many cases (for example version numbers) they
  73 represent small integers which can be more easily manipulated if converted to
  74 an appropriate C integer type.
  75
  76 =head1 BUGS
  77
  78 The ambigious return values of ASN1_INTEGER_get() and ASN1_ENUMERATED_get()
  79 mean these functions should be avoided if possible. They are retained for
  80 compatibility. Normally the ambigious return values are not legitimate
  81 values for the fields they represent.
  82
  83 =head1 RETURN VALUES
  84
  85 ASN1_INTEGER_set_int64(), ASN1_INTEGER_set(), ASN1_ENUMERATED_set_int64() and
  86 ASN1_ENUMERATED_set() return 1 for success and 0 for failure. They will only
  87 fail if a memory allocation error occurs.
  88
  89 ASN1_INTEGER_get_int64() and ASN1_ENUMERATED_get_int64() return 1 for success
  90 and 0 for failure. They will fail if the passed type is incorrect (this will
  91 only happen if there is a programming error) or if the value exceeds the range
  92 of an B<int64_t> type.
  93
  94 BN_to_ASN1_INTEGER() and BN_to_ASN1_ENUMERATED() return an B<ASN1_INTEGER> or
  95 B<ASN1_ENUMERATED> structure respectively or NULL if an error occurs. They will
  96 only fail due to a memory allocation error.
  97
  98 ASN1_INTEGER_to_BN() and ASN1_ENUMERATED_to_BN() return a B<BIGNUM> structure
  99 of NULL if an error occurs. They can fail if the pased type is incorrect
 100 (due to programming error) or due to a memory allocation failure.
 101
 102 =head1 SEE ALSO
 103
 104 L<ERR_get_error(3)|ERR_get_error(3)>
 105
 106 =head1 HISTORY
 107
 108 ASN1_INTEGER_set_int64(), ASN1_INTEGER_get_int64(),
 109 ASN1_ENUMERATED_set_int64() and ASN1_ENUMERATED_get_int64()
 110 were added to OpenSSL 1.1.0.
 111
 112 =cut