tfSslSetSignatureHashAlgorithms

Table of Contents >> SSL Programmer's Reference

#include <trsocket.h>

int tfSslSetSignatureHashAlgorithms	(
	int sessionId,
	ttSignatureHashPairPtr sigHashArrayPtr,
	int sigHashArrayLen
	);

Function Description

Use this function to override the default signature and hash functions allowed for a TLS session. This capability corresponds to the signature_algorithms extension that was added with TLS 1.2 (see RFC 5246, section 7.4.1.4.1) — it has no effect on TLS 1.1 and lower connections.

This function accepts an array of algorithm pairs. Each pair consists of a signature algorithm (SADB_PUBKEY_RSA, SADB_PUBKEY_DSA or SADB_PUBKEY_ECDSA) and a hash algorithm (e.g. SADB_AALG_SHA1HMAC). You must specify all supported combinations since some hash algorithms may pair with one signature algorithm but not another. Order may be important, if the peer chooses the first entry that it supports from the list that it receives.

The default algorithm pairs supported are shown below. Note that the MD5 hash algorithm is missing from the default support because it is considered too weak. If you wish to change the content or order of the default list, call tfSslSetSignatureHashAlgorithms() with the full list you wish to support.

Note:

The list you provide must include algorithms that are compatible with the list of cipher suites you support and the certificate you attach to the session, if any.

Default Signature-Hash Algorithm Pairs

The default set of signature-hash algorithm pairs depends on your trsystem.h configuration. For example, if you do not enable TM_USE_SHA512, SHA-512 will not be included; if you do not enable TM_PUBKEY_USE_DSA, DSA will not be included.

The list of pairs is sent and parsed in the numerical order shown in the following matrix, which may have significance if the peer places any importance on order. Entries marked as "–" are not supported.

Hash \ Signature	SADB_PUBKEY_RSA	SADB_PUBKEY_ECDSA	SADB_PUBKEY_DSA
SADB_AALG_SHA512HMAC	1	2	–
SADB_AALG_SHA384HMAC	3	4	7
SADB_AALG_SHA256HMAC	5	6	8
SADB_AALG_SHA1HMAC	9	10	11

In C coding terms, this list might appear as follows:

static const ttSignatureHashPair sigHashList[] =
  { {SADB_AALG_SHA512HMAC, SADB_PUBKEY_RSA},
    {SADB_AALG_SHA512HMAC, SADB_PUBKEY_ECDSA},
    {SADB_AALG_SHA384HMAC, SADB_PUBKEY_RSA},
      ⋮
    {SADB_AALG_SHA1HMAC, SADB_PUBKEY_DSA}
  };
 
#define SIG_HASH_LIST_LENGTH (sizeof(sigHashList) / sizeof(*sigHashList))

Parameters

• sessionId

  The session to update.

• sigHashArrayPtr

  Array of ttSignatureHashPair entries to support, in order of importance (most to least).

• sigHashArrayLen

  Number of entries in sigHashArrayPtr.

Returns

• TM_ENOERROR

  Success

• TM_EINVAL

  Invalid input parameter

• TM_ENOBUFS

  Insufficient memory

• TM_EPERM

  TLS 1.2 only; define TM_USE_TLS_VERSION_12 in your trsystem.h

Table of Contents >> SSL Programmer's Reference