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>
diff --git a/include/openssl/x509.h b/include/openssl/x509.h index 5022f46..c530f1f 100644 --- a/include/openssl/x509.h +++ b/include/openssl/x509.h
@@ -1375,6 +1375,80 @@ 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_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 @@ // 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);