Tidy up docs for #defines.
This removes the special-case for #defines in doc.go.
Change-Id: I6bf750485a94ad28c3975644c74a17c550bb3224
Reviewed-on: https://boringssl-review.googlesource.com/31505
Reviewed-by: Adam Langley <agl@google.com>
diff --git a/include/openssl/bio.h b/include/openssl/bio.h
index adb641b..dcf8ab7 100644
--- a/include/openssl/bio.h
+++ b/include/openssl/bio.h
@@ -677,26 +677,49 @@
OPENSSL_EXPORT int BIO_get_init(BIO *bio);
// These are values of the |cmd| argument to |BIO_ctrl|.
-#define BIO_CTRL_RESET 1 // opt - rewind/zero etc
-#define BIO_CTRL_EOF 2 // opt - are we at the eof
-#define BIO_CTRL_INFO 3 // opt - extra tit-bits
-#define BIO_CTRL_SET 4 // man - set the 'IO' type
-#define BIO_CTRL_GET 5 // man - get the 'IO' type
-#define BIO_CTRL_PUSH 6
-#define BIO_CTRL_POP 7
-#define BIO_CTRL_GET_CLOSE 8 // man - set the 'close' on free
-#define BIO_CTRL_SET_CLOSE 9 // man - set the 'close' on free
-#define BIO_CTRL_PENDING 10 // opt - is their more data buffered
-#define BIO_CTRL_FLUSH 11 // opt - 'flush' buffered output
-#define BIO_CTRL_WPENDING 13 // opt - number of bytes still to write
-// callback is int cb(BIO *bio,state,ret);
-#define BIO_CTRL_SET_CALLBACK 14 // opt - set callback function
-#define BIO_CTRL_GET_CALLBACK 15 // opt - set callback function
-#define BIO_CTRL_SET_FILENAME 30 // BIO_s_file special
-// BIO_CTRL_DUP is never used, but exists to allow code to compile more
-// easily.
-#define BIO_CTRL_DUP 12
+// BIO_CTRL_RESET implements |BIO_reset|. The arguments are unused.
+#define BIO_CTRL_RESET 1
+
+// BIO_CTRL_EOF implements |BIO_eof|. The arguments are unused.
+#define BIO_CTRL_EOF 2
+
+// BIO_CTRL_INFO is a legacy command that returns information specific to the
+// type of |BIO|. It is not safe to call generically and should not be
+// implemented in new |BIO| types.
+#define BIO_CTRL_INFO 3
+
+// BIO_CTRL_GET_CLOSE returns the close flag set by |BIO_CTRL_SET_CLOSE|. The
+// arguments are unused.
+#define BIO_CTRL_GET_CLOSE 8
+
+// BIO_CTRL_SET_CLOSE implements |BIO_set_close|. The |larg| argument is the
+// close flag.
+#define BIO_CTRL_SET_CLOSE 9
+
+// BIO_CTRL_PENDING implements |BIO_pending|. The arguments are unused.
+#define BIO_CTRL_PENDING 10
+
+// BIO_CTRL_FLUSH implements |BIO_flush|. The arguments are unused.
+#define BIO_CTRL_FLUSH 11
+
+// BIO_CTRL_WPENDING implements |BIO_wpending|. The arguments are unused.
+#define BIO_CTRL_WPENDING 13
+
+// BIO_CTRL_SET_CALLBACK sets an informational callback of type
+// int cb(BIO *bio, int state, int ret)
+#define BIO_CTRL_SET_CALLBACK 14
+
+// BIO_CTRL_GET_CALLBACK returns the callback set by |BIO_CTRL_SET_CALLBACK|.
+#define BIO_CTRL_GET_CALLBACK 15
+
+// The following are never used, but are defined to aid porting existing code.
+#define BIO_CTRL_SET 4
+#define BIO_CTRL_GET 5
+#define BIO_CTRL_PUSH 6
+#define BIO_CTRL_POP 7
+#define BIO_CTRL_DUP 12
+#define BIO_CTRL_SET_FILENAME 30
// Deprecated functions.
@@ -733,8 +756,8 @@
#define BIO_FLAGS_RWS (BIO_FLAGS_READ | BIO_FLAGS_WRITE | BIO_FLAGS_IO_SPECIAL)
#define BIO_FLAGS_SHOULD_RETRY 0x08
#define BIO_FLAGS_BASE64_NO_NL 0x100
-// This is used with memory BIOs: it means we shouldn't free up or change the
-// data in any way.
+// BIO_FLAGS_MEM_RDONLY is used with memory BIOs. It means we shouldn't free up
+// or change the data in any way.
#define BIO_FLAGS_MEM_RDONLY 0x200
// These are the 'types' of BIOs
@@ -762,7 +785,7 @@
#define BIO_TYPE_ASN1 (22 | 0x0200) // filter
#define BIO_TYPE_COMP (23 | 0x0200) // filter
-// |BIO_TYPE_DESCRIPTOR| denotes that the |BIO| responds to the |BIO_C_SET_FD|
+// BIO_TYPE_DESCRIPTOR denotes that the |BIO| responds to the |BIO_C_SET_FD|
// (|BIO_set_fd|) and |BIO_C_GET_FD| (|BIO_get_fd|) control hooks.
#define BIO_TYPE_DESCRIPTOR 0x0100 // socket, fd, connect or accept
#define BIO_TYPE_FILTER 0x0200
@@ -809,61 +832,61 @@
size_t num_read, num_write;
};
-#define BIO_C_SET_CONNECT 100
-#define BIO_C_DO_STATE_MACHINE 101
-#define BIO_C_SET_NBIO 102
-#define BIO_C_SET_PROXY_PARAM 103
-#define BIO_C_SET_FD 104
-#define BIO_C_GET_FD 105
-#define BIO_C_SET_FILE_PTR 106
-#define BIO_C_GET_FILE_PTR 107
-#define BIO_C_SET_FILENAME 108
-#define BIO_C_SET_SSL 109
-#define BIO_C_GET_SSL 110
-#define BIO_C_SET_MD 111
-#define BIO_C_GET_MD 112
-#define BIO_C_GET_CIPHER_STATUS 113
-#define BIO_C_SET_BUF_MEM 114
-#define BIO_C_GET_BUF_MEM_PTR 115
-#define BIO_C_GET_BUFF_NUM_LINES 116
-#define BIO_C_SET_BUFF_SIZE 117
-#define BIO_C_SET_ACCEPT 118
-#define BIO_C_SSL_MODE 119
-#define BIO_C_GET_MD_CTX 120
-#define BIO_C_GET_PROXY_PARAM 121
-#define BIO_C_SET_BUFF_READ_DATA 122 // data to read first
-#define BIO_C_GET_ACCEPT 124
-#define BIO_C_SET_SSL_RENEGOTIATE_BYTES 125
-#define BIO_C_GET_SSL_NUM_RENEGOTIATES 126
-#define BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT 127
-#define BIO_C_FILE_SEEK 128
-#define BIO_C_GET_CIPHER_CTX 129
-#define BIO_C_SET_BUF_MEM_EOF_RETURN 130 //return end of input value
-#define BIO_C_SET_BIND_MODE 131
-#define BIO_C_GET_BIND_MODE 132
-#define BIO_C_FILE_TELL 133
-#define BIO_C_GET_SOCKS 134
-#define BIO_C_SET_SOCKS 135
+#define BIO_C_SET_CONNECT 100
+#define BIO_C_DO_STATE_MACHINE 101
+#define BIO_C_SET_NBIO 102
+#define BIO_C_SET_PROXY_PARAM 103
+#define BIO_C_SET_FD 104
+#define BIO_C_GET_FD 105
+#define BIO_C_SET_FILE_PTR 106
+#define BIO_C_GET_FILE_PTR 107
+#define BIO_C_SET_FILENAME 108
+#define BIO_C_SET_SSL 109
+#define BIO_C_GET_SSL 110
+#define BIO_C_SET_MD 111
+#define BIO_C_GET_MD 112
+#define BIO_C_GET_CIPHER_STATUS 113
+#define BIO_C_SET_BUF_MEM 114
+#define BIO_C_GET_BUF_MEM_PTR 115
+#define BIO_C_GET_BUFF_NUM_LINES 116
+#define BIO_C_SET_BUFF_SIZE 117
+#define BIO_C_SET_ACCEPT 118
+#define BIO_C_SSL_MODE 119
+#define BIO_C_GET_MD_CTX 120
+#define BIO_C_GET_PROXY_PARAM 121
+#define BIO_C_SET_BUFF_READ_DATA 122 // data to read first
+#define BIO_C_GET_ACCEPT 124
+#define BIO_C_SET_SSL_RENEGOTIATE_BYTES 125
+#define BIO_C_GET_SSL_NUM_RENEGOTIATES 126
+#define BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT 127
+#define BIO_C_FILE_SEEK 128
+#define BIO_C_GET_CIPHER_CTX 129
+#define BIO_C_SET_BUF_MEM_EOF_RETURN 130 // return end of input value
+#define BIO_C_SET_BIND_MODE 131
+#define BIO_C_GET_BIND_MODE 132
+#define BIO_C_FILE_TELL 133
+#define BIO_C_GET_SOCKS 134
+#define BIO_C_SET_SOCKS 135
-#define BIO_C_SET_WRITE_BUF_SIZE 136 // for BIO_s_bio
-#define BIO_C_GET_WRITE_BUF_SIZE 137
-#define BIO_C_GET_WRITE_GUARANTEE 140
-#define BIO_C_GET_READ_REQUEST 141
-#define BIO_C_SHUTDOWN_WR 142
-#define BIO_C_NREAD0 143
-#define BIO_C_NREAD 144
-#define BIO_C_NWRITE0 145
-#define BIO_C_NWRITE 146
-#define BIO_C_RESET_READ_REQUEST 147
-#define BIO_C_SET_MD_CTX 148
+#define BIO_C_SET_WRITE_BUF_SIZE 136 // for BIO_s_bio
+#define BIO_C_GET_WRITE_BUF_SIZE 137
+#define BIO_C_GET_WRITE_GUARANTEE 140
+#define BIO_C_GET_READ_REQUEST 141
+#define BIO_C_SHUTDOWN_WR 142
+#define BIO_C_NREAD0 143
+#define BIO_C_NREAD 144
+#define BIO_C_NWRITE0 145
+#define BIO_C_NWRITE 146
+#define BIO_C_RESET_READ_REQUEST 147
+#define BIO_C_SET_MD_CTX 148
-#define BIO_C_SET_PREFIX 149
-#define BIO_C_GET_PREFIX 150
-#define BIO_C_SET_SUFFIX 151
-#define BIO_C_GET_SUFFIX 152
+#define BIO_C_SET_PREFIX 149
+#define BIO_C_GET_PREFIX 150
+#define BIO_C_SET_SUFFIX 151
+#define BIO_C_GET_SUFFIX 152
-#define BIO_C_SET_EX_ARG 153
-#define BIO_C_GET_EX_ARG 154
+#define BIO_C_SET_EX_ARG 153
+#define BIO_C_GET_EX_ARG 154
#if defined(__cplusplus)
diff --git a/include/openssl/bn.h b/include/openssl/bn.h
index e8cc70a..82195ed 100644
--- a/include/openssl/bn.h
+++ b/include/openssl/bn.h
@@ -630,9 +630,12 @@
// BN_pseudo_rand_range is an alias for BN_rand_range.
OPENSSL_EXPORT int BN_pseudo_rand_range(BIGNUM *rnd, const BIGNUM *range);
-// BN_GENCB holds a callback function that is used by generation functions that
-// can take a very long time to complete. Use |BN_GENCB_set| to initialise a
-// |BN_GENCB| structure.
+#define BN_GENCB_GENERATED 0
+#define BN_GENCB_PRIME_TEST 1
+
+// bn_gencb_st, or |BN_GENCB|, holds a callback function that is used by
+// generation functions that can take a very long time to complete. Use
+// |BN_GENCB_set| to initialise a |BN_GENCB| structure.
//
// The callback receives the address of that |BN_GENCB| structure as its last
// argument and the user is free to put an arbitrary pointer in |arg|. The other
@@ -648,9 +651,6 @@
//
// When other code needs to call a BN generation function it will often take a
// BN_GENCB argument and may call the function with other argument values.
-#define BN_GENCB_GENERATED 0
-#define BN_GENCB_PRIME_TEST 1
-
struct bn_gencb_st {
void *arg; // callback-specific data
int (*callback)(int event, int n, struct bn_gencb_st *);
diff --git a/include/openssl/cipher.h b/include/openssl/cipher.h
index 727d7a7..b8d4e52 100644
--- a/include/openssl/cipher.h
+++ b/include/openssl/cipher.h
@@ -438,7 +438,7 @@
// EVP_CIPH_NO_PADDING disables padding in block ciphers.
#define EVP_CIPH_NO_PADDING 0x800
-// EVP_CIPHER_CTX_ctrl commands.
+// The following are |EVP_CIPHER_CTX_ctrl| commands.
#define EVP_CTRL_INIT 0x0
#define EVP_CTRL_SET_KEY_LENGTH 0x1
#define EVP_CTRL_GET_RC2_KEY_BITS 0x2
@@ -454,15 +454,12 @@
#define EVP_CTRL_AEAD_SET_IV_FIXED 0x12
#define EVP_CTRL_GCM_IV_GEN 0x13
#define EVP_CTRL_AEAD_SET_MAC_KEY 0x17
-// Set the GCM invocation field, decrypt only
+// EVP_CTRL_GCM_SET_IV_INV sets the GCM invocation field, decrypt only
#define EVP_CTRL_GCM_SET_IV_INV 0x18
-// GCM TLS constants
-// Length of fixed part of IV derived from PRF
+// The following constants are unused.
#define EVP_GCM_TLS_FIXED_IV_LEN 4
-// Length of explicit part of IV part of TLS records
#define EVP_GCM_TLS_EXPLICIT_IV_LEN 8
-// Length of tag for TLS
#define EVP_GCM_TLS_TAG_LEN 16
// The following are legacy aliases for AEAD |EVP_CIPHER_CTX_ctrl| values.
diff --git a/include/openssl/rsa.h b/include/openssl/rsa.h
index 98bb31c..47e2d34 100644
--- a/include/openssl/rsa.h
+++ b/include/openssl/rsa.h
@@ -175,11 +175,19 @@
// These functions are considered non-mutating for thread-safety purposes and
// may be used concurrently.
-// Padding types for encryption.
+// RSA_PKCS1_PADDING denotes PKCS#1 v1.5 padding. When used with encryption,
+// this is RSAES-PKCS1-v1_5. When used with signing, this is RSASSA-PKCS1-v1_5.
#define RSA_PKCS1_PADDING 1
+
+// RSA_NO_PADDING denotes a raw RSA operation.
#define RSA_NO_PADDING 3
+
+// RSA_PKCS1_OAEP_PADDING denotes the RSAES-OAEP encryption scheme.
#define RSA_PKCS1_OAEP_PADDING 4
-// RSA_PKCS1_PSS_PADDING can only be used via the EVP interface.
+
+// RSA_PKCS1_PSS_PADDING denotes the RSASSA-PSS signature scheme. This value may
+// not be passed into |RSA_sign_raw|, only |EVP_PKEY_CTX_set_rsa_padding|. See
+// also |RSA_sign_pss_mgf1| and |RSA_verify_pss_mgf1|.
#define RSA_PKCS1_PSS_PADDING 6
// RSA_encrypt encrypts |in_len| bytes from |in| to the public key from |rsa|
@@ -285,7 +293,8 @@
//
// The |padding| argument must be one of the |RSA_*_PADDING| values. If in
// doubt, |RSA_PKCS1_PADDING| is the most common but |RSA_PKCS1_PSS_PADDING|
-// (via the |EVP_PKEY| interface) is preferred for new protocols.
+// (via |RSA_sign_pss_mgf1| or the |EVP_PKEY| interface) is preferred for new
+// protocols.
OPENSSL_EXPORT int RSA_sign_raw(RSA *rsa, size_t *out_len, uint8_t *out,
size_t max_out, const uint8_t *in,
size_t in_len, int padding);
@@ -330,7 +339,8 @@
//
// The |padding| argument must be one of the |RSA_*_PADDING| values. If in
// doubt, |RSA_PKCS1_PADDING| is the most common but |RSA_PKCS1_PSS_PADDING|
-// (via the |EVP_PKEY| interface) is preferred for new protocols.
+// (via |RSA_verify_pss_mgf1| or the |EVP_PKEY| interface) is preferred for new
+// protocols.
OPENSSL_EXPORT int RSA_verify_raw(RSA *rsa, size_t *out_len, uint8_t *out,
size_t max_out, const uint8_t *in,
size_t in_len, int padding);
diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h
index daa58b0..5546f4e 100644
--- a/include/openssl/ssl.h
+++ b/include/openssl/ssl.h
@@ -4314,6 +4314,7 @@
//
// These defines exist for node.js, with the hope that we can eliminate the
// need for them over time.
+
#define SSLerr(function, reason) \
ERR_put_error(ERR_LIB_SSL, 0, reason, __FILE__, __LINE__)
diff --git a/util/doc.go b/util/doc.go
index 040ac79..ab21547 100644
--- a/util/doc.go
+++ b/util/doc.go
@@ -82,6 +82,19 @@
return strings.HasPrefix(line, commentStart) || strings.HasPrefix(line, lineComment)
}
+func commentSubject(line string) string {
+ if strings.HasPrefix(line, "A ") {
+ line = line[len("A "):]
+ } else if strings.HasPrefix(line, "An ") {
+ line = line[len("An "):]
+ }
+ idx := strings.IndexAny(line, " ,")
+ if idx < 0 {
+ return line
+ }
+ return line[:idx]
+}
+
func extractComment(lines []string, lineNo int) (comment []string, rest []string, restLineNo int, err error) {
if len(lines) == 0 {
return nil, lines, lineNo, nil
@@ -426,17 +439,22 @@
// As a matter of style, comments should start
// with the name of the thing that they are
// commenting on. We make an exception here for
- // #defines (because we often have blocks of
- // them) and collective comments, which are
- // detected by starting with “The” or “These”.
+ // collective comments, which are detected by
+ // starting with “The” or “These”.
if len(comment) > 0 &&
- !strings.HasPrefix(comment[0], name) &&
- !strings.HasPrefix(comment[0], "A "+name) &&
- !strings.HasPrefix(comment[0], "An "+name) &&
- !strings.HasPrefix(decl, "#define ") &&
+ len(name) > 0 &&
!strings.HasPrefix(comment[0], "The ") &&
!strings.HasPrefix(comment[0], "These ") {
- return nil, fmt.Errorf("Comment for %q doesn't seem to match line %s:%d\n", name, path, declLineNo)
+ subject := commentSubject(comment[0])
+ ok := subject == name
+ if l := len(subject); l > 0 && subject[l-1] == '*' {
+ // Groups of names, notably #defines, are often
+ // denoted with a wildcard.
+ ok = strings.HasPrefix(name, subject[:l-1])
+ }
+ if !ok {
+ return nil, fmt.Errorf("Comment for %q doesn't seem to match line %s:%d\n", name, path, declLineNo)
+ }
}
anchor := sanitizeAnchor(name)
// TODO(davidben): Enforce uniqueness. This is
