Document a few more functions in x509.h.

While I'm there, tidy up some variable names and stray parens.

Change-Id: Ifec36a532b9e9799a633b6e3b250b74255620283
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/42665
Reviewed-by: Adam Langley <agl@google.com>

crypto/x509/x509_txt.c

@@ -56,144 +56,144 @@
 
 #include <openssl/x509.h>
 
-const char *X509_verify_cert_error_string(long n)
+const char *X509_verify_cert_error_string(long err)
 {
-    switch ((int)n) {
+    switch (err) {
     case X509_V_OK:
-        return ("ok");
+        return "ok";
     case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT:
-        return ("unable to get issuer certificate");
+        return "unable to get issuer certificate";
     case X509_V_ERR_UNABLE_TO_GET_CRL:
-        return ("unable to get certificate CRL");
+        return "unable to get certificate CRL";
     case X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE:
-        return ("unable to decrypt certificate's signature");
+        return "unable to decrypt certificate's signature";
     case X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE:
-        return ("unable to decrypt CRL's signature");
+        return "unable to decrypt CRL's signature";
     case X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY:
-        return ("unable to decode issuer public key");
+        return "unable to decode issuer public key";
     case X509_V_ERR_CERT_SIGNATURE_FAILURE:
-        return ("certificate signature failure");
+        return "certificate signature failure";
     case X509_V_ERR_CRL_SIGNATURE_FAILURE:
-        return ("CRL signature failure");
+        return "CRL signature failure";
     case X509_V_ERR_CERT_NOT_YET_VALID:
-        return ("certificate is not yet valid");
+        return "certificate is not yet valid";
     case X509_V_ERR_CRL_NOT_YET_VALID:
-        return ("CRL is not yet valid");
+        return "CRL is not yet valid";
     case X509_V_ERR_CERT_HAS_EXPIRED:
-        return ("certificate has expired");
+        return "certificate has expired";
     case X509_V_ERR_CRL_HAS_EXPIRED:
-        return ("CRL has expired");
+        return "CRL has expired";
     case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD:
-        return ("format error in certificate's notBefore field");
+        return "format error in certificate's notBefore field";
     case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD:
-        return ("format error in certificate's notAfter field");
+        return "format error in certificate's notAfter field";
     case X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD:
-        return ("format error in CRL's lastUpdate field");
+        return "format error in CRL's lastUpdate field";
     case X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD:
-        return ("format error in CRL's nextUpdate field");
+        return "format error in CRL's nextUpdate field";
     case X509_V_ERR_OUT_OF_MEM:
-        return ("out of memory");
+        return "out of memory";
     case X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT:
-        return ("self signed certificate");
+        return "self signed certificate";
     case X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN:
-        return ("self signed certificate in certificate chain");
+        return "self signed certificate in certificate chain";
     case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY:
-        return ("unable to get local issuer certificate");
+        return "unable to get local issuer certificate";
     case X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE:
-        return ("unable to verify the first certificate");
+        return "unable to verify the first certificate";
     case X509_V_ERR_CERT_CHAIN_TOO_LONG:
-        return ("certificate chain too long");
+        return "certificate chain too long";
     case X509_V_ERR_CERT_REVOKED:
-        return ("certificate revoked");
+        return "certificate revoked";
     case X509_V_ERR_INVALID_CA:
-        return ("invalid CA certificate");
+        return "invalid CA certificate";
     case X509_V_ERR_INVALID_NON_CA:
-        return ("invalid non-CA certificate (has CA markings)");
+        return "invalid non-CA certificate (has CA markings)";
     case X509_V_ERR_PATH_LENGTH_EXCEEDED:
-        return ("path length constraint exceeded");
+        return "path length constraint exceeded";
     case X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED:
-        return ("proxy path length constraint exceeded");
+        return "proxy path length constraint exceeded";
     case X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED:
         return
-            ("proxy certificates not allowed, please set the appropriate flag");
+            "proxy certificates not allowed, please set the appropriate flag";
     case X509_V_ERR_INVALID_PURPOSE:
-        return ("unsupported certificate purpose");
+        return "unsupported certificate purpose";
     case X509_V_ERR_CERT_UNTRUSTED:
-        return ("certificate not trusted");
+        return "certificate not trusted";
     case X509_V_ERR_CERT_REJECTED:
-        return ("certificate rejected");
+        return "certificate rejected";
     case X509_V_ERR_APPLICATION_VERIFICATION:
-        return ("application verification failure");
+        return "application verification failure";
     case X509_V_ERR_SUBJECT_ISSUER_MISMATCH:
-        return ("subject issuer mismatch");
+        return "subject issuer mismatch";
     case X509_V_ERR_AKID_SKID_MISMATCH:
-        return ("authority and subject key identifier mismatch");
+        return "authority and subject key identifier mismatch";
     case X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH:
-        return ("authority and issuer serial number mismatch");
+        return "authority and issuer serial number mismatch";
     case X509_V_ERR_KEYUSAGE_NO_CERTSIGN:
-        return ("key usage does not include certificate signing");
+        return "key usage does not include certificate signing";
     case X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER:
-        return ("unable to get CRL issuer certificate");
+        return "unable to get CRL issuer certificate";
     case X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION:
-        return ("unhandled critical extension");
+        return "unhandled critical extension";
     case X509_V_ERR_KEYUSAGE_NO_CRL_SIGN:
-        return ("key usage does not include CRL signing");
+        return "key usage does not include CRL signing";
     case X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE:
-        return ("key usage does not include digital signature");
+        return "key usage does not include digital signature";
     case X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION:
-        return ("unhandled critical CRL extension");
+        return "unhandled critical CRL extension";
     case X509_V_ERR_INVALID_EXTENSION:
-        return ("invalid or inconsistent certificate extension");
+        return "invalid or inconsistent certificate extension";
     case X509_V_ERR_INVALID_POLICY_EXTENSION:
-        return ("invalid or inconsistent certificate policy extension");
+        return "invalid or inconsistent certificate policy extension";
     case X509_V_ERR_NO_EXPLICIT_POLICY:
-        return ("no explicit policy");
+        return "no explicit policy";
     case X509_V_ERR_DIFFERENT_CRL_SCOPE:
-        return ("Different CRL scope");
+        return "Different CRL scope";
     case X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE:
-        return ("Unsupported extension feature");
+        return "Unsupported extension feature";
     case X509_V_ERR_UNNESTED_RESOURCE:
-        return ("RFC 3779 resource not subset of parent's resources");
+        return "RFC 3779 resource not subset of parent's resources";
 
     case X509_V_ERR_PERMITTED_VIOLATION:
-        return ("permitted subtree violation");
+        return "permitted subtree violation";
     case X509_V_ERR_EXCLUDED_VIOLATION:
-        return ("excluded subtree violation");
+        return "excluded subtree violation";
     case X509_V_ERR_SUBTREE_MINMAX:
-        return ("name constraints minimum and maximum not supported");
+        return "name constraints minimum and maximum not supported";
     case X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE:
-        return ("unsupported name constraint type");
+        return "unsupported name constraint type";
     case X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX:
-        return ("unsupported or invalid name constraint syntax");
+        return "unsupported or invalid name constraint syntax";
     case X509_V_ERR_UNSUPPORTED_NAME_SYNTAX:
-        return ("unsupported or invalid name syntax");
+        return "unsupported or invalid name syntax";
     case X509_V_ERR_CRL_PATH_VALIDATION_ERROR:
-        return ("CRL path validation error");
+        return "CRL path validation error";
 
     case X509_V_ERR_SUITE_B_INVALID_VERSION:
-        return ("Suite B: certificate version invalid");
+        return "Suite B: certificate version invalid";
     case X509_V_ERR_SUITE_B_INVALID_ALGORITHM:
-        return ("Suite B: invalid public key algorithm");
+        return "Suite B: invalid public key algorithm";
     case X509_V_ERR_SUITE_B_INVALID_CURVE:
-        return ("Suite B: invalid ECC curve");
+        return "Suite B: invalid ECC curve";
     case X509_V_ERR_SUITE_B_INVALID_SIGNATURE_ALGORITHM:
-        return ("Suite B: invalid signature algorithm");
+        return "Suite B: invalid signature algorithm";
     case X509_V_ERR_SUITE_B_LOS_NOT_ALLOWED:
-        return ("Suite B: curve not allowed for this LOS");
+        return "Suite B: curve not allowed for this LOS";
     case X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256:
-        return ("Suite B: cannot sign P-384 with P-256");
+        return "Suite B: cannot sign P-384 with P-256";
 
     case X509_V_ERR_HOSTNAME_MISMATCH:
-        return ("Hostname mismatch");
+        return "Hostname mismatch";
     case X509_V_ERR_EMAIL_MISMATCH:
-        return ("Email address mismatch");
+        return "Email address mismatch";
     case X509_V_ERR_IP_ADDRESS_MISMATCH:
-        return ("IP address mismatch");
+        return "IP address mismatch";
 
     case X509_V_ERR_INVALID_CALL:
-        return ("Invalid certificate verification context");
+        return "Invalid certificate verification context";
     case X509_V_ERR_STORE_LOOKUP:
-        return ("Issuer certificate lookup error");
+        return "Issuer certificate lookup error";
 
     case X509_V_ERR_NAME_CONSTRAINTS_WITHOUT_SANS:
         return "Issuer has name constraints but leaf has no SANs";

crypto/x509/x_all.c

@@ -66,20 +66,20 @@
 #include <openssl/rsa.h>
 #include <openssl/stack.h>
 
-int X509_verify(X509 *a, EVP_PKEY *r)
+int X509_verify(X509 *x509, EVP_PKEY *pkey)
 {
-    if (X509_ALGOR_cmp(a->sig_alg, a->cert_info->signature)) {
+    if (X509_ALGOR_cmp(x509->sig_alg, x509->cert_info->signature)) {
         OPENSSL_PUT_ERROR(X509, X509_R_SIGNATURE_ALGORITHM_MISMATCH);
         return 0;
     }
-    return (ASN1_item_verify(ASN1_ITEM_rptr(X509_CINF), a->sig_alg,
-                             a->signature, a->cert_info, r));
+    return ASN1_item_verify(ASN1_ITEM_rptr(X509_CINF), x509->sig_alg,
+                            x509->signature, x509->cert_info, pkey);
 }
 
-int X509_REQ_verify(X509_REQ *a, EVP_PKEY *r)
+int X509_REQ_verify(X509_REQ *req, EVP_PKEY *pkey)
 {
-    return (ASN1_item_verify(ASN1_ITEM_rptr(X509_REQ_INFO),
-                             a->sig_alg, a->signature, a->req_info, r));
+    return ASN1_item_verify(ASN1_ITEM_rptr(X509_REQ_INFO),
+                            req->sig_alg, req->signature, req->req_info, pkey);
 }
 
 int X509_sign(X509 *x, EVP_PKEY *pkey, const EVP_MD *md)
@@ -131,10 +131,10 @@ int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *x, EVP_PKEY *pkey, const EVP_MD *md)
                            x->signature, x->spkac, pkey, md));
 }
 
