Simple PKCS #11 Remote Procedure Call (RPC) Protocol

1.1. Relationship to Other Protocols

While KMIP [KMIP] provides a comprehensive protocol for key management operations, the PKCS #11 RPC protocol serves a different purpose:¶

• Scope: PKCS #11 RPC is specifically designed for exposing existing PKCS #11 modules over a trusted communication channel, whereas KMIP is a general-purpose key management protocol¶

• Design Goals: PKCS #11 RPC prioritizes minimal overhead and faithful PKCS #11 semantics, making it suitable for local IPC scenarios¶

• Use Cases: PKCS #11 RPC is optimized for scenarios like sandbox forwarding, where existing PKCS #11 modules need to be accessed remotely without translation¶

The protocol does not aim to be a general-purpose key management protocol or to provide features beyond what PKCS #11 itself offers.¶

1.2. Conventions and Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

2.1. Architecture

The protocol consists of:¶

1. Transport Layer: Provides a reliable bidirectional byte stream¶

2. Message Layer: Defines message framing and serialization¶

3. Call Layer: Maps PKCS #11 functions to RPC calls¶

4. Version Negotiation: Allows clients and servers to agree on protocol capabilities¶

┌─────────────────────────────────────────────┐
│          PKCS #11 Application               │
└─────────────────┬───────────────────────────┘
                  │ PKCS #11 API
┌─────────────────▼───────────────────────────┐
│          PKCS #11 RPC Client                │
└─────────────────┬───────────────────────────┘
                  │ RPC Protocol
                  │ (over transport)
┌─────────────────▼───────────────────────────┐
│          PKCS #11 RPC Server                │
└─────────────────┬───────────────────────────┘
                  │ PKCS #11 API
┌─────────────────▼───────────────────────────┐
│     PKCS #11 Module (e.g., SoftHSM)         │
└─────────────────────────────────────────────┘

3.1. Transport Address

Formally, a transport address takes the following form (for explanation of Augmented BNF, see [RFC5234]).¶

