crashpad/util/win/registration_protocol_win.h

// Copyright 2015 The Crashpad Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#ifndef CRASHPAD_UTIL_WIN_REGISTRATION_PROTOCOL_WIN_H_
#define CRASHPAD_UTIL_WIN_REGISTRATION_PROTOCOL_WIN_H_

#include <windows.h>
#include <stdint.h>

#include <string>

#include "util/win/address_types.h"

namespace crashpad {

#pragma pack(push, 1)

//! \brief Structure read out of the client process by the crash handler when an
//!     exception occurs.
struct ExceptionInformation {
  //! \brief The address of an EXCEPTION_POINTERS structure in the client
  //!     process that describes the exception.
  WinVMAddress exception_pointers;

  //! \brief The thread on which the exception happened.
  DWORD thread_id;
};

//! \brief Context to be passed to WerRegisterRuntimeExceptionModule().
//!
//! Used by the crashpad client, and the WER exception DLL.
struct WerRegistration {
  //! \brief The expected value of `version`. This should be changed whenever
  //!     this struct is modified incompatibly.
  enum { kWerRegistrationVersion = 1 };
  //! \brief Version field to detect skew between target process and helper.
  //!     Should be set to kWerRegistrationVersion.
  int version;
  //! \brief Used by DumpWithoutCrashing and the WER module to initiate a dump.
  //!     These handles are leaked in the client process.
  HANDLE dump_without_crashing;
  //! \brief Used by DumpWithoutCrashing to signal that a dump has been taken.
  //!     These handles are leaked in the client process.
  HANDLE dump_completed;
  //! \brief Set just before and cleared just after the events above are
  //!     triggered or signalled in a normal DumpWithoutCrashing call.
  //! When `true` the WER handler should not set the exception structures until
  //! after dump_completed has been signalled.
  bool in_dump_without_crashing;
  //! \brief Address of g_non_crash_exception_information.
  //!
  //! Provided by the target process. Just before dumping we will point
  //! (*crashpad_exception_info).exception_pointers at `pointers`. As WerFault
  //! loads the helper with the same bitness as the client this can be void*.
  void* crashpad_exception_info;
  //! \brief These will point into the `exception` and `context` members in this
  //!     structure.
  //!
  //! Filled in by the helper DLL.
  EXCEPTION_POINTERS pointers;
  //! \brief The exception provided by WerFault.
  //!
  //! Filled in by the helper DLL.
  EXCEPTION_RECORD exception;
  //! \brief The context provided by WerFault.
  //!
  //! Filled in by the helper DLL.
  CONTEXT context;
};

//! \brief A client registration request.
struct RegistrationRequest {
  //! \brief The expected value of `version`. This should be changed whenever
  //!     the messages or ExceptionInformation are modified incompatibly.
  enum { kMessageVersion = 1 };

  //! \brief Version field to detect skew between client and server. Should be
  //!     set to kMessageVersion.
  int version;

  //! \brief The PID of the client process.
  DWORD client_process_id;

  //! \brief The address, in the client process's address space, of an
  //!     ExceptionInformation structure, used when handling a crash dump
  //!     request.
  WinVMAddress crash_exception_information;

  //! \brief The address, in the client process's address space, of an
  //!     ExceptionInformation structure, used when handling a non-crashing dump
  //!     request.
  WinVMAddress non_crash_exception_information;

  //! \brief The address, in the client process's address space, of a
  //!     `CRITICAL_SECTION` allocated with a valid .DebugInfo field. This can
  //!     be accomplished by using
  //!     InitializeCriticalSectionWithDebugInfoIfPossible() or equivalent. This
  //!     value can be `0`, however then limited lock data will be available in
  //!     minidumps.
  WinVMAddress critical_section_address;
};

//! \brief A message only sent to the server by itself to trigger shutdown.
struct ShutdownRequest {
  //! \brief A randomly generated token used to validate the the shutdown
  //!     request was not sent from another process.
  uint64_t token;
};

//! \brief The message passed from client to server by
//!     SendToCrashHandlerServer().
struct ClientToServerMessage {
  //! \brief Indicates which field of the union is in use.
  enum Type : uint32_t {
    //! \brief For RegistrationRequest.
    kRegister,

    //! \brief For ShutdownRequest.
    kShutdown,

    //! \brief An empty message sent by the initial client in asynchronous mode.
    //!     No data is required, this just confirms that the server is ready to
    //!     accept client registrations.
    kPing,
  } type;

  union {
    RegistrationRequest registration;
    ShutdownRequest shutdown;
  };
};

//! \brief A client registration response.
struct RegistrationResponse {
  //! \brief An event `HANDLE`, valid in the client process, that should be
  //!     signaled to request a crash report. Clients should convert the value
  //!     to a `HANDLE` by calling IntToHandle().
  int request_crash_dump_event;

  //! \brief An event `HANDLE`, valid in the client process, that should be
  //!     signaled to request a non-crashing dump be taken. Clients should
  //!     convert the value to a `HANDLE` by calling IntToHandle().
  int request_non_crash_dump_event;

  //! \brief An event `HANDLE`, valid in the client process, that will be
  //!     signaled by the server when the non-crashing dump is complete. Clients
  //!     should convert the value to a `HANDLE` by calling IntToHandle().
  int non_crash_dump_completed_event;
};

//! \brief The response sent back to the client via SendToCrashHandlerServer().
union ServerToClientMessage {
  RegistrationResponse registration;
};

#pragma pack(pop)

//! \brief Connect over the given \a pipe_name, passing \a message to the
//!     server, storing the server's reply into \a response.
//!
//! Typically clients will not use this directly, instead using
//! CrashpadClient::SetHandler().
//!
//! \sa CrashpadClient::SetHandler()
bool SendToCrashHandlerServer(const std::wstring& pipe_name,
                              const ClientToServerMessage& message,
                              ServerToClientMessage* response);

//! \brief Wraps CreateNamedPipe() to create a single named pipe instance.
//!
//! \param[in] pipe_name The name to use for the pipe.
//! \param[in] first_instance If `true`, the named pipe instance will be
//!     created with `FILE_FLAG_FIRST_PIPE_INSTANCE`. This ensures that the the
//!     pipe name is not already in use when created. The first instance will be
//!     created with an untrusted integrity SACL so instances of this pipe can
//!     be connected to by processes of any integrity level.
HANDLE CreateNamedPipeInstance(const std::wstring& pipe_name,
                               bool first_instance);

//! \brief Returns the `SECURITY_DESCRIPTOR` blob that will be used for creating
//!     the connection pipe in CreateNamedPipeInstance().
//!
//! This function is only exposed for testing.
//!
//! \param[out] size The size of the returned blob. May be `nullptr` if not
//!     required.
//!
//! \return A pointer to a self-relative `SECURITY_DESCRIPTOR`. Ownership is not
//!     transferred to the caller.
const void* GetSecurityDescriptorForNamedPipeInstance(size_t* size);

//! \brief Returns the `SECURITY_DESCRIPTOR` blob that will be used for creating
//!     the connection pipe in CreateNamedPipeInstance() if the full descriptor
//!     can't be created.
//!
//! This function is only exposed for testing.
//!
//! \param[out] size The size of the returned blob. May be `nullptr` if not
//!     required.
//!
//! \return A pointer to a self-relative `SECURITY_DESCRIPTOR`. Ownership is not
//!     transferred to the caller.
const void* GetFallbackSecurityDescriptorForNamedPipeInstance(size_t* size);

}  // namespace crashpad

#endif  // CRASHPAD_UTIL_WIN_REGISTRATION_PROTOCOL_WIN_H_