-int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *x, EVP_PKEY *pkey)
+int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *spki, EVP_PKEY *pkey)
 {
-    return (ASN1_item_verify(ASN1_ITEM_rptr(NETSCAPE_SPKAC), x->sig_algor,
-                             x->signature, x->spkac, pkey));
+    return (ASN1_item_verify(ASN1_ITEM_rptr(NETSCAPE_SPKAC), spki->sig_algor,
+                             spki->signature, spki->spkac, pkey));
 }
 
 #ifndef OPENSSL_NO_FP_API

crypto/x509/x_crl.c

@@ -411,10 +411,10 @@ int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev)
     return 1;
 }
 
-int X509_CRL_verify(X509_CRL *crl, EVP_PKEY *r)
+int X509_CRL_verify(X509_CRL *crl, EVP_PKEY *pkey)
 {
     if (crl->meth->crl_verify)
-        return crl->meth->crl_verify(crl, r);
+        return crl->meth->crl_verify(crl, pkey);
     return 0;
 }
 

include/openssl/x509.h

@@ -643,14 +643,31 @@ OPENSSL_EXPORT void *X509_CRL_get_meth_data(X509_CRL *crl);
 // object.
 OPENSSL_EXPORT X509_PUBKEY *X509_get_X509_PUBKEY(const X509 *x509);
 
