RSA 身份验证代理 API 文档中的函数签名是否正确？

我有一些使用 RSA 身份验证代理记录的 API 的软件。该产品作为服务在域中的客户端计算机上运行，​​并通过与集中安装的“RSA 身份验证管理器”通信来对本地用户进行身份验证。

身份验证代理的 API 公开记录在此处：适用于 C 开发人员指南的身份验证代理 API 8.1.1 https://community.rsa.com/docs/DOC-36840。但是，文档似乎不正确，并且我无权访问 RSA 头文件 - 它们不是公开的；仅 PDF 文档可供下载，无需向 RSA 支付费用。如果这里有人可以访问最新头文件，你能帮我确认一下文档是否已经过时了吗？

API 文档中给出的函数签名似乎不正确 - 事实上，我绝对确信它们在 x64 机器上是错误的。例如，最新的 PDF 文档显示以下内容：

int WINAPI AceSetUserData(SDI_HANDLE hdl, unsigned int userData)
int WINAPI AceGetUserData(SDI_HANDLE hdl, unsigned int *pUserData)

该文档多次指出“userData”值是一个 32 位数量，例如在文档中AceInit, AceSetUserData, and AceGetUserData。文档的相关摘录AceGetUserData:

该函数是同步的，调用者必须提供一个指向 32 位存储区域（即无符号整数）的指针作为第二个参数，以便将用户数据值复制到其中。

这显然是错误的 - 从一些实验来看，如果您传入一个指向填充有 0xff 的缓冲区中心的指针，AceGetUserData is 确实写出 64 位值，而不是 32 位数量。

我的版本aceclnt.dll是 8.1.3.563；相应的文档标记为“Authentication Agent API 8.1 SP1”，这对应于 Authentication Agent 本身的版本 7.3.1。

测试代码

给出了完整的测试代码，即使它与问题根本无关...如果其他人运行测试代码对我来说没有用（我知道它的作用！），我需要的是有权访问 RSA 标头的人可以确认函数签名的文件。

#include <assert.h>
#include <stdlib.h>
#include <stdint.h>

#ifdef WIN32
#include <Windows.h>
#include <tchar.h>
#define SDAPI WINAPI
#else
#define SDAPI
#endif
typedef int SDI_HANDLE;
typedef uint32_t SD_BOOL;
typedef void (SDAPI* AceCallback)(SDI_HANDLE);
#define ACE_SUCCESS                    1
#define ACE_PROCESSING                 150

typedef SD_BOOL (SDAPI* AceInitializeEx_proto)(const char*, char*, uint32_t);
typedef int (SDAPI* AceInit_proto)(SDI_HANDLE*, void*, AceCallback);
typedef int (SDAPI* AceClose_proto)(SDI_HANDLE, AceCallback);

typedef int (SDAPI* AceGetUserData_proto)(SDI_HANDLE, void*);
typedef int (SDAPI* AceSetUserData_proto)(SDI_HANDLE, void*);

struct Api {
  AceInitializeEx_proto AceInitializeEx;
  AceInit_proto AceInit;
  AceClose_proto AceClose;
  AceGetUserData_proto AceGetUserData;
  AceSetUserData_proto AceSetUserData;
} api;

static void api_init(struct Api* api) {
  // All error-checking stripped...
  HMODULE dll = LoadLibrary(_T("aceclnt.dll")); // leak this for the demo
  api->AceInitializeEx = (AceInitializeEx_proto)GetProcAddress(dll, "AceInitializeEx");
  api->AceInit = (AceInit_proto)GetProcAddress(dll, "AceInit");
  api->AceClose = (AceClose_proto)GetProcAddress(dll, "AceClose");
  api->AceGetUserData = (AceGetUserData_proto)GetProcAddress(dll, "AceGetUserData");
  api->AceSetUserData = (AceSetUserData_proto)GetProcAddress(dll, "AceSetUserData");

  int success = api->AceInitializeEx("C:\\my\\conf\\directory", 0, 0);
  assert(success);
}

static void demoFunction(SDI_HANDLE handle) {
  union {
    unsigned char testBuffer[sizeof(void *) * 3];
    void *forceAlignment;
  } u;

  memset(u.testBuffer, 0xA5, sizeof u.testBuffer);

  int err = api.AceGetUserData(handle, (void*)(u.testBuffer + sizeof(void*)));
  assert(err == ACE_SUCCESS);

  fputs("DEBUG: testBuffer =", stderr);
  for (size_t i = 0; i < sizeof(u.testBuffer); i++) {
    if (i % 4 == 0)
      putc(' ', stderr);
    fprintf(stderr, "%02x", u.testBuffer[i]);
  }
  fputc('\n', stderr);
  // Prints:
  // DEBUG: testBuffer = a5a5a5a5 a5a5a5a5 00000000 00000000 a5a5a5a5 a5a5a5a5
  // According to the docs, this should only write out a 32-bit value
}

static void SDAPI demoCallback(SDI_HANDLE h) {
  fprintf(stderr, "Callback invoked, handle = %p\n", (void*)h);
}

int main(int argc, const char** argv)
{
  api_init(&api);
  SDI_HANDLE h;

  int err = api.AceInit(&h, /* contentious argument */ 0, &demoCallback);
  assert(err == ACE_PROCESSING);

  demoFunction(h);

  api.AceClose(h, 0);

  return 0;
}

当您从文档中复制函数/类型定义时，您基本上没有也永远不会拥有您正在使用的 .dll 版本的正确定义，并且可能总是以崩溃或更糟的情况而告终，未定义行为。

你可以做的是调试相应的.dll：

你运行 Visual Studio 吗？我记得 VS 可以在调试模式下输入函数调用并显示程序集，但现在不确定情况如何。但任何反汇编程序都应该可以做到这一点。作为x64 ABI https://msdn.microsoft.com/en-us/library/9z1stfyw.aspx登记rcx得到第一个参数，rdx第二。如果函数内部使用 32 位寄存器名称或清除高 32 位，则可以假定为 32 位整数。如果它使用它来加载地址（例如lea指令）你可以假设一个指针。但正如你所看到的，这可能不是你想要走的路......

那么你还剩下什么呢？

您链接的文档说明了 32 位和 64 位库 - 取决于您使用的平台。我猜您使用的是 64 位库，并且 RSA 没有更新该库的文档，但在某些时候开发人员需要将该库升级到 64 位。

因此，请这样想：如果您是 API 开发人员，什么可以迁移到 64 位，什么不可以。例如。需要跨 32/64 实现工作的所有内容（通过网络发送或在磁盘上存储和共享的内容）都无法触及。但实例本地的所有内容都可以迁移。作为userData似乎是一个运行时的事情，支持平台提供的任何内容都是有意义的：unsigned long在 64 位和unsigned int在 32 位上。

你已经明白了userData必须是 64 位。但这并不是因为该函数写出了 64 位整数，而是因为该函数首先看到的是 64 位值。由于整数是按值传递的（我猜一般来说，但绝对是在WINAPI https://msdn.microsoft.com/en-us/library/zxk0tw93.aspx），如果它是 32 位数据类型，则该函数绝对不可能看到完整的 64 位值。因此，API 开发人员很可能将数据类型更改为unsigned long（无论如何都是 64 位类型）。

PS：如果您最终将指针放入 userData 中，请将指针强制转换为uintptr_t并存储/读取该类型。