doc/man3/SSL_set1_server_cert_type.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_set1_client_cert_type,
   6 SSL_set1_server_cert_type,
   7 SSL_CTX_set1_client_cert_type,
   8 SSL_CTX_set1_server_cert_type,
   9 SSL_get0_client_cert_type,
  10 SSL_get0_server_cert_type,
  11 SSL_CTX_get0_client_cert_type,
  12 SSL_CTX_get0_server_cert_type - certificate type (RFC7250) support
  13
  14 =head1 SYNOPSIS
  15
  16  #include <openssl/ssl.h>
  17
  18  int SSL_set1_client_cert_type(SSL *s, const unsigned char *val, size_t len);
  19  int SSL_set1_server_cert_type(SSL *s, const unsigned char *val, size_t len);
  20  int SSL_CTX_set1_client_cert_type(SSL_CTX *ctx, const unsigned char *val, size_t len);
  21  int SSL_CTX_set1_server_cert_type(SSL_CTX *ctx, const unsigned char *val, size_t len);
  22  int SSL_get0_client_cert_type(const SSL *s, unsigned char **val, size_t *len);
  23  int SSL_get0_server_cert_type(const SSL *s, unsigned char **val, size_t *len);
  24  int SSL_CTX_get0_client_cert_type(const SSL_CTX *ctx, unsigned char **val, size_t *len);
  25  int SSL_CTX_get0_server_cert_type(const SSL_CTX *s, unsigned char **val, size_t *len);
  26
  27 =head1 DESCRIPTION
  28
  29 The SSL_set1_client_cert_type() and SSL_CTX_set1_client_cert_type() functions
  30 set the values for the client certificate type extension.
  31 The SSL_get0_client_cert_type() and SSL_CTX_get0_client_cert_type() functions
  32 retrieve the local values to be used in the client certificate type extension.
  33
  34 The SSL_set1_server_cert_type() and SSL_CTX_set1_server_cert_type() functions
  35 set the values for the server certificate type extension.
  36 The SSL_get0_server_cert_type() and SSL_CTX_get0_server_cert_type() functions
  37 retrieve the local values to be used in the server certificate type extension.
  38
  39 =head1 NOTES
  40
  41 The certificate type extensions are used to negotiate the certificate type to
  42 be used in the handshake.
  43 These extensions let each side know what its peer is able to accept.
  44
  45 The client certificate type is sent from the client to the server to indicate
  46 what certificate types the client is able to present.
  47 Values are configured in preference order.
  48 On the server, this setting determines which certificate types the server is
  49 willing to accept.
  50 The server ultimately chooses what type to request (if any) from the values
  51 that are mutually supported.
  52 By default (if no explicit settings are specified), only X.509 certificates
  53 are supported.
  54
  55 The server certificate type is sent from the client to the server to indicate
  56 what certificate types the client accepts.
  57 Values are configured in preference order.
  58 On the server, this setting determines which certificate types the server is
  59 willing to present.
  60 The server ultimately chooses what type to use from the values that are
  61 mutually supported.
  62 By default (if no explicit settings are specified), only X.509 certificates
  63 are supported.
  64
  65 Having RPK specified first means that side will attempt to send (or request)
  66 RPKs if its peer also supports RPKs, otherwise X.509 certificate will be used
  67 if both have specified that (or have not configured these options).
  68
  69 The two supported values in the B<val> array are:
  70
  71 =over 4
  72
  73 =item TLSEXT_cert_type_x509
  74
  75 Which corresponds to an X.509 certificate normally used in TLS.
  76
  77 =item TLSEXT_cert_type_rpk
  78
  79 Which corresponds to a raw public key.
  80
  81 =back
  82
  83 If B<val> is set to a non-NULL value, then the extension is sent in the handshake.
  84 If b<val> is set to a NULL value (and B<len> is 0), then the extension is
  85 disabled. The default value is NULL, meaning the extension is not sent, and
  86 X.509 certificates are used in the handshake.
  87
  88 Raw public keys may be used in place of certificates when specified in the
  89 certificate type and negotiated.
  90 Raw public keys have no subject, issuer, validity dates or digital signature.
  91
  92 Use the L<SSL_get_negotiated_client_cert_type(3)> and
  93 L<SSL_get_negotiated_server_cert_type(3)> functions to get the negotiated cert
  94 type values (at the conclusion of the handshake, or in callbacks that happen
  95 after the TLS ServerHello has been processed).
  96
  97 =head1 RETURN VALUES
  98
  99 All functions return 1 on success and 0 on failure.
 100
 101 The memory returned from the get0 functions must not be freed.
 102
 103 =head1 EXAMPLES
 104
 105 To use raw public keys on the server, set up the SSL_CTX and SSL as follows:
 106
 107  SSL_CTX *ctx;
 108  SSL *ssl;
 109  unsigned char cert_type[] = { TLSEXT_cert_type_rpk, TLSEXT_cert_type_x509 };
 110  EVP_PKEY *rpk;
 111
 112  /* Assign rpk to an EVP_PKEY from a file or other means */
 113
 114  if ((ctx = SSL_CTX_new(TLS_server_method())) == NULL)
 115      /* error */
 116  if ((ssl = SSL_new(ctx)) == NULL)
 117      /* error */
 118  if (!SSL_set1_server_cert_type(ssl, cert_type, sizeof(cert_type)))
 119      /* error */
 120
 121  /* A certificate does not need to be specified when using raw public keys */
 122  if (!SSL_use_PrivateKey(ssl, rpk))
 123      /* error */
 124
 125  /* Perform SSL_accept() operations */
 126
 127 To connect to this server, set the client SSL_CTX and SSL as follows:
 128
 129  /* Connect function */
 130
 131  SSL_CTX *ctx;
 132  SSL *ssl;
 133  const char *dane_tlsa_domain = "smtp.example.com";
 134  unsigned char cert_type[] = { TLSEXT_cert_type_rpk, TLSEXT_cert_type_x509 };
 135  EVP_PKEY *rpk;
 136  int verify_result;
 137
 138  /* Assign rpk to an EVP_PKEY from a file or other means */
 139
 140  if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL)
 141      /* error */
 142  if (SSL_CTX_dane_enable(ctx) <= 0)
 143      /* error */
 144  if ((ssl = SSL_new(ctx)) == NULL)
 145      /* error */
 146  /*
 147   * The `dane_tlsa_domain` arguments sets the default SNI hostname.
 148   * It may be set to NULL when enabling DANE on the server side.
 149   */
 150  if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0)
 151      /* error */
 152  if (!SSL_set1_server_cert_type(ssl, cert_type, sizeof(cert_type)))
 153      /* error */
 154  if (!SSL_add_expected_rpk(ssl, rpk))
 155      /* error */
 156
 157  /* Do SSL_connect() handshake and handle errors here */
 158
 159  /* Optional: verify the peer RPK */
 160  verify_result = SSL_get_verify_result(ssl);
 161  if (verify_result == X509_V_OK) {
 162      /* The server's raw public key matched the TLSA record */
 163  } else if (verify_result == X509_V_ERR_DANE_NO_MATCH) {
 164      /*
 165       * The server's raw public key, or public key in certificate, did not
 166       * match the TLSA record
 167       */
 168  } else if (verify_result == X509_V_ERR_RPK_UNTRUSTED) {
 169      /*
 170       * No TLSA records of the correct type are available to verify the
 171       * server's raw public key. This would not happen in this example,
 172       * as a TLSA record is configured.
 173       */
 174  } else {
 175      /* Some other verify error */
 176  }
 177
 178 To validate client raw public keys, code from the client example may need to be
 179 incorporated into the server side.
 180
 181 =head1 SEE ALSO
 182
 183 L<SSL_get0_peer_rpk(3)>,
 184 L<SSL_get_negotiated_client_cert_type(3)>,
 185 L<SSL_get_negotiated_server_cert_type(3)>,
 186 L<SSL_use_certificate(3)>
 187
 188 =head1 HISTORY
 189
 190 These functions were added in OpenSSL 3.2.
 191
 192 =head1 COPYRIGHT
 193
 194 Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.
 195
 196 =cut