-OPENSSL_EXPORT const char *X509_verify_cert_error_string(long n);
+// 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.
+//
+// TODO(davidben): Move this function to x509_vfy.h, with the |X509_V_*|
+// definitions, or fold x509_vfy.h into this function.
+OPENSSL_EXPORT const char *X509_verify_cert_error_string(long err);
 
-#ifndef OPENSSL_NO_EVP
-OPENSSL_EXPORT int X509_verify(X509 *a, EVP_PKEY *r);
+// X509_verify checks that |x509| has a valid signature by |pkey|. It returns
+// one if the signature is valid and zero otherwise. Note this function only
+// checks the signature itself and does not perform a full certificate
+// validation.
+OPENSSL_EXPORT int X509_verify(X509 *x509, EVP_PKEY *pkey);
+
+// X509_REQ_verify checks that |req| has a valid signature by |pkey|. It returns
+// one if the signature is valid and zero otherwise.
+OPENSSL_EXPORT int X509_REQ_verify(X509_REQ *req, EVP_PKEY *pkey);
+
+// X509_CRL_verify checks that |crl| has a valid signature by |pkey|. It returns
+// one if the signature is valid and zero otherwise.
+OPENSSL_EXPORT int X509_CRL_verify(X509_CRL *crl, EVP_PKEY *pkey);
 