pk11-transport-addr   = pk11-transport-type ":" pk11-transport-attrs
pk11-transport-attrs  = [ pk11-transport-attr *(";" pk11-transport-attr) ]
pk11-attr-name-char   = ALPHA / DIGIT / "-" / "_"
pk11-attr-value-char  = %x20-3A / %x3C-7E /
pk11-attr-value-qchar = pk11-attr-value-char / ("\" %x20-%7E)
pk11-attr-value       = *pk11-attr-value-char /
                        DQUOTE *pk11-attr-value-qchar DQUOTE
                             ; quoted strings may contain backslash escaped
                             ; characters, such as \;, \"
pk11-transport-attr   = 1*pk11-attr-name-char "=" *pk11-attr-value

In the p11-glue project [P11-GLUE], this is configured in module configuration files with the remote: keyword.¶

3.2. Transport Types

3.3. Transport Address Examples

This section contains some example of how transport can be identified using the transport address.¶

The p11-glue project [P11-GLUE] provides a simple helper program, p11-kit remote, which translates PKCS #11 RPC into C function calls.¶

The following example instructs the client to launch the p11-kit remote command and connect to it through a pipe transport.¶

exec:command="p11-kit remote /usr/lib64/pkcs11/libpkcs11module.so"

This is useful to sandbox a proprietary PKCS #11 modules. The command line of the above can be inside a sandbox created with bubblewrap.¶

exec:command="bwrap --unshare-all --dir /tmp --ro-bind /etc/conf /etc/conf --proc /proc --dev /dev --ro-bind /usr /usr --symlink /usr/lib64 /lib64 --ro-bind /run/pcscd /run/pcscd p11-kit remote /usr/lib64/pkcs11/libpkcs11module.so"

The p11-glue project [P11-GLUE] also provides a standalone server program, p11-kit server, which listens on a Unix domain socket. The following example tells the client to connect to a Unix domain socket on the path "/path/to/socket".¶

unix:path=/path/to/socket

Similarly, if the server is running on a host of a virtual machine, the client can connect to it with the following address, where CID 2 is the well-known address of the host.¶

vsock:cid=2;port=1111

4.1. Protocol Versions

The following protocol versions are defined:¶

• Version 0: Initial version supporting PKCS #11 2.x functions¶

• Version 1: Adds PKCS #11 3.0 functions (message-based encryption, C_LoginUser, C_SessionCancel)¶

• Version 2: Adds functions with mechanism parameter updates (C_InitToken2, C_DeriveKey2)¶

4.2. Negotiation Procedure

The version negotiation follows a challenge-and-reconnect approach for transports that support reconnection:¶

1. Client sends a single byte containing its maximum supported version¶

2. Server receives the client version byte¶

3. Server determines the negotiated version:¶

   • If client version > server maximum: use server maximum¶

   • Otherwise: use client version¶

4. Server sends a single byte containing the negotiated version¶

5. Client receives negotiated version byte¶

If the server does not support version negotiation (i.e., only supports version 0), it will not respond correctly to non-zero version bytes. In this case:¶

1. Client detects negotiation failure¶

2. Client disconnects from server¶

3. Client reconnects to server¶

4. Client sends version byte 0¶

5. Server acknowledges with version byte 0¶

Client                           Server
   |                                |
   |------- Version 2 (0x02) ------>|
   |                                | (Server max = 2)
   |<------ Version 2 (0x02) -------|
   |                                |

Client                           Server
   |                                |
   |------- Version 2 (0x02) ------>|
   |                                | (Server max = 1)
   |<------ Version 1 (0x01) -------|
   |                                |
   |---- Reconnect ---------------->|
   |                                |
   |------- Version 1 (0x01) ------>|
   |<------ Version 1 (0x01) -------|
   |                                |

Client                           Server (v0 only)
   |                                |
   |------- Version 2 (0x02) ------>|
   |                                | (No response or error)
   | <-- (Connection Error) --------|
   |                                |
   |---- Reconnect ---------------->|
   |                                |
   |------- Version 0 (0x00) ------>|
   |<------ Version 0 (0x00) -------|
   |                                |

5.1. Message Header

Each message begins with a 12-byte header:¶

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           Call Code                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                        Options Length                         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         Buffer Length                         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Where:¶

• Call Code (4 bytes): Unsigned 32-bit integer identifying the function call or response. For requests, this identifies the PKCS #11 function. For responses, this echoes the call code from the request.¶

• Options Length (4 bytes): Length in bytes of the options area¶

• Buffer Length (4 bytes): Length in bytes of the message body¶

All multi-byte integers are encoded in network byte order (big-endian).¶

5.2. Options Area

The options area contains transport-specific metadata. In the current implementation, it typically contains the module name for multi-module scenarios. The format of the options area is implementation-defined.¶

5.3. Message Body

The message body contains the serialized function arguments (for requests) or return values (for responses).¶

5.4. Call Codes

Call codes are monotonically increasing integers assigned by the client for request-response matching. The server MUST echo the call code in the response.¶

6.1. Type Signatures

Type signatures comprises a series of type codes as defined below. Most of them represent a single type, such as CK_BYTE, while a couple of them, a and f, represent arrays and output buffers of elements in other types signified by the following type code. For example, ay means an array of CK_BYTE.¶

6.2. Primitive Types

6.3. String Types

6.4. Record Types

6.5. Array Types

Arrays are serialized as:¶

1. Length (4 bytes): Number of elements following¶

2. Data (variable): Array contents¶

The size of each element is determined by the following type signature. For example, a CK_BYTE array ('ay') has elements of one octet, while a CK_ULONG array ('au') has elements of 8 octets.¶

6.6. Buffer Types

The protocol implements the PKCS #11 convention for variable-length output parameters, signified by the f_ (buffer) type signature.¶

The serialization of the argument of type f_ depends on the element type. For the types with known sizes, the client only sends the number of elements. For the types with unknown sizes, the client additionally sends "templates" with which only the fixed fields are filled.¶

For example, to receive an attribute array with C_GetAttributeValue, the client sends a request with a type signature including fA and the corresponding argument serialized as:¶

1. Length (4 bytes): Number of elements following¶

2. Templates: Array of CK_ATTRIBUTE serialized as if pValue field is NULL¶

Note that for recursively serialized attributes, only the leaf CK_ATTRIBUTE values have pValue field set to NULL.¶

When the call is successfull, the server responds with an array of CK_ATTRIBUTE aA filled with the actual ulValueLen and pValue for each attribute.¶

7.1. Call Identifiers

Call identifiers are defined in the range:¶

• 0: P11_RPC_CALL_ERROR (error response)¶

• 1-57: PKCS #11 2.x functions¶

• 58-79: PKCS #11 3.0 functions (version 1+)¶

• 80-81: Extended functions with mechanism parameter updates (version 2+)¶

7.2. Example Function Mappings

Request:
  - CK_SLOT_ID slot_id (u)
  - Buffer indicator for mechanisms (f)
  - CK_ULONG count (u) - capacity of buffer

Response:
  - CK_MECHANISM_TYPE array (au)

Request:
  - CK_SESSION_HANDLE session (u)
  - CK_OBJECT_HANDLE object (u)
  - Attribute template (fA)

Response:
  - Filled attribute array (aA)
  - CK_RV result code (u)

Request:
  - CK_SESSION_HANDLE session (u)
  - Plaintext data (ay)
  - Buffer for ciphertext (fy)

Response:
  - Ciphertext data (ay)

7.3. PKCS #11 3.0 Functions (Version 1+)

Version 1 of the protocol adds support for PKCS #11 3.0 functions:¶

• C_LoginUser (call ID 58): Enhanced login with username¶

• C_SessionCancel (call ID 59): Cancel ongoing session operations¶

• Message-based encryption functions (call IDs 60-67):¶

  • C_MessageEncryptInit, C_EncryptMessage, C_EncryptMessageBegin, C_EncryptMessageNext, C_MessageEncryptFinal¶

  • C_MessageDecryptInit, C_DecryptMessage, C_DecryptMessageBegin, C_DecryptMessageNext, C_MessageDecryptFinal¶

• Message-based signature functions (call IDs 68-75):¶

  • C_MessageSignInit, C_SignMessage, C_SignMessageBegin, C_SignMessageNext, C_MessageSignFinal¶

  • C_MessageVerifyInit, C_VerifyMessage, C_VerifyMessageBegin, C_VerifyMessageNext, C_MessageVerifyFinal¶

7.4. Extended Functions (Version 2+)

Version 2 adds functions that return updated mechanism parameters:¶

8.1. Version 0

Initial protocol version supporting PKCS #11 2.40 functions:¶

• All functions from C_Initialize through C_WaitForSlotEvent¶

• Call IDs 1-57¶

• No version negotiation (always uses version byte 0x00)¶

8.2. Version 1

Adds PKCS #11 3.0 function support:¶

• Version negotiation support¶

• C_LoginUser and C_SessionCancel¶

• Message-based encryption functions¶

• Message-based signature functions¶

• Call IDs 58-79¶

Backward compatibility: Version 1 servers can communicate with version 0 clients by using only version 0 function calls.¶

8.3. Version 2

Adds functions with mechanism parameter updates:¶

• C_InitToken2: Uses space-padded label string¶

• C_DeriveKey2: Returns updated mechanism parameters¶

• Call IDs 80-81¶

Backward compatibility: - Version 2 servers can downgrade to version 1 or 0 - For version 0-1 clients, C_InitToken and C_DeriveKey are used - Mechanism parameter updates are not available at lower versions¶

9.1. PKCS #11 Return Codes

All PKCS #11 return codes (CK_RV) are transmitted as unsigned 32-bit integers in response messages. The protocol does not define additional error codes beyond those in PKCS #11.¶

9.2. Protocol Errors

Protocol-level errors are handled as follows:¶

10.1. Authentication

The protocol itself does not provide authentication mechanisms. Authentication is delegated to the transport layer:¶

• For Unix domain sockets: File system permissions and optional SO_PEERCRED¶

• For VSOCK: VM isolation boundaries¶

10.2. Confidentiality and Integrity

The protocol does not provide encryption or integrity protection. These properties must be provided by:¶

• Operating system isolation (e.g., Unix domain sockets with file system permissions)¶

• Hypervisor isolation (e.g., VSOCK between VMs)¶

For scenarios requiring confidentiality and integrity without transport-level security, implementers should use TLS or similar protocols.¶

10.3. Sandboxing

A key use case for the protocol is to sandbox untrusted PKCS #11 modules. When sandboxing:¶

• The server process should run with minimal privileges¶

• File system access should be restricted using tools like bubblewrap¶

• Seccomp filters should limit available system calls¶

• Resource limits should prevent denial of service¶

10.4. Sensitive Data

The protocol transmits sensitive cryptographic material (keys, PINs, plaintext) in serialized form. Implementations must:¶

• Ensure transport channels are appropriately secured¶

• Zero sensitive memory after use¶

• Avoid logging sensitive parameters¶

• Respect PKCS #11 CKA_SENSITIVE and CKA_EXTRACTABLE attributes¶

10.5. Input Validation

Servers must validate all input parameters:¶

• Array lengths must be checked against buffer sizes¶

• Attribute types must be validated¶

• Mechanism parameters must be validated according to PKCS #11 specifications¶

• Call IDs must be within valid ranges¶

Failure to validate inputs may lead to buffer overflows, denial of service, or information disclosure.¶

12.1. Endianness and Data Models

The protocol uses network byte order (big-endian) for all multi-byte integers. The 64-bit encoding of CK_ULONG ensures interoperability across different platforms:¶

• LP64 systems (Unix/Linux 64-bit): CK_ULONG is 64-bit natively¶

• LLP64 systems (Windows 64-bit): CK_ULONG is 32-bit natively¶

• ILP32 systems (32-bit): CK_ULONG is 32-bit natively¶

Implementations must handle this conversion carefully, particularly when CK_ULONG values exceed 32-bit range on LLP64 systems.¶

12.2. Buffer Management

The protocol's variable-length output convention requires two round trips for unknown-size outputs:¶

1. First call with NULL pointer to determine size¶

2. Second call with appropriately sized buffer¶

Implementations should optimize common cases where sizes are known or bounded.¶

12.3. Mechanism Parameter Handling

Different PKCS #11 mechanisms use different parameter structures. Implementations must:¶

• Maintain tables mapping mechanism types to parameter structures¶

• Validate parameter structures according to PKCS #11 specifications¶

• Handle vendor-specific mechanisms gracefully¶

12.4. Threading and Concurrency

The protocol supports concurrent calls through the call code mechanism. Multiple threads can:¶

• Send requests with different call codes¶

• Receive responses in any order¶

• Match responses to requests via call code¶

Implementations must ensure thread-safe access to the transport layer and proper request-response matching.¶

12.5. Performance Optimization

For high-performance scenarios:¶

• Connection pooling can reduce setup overhead¶

• Batch operations should be used when available¶

• Local caching of token information can reduce round trips¶

• Unix domain sockets typically offer better performance than exec-based transports¶

13.1. Normative References

[PKCS11-v2.40]

OASIS, "PKCS #11 Cryptographic Token Interface Base Specification Version 2.40", April 2015, <http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.html>.

[PKCS11-v3.1]

OASIS, "PKCS #11 Cryptographic Token Interface Specification Version 3.1", June 2021, <https://docs.oasis-open.org/pkcs11/pkcs11-spec/v3.1/pkcs11-spec-v3.1.pdf>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC5234]

Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, <https://www.rfc-editor.org/rfc/rfc5234>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

13.2. Informative References

[DBUS]

freedesktop.org, "D-Bus Specification", n.d., <https://dbus.freedesktop.org/doc/dbus-specification.html>.

[KMIP]

OASIS, "Key Management Interoperability Protocol Specification Version 2.1", January 2020, <https://docs.oasis-open.org/kmip/kmip-spec/v2.1/kmip-spec-v2.1.html>.

[P11-GLUE]

p11-glue Project, "p11-glue: Standardizing PKCS #11", n.d., <https://p11-glue.github.io/p11-glue/>.