Document PKCS8_PRIV_KEY_INFO and X509_SIG Bug: 426 Change-Id: Ie96fd593817cbbfc11f78bb5608fcc9eb0b8d773 Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/63944 Commit-Queue: David Benjamin <davidben@google.com> Reviewed-by: Bob Beck <bbe@google.com>
diff --git a/include/openssl/x509.h b/include/openssl/x509.h index c530f1f..812e86d 100644 --- a/include/openssl/x509.h +++ b/include/openssl/x509.h
@@ -1970,6 +1970,90 @@ OPENSSL_EXPORT int i2d_RSA_PSS_PARAMS(const RSA_PSS_PARAMS *in, uint8_t **outp); +// PKCS#8 private keys. +// +// The |PKCS8_PRIV_KEY_INFO| type represents a PKCS#8 PrivateKeyInfo (RFC 5208) +// structure. This is analogous to SubjectPublicKeyInfo and uses the same +// AlgorithmIdentifiers, but carries private keys and is not part of X.509 +// itself. +// +// TODO(davidben): Do these functions really belong in this header? + +// PKCS8_PRIV_KEY_INFO is an |ASN1_ITEM| whose ASN.1 type is PrivateKeyInfo and +// C type is |PKCS8_PRIV_KEY_INFO*|. +DECLARE_ASN1_ITEM(PKCS8_PRIV_KEY_INFO) + +// PKCS8_PRIV_KEY_INFO_new returns a newly-allocated, empty +// |PKCS8_PRIV_KEY_INFO| object, or NULL on error. +OPENSSL_EXPORT PKCS8_PRIV_KEY_INFO *PKCS8_PRIV_KEY_INFO_new(void); + +// PKCS8_PRIV_KEY_INFO_free releases memory associated with |key|. +OPENSSL_EXPORT void PKCS8_PRIV_KEY_INFO_free(PKCS8_PRIV_KEY_INFO *key); + +// d2i_PKCS8_PRIV_KEY_INFO parses up to |len| bytes from |*inp| as a DER-encoded +// PrivateKeyInfo, as described in |d2i_SAMPLE|. +OPENSSL_EXPORT PKCS8_PRIV_KEY_INFO *d2i_PKCS8_PRIV_KEY_INFO( + PKCS8_PRIV_KEY_INFO **out, const uint8_t **inp, long len); + +// i2d_PKCS8_PRIV_KEY_INFO marshals |key| as a DER-encoded PrivateKeyInfo, as +// described in |i2d_SAMPLE|. +OPENSSL_EXPORT int i2d_PKCS8_PRIV_KEY_INFO(const PKCS8_PRIV_KEY_INFO *key, + uint8_t **outp); + +// EVP_PKCS82PKEY returns |p8| as a newly-allocated |EVP_PKEY|, or NULL if the +// key was unsupported or could not be decoded. The caller must release the +// result with |EVP_PKEY_free| when done. +// +// Use |EVP_parse_private_key| instead. +OPENSSL_EXPORT EVP_PKEY *EVP_PKCS82PKEY(const PKCS8_PRIV_KEY_INFO *p8); + +// EVP_PKEY2PKCS8 encodes |pkey| as a PKCS#8 PrivateKeyInfo (RFC 5208), +// represented as a newly-allocated |PKCS8_PRIV_KEY_INFO|, or NULL on error. The +// caller must release the result with |PKCS8_PRIV_KEY_INFO_free| when done. +// +// Use |EVP_marshal_private_key| instead. +OPENSSL_EXPORT PKCS8_PRIV_KEY_INFO *EVP_PKEY2PKCS8(const EVP_PKEY *pkey); + + +// Algorithm and octet string pairs. +// +// The |X509_SIG| type represents an ASN.1 SEQUENCE type of an +// AlgorithmIdentifier and an OCTET STRING. Although named |X509_SIG|, there is +// no type in X.509 which matches this format. The two common types which do are +// DigestInfo (RFC 2315 and RFC 8017), and EncryptedPrivateKeyInfo (RFC 5208). + +// X509_SIG is an |ASN1_ITEM| whose ASN.1 type is the SEQUENCE described above +// and C type is |X509_SIG*|. +DECLARE_ASN1_ITEM(X509_SIG) + +// X509_SIG_new returns a newly-allocated, empty |X509_SIG| object, or NULL on +// error. +OPENSSL_EXPORT X509_SIG *X509_SIG_new(void); + +// X509_SIG_free releases memory associated with |key|. +OPENSSL_EXPORT void X509_SIG_free(X509_SIG *key); + +// d2i_X509_SIG parses up to |len| bytes from |*inp| as a DER-encoded algorithm +// and octet string pair, as described in |d2i_SAMPLE|. +OPENSSL_EXPORT X509_SIG *d2i_X509_SIG(X509_SIG **out, const uint8_t **inp, + long len); + +// i2d_X509_SIG marshals |sig| as a DER-encoded algorithm +// and octet string pair, as described in |i2d_SAMPLE|. +OPENSSL_EXPORT int i2d_X509_SIG(const X509_SIG *sig, uint8_t **outp); + +// X509_SIG_get0 sets |*out_alg| and |*out_digest| to non-owning pointers to +// |sig|'s algorithm and digest fields, respectively. Either |out_alg| and +// |out_digest| may be NULL to skip those fields. +OPENSSL_EXPORT void X509_SIG_get0(const X509_SIG *sig, + const X509_ALGOR **out_alg, + const ASN1_OCTET_STRING **out_digest); + +// X509_SIG_getm behaves like |X509_SIG_get0| but returns mutable pointers. +OPENSSL_EXPORT void X509_SIG_getm(X509_SIG *sig, X509_ALGOR **out_alg, + ASN1_OCTET_STRING **out_digest); + + // Printing functions. // // The following functions output human-readable representations of @@ -2566,17 +2650,6 @@ DEFINE_STACK_OF(X509_INFO) -// X509_SIG_get0 sets |*out_alg| and |*out_digest| to non-owning pointers to -// |sig|'s algorithm and digest fields, respectively. Either |out_alg| and -// |out_digest| may be NULL to skip those fields. -OPENSSL_EXPORT void X509_SIG_get0(const X509_SIG *sig, - const X509_ALGOR **out_alg, - const ASN1_OCTET_STRING **out_digest); - -// X509_SIG_getm behaves like |X509_SIG_get0| but returns mutable pointers. -OPENSSL_EXPORT void X509_SIG_getm(X509_SIG *sig, X509_ALGOR **out_alg, - ASN1_OCTET_STRING **out_digest); - // X509_verify_cert_error_string returns |err| as a human-readable string, where // |err| should be one of the |X509_V_*| values. If |err| is unknown, it returns // a default description. @@ -2589,8 +2662,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_SIG) - OPENSSL_EXPORT int X509_TRUST_set(int *t, int trust); @@ -2644,24 +2715,6 @@ OPENSSL_EXPORT int X509_verify_cert(X509_STORE_CTX *ctx); -// PKCS#8 utilities - -DECLARE_ASN1_FUNCTIONS_const(PKCS8_PRIV_KEY_INFO) - -// EVP_PKCS82PKEY returns |p8| as a newly-allocated |EVP_PKEY|, or NULL if the -// key was unsupported or could not be decoded. If non-NULL, the caller must -// release the result with |EVP_PKEY_free| when done. -// -// Use |EVP_parse_private_key| instead. -OPENSSL_EXPORT EVP_PKEY *EVP_PKCS82PKEY(const PKCS8_PRIV_KEY_INFO *p8); - -// EVP_PKEY2PKCS8 encodes |pkey| as a PKCS#8 PrivateKeyInfo (RFC 5208), -// represented as a newly-allocated |PKCS8_PRIV_KEY_INFO|, or NULL on error. The -// caller must release the result with |PKCS8_PRIV_KEY_INFO_free| when done. -// -// Use |EVP_marshal_private_key| instead. -OPENSSL_EXPORT PKCS8_PRIV_KEY_INFO *EVP_PKEY2PKCS8(const EVP_PKEY *pkey); - 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);