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