-OPENSSL_EXPORT int X509_REQ_verify(X509_REQ *a, EVP_PKEY *r);
-OPENSSL_EXPORT int X509_CRL_verify(X509_CRL *a, EVP_PKEY *r);
-OPENSSL_EXPORT int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *a, EVP_PKEY *r);
+// 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);
 
 OPENSSL_EXPORT NETSCAPE_SPKI *NETSCAPE_SPKI_b64_decode(const char *str,
                                                        int len);
@@ -684,7 +701,6 @@ OPENSSL_EXPORT int X509_REQ_digest(const X509_REQ *data, const EVP_MD *type,
                                    unsigned char *md, unsigned int *len);
 OPENSSL_EXPORT int X509_NAME_digest(const X509_NAME *data, const EVP_MD *type,
                                     unsigned char *md, unsigned int *len);
-#endif
 
 // X509_parse_from_buffer parses an X.509 structure from |buf| and returns a
 // fresh X509 or NULL on error. There must not be any trailing data in |buf|.
@@ -882,7 +898,6 @@ OPENSSL_EXPORT void X509_PKEY_free(X509_PKEY *a);
 DECLARE_ASN1_FUNCTIONS(NETSCAPE_SPKI)
 DECLARE_ASN1_FUNCTIONS(NETSCAPE_SPKAC)
 
-#ifndef OPENSSL_NO_EVP
 OPENSSL_EXPORT X509_INFO *X509_INFO_new(void);
 OPENSSL_EXPORT void X509_INFO_free(X509_INFO *a);
 OPENSSL_EXPORT char *X509_NAME_oneline(const X509_NAME *a, char *buf, int size);
@@ -906,7 +921,6 @@ OPENSSL_EXPORT int ASN1_item_sign_ctx(const ASN1_ITEM *it, X509_ALGOR *algor1,
                                       X509_ALGOR *algor2,
                                       ASN1_BIT_STRING *signature, void *asn,
                                       EVP_MD_CTX *ctx);
-#endif
 
 OPENSSL_EXPORT int X509_set_version(X509 *x, long version);
 OPENSSL_EXPORT int X509_set_serialNumber(X509 *x, ASN1_INTEGER *serial);