Move the old SPKAC types to their own section Also fixes some copy-paste errors in earlier docs. Bug: 426 Change-Id: I330445477b6feb50f65a868130387804114f23a8 Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/59205 Commit-Queue: David Benjamin <davidben@google.com> Auto-Submit: David Benjamin <davidben@google.com> Reviewed-by: Adam Langley <agl@google.com>
diff --git a/include/openssl/x509.h b/include/openssl/x509.h index 776a842..8deb767 100644 --- a/include/openssl/x509.h +++ b/include/openssl/x509.h
@@ -1533,6 +1533,112 @@ int idx); +// SignedPublicKeyAndChallenge structures. +// +// The SignedPublicKeyAndChallenge (SPKAC) is a legacy structure to request +// certificates, primarily in the legacy <keygen> HTML tag. An SPKAC structure +// is represented by a |NETSCAPE_SPKI| structure. +// +// The structure is described in +// https://developer.mozilla.org/en-US/docs/Web/HTML/Element/keygen + +// A Netscape_spki_st, or |NETSCAPE_SPKI|, represents a +// SignedPublicKeyAndChallenge structure. Although this structure contains a +// |spkac| field of type |NETSCAPE_SPKAC|, these are misnamed. The SPKAC is the +// entire structure, not the signed portion. +struct Netscape_spki_st { + NETSCAPE_SPKAC *spkac; + X509_ALGOR *sig_algor; + ASN1_BIT_STRING *signature; +} /* NETSCAPE_SPKI */; + +// NETSCAPE_SPKI is an |ASN1_ITEM| whose ASN.1 type is +// SignedPublicKeyAndChallenge and C type is |NETSCAPE_SPKI*|. +DECLARE_ASN1_ITEM(NETSCAPE_SPKI) + +// NETSCAPE_SPKI_new returns a newly-allocated, empty |NETSCAPE_SPKI| object, or +// NULL on error. +OPENSSL_EXPORT NETSCAPE_SPKI *NETSCAPE_SPKI_new(void); + +// NETSCAPE_SPKI_free releases memory associated with |spki|. +OPENSSL_EXPORT void NETSCAPE_SPKI_free(NETSCAPE_SPKI *spki); + +// d2i_NETSCAPE_SPKI parses up to |len| bytes from |*inp| as a DER-encoded +// SignedPublicKeyAndChallenge structure, as described in |d2i_SAMPLE|. +OPENSSL_EXPORT NETSCAPE_SPKI *d2i_NETSCAPE_SPKI(NETSCAPE_SPKI **out, + const uint8_t **inp, long len); + +// i2d_NETSCAPE_SPKI marshals |spki| as a DER-encoded +// SignedPublicKeyAndChallenge structure, as described in |i2d_SAMPLE|. +OPENSSL_EXPORT int i2d_NETSCAPE_SPKI(const NETSCAPE_SPKI *spki, uint8_t **outp); + +// NETSCAPE_SPKI_verify checks that |spki| has a valid signature by |pkey|. It +// returns one if the signature is valid and zero otherwise. +OPENSSL_EXPORT int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *spki, EVP_PKEY *pkey); + +// NETSCAPE_SPKI_b64_decode decodes |len| bytes from |str| as a base64-encoded +// SignedPublicKeyAndChallenge structure. It returns a newly-allocated +// |NETSCAPE_SPKI| structure with the result, or NULL on error. If |len| is 0 or +// negative, the length is calculated with |strlen| and |str| must be a +// NUL-terminated C string. +OPENSSL_EXPORT NETSCAPE_SPKI *NETSCAPE_SPKI_b64_decode(const char *str, + ossl_ssize_t len); + +// NETSCAPE_SPKI_b64_encode encodes |spki| as a base64-encoded +// SignedPublicKeyAndChallenge structure. It returns a newly-allocated +// NUL-terminated C string with the result, or NULL on error. The caller must +// release the memory with |OPENSSL_free| when done. +OPENSSL_EXPORT char *NETSCAPE_SPKI_b64_encode(NETSCAPE_SPKI *spki); + +// NETSCAPE_SPKI_get_pubkey decodes and returns the public key in |spki| as an +// |EVP_PKEY|, or NULL on error. The caller takes ownership of the resulting +// pointer and must call |EVP_PKEY_free| when done. +OPENSSL_EXPORT EVP_PKEY *NETSCAPE_SPKI_get_pubkey(NETSCAPE_SPKI *spki); + +// NETSCAPE_SPKI_set_pubkey sets |spki|'s public key to |pkey|. It returns one +// on success or zero on error. This function does not take ownership of |pkey|, +// so the caller may continue to manage its lifetime independently of |spki|. +OPENSSL_EXPORT int NETSCAPE_SPKI_set_pubkey(NETSCAPE_SPKI *spki, + EVP_PKEY *pkey); + +// NETSCAPE_SPKI_sign signs |spki| with |pkey| and replaces the signature +// algorithm and signature fields. It returns the length of the signature on +// success and zero on error. This function uses digest algorithm |md|, or +// |pkey|'s default if NULL. Other signing parameters use |pkey|'s defaults. +OPENSSL_EXPORT int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *spki, EVP_PKEY *pkey, + const EVP_MD *md); + +// A Netscape_spkac_st, or |NETSCAPE_SPKAC|, represents a PublicKeyAndChallenge +// structure. This type is misnamed. The full SPKAC includes the signature, +// which is represented with the |NETSCAPE_SPKI| type. +struct Netscape_spkac_st { + X509_PUBKEY *pubkey; + ASN1_IA5STRING *challenge; +} /* NETSCAPE_SPKAC */; + +// NETSCAPE_SPKAC is an |ASN1_ITEM| whose ASN.1 type is PublicKeyAndChallenge +// and C type is |NETSCAPE_SPKAC*|. +DECLARE_ASN1_ITEM(NETSCAPE_SPKAC) + +// NETSCAPE_SPKAC_new returns a newly-allocated, empty |NETSCAPE_SPKAC| object, +// or NULL on error. +OPENSSL_EXPORT NETSCAPE_SPKAC *NETSCAPE_SPKAC_new(void); + +// NETSCAPE_SPKAC_free releases memory associated with |spkac|. +OPENSSL_EXPORT void NETSCAPE_SPKAC_free(NETSCAPE_SPKAC *spkac); + +// d2i_NETSCAPE_SPKAC parses up to |len| bytes from |*inp| as a DER-encoded +// PublicKeyAndChallenge structure, as described in |d2i_SAMPLE|. +OPENSSL_EXPORT NETSCAPE_SPKAC *d2i_NETSCAPE_SPKAC(NETSCAPE_SPKAC **out, + const uint8_t **inp, + long len); + +// i2d_NETSCAPE_SPKAC marshals |spkac| as a DER-encoded PublicKeyAndChallenge +// structure, as described in |i2d_SAMPLE|. +OPENSSL_EXPORT int i2d_NETSCAPE_SPKAC(const NETSCAPE_SPKAC *spkac, + uint8_t **outp); + + // Printing functions. // // The following functions output human-readable representations of @@ -1563,11 +1669,11 @@ // X509_FLAG_NO_ISSUER skips printing the issuer. #define X509_FLAG_NO_ISSUER (1L << 4) -// X509_FLAG_NO_ISSUER skips printing the notBefore and notAfter times. It is +// X509_FLAG_NO_VALIDITY skips printing the notBefore and notAfter times. It is // ignored in |X509_REQ_print_fp|. #define X509_FLAG_NO_VALIDITY (1L << 5) -// X509_FLAG_NO_ISSUER skips printing the subject. +// X509_FLAG_NO_SUBJECT skips printing the subject. #define X509_FLAG_NO_SUBJECT (1L << 6) // X509_FLAG_NO_PUBKEY skips printing the public key. @@ -2125,20 +2231,6 @@ DEFINE_STACK_OF(X509_INFO) -// The next 2 structures and their 8 routines were sent to me by -// Pat Richard <patr@x509.com> and are used to manipulate -// Netscapes spki structures - useful if you are writing a CA web page -struct Netscape_spkac_st { - X509_PUBKEY *pubkey; - ASN1_IA5STRING *challenge; // challenge sent in atlas >= PR2 -} /* NETSCAPE_SPKAC */; - -struct Netscape_spki_st { - NETSCAPE_SPKAC *spkac; // signed public key and challenge - X509_ALGOR *sig_algor; - ASN1_BIT_STRING *signature; -} /* NETSCAPE_SPKI */; - // X509_get_pathlen returns path length constraint from the basic constraints // extension in |x509|. (See RFC 5280, section 4.2.1.9.) It returns -1 if the // constraint is not present, or if some extension in |x509| was invalid. @@ -2164,42 +2256,6 @@ // a default description. OPENSSL_EXPORT const char *X509_verify_cert_error_string(long err); -// NETSCAPE_SPKI_verify checks that |spki| has a valid signature by |pkey|. It -// returns one if the signature is valid and zero otherwise. -OPENSSL_EXPORT int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *spki, EVP_PKEY *pkey); - -// NETSCAPE_SPKI_b64_decode decodes |len| bytes from |str| as a base64-encoded -// Netscape signed public key and challenge (SPKAC) structure. It returns a -// newly-allocated |NETSCAPE_SPKI| structure with the result, or NULL on error. -// If |len| is 0 or negative, the length is calculated with |strlen| and |str| -// must be a NUL-terminated C string. -OPENSSL_EXPORT NETSCAPE_SPKI *NETSCAPE_SPKI_b64_decode(const char *str, - ossl_ssize_t len); - -// NETSCAPE_SPKI_b64_encode encodes |spki| as a base64-encoded Netscape signed -// public key and challenge (SPKAC) structure. It returns a newly-allocated -// NUL-terminated C string with the result, or NULL on error. The caller must -// release the memory with |OPENSSL_free| when done. -OPENSSL_EXPORT char *NETSCAPE_SPKI_b64_encode(NETSCAPE_SPKI *spki); - -// NETSCAPE_SPKI_get_pubkey decodes and returns the public key in |spki| as an -// |EVP_PKEY|, or NULL on error. The caller takes ownership of the resulting -// pointer and must call |EVP_PKEY_free| when done. -OPENSSL_EXPORT EVP_PKEY *NETSCAPE_SPKI_get_pubkey(NETSCAPE_SPKI *spki); - -// NETSCAPE_SPKI_set_pubkey sets |spki|'s public key to |pkey|. It returns one -// on success or zero on error. This function does not take ownership of |pkey|, -// so the caller may continue to manage its lifetime independently of |spki|. -OPENSSL_EXPORT int NETSCAPE_SPKI_set_pubkey(NETSCAPE_SPKI *spki, - EVP_PKEY *pkey); - -// NETSCAPE_SPKI_sign signs |spki| with |pkey| and replaces the signature -// algorithm and signature fields. It returns the length of the signature on -// success and zero on error. This function uses digest algorithm |md|, or -// |pkey|'s default if NULL. Other signing parameters use |pkey|'s defaults. -OPENSSL_EXPORT int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *spki, EVP_PKEY *pkey, - const EVP_MD *md); - // X509_REVOKED_dup returns a newly-allocated copy of |rev|, or NULL on error. // This function works by serializing the structure, so if |rev| is incomplete, // it may fail. @@ -2246,9 +2302,6 @@ OPENSSL_EXPORT X509_PKEY *X509_PKEY_new(void); OPENSSL_EXPORT void X509_PKEY_free(X509_PKEY *a); -DECLARE_ASN1_FUNCTIONS_const(NETSCAPE_SPKI) -DECLARE_ASN1_FUNCTIONS_const(NETSCAPE_SPKAC) - OPENSSL_EXPORT X509_INFO *X509_INFO_new(void); OPENSSL_EXPORT void X509_INFO_free(X509_INFO *a);