3.1.4.1 ExchangePublicKeys (Opnum 0)

  • Article 

 HRESULT ExchangePublicKeys(
   [in] handle_t Binding,
   [in] KEY_LENGTH ClientKeyLength,
   [in, unique, size_is(ClientKeyLength)] 
     byte* ClientKey,
   [out, ref] KEY_LENGTH* pServerKeyLength,
   [out, ref, size_is(, *pServerKeyLength)] 
     byte** pServerKey
 );

Binding: An RPC binding handle parameter as described in [C706] section 2.3.1, Binding Handles.

ClientKeyLength: Length of the client's local certificate, or zero if ClientKey is NULL.

ClientKey: The client's local certificate, encoded as a CERTIFICATE_BLOB (section 2.2.2). If NULL, the client is choosing not to send a certificate.

pServerKeyLength: On output, the length of the server's local certificate. Set to zero if the return value is nonzero, or if pServerKey is NULL.

pServerKey: On output, the server's local certificate, encoded as a CERTIFICATE_BLOB (section 2.2.2). If NULL, the server is choosing not to return a certificate. Set to NULL if the return value is nonzero. Ignored on the client if the method returns an error or throws an exception.

Return Values: An HRESULT indicating return status. See [MS-ERREF] for details of the HRESULT type.

ERROR_SUCCESS (0x00000000)

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

The server MUST first check whether the client's identity, as reported by Kerberos to the RPC layer, is an account in a domain that is trusted by the server, returning 0x80070005 if it is not. See [MS-RPCE] section 3.3.3.4.3 for details of acquiring the client identity. The server MAY apply other implementation-specific criteria to the account.<2>

If ClientKeyLength is nonzero, the server MUST decode the client certificate. If an error occurs during decoding, the server MUST return a nonzero error. The subject of the client certificate MUST be a SID string, as defined in [MS-DTYP] section 2.4.2.1, representing the client's Kerberos identity; otherwise, the server MUST return 0x80070005. If the SID string represents the client's Kerberos identity, the server MUST add the certificate to its table of peer certificates. The server MAY impose implementation-specific limits on the size of the table.<3> If the client certificate is not added because of such a limit, the server MUST return 0x80040006. If the table already contains a certificate corresponding to this client, the server MAY choose whether to replace or augment the prior certificate.<4> The server MUST return zero in either case.

If ClientKeyLength is zero, then the server MUST NOT decode the client certificate.

The server MUST encode its own certificate as a CERTIFICATE_BLOB, returning the encoded buffer in pServerKey.

If an error occurs during encoding, the server MUST return a nonzero value. Otherwise, the server MUST return zero.

The client and server SHOULD NOT include a KEY_PROV_INFO property in the CERTIFICATE_BLOB, because it refers to local resources on the sender. Recipients SHOULD ignore the KEY_PROV_INFO property.<5>