ASN1_INTEGER_get_int64.pod 5.1 KB

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