Document X509_PUBKEY functions
Bug: 426 Change-Id: I29d4e1d5a5c319ba7bedab197efaf0427a8115af Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/63943 Reviewed-by: Bob Beck <bbe@google.com> Commit-Queue: David Benjamin <davidben@google.com>
This commit is contained in:
David Benjamin
committed by
Boringssl LUCI CQ
Boringssl LUCI CQ
parent
3bfb4ea03f
commit
4e400359bc
+74
-44
@@ -1375,6 +1375,80 @@ OPENSSL_EXPORT X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt(
|
||||
ossl_ssize_t len);
|
||||
|
||||
|
||||
// Public keys.
|
||||
//
|
||||
// X.509 encodes public keys as SubjectPublicKeyInfo (RFC 5280), sometimes
|
||||
// referred to as SPKI. These are represented in this library by |X509_PUBKEY|.
|
||||
|
||||
// X509_PUBKEY is an |ASN1_ITEM| whose ASN.1 type is SubjectPublicKeyInfo and C
|
||||
// type is |X509_PUBKEY*|.
|
||||
DECLARE_ASN1_ITEM(X509_PUBKEY)
|
||||
|
||||
// X509_PUBKEY_new returns a newly-allocated, empty |X509_PUBKEY| object, or
|
||||
// NULL on error.
|
||||
OPENSSL_EXPORT X509_PUBKEY *X509_PUBKEY_new(void);
|
||||
|
||||
// X509_PUBKEY_free releases memory associated with |key|.
|
||||
OPENSSL_EXPORT void X509_PUBKEY_free(X509_PUBKEY *key);
|
||||
|
||||
// d2i_X509_PUBKEY parses up to |len| bytes from |*inp| as a DER-encoded
|
||||
// SubjectPublicKeyInfo, as described in |d2i_SAMPLE|.
|
||||
OPENSSL_EXPORT X509_PUBKEY *d2i_X509_PUBKEY(X509_PUBKEY **out,
|
||||
const uint8_t **inp, long len);
|
||||
|
||||
// i2d_X509_PUBKEY marshals |key| as a DER-encoded SubjectPublicKeyInfo, as
|
||||
// described in |i2d_SAMPLE|.
|
||||
OPENSSL_EXPORT int i2d_X509_PUBKEY(const X509_PUBKEY *key, uint8_t **outp);
|
||||
|
||||
// X509_PUBKEY_set serializes |pkey| into a newly-allocated |X509_PUBKEY|
|
||||
// structure. On success, it frees |*x| if non-NULL, then sets |*x| to the new
|
||||
// object, and returns one. Otherwise, it returns zero.
|
||||
OPENSSL_EXPORT int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey);
|
||||
|
||||
// X509_PUBKEY_get decodes the public key in |key| and returns an |EVP_PKEY| on
|
||||
// success, or NULL on error or unrecognized algorithm. The caller must release
|
||||
// the result with |EVP_PKEY_free| when done. The |EVP_PKEY| is cached in |key|,
|
||||
// so callers must not mutate the result.
|
||||
OPENSSL_EXPORT EVP_PKEY *X509_PUBKEY_get(X509_PUBKEY *key);
|
||||
|
||||
// X509_PUBKEY_set0_param sets |pub| to a key with AlgorithmIdentifier
|
||||
// determined by |obj|, |param_type|, and |param_value|, and an encoded
|
||||
// public key of |key|. On success, it gives |pub| ownership of all the other
|
||||
// parameters and returns one. Otherwise, it returns zero. |key| must have been
|
||||
// allocated by |OPENSSL_malloc|. |obj| and, if applicable, |param_value| must
|
||||
// not be freed after a successful call, and must have been allocated in a
|
||||
// manner compatible with |ASN1_OBJECT_free| or |ASN1_STRING_free|.
|
||||
//
|
||||
// |obj|, |param_type|, and |param_value| are interpreted as in
|
||||
// |X509_ALGOR_set0|. See |X509_ALGOR_set0| for details.
|
||||
OPENSSL_EXPORT int X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *obj,
|
||||
int param_type, void *param_value,
|
||||
uint8_t *key, int key_len);
|
||||
|
||||
// X509_PUBKEY_get0_param outputs fields of |pub| and returns one. If |out_obj|
|
||||
// is not NULL, it sets |*out_obj| to AlgorithmIdentifier's OID. If |out_key|
|
||||
// is not NULL, it sets |*out_key| and |*out_key_len| to the encoded public key.
|
||||
// If |out_alg| is not NULL, it sets |*out_alg| to the AlgorithmIdentifier.
|
||||
//
|
||||
// All pointers outputted by this function are internal to |pub| and must not be
|
||||
// freed by the caller. Additionally, although some outputs are non-const,
|
||||
// callers must not mutate the resulting objects.
|
||||
//
|
||||
// Note: X.509 SubjectPublicKeyInfo structures store the encoded public key as a
|
||||
// BIT STRING. |*out_key| and |*out_key_len| will silently pad the key with zero
|
||||
// bits if |pub| did not contain a whole number of bytes. Use
|
||||
// |X509_PUBKEY_get0_public_key| to preserve this information.
|
||||
OPENSSL_EXPORT int X509_PUBKEY_get0_param(ASN1_OBJECT **out_obj,
|
||||
const uint8_t **out_key,
|
||||
int *out_key_len,
|
||||
X509_ALGOR **out_alg,
|
||||
X509_PUBKEY *pub);
|
||||
|
||||
// X509_PUBKEY_get0_public_key returns |pub|'s encoded public key.
|
||||
OPENSSL_EXPORT const ASN1_BIT_STRING *X509_PUBKEY_get0_public_key(
|
||||
const X509_PUBKEY *pub);
|
||||
|
||||
|
||||
// Extensions.
|
||||
//
|
||||
// X.509 certificates and CRLs may contain a list of extensions (RFC 5280).
|
||||
@@ -2515,19 +2589,6 @@ OPENSSL_EXPORT const char *X509_get_default_cert_dir_env(void);
|
||||
OPENSSL_EXPORT const char *X509_get_default_cert_file_env(void);
|
||||
OPENSSL_EXPORT const char *X509_get_default_private_dir(void);
|
||||
|
||||
DECLARE_ASN1_FUNCTIONS_const(X509_PUBKEY)
|
||||
|
||||
// X509_PUBKEY_set serializes |pkey| into a newly-allocated |X509_PUBKEY|
|
||||
// structure. On success, it frees |*x|, sets |*x| to the new object, and
|
||||
// returns one. Otherwise, it returns zero.
|
||||
OPENSSL_EXPORT int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey);
|
||||
|
||||
// X509_PUBKEY_get decodes the public key in |key| and returns an |EVP_PKEY| on
|
||||
// success, or NULL on error. The caller must release the result with
|
||||
// |EVP_PKEY_free| when done. The |EVP_PKEY| is cached in |key|, so callers must
|
||||
// not mutate the result.
|
||||
OPENSSL_EXPORT EVP_PKEY *X509_PUBKEY_get(X509_PUBKEY *key);
|
||||
|
||||
DECLARE_ASN1_FUNCTIONS_const(X509_SIG)
|
||||
|
||||
|
||||
@@ -2601,37 +2662,6 @@ OPENSSL_EXPORT EVP_PKEY *EVP_PKCS82PKEY(const PKCS8_PRIV_KEY_INFO *p8);
|
||||
// Use |EVP_marshal_private_key| instead.
|
||||
OPENSSL_EXPORT PKCS8_PRIV_KEY_INFO *EVP_PKEY2PKCS8(const EVP_PKEY *pkey);
|
||||
|
||||
// X509_PUBKEY_set0_param sets |pub| to a key with AlgorithmIdentifier
|
||||
// determined by |obj|, |param_type|, and |param_value|, and an encoded
|
||||
// public key of |key|. On success, it takes ownership of all its parameters and
|
||||
// returns one. Otherwise, it returns zero. |key| must have been allocated by
|
||||
// |OPENSSL_malloc|.
|
||||
//
|
||||
// |obj|, |param_type|, and |param_value| are interpreted as in
|
||||
// |X509_ALGOR_set0|. See |X509_ALGOR_set0| for details.
|
||||
OPENSSL_EXPORT int X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *obj,
|
||||
int param_type, void *param_value,
|
||||
uint8_t *key, int key_len);
|
||||
|
||||
// X509_PUBKEY_get0_param outputs fields of |pub| and returns one. If |out_obj|
|
||||
// is not NULL, it sets |*out_obj| to AlgorithmIdentifier's OID. If |out_key|
|
||||
// is not NULL, it sets |*out_key| and |*out_key_len| to the encoded public key.
|
||||
// If |out_alg| is not NULL, it sets |*out_alg| to the AlgorithmIdentifier.
|
||||
//
|
||||
// Note: X.509 SubjectPublicKeyInfo structures store the encoded public key as a
|
||||
// BIT STRING. |*out_key| and |*out_key_len| will silently pad the key with zero
|
||||
// bits if |pub| did not contain a whole number of bytes. Use
|
||||
// |X509_PUBKEY_get0_public_key| to preserve this information.
|
||||
OPENSSL_EXPORT int X509_PUBKEY_get0_param(ASN1_OBJECT **out_obj,
|
||||
const uint8_t **out_key,
|
||||
int *out_key_len,
|
||||
X509_ALGOR **out_alg,
|
||||
X509_PUBKEY *pub);
|
||||
|
||||
// X509_PUBKEY_get0_public_key returns |pub|'s encoded public key.
|
||||
OPENSSL_EXPORT const ASN1_BIT_STRING *X509_PUBKEY_get0_public_key(
|
||||
const X509_PUBKEY *pub);
|
||||
|
||||
OPENSSL_EXPORT int X509_check_trust(X509 *x, int id, int flags);
|
||||
OPENSSL_EXPORT int X509_TRUST_get_count(void);
|
||||
OPENSSL_EXPORT X509_TRUST *X509_TRUST_get0(int idx);
|
||||
|
||||
Reference in New Issue
Block a user