BoringSSL Documentation

gMock is a C++ framework for creating and using mock classes. It is designed to help developers derive better system designs and write more effective tests by providing a declarative syntax for defining mocks and controlling their behavior.

Key features include:

• Declarative Mock Definition: Define mock objects using a specialized syntax.
• Partial (Hybrid) Mocks: Create objects that combine real implementation with mocked behavior.
• Argument Validation: Uses a rich set of matchers to validate function arguments.
• Behavior Control: Intuitive syntax for specifying how mocks should respond to calls.
• Automatic Verification: Automatically verifies expectations without requiring a manual record-and-replay step.
• Ordering Constraints: Supports expressing arbitrary (partial) ordering constraints on function calls.
• Extensibility: Users can define custom matchers and actions.
• No Exceptions: Designed to work without relying on C++ exceptions.
• Type Support: Handles functions of arbitrary types and overloaded functions.

The following testing patterns are demonstrated in the Googletest sample directory:

• Basic Testing: Testing simple C++ functions (Sample #1).
• Class Testing: Unit testing classes with multiple member functions (Sample #2).
• Test Fixtures: Using testing::Test to share setup/teardown logic (Sample #3).
• Fixture Inheritance: Using a base test fixture to provide shared logic to derived fixtures (Sample #5).
• Type-Parameterized Tests: Running the same test logic against different types (Sample #6).
• Value-Parameterized Tests: Running tests with different input values, including the use of Combine() to create Cartesian products of parameters (Samples #7 and #8).
• Listener and Reflection APIs: Using the listener API to modify console output or implement custom tools like a memory leak checker, and using the reflection API to inspect test results (Samples #9 and #10).

When testing different implementations of the same interface, choose based on your setup requirements:

• Use Typed Tests if:

  • Instances of different implementations can be created similarly (e.g., via a common default constructor or a templated factory function like CreateInstance<TypeParam>()).
  • You want the default output to include the specific type name when a test fails.
  • Note: You must ensure you are testing against the interface type (e.g., using implicit_cast<MyInterface*>(my_concrete_impl)) rather than just the concrete type.

• Use Value-Parameterized Tests if:

  • You need different code patterns to create instances (e.g., new Foo vs new Bar(5)).
  • It is easier to wrap differences in factory function pointers passed as parameters.
  • Note: By default, these only show the iteration number on failure. To get useful output, define a function that returns the iteration name and pass it as the third parameter to INSTANTIATE_TEST_SUITE_P.

BoringSSL's C-based APIs do not support closures (functions with bound variables). To pass application-specific state to a callback, you must use one of two patterns depending on the API signature:

1. APIs with an explicit arg parameter: These APIs provide a void *arg parameter that is passed back to your callback. You can use this to pass a pointer to a C++ object, such as a std::function.
2. APIs without an explicit arg parameter: These APIs expect the callback to retrieve state from the object being operated on (e.g., an SSL object). In these cases, use ex_data to associate your application state with the BoringSSL object.

Important: You must ensure that any state passed via arg or ex_data outlives the BoringSSL object to avoid use-after-free errors.

// Pattern 1: Using an explicit 'arg' parameter with std::function
int RunCertCallback(SSL *ssl, void *arg) {
  auto *f = static_cast<std::function<int(SSL*)>*>(arg);
  return (*f)(ssl);
}

std::function<int(SSL*)> cert_cb = ...;
SSL_CTX_set_cert_cb(ctx, RunCertCallback, &cert_cb);

To reduce memory overhead and avoid duplicating certificate data in memory, BoringSSL provides a buffer-based approach instead of using standard OpenSSL X509 structures. This is highly recommended for applications making many TLS connections.

Key Components

• CRYPTO_BUFFER: An opaque byte string representing certificate data.
• CRYPTO_BUFFER_POOL: An intern table that ensures only a single copy of any given byte string is kept in a pool, enabling deduplication across connections and SSL_CTXs.

Implementation Steps

1. Use Buffer-based Methods: Use TLS_with_buffers_method to return an SSL_METHOD that avoids creating X509 objects.
2. Install a Pool: Use SSL_CTX_set1_buffer_pool to install a pool on an SSL_CTX for deduplication.
3. Avoid X509 APIs: When using buffers, do not call functions that deal with X509 or X509_NAME objects (e.g., SSL_get_peer_certificate or SSL_get_peer_cert_chain). Doing so will trigger an assert in debug mode or return NULL in release mode.
4. Use Buffer Alternatives: Use buffer-based alternatives like SSL_get0_peer_certificates (check ssl.h for specific functions taking/returning CRYPTO_BUFFER).
5. Implement Custom Verification: Because auto-chaining is disabled when using buffers, you must implement your own certificate verification using SSL_[CTX_]set_custom_verify, otherwise all connections will fail.

Using these APIs allows you to eventually eliminate the OpenSSL X.509 and ASN.1 code from your binary if linked statically.