doc/gnutls.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!-- This manual is last updated 23 March 2015 for version
   4 3.3.26 of GnuTLS.
   5
   6 Copyright (C) 2001-2013 Free Software Foundation, Inc.\\
   7 Copyright (C) 2001-2013 Nikos Mavrogiannopoulos
   8
   9 Permission is granted to copy, distribute and/or modify this document
  10 under the terms of the GNU Free Documentation License, Version 1.3 or
  11 any later version published by the Free Software Foundation; with no
  12 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
  13 copy of the license is included in the section entitled "GNU Free
  14 Documentation License". -->
  15 <!-- Created by GNU Texinfo 6.3, http://www.gnu.org/software/texinfo/ -->
  16 <head>
  17 <title>GnuTLS 3.3.26</title>
  18
  19 <meta name="description" content="GnuTLS 3.3.26">
  20 <meta name="keywords" content="GnuTLS 3.3.26">
  21 <meta name="resource-type" content="document">
  22 <meta name="distribution" content="global">
  23 <meta name="Generator" content="makeinfo">
  24 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  25 <link href="#Top" rel="start" title="Top">
  26 <link href="#Function-and-Data-Index" rel="index" title="Function and Data Index">
  27 <link href="#SEC_Contents" rel="contents" title="Table of Contents">
  28 <link href="dir.html#Top" rel="up" title="(dir)">
  29 <style type="text/css">
  30 <!--
  31 a.summary-letter {text-decoration: none}
  32 blockquote.indentedblock {margin-right: 0em}
  33 blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
  34 blockquote.smallquotation {font-size: smaller}
  35 div.display {margin-left: 3.2em}
  36 div.example {margin-left: 3.2em}
  37 div.lisp {margin-left: 3.2em}
  38 div.smalldisplay {margin-left: 3.2em}
  39 div.smallexample {margin-left: 3.2em}
  40 div.smalllisp {margin-left: 3.2em}
  41 kbd {font-style: oblique}
  42 pre.display {font-family: inherit}
  43 pre.format {font-family: inherit}
  44 pre.menu-comment {font-family: serif}
  45 pre.menu-preformatted {font-family: serif}
  46 pre.smalldisplay {font-family: inherit; font-size: smaller}
  47 pre.smallexample {font-size: smaller}
  48 pre.smallformat {font-family: inherit; font-size: smaller}
  49 pre.smalllisp {font-size: smaller}
  50 span.nolinebreak {white-space: nowrap}
  51 span.roman {font-family: initial; font-weight: normal}
  52 span.sansserif {font-family: sans-serif; font-weight: normal}
  53 ul.no-bullet {list-style: none}
  54 body {
  55         margin: 2%;
  56         padding: 0 5%;
  57         background: #ffffff;
  58 }
  59 h1,h2,h3,h4,h5 {
  60     font-weight: bold;
  61     padding: 5px 5px 5px 5px;
  62     background-color: #c2e0ff;
  63     color: #336699;
  64 }
  65 h1 {
  66     padding: 2em 2em 2em 5%;
  67     color: white;
  68     background: #336699;
  69     text-align: center;
  70     letter-spacing: 3px;
  71 }
  72 h2 { text-decoration: underline; }
  73 pre {
  74   margin: 0 5%;
  75   padding: 0.5em;
  76 }
  77 pre.example,pre.verbatim {
  78   padding-bottom: 1em;
  79
  80   border: solid #c2e0ff;
  81   background: #f0faff;
  82   border-width: 1px 1px 1px 5px;
  83   margin: 1em auto;
  84   width: 90%;
  85 }
  86
  87 div.node {
  88   margin: 0 -5% 0 -2%;
  89   padding: 0.5em 0.5em;
  90   margin-top: 0.5em;
  91   margin-bottom: 0.5em;
  92   font-weight: bold;
  93 }
  94 dd, li {
  95   padding-top: 0.1em;
  96   padding-bottom: 0.1em;
  97 }
  98 div.float {
  99
 100   margin-bottom: 0.5em;
 101   text-align: center;
 102 }
 103
 104 table {
 105   text-align: left;
 106   margin-left:auto;
 107   margin-right:auto;
 108   border-spacing: 7px;
 109   width: 50%;
 110 }
 111
 112 th {
 113   padding: 0;
 114   color: #336699;
 115   background-color: #c2e0ff;
 116   border: solid #000000;
 117   border-width: 0px;
 118   margin: 1em auto;
 119   text-align: center;
 120   margin-left:auto;
 121   margin-right:auto;
 122 }
 123
 124 td {
 125   padding: 0;
 126   border: solid #000000;
 127   background-color: #f0faff;
 128   border-width: 0px;
 129   margin: 1em auto;
 130   text-align: left;
 131   margin-left:auto;
 132   margin-right:auto;
 133   padding-left: 1em;
 134 }
 135
 136 dl {
 137   text-align: left;
 138   margin-left:auto;
 139   margin-right:auto;
 140   width: 50%;
 141
 142   padding-left: 1em;
 143   border: solid #c2e0ff;
 144   background: #f0faff;
 145   border-width: 5px 1px 1px 1px;
 146   margin: 1em auto;
 147 }
 148
 149 -->
 150 </style>
 151
 152
 153 </head>
 154
 155 <body lang="en">
 156 <h1 class="settitle" align="center">GnuTLS 3.3.26</h1>
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175 <a name="SEC_Contents"></a>
 176 <h2 class="contents-heading">Table of Contents</h2>
 177
 178 <div class="contents">
 179
 180 <ul class="no-bullet">
 181   <li><a name="toc-Preface-1" href="#Preface">1 Preface</a></li>
 182   <li><a name="toc-Introduction-to-GnuTLS-1" href="#Introduction-to-GnuTLS">2 Introduction to GnuTLS</a>
 183   <ul class="no-bullet">
 184     <li><a name="toc-Downloading-and-installing-1" href="#Downloading-and-installing">2.1 Downloading and installing</a></li>
 185     <li><a name="toc-Overview" href="#Document-overview">2.2 Overview</a></li>
 186   </ul></li>
 187   <li><a name="toc-Introduction-to-TLS-and-DTLS" href="#Introduction-to-TLS">3 Introduction to <acronym>TLS</acronym> and <acronym>DTLS</acronym></a>
 188   <ul class="no-bullet">
 189     <li><a name="toc-TLS-layers-1" href="#TLS-layers">3.1 TLS layers</a></li>
 190     <li><a name="toc-The-transport-layer-1" href="#The-transport-layer">3.2 The transport layer</a></li>
 191     <li><a name="toc-The-TLS-record-protocol-1" href="#The-TLS-record-protocol">3.3 The TLS record protocol</a>
 192     <ul class="no-bullet">
 193       <li><a name="toc-Encryption-algorithms-used-in-the-record-layer-1" href="#Encryption-algorithms-used-in-the-record-layer">3.3.1 Encryption algorithms used in the record layer</a></li>
 194       <li><a name="toc-Compression-algorithms-used-in-the-record-layer-1" href="#Compression-algorithms-used-in-the-record-layer">3.3.2 Compression algorithms used in the record layer</a></li>
 195       <li><a name="toc-Weaknesses-and-countermeasures-1" href="#Weaknesses-and-countermeasures">3.3.3 Weaknesses and countermeasures</a></li>
 196       <li><a name="toc-On-record-padding" href="#On-Record-Padding">3.3.4 On record padding</a></li>
 197     </ul></li>
 198     <li><a name="toc-The-TLS-alert-protocol" href="#The-TLS-Alert-Protocol">3.4 The TLS alert protocol</a></li>
 199     <li><a name="toc-The-TLS-handshake-protocol" href="#The-TLS-Handshake-Protocol">3.5 The TLS handshake protocol</a>
 200     <ul class="no-bullet">
 201       <li><a name="toc-TLS-ciphersuites" href="#TLS-Cipher-Suites">3.5.1 TLS ciphersuites</a></li>
 202       <li><a name="toc-Authentication-1" href="#Authentication">3.5.2 Authentication</a></li>
 203       <li><a name="toc-Client-authentication" href="#Client-Authentication">3.5.3 Client authentication</a></li>
 204       <li><a name="toc-Resuming-sessions" href="#Resuming-Sessions">3.5.4 Resuming sessions</a></li>
 205     </ul></li>
 206     <li><a name="toc-TLS-extensions" href="#TLS-Extensions">3.6 TLS extensions</a>
 207     <ul class="no-bullet">
 208       <li><a name="toc-Maximum-fragment-length-negotiation-1" href="#Maximum-fragment-length-negotiation">3.6.1 Maximum fragment length negotiation</a></li>
 209       <li><a name="toc-Server-name-indication-1" href="#Server-name-indication">3.6.2 Server name indication</a></li>
 210       <li><a name="toc-Session-tickets-1" href="#Session-tickets">3.6.3 Session tickets</a></li>
 211       <li><a name="toc-HeartBeat-1" href="#HeartBeat">3.6.4 HeartBeat</a></li>
 212       <li><a name="toc-Safe-renegotiation-1" href="#Safe-renegotiation">3.6.5 Safe renegotiation</a></li>
 213       <li><a name="toc-OCSP-status-request-1" href="#OCSP-status-request">3.6.6 OCSP status request</a></li>
 214       <li><a name="toc-SRTP-1" href="#SRTP">3.6.7 SRTP</a></li>
 215       <li><a name="toc-Application-Layer-Protocol-Negotiation-_0028ALPN_0029-1" href="#Application-Layer-Protocol-Negotiation-_0028ALPN_0029">3.6.8 Application Layer Protocol Negotiation (ALPN)</a></li>
 216     </ul></li>
 217     <li><a name="toc-How-to-use-TLS-in-application-protocols-1" href="#How-to-use-TLS-in-application-protocols">3.7 How to use <acronym>TLS</acronym> in application protocols</a>
 218     <ul class="no-bullet">
 219       <li><a name="toc-Separate-ports-1" href="#Separate-ports">3.7.1 Separate ports</a></li>
 220       <li><a name="toc-Upward-negotiation-1" href="#Upward-negotiation">3.7.2 Upward negotiation</a></li>
 221     </ul></li>
 222     <li><a name="toc-On-SSL-2-and-older-protocols-1" href="#On-SSL-2-and-older-protocols">3.8 On SSL 2 and older protocols</a></li>
 223   </ul></li>
 224   <li><a name="toc-Authentication-methods-1" href="#Authentication-methods">4 Authentication methods</a>
 225   <ul class="no-bullet">
 226     <li><a name="toc-Certificate-authentication-1" href="#Certificate-authentication">4.1 Certificate authentication</a>
 227     <ul class="no-bullet">
 228       <li><a name="toc-X_002e509-certificates-1" href="#X_002e509-certificates">4.1.1 <acronym>X.509</acronym> certificates</a>
 229       <ul class="no-bullet">
 230         <li><a name="toc-X_002e509-certificate-structure-1" href="#X_002e509-certificate-structure">4.1.1.1 <acronym>X.509</acronym> certificate structure</a></li>
 231         <li><a name="toc-Importing-an-X_002e509-certificate-1" href="#Importing-an-X_002e509-certificate">4.1.1.2 Importing an X.509 certificate</a></li>
 232         <li><a name="toc-X_002e509-distinguished-names-1" href="#X_002e509-distinguished-names">4.1.1.3 X.509 distinguished names</a></li>
 233         <li><a name="toc-X_002e509-extensions-1" href="#X_002e509-extensions">4.1.1.4 X.509 extensions</a></li>
 234         <li><a name="toc-Accessing-public-and-private-keys" href="#X_002e509-public-and-private-keys">4.1.1.5 Accessing public and private keys</a></li>
 235         <li><a name="toc-Verifying-X_002e509-certificate-paths-1" href="#Verifying-X_002e509-certificate-paths">4.1.1.6 Verifying <acronym>X.509</acronym> certificate paths</a></li>
 236         <li><a name="toc-Verifying-a-certificate-in-the-context-of-TLS-session-1" href="#Verifying-a-certificate-in-the-context-of-TLS-session">4.1.1.7 Verifying a certificate in the context of TLS session</a></li>
 237         <li><a name="toc-Verifying-a-certificate-using-PKCS-_002311" href="#Verification-using-PKCS11">4.1.1.8 Verifying a certificate using PKCS #11</a></li>
 238       </ul></li>
 239       <li><a name="toc-OpenPGP-certificates-1" href="#OpenPGP-certificates">4.1.2 <acronym>OpenPGP</acronym> certificates</a>
 240       <ul class="no-bullet">
 241         <li><a name="toc-OpenPGP-certificate-structure" href="#OpenPGP-certificate-structure">4.1.2.1 <acronym>OpenPGP</acronym> certificate structure</a></li>
 242         <li><a name="toc-Verifying-an-OpenPGP-certificate" href="#Verifying-an-OpenPGP-certificate">4.1.2.2 Verifying an <acronym>OpenPGP</acronym> certificate</a></li>
 243         <li><a name="toc-Verifying-a-certificate-in-the-context-of-a-TLS-session" href="#Verifying-a-certificate-in-the-context-of-a-TLS-session">4.1.2.3 Verifying a certificate in the context of a TLS session</a></li>
 244       </ul></li>
 245       <li><a name="toc-Advanced-certificate-verification-1" href="#Advanced-certificate-verification">4.1.3 Advanced certificate verification</a>
 246       <ul class="no-bullet">
 247         <li><a name="toc-Verifying-a-certificate-using-trust-on-first-use-authentication-1" href="#Verifying-a-certificate-using-trust-on-first-use-authentication">4.1.3.1 Verifying a certificate using trust on first use authentication</a></li>
 248         <li><a name="toc-Verifying-a-certificate-using-DANE-_0028DNSSEC_0029" href="#Verifying-a-certificate-using-DANE">4.1.3.2 Verifying a certificate using DANE (DNSSEC)</a></li>
 249       </ul></li>
 250       <li><a name="toc-Digital-signatures-1" href="#Digital-signatures">4.1.4 Digital signatures</a>
 251       <ul class="no-bullet">
 252         <li><a name="toc-Trading-security-for-interoperability" href="#Trading-security-for-interoperability">4.1.4.1 Trading security for interoperability</a></li>
 253       </ul></li>
 254     </ul></li>
 255     <li><a name="toc-More-on-certificate-authentication-1" href="#More-on-certificate-authentication">4.2 More on certificate authentication</a>
 256     <ul class="no-bullet">
 257       <li><a name="toc-PKCS-_002310-certificate-requests" href="#PKCS-10-certificate-requests">4.2.1 <acronym>PKCS</acronym> #10 certificate requests</a></li>
 258       <li><a name="toc-PKIX-certificate-revocation-lists-1" href="#PKIX-certificate-revocation-lists">4.2.2 PKIX certificate revocation lists</a></li>
 259       <li><a name="toc-OCSP-certificate-status-checking-1" href="#OCSP-certificate-status-checking">4.2.3 <acronym>OCSP</acronym> certificate status checking</a></li>
 260       <li><a name="toc-Managing-encrypted-keys-1" href="#Managing-encrypted-keys">4.2.4 Managing encrypted keys</a></li>
 261       <li><a name="toc-Invoking-certtool" href="#certtool-Invocation">4.2.5 Invoking certtool</a></li>
 262       <li><a name="toc-Invoking-ocsptool" href="#ocsptool-Invocation">4.2.6 Invoking ocsptool</a></li>
 263       <li><a name="toc-Invoking-danetool" href="#danetool-Invocation">4.2.7 Invoking danetool</a></li>
 264     </ul></li>
 265     <li><a name="toc-Shared_002dkey-and-anonymous-authentication-1" href="#Shared_002dkey-and-anonymous-authentication">4.3 Shared-key and anonymous authentication</a>
 266     <ul class="no-bullet">
 267       <li><a name="toc-SRP-authentication-1" href="#SRP-authentication">4.3.1 SRP authentication</a>
 268       <ul class="no-bullet">
 269         <li><a name="toc-Authentication-using-SRP-1" href="#Authentication-using-SRP">4.3.1.1 Authentication using <acronym>SRP</acronym></a></li>
 270         <li><a name="toc-Invoking-srptool" href="#srptool-Invocation">4.3.1.2 Invoking srptool</a></li>
 271       </ul></li>
 272       <li><a name="toc-PSK-authentication-1" href="#PSK-authentication">4.3.2 PSK authentication</a>
 273       <ul class="no-bullet">
 274         <li><a name="toc-Authentication-using-PSK-1" href="#Authentication-using-PSK">4.3.2.1 Authentication using <acronym>PSK</acronym></a></li>
 275         <li><a name="toc-Invoking-psktool" href="#psktool-Invocation">4.3.2.2 Invoking psktool</a></li>
 276       </ul></li>
 277       <li><a name="toc-Anonymous-authentication-1" href="#Anonymous-authentication">4.3.3 Anonymous authentication</a></li>
 278     </ul></li>
 279     <li><a name="toc-Selecting-an-appropriate-authentication-method-1" href="#Selecting-an-appropriate-authentication-method">4.4 Selecting an appropriate authentication method</a>
 280     <ul class="no-bullet">
 281       <li><a name="toc-Two-peers-with-an-out_002dof_002dband-channel" href="#Two-peers-with-an-out_002dof_002dband-channel">4.4.1 Two peers with an out-of-band channel</a></li>
 282       <li><a name="toc-Two-peers-without-an-out_002dof_002dband-channel" href="#Two-peers-without-an-out_002dof_002dband-channel">4.4.2 Two peers without an out-of-band channel</a></li>
 283       <li><a name="toc-Two-peers-and-a-trusted-third-party" href="#Two-peers-and-a-trusted-third-party">4.4.3 Two peers and a trusted third party</a></li>
 284     </ul></li>
 285   </ul></li>
 286   <li><a name="toc-Hardware-security-modules-and-abstract-key-types-1" href="#Hardware-security-modules-and-abstract-key-types">5 Hardware security modules and abstract key types</a>
 287   <ul class="no-bullet">
 288     <li><a name="toc-Abstract-key-types-1" href="#Abstract-key-types">5.1 Abstract key types</a>
 289     <ul class="no-bullet">
 290       <li><a name="toc-Public-keys" href="#Abstract-public-keys">5.1.1 Public keys</a></li>
 291       <li><a name="toc-Private-keys" href="#Abstract-private-keys">5.1.2 Private keys</a></li>
 292       <li><a name="toc-Operations-1" href="#Operations">5.1.3 Operations</a></li>
 293     </ul></li>
 294     <li><a name="toc-Smart-cards-and-HSMs-1" href="#Smart-cards-and-HSMs">5.2 Smart cards and HSMs</a>
 295     <ul class="no-bullet">
 296       <li><a name="toc-Initialization-1" href="#PKCS11-Initialization">5.2.1 Initialization</a></li>
 297       <li><a name="toc-Accessing-objects-that-require-a-PIN-1" href="#Accessing-objects-that-require-a-PIN">5.2.2 Accessing objects that require a PIN</a></li>
 298       <li><a name="toc-Reading-objects-1" href="#Reading-objects">5.2.3 Reading objects</a></li>
 299       <li><a name="toc-Writing-objects-1" href="#Writing-objects">5.2.4 Writing objects</a></li>
 300       <li><a name="toc-Using-a-PKCS-_002311-token-with-TLS" href="#Using-a-PKCS11-token-with-TLS">5.2.5 Using a <acronym>PKCS</acronym> #11 token with TLS</a></li>
 301       <li><a name="toc-Invoking-p11tool" href="#p11tool-Invocation">5.2.6 Invoking p11tool</a></li>
 302       <li><a name="toc-p11tool-help_002fusage-_0028_002d_002dhelp_0029" href="#p11tool-help_002fusage-_0028_002d_002dhelp_0029">5.2.7 p11tool help/usage (<samp>--help</samp>)</a></li>
 303       <li><a name="toc-debug-option-_0028_002dd_0029" href="#debug-option-_0028_002dd_0029">5.2.8 debug option (-d)</a></li>
 304       <li><a name="toc-export_002dchain-option" href="#export_002dchain-option">5.2.9 export-chain option</a></li>
 305       <li><a name="toc-list_002dall_002dprivkeys-option" href="#list_002dall_002dprivkeys-option">5.2.10 list-all-privkeys option</a></li>
 306       <li><a name="toc-list_002dprivkeys-option" href="#list_002dprivkeys-option">5.2.11 list-privkeys option</a></li>
 307       <li><a name="toc-list_002dkeys-option" href="#list_002dkeys-option">5.2.12 list-keys option</a></li>
 308       <li><a name="toc-write-option" href="#write-option">5.2.13 write option</a></li>
 309       <li><a name="toc-generate_002drandom-option" href="#generate_002drandom-option">5.2.14 generate-random option</a></li>
 310       <li><a name="toc-generate_002drsa-option" href="#generate_002drsa-option">5.2.15 generate-rsa option</a></li>
 311       <li><a name="toc-generate_002ddsa-option" href="#generate_002ddsa-option">5.2.16 generate-dsa option</a></li>
 312       <li><a name="toc-generate_002decc-option" href="#generate_002decc-option">5.2.17 generate-ecc option</a></li>
 313       <li><a name="toc-export_002dpubkey-option" href="#export_002dpubkey-option">5.2.18 export-pubkey option</a></li>
 314       <li><a name="toc-set_002did-option" href="#set_002did-option">5.2.19 set-id option</a></li>
 315       <li><a name="toc-set_002dlabel-option" href="#set_002dlabel-option">5.2.20 set-label option</a></li>
 316       <li><a name="toc-id-option" href="#id-option">5.2.21 id option</a></li>
 317       <li><a name="toc-mark_002dwrap-option" href="#mark_002dwrap-option">5.2.22 mark-wrap option</a></li>
 318       <li><a name="toc-mark_002dtrusted-option" href="#mark_002dtrusted-option">5.2.23 mark-trusted option</a></li>
 319       <li><a name="toc-mark_002dca-option" href="#mark_002dca-option">5.2.24 mark-ca option</a></li>
 320       <li><a name="toc-mark_002dprivate-option" href="#mark_002dprivate-option">5.2.25 mark-private option</a></li>
 321       <li><a name="toc-trusted-option" href="#trusted-option">5.2.26 trusted option</a></li>
 322       <li><a name="toc-ca-option" href="#ca-option">5.2.27 ca option</a></li>
 323       <li><a name="toc-private-option" href="#private-option">5.2.28 private option</a></li>
 324       <li><a name="toc-so_002dlogin-option" href="#so_002dlogin-option">5.2.29 so-login option</a></li>
 325       <li><a name="toc-admin_002dlogin-option" href="#admin_002dlogin-option">5.2.30 admin-login option</a></li>
 326       <li><a name="toc-curve-option" href="#curve-option">5.2.31 curve option</a></li>
 327       <li><a name="toc-sec_002dparam-option" href="#sec_002dparam-option">5.2.32 sec-param option</a></li>
 328       <li><a name="toc-inder-option" href="#inder-option">5.2.33 inder option</a></li>
 329       <li><a name="toc-inraw-option" href="#inraw-option">5.2.34 inraw option</a></li>
 330       <li><a name="toc-outder-option" href="#outder-option">5.2.35 outder option</a></li>
 331       <li><a name="toc-outraw-option" href="#outraw-option">5.2.36 outraw option</a></li>
 332       <li><a name="toc-set_002dpin-option" href="#set_002dpin-option">5.2.37 set-pin option</a></li>
 333       <li><a name="toc-set_002dso_002dpin-option" href="#set_002dso_002dpin-option">5.2.38 set-so-pin option</a></li>
 334       <li><a name="toc-provider-option" href="#provider-option">5.2.39 provider option</a></li>
 335       <li><a name="toc-p11tool-exit-status-1" href="#p11tool-exit-status-1">5.2.40 p11tool exit status</a></li>
 336       <li><a name="toc-p11tool-See-Also-1" href="#p11tool-See-Also-1">5.2.41 p11tool See Also</a></li>
 337       <li><a name="toc-p11tool-Examples-1" href="#p11tool-Examples-1">5.2.42 p11tool Examples</a></li>
 338     </ul></li>
 339     <li><a name="toc-Trusted-Platform-Module-_0028TPM_0029" href="#Trusted-Platform-Module">5.3 Trusted Platform Module (TPM)</a>
 340     <ul class="no-bullet">
 341       <li><a name="toc-Keys-in-TPM-1" href="#Keys-in-TPM">5.3.1 Keys in TPM</a></li>
 342       <li><a name="toc-Key-generation-1" href="#Key-generation">5.3.2 Key generation</a></li>
 343       <li><a name="toc-Using-keys-1" href="#Using-keys">5.3.3 Using keys</a></li>
 344       <li><a name="toc-Invoking-tpmtool" href="#tpmtool-Invocation">5.3.4 Invoking tpmtool</a></li>
 345       <li><a name="toc-tpmtool-help_002fusage-_0028_002d_002dhelp_0029" href="#tpmtool-help_002fusage-_0028_002d_002dhelp_0029">5.3.5 tpmtool help/usage (<samp>--help</samp>)</a></li>
 346       <li><a name="toc-debug-option-_0028_002dd_0029-1" href="#debug-option-_0028_002dd_0029-1">5.3.6 debug option (-d)</a></li>
 347       <li><a name="toc-generate_002drsa-option-1" href="#generate_002drsa-option-1">5.3.7 generate-rsa option</a></li>
 348       <li><a name="toc-user-option" href="#user-option">5.3.8 user option</a></li>
 349       <li><a name="toc-system-option" href="#system-option">5.3.9 system option</a></li>
 350       <li><a name="toc-test_002dsign-option" href="#test_002dsign-option">5.3.10 test-sign option</a></li>
 351       <li><a name="toc-sec_002dparam-option-1" href="#sec_002dparam-option-1">5.3.11 sec-param option</a></li>
 352       <li><a name="toc-inder-option-1" href="#inder-option-1">5.3.12 inder option</a></li>
 353       <li><a name="toc-outder-option-1" href="#outder-option-1">5.3.13 outder option</a></li>
 354       <li><a name="toc-tpmtool-exit-status-1" href="#tpmtool-exit-status-1">5.3.14 tpmtool exit status</a></li>
 355       <li><a name="toc-tpmtool-See-Also-1" href="#tpmtool-See-Also-1">5.3.15 tpmtool See Also</a></li>
 356       <li><a name="toc-tpmtool-Examples-1" href="#tpmtool-Examples-1">5.3.16 tpmtool Examples</a></li>
 357     </ul></li>
 358   </ul></li>
 359   <li><a name="toc-How-to-use-GnuTLS-in-applications-1" href="#How-to-use-GnuTLS-in-applications">6 How to use <acronym>GnuTLS</acronym> in applications</a>
 360   <ul class="no-bullet">
 361     <li><a name="toc-Introduction" href="#Introduction-to-the-library">6.1 Introduction</a>
 362     <ul class="no-bullet">
 363       <li><a name="toc-General-idea-1" href="#General-idea">6.1.1 General idea</a></li>
 364       <li><a name="toc-Error-handling-1" href="#Error-handling">6.1.2 Error handling</a></li>
 365       <li><a name="toc-Common-types-1" href="#Common-types">6.1.3 Common types</a></li>
 366       <li><a name="toc-Debugging-and-auditing-1" href="#Debugging-and-auditing">6.1.4 Debugging and auditing</a></li>
 367       <li><a name="toc-Thread-safety-1" href="#Thread-safety">6.1.5 Thread safety</a></li>
 368       <li><a name="toc-Sessions-and-fork-1" href="#Sessions-and-fork">6.1.6 Sessions and fork</a></li>
 369       <li><a name="toc-Callback-functions-1" href="#Callback-functions">6.1.7 Callback functions</a></li>
 370     </ul></li>
 371     <li><a name="toc-Preparation-1" href="#Preparation">6.2 Preparation</a>
 372     <ul class="no-bullet">
 373       <li><a name="toc-Headers-1" href="#Headers">6.2.1 Headers</a></li>
 374       <li><a name="toc-Initialization-2" href="#Initialization">6.2.2 Initialization</a></li>
 375       <li><a name="toc-Version-check-1" href="#Version-check">6.2.3 Version check</a></li>
 376       <li><a name="toc-Building-the-source-1" href="#Building-the-source">6.2.4 Building the source</a></li>
 377     </ul></li>
 378     <li><a name="toc-Session-initialization-1" href="#Session-initialization">6.3 Session initialization</a></li>
 379     <li><a name="toc-Associating-the-credentials-1" href="#Associating-the-credentials">6.4 Associating the credentials</a>
 380     <ul class="no-bullet">
 381       <li><a name="toc-Certificates" href="#Certificate-credentials">6.4.1 Certificates</a></li>
 382       <li><a name="toc-SRP" href="#SRP-credentials">6.4.2 SRP</a></li>
 383       <li><a name="toc-PSK" href="#PSK-credentials">6.4.3 PSK</a></li>
 384       <li><a name="toc-Anonymous" href="#Anonymous-credentials">6.4.4 Anonymous</a></li>
 385     </ul></li>
 386     <li><a name="toc-Setting-up-the-transport-layer-1" href="#Setting-up-the-transport-layer">6.5 Setting up the transport layer</a>
 387     <ul class="no-bullet">
 388       <li><a name="toc-Asynchronous-operation-1" href="#Asynchronous-operation">6.5.1 Asynchronous operation</a></li>
 389       <li><a name="toc-DTLS-sessions-1" href="#DTLS-sessions">6.5.2 DTLS sessions</a></li>
 390     </ul></li>
 391     <li><a name="toc-TLS-handshake-1" href="#TLS-handshake">6.6 TLS handshake</a></li>
 392     <li><a name="toc-Data-transfer-and-termination-1" href="#Data-transfer-and-termination">6.7 Data transfer and termination</a></li>
 393     <li><a name="toc-Buffered-data-transfer-1" href="#Buffered-data-transfer">6.8 Buffered data transfer</a></li>
 394     <li><a name="toc-Handling-alerts-1" href="#Handling-alerts">6.9 Handling alerts</a></li>
 395     <li><a name="toc-Priority-strings" href="#Priority-Strings">6.10 Priority strings</a></li>
 396     <li><a name="toc-Selecting-cryptographic-key-sizes-1" href="#Selecting-cryptographic-key-sizes">6.11 Selecting cryptographic key sizes</a></li>
 397     <li><a name="toc-Advanced-topics-1" href="#Advanced-topics">6.12 Advanced topics</a>
 398     <ul class="no-bullet">
 399       <li><a name="toc-Session-resumption-1" href="#Session-resumption">6.12.1 Session resumption</a></li>
 400       <li><a name="toc-Certificate-verification-1" href="#Certificate-verification">6.12.2 Certificate verification</a>
 401       <ul class="no-bullet">
 402         <li><a name="toc-Trust-on-first-use" href="#Trust-on-first-use">6.12.2.1 Trust on first use</a></li>
 403         <li><a name="toc-DANE-verification" href="#DANE-verification">6.12.2.2 DANE verification</a></li>
 404       </ul></li>
 405       <li><a name="toc-Parameter-generation-1" href="#Parameter-generation">6.12.3 Parameter generation</a></li>
 406       <li><a name="toc-Deriving-keys-for-other-applications_002fprotocols-1" href="#Deriving-keys-for-other-applications_002fprotocols">6.12.4 Deriving keys for other applications/protocols</a></li>
 407       <li><a name="toc-Channel-bindings" href="#Channel-Bindings">6.12.5 Channel bindings</a></li>
 408       <li><a name="toc-Interoperability-1" href="#Interoperability">6.12.6 Interoperability</a></li>
 409       <li><a name="toc-Compatibility-with-the-OpenSSL-library-1" href="#Compatibility-with-the-OpenSSL-library">6.12.7 Compatibility with the OpenSSL library</a></li>
 410     </ul></li>
 411   </ul></li>
 412   <li><a name="toc-GnuTLS-application-examples-1" href="#GnuTLS-application-examples">7 GnuTLS application examples</a>
 413   <ul class="no-bullet">
 414     <li><a name="toc-Client-examples-1" href="#Client-examples">7.1 Client examples</a>
 415     <ul class="no-bullet">
 416       <li><a name="toc-Simple-client-example-with-X_002e509-certificate-support-1" href="#Simple-client-example-with-X_002e509-certificate-support">7.1.1 Simple client example with <acronym>X.509</acronym> certificate support</a></li>
 417       <li><a name="toc-Simple-client-example-with-SSH_002dstyle-certificate-verification-1" href="#Simple-client-example-with-SSH_002dstyle-certificate-verification">7.1.2 Simple client example with SSH-style certificate verification</a></li>
 418       <li><a name="toc-Simple-client-example-with-anonymous-authentication-1" href="#Simple-client-example-with-anonymous-authentication">7.1.3 Simple client example with anonymous authentication</a></li>
 419       <li><a name="toc-Simple-datagram-TLS-client-example" href="#Simple-Datagram-TLS-client-example">7.1.4 Simple datagram <acronym>TLS</acronym> client example</a></li>
 420       <li><a name="toc-Obtaining-session-information-1" href="#Obtaining-session-information">7.1.5 Obtaining session information</a></li>
 421       <li><a name="toc-Using-a-callback-to-select-the-certificate-to-use-1" href="#Using-a-callback-to-select-the-certificate-to-use">7.1.6 Using a callback to select the certificate to use</a></li>
 422       <li><a name="toc-Verifying-a-certificate-1" href="#Verifying-a-certificate">7.1.7 Verifying a certificate</a></li>
 423       <li><a name="toc-Using-a-smart-card-with-TLS" href="#Client-using-a-smart-card-with-TLS">7.1.8 Using a smart card with TLS</a></li>
 424       <li><a name="toc-Client-with-resume-capability-example" href="#Client-with-Resume-capability-example">7.1.9 Client with resume capability example</a></li>
 425       <li><a name="toc-Simple-client-example-with-SRP-authentication-1" href="#Simple-client-example-with-SRP-authentication">7.1.10 Simple client example with <acronym>SRP</acronym> authentication</a></li>
 426       <li><a name="toc-Simple-client-example-using-the-C_002b_002b-API" href="#Simple-client-example-in-C_002b_002b">7.1.11 Simple client example using the C++ API</a></li>
 427       <li><a name="toc-Helper-functions-for-TCP-connections-1" href="#Helper-functions-for-TCP-connections">7.1.12 Helper functions for TCP connections</a></li>
 428       <li><a name="toc-Helper-functions-for-UDP-connections-1" href="#Helper-functions-for-UDP-connections">7.1.13 Helper functions for UDP connections</a></li>
 429     </ul></li>
 430     <li><a name="toc-Server-examples-1" href="#Server-examples">7.2 Server examples</a>
 431     <ul class="no-bullet">
 432       <li><a name="toc-Echo-server-with-X_002e509-authentication-1" href="#Echo-server-with-X_002e509-authentication">7.2.1 Echo server with <acronym>X.509</acronym> authentication</a></li>
 433       <li><a name="toc-Echo-server-with-OpenPGP-authentication-1" href="#Echo-server-with-OpenPGP-authentication">7.2.2 Echo server with <acronym>OpenPGP</acronym> authentication</a></li>
 434       <li><a name="toc-Echo-server-with-SRP-authentication-1" href="#Echo-server-with-SRP-authentication">7.2.3 Echo server with <acronym>SRP</acronym> authentication</a></li>
 435       <li><a name="toc-Echo-server-with-anonymous-authentication-1" href="#Echo-server-with-anonymous-authentication">7.2.4 Echo server with anonymous authentication</a></li>
 436       <li><a name="toc-DTLS-echo-server-with-X_002e509-authentication-1" href="#DTLS-echo-server-with-X_002e509-authentication">7.2.5 DTLS echo server with <acronym>X.509</acronym> authentication</a></li>
 437     </ul></li>
 438     <li><a name="toc-OCSP-example-1" href="#OCSP-example">7.3 OCSP example</a></li>
 439     <li><a name="toc-Miscellaneous-examples-1" href="#Miscellaneous-examples">7.4 Miscellaneous examples</a>
 440     <ul class="no-bullet">
 441       <li><a name="toc-Checking-for-an-alert-1" href="#Checking-for-an-alert">7.4.1 Checking for an alert</a></li>
 442       <li><a name="toc-X_002e509-certificate-parsing-example-1" href="#X_002e509-certificate-parsing-example">7.4.2 <acronym>X.509</acronym> certificate parsing example</a></li>
 443       <li><a name="toc-Listing-the-ciphersuites-in-a-priority-string-1" href="#Listing-the-ciphersuites-in-a-priority-string">7.4.3 Listing the ciphersuites in a priority string</a></li>
 444       <li><a name="toc-PKCS-_002312-structure-generation-example" href="#PKCS12-structure-generation-example">7.4.4 PKCS #12 structure generation example</a></li>
 445     </ul></li>
 446   </ul></li>
 447   <li><a name="toc-Using-GnuTLS-as-a-cryptographic-library-1" href="#Using-GnuTLS-as-a-cryptographic-library">8 Using GnuTLS as a cryptographic library</a>
 448   <ul class="no-bullet">
 449     <li><a name="toc-Symmetric-algorithms-1" href="#Symmetric-algorithms">8.1 Symmetric algorithms</a></li>
 450     <li><a name="toc-Public-key-algorithms-1" href="#Public-key-algorithms">8.2 Public key algorithms</a></li>
 451     <li><a name="toc-Hash-and-HMAC-functions-1" href="#Hash-and-HMAC-functions">8.3 Hash and HMAC functions</a></li>
 452     <li><a name="toc-Random-number-generation-1" href="#Random-number-generation">8.4 Random number generation</a></li>
 453   </ul></li>
 454   <li><a name="toc-Other-included-programs-1" href="#Other-included-programs">9 Other included programs</a>
 455   <ul class="no-bullet">
 456     <li><a name="toc-Invoking-gnutls_002dcli" href="#gnutls_002dcli-Invocation">9.1 Invoking gnutls-cli</a></li>
 457     <li><a name="toc-Invoking-gnutls_002dserv" href="#gnutls_002dserv-Invocation">9.2 Invoking gnutls-serv</a></li>
 458     <li><a name="toc-Invoking-gnutls_002dcli_002ddebug" href="#gnutls_002dcli_002ddebug-Invocation">9.3 Invoking gnutls-cli-debug</a></li>
 459   </ul></li>
 460   <li><a name="toc-Internal-Architecture-of-GnuTLS" href="#Internal-architecture-of-GnuTLS">10 Internal Architecture of GnuTLS</a>
 461   <ul class="no-bullet">
 462     <li><a name="toc-The-TLS-Protocol-1" href="#The-TLS-Protocol">10.1 The TLS Protocol</a></li>
 463     <li><a name="toc-TLS-Handshake-Protocol-1" href="#TLS-Handshake-Protocol">10.2 TLS Handshake Protocol</a></li>
 464     <li><a name="toc-TLS-Authentication-Methods-1" href="#TLS-Authentication-Methods">10.3 TLS Authentication Methods</a></li>
 465     <li><a name="toc-TLS-Extension-Handling-1" href="#TLS-Extension-Handling">10.4 TLS Extension Handling</a></li>
 466     <li><a name="toc-Cryptographic-Backend-1" href="#Cryptographic-Backend">10.5 Cryptographic Backend</a></li>
 467   </ul></li>
 468   <li><a name="toc-Upgrading-from-previous-versions-1" href="#Upgrading-from-previous-versions">Appendix A Upgrading from previous versions</a></li>
 469   <li><a name="toc-Support-1" href="#Support">Appendix B Support</a>
 470   <ul class="no-bullet">
 471     <li><a name="toc-Getting-Help" href="#Getting-help">B.1 Getting Help</a></li>
 472     <li><a name="toc-Commercial-Support-1" href="#Commercial-Support">B.2 Commercial Support</a></li>
 473     <li><a name="toc-Bug-Reports-1" href="#Bug-Reports">B.3 Bug Reports</a></li>
 474     <li><a name="toc-Contributing-1" href="#Contributing">B.4 Contributing</a></li>
 475     <li><a name="toc-Certification-1" href="#Certification">B.5 Certification</a></li>
 476   </ul></li>
 477   <li><a name="toc-Error-Codes-and-Descriptions" href="#Error-codes">Appendix C Error Codes and Descriptions</a></li>
 478   <li><a name="toc-Supported-Ciphersuites" href="#Supported-ciphersuites">Appendix D Supported Ciphersuites</a></li>
 479   <li><a name="toc-API-reference-1" href="#API-reference">Appendix E API reference</a>
 480   <ul class="no-bullet">
 481     <li><a name="toc-Core-TLS-API-1" href="#Core-TLS-API">E.1 Core TLS API</a></li>
 482     <li><a name="toc-Datagram-TLS-API-1" href="#Datagram-TLS-API">E.2 Datagram TLS API</a></li>
 483     <li><a name="toc-X_002e509-certificate-API" href="#X509-certificate-API">E.3 <acronym>X.509</acronym> certificate API</a></li>
 484     <li><a name="toc-OCSP-API-1" href="#OCSP-API">E.4 <acronym>OCSP</acronym> API</a></li>
 485     <li><a name="toc-OpenPGP-API-1" href="#OpenPGP-API">E.5 <acronym>OpenPGP</acronym> API</a></li>
 486     <li><a name="toc-PKCS-12-API-1" href="#PKCS-12-API">E.6 PKCS 12 API</a></li>
 487     <li><a name="toc-Hardware-token-via-PKCS-11-API" href="#PKCS-11-API">E.7 Hardware token via PKCS 11 API</a></li>
 488     <li><a name="toc-TPM-API-1" href="#TPM-API">E.8 TPM API</a></li>
 489     <li><a name="toc-Abstract-key-API-1" href="#Abstract-key-API">E.9 Abstract key API</a></li>
 490     <li><a name="toc-DANE-API-1" href="#DANE-API">E.10 DANE API</a></li>
 491     <li><a name="toc-Cryptographic-API-1" href="#Cryptographic-API">E.11 Cryptographic API</a></li>
 492     <li><a name="toc-Compatibility-API-1" href="#Compatibility-API">E.12 Compatibility API</a></li>
 493   </ul></li>
 494   <li><a name="toc-Copying-Information-1" href="#Copying-Information">Appendix F Copying Information</a></li>
 495   <li><a name="toc-Bibliography-1" href="#Bibliography">Bibliography</a></li>
 496   <li><a name="toc-Function-and-Data-Index-1" href="#Function-and-Data-Index">Function and Data Index</a></li>
 497   <li><a name="toc-Concept-Index-1" href="#Concept-Index">Concept Index</a></li>
 498 </ul>
 499 </div>
 500
 501
 502 <a name="Top"></a>
 503 <div class="header">
 504 <p>
 505 Next: <a href="#Preface" accesskey="n" rel="next">Preface</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
 506 </div>
 507 <a name="GnuTLS"></a>
 508 <h1 class="top">GnuTLS</h1>
 509
 510 <p>This manual is last updated 23 March 2015 for version
 511 3.3.26 of GnuTLS.
 512 </p>
 513 <p>Copyright &copy; 2001-2013 Free Software Foundation, Inc.\\
 514 Copyright &copy; 2001-2013 Nikos Mavrogiannopoulos
 515 </p>
 516 <blockquote>
 517 <p>Permission is granted to copy, distribute and/or modify this document
 518 under the terms of the GNU Free Documentation License, Version 1.3 or
 519 any later version published by the Free Software Foundation; with no
 520 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
 521 copy of the license is included in the section entitled &ldquo;GNU Free
 522 Documentation License&rdquo;.
 523 </p></blockquote>
 524
 525
 526 <table class="menu" border="0" cellspacing="0">
 527 <tr><td align="left" valign="top">&bull; <a href="#Preface" accesskey="1">Preface</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 528 </td></tr>
 529 <tr><td align="left" valign="top">&bull; <a href="#Introduction-to-GnuTLS" accesskey="2">Introduction to GnuTLS</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 530 </td></tr>
 531 <tr><td align="left" valign="top">&bull; <a href="#Introduction-to-TLS" accesskey="3">Introduction to TLS</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 532 </td></tr>
 533 <tr><td align="left" valign="top">&bull; <a href="#Authentication-methods" accesskey="4">Authentication methods</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 534 </td></tr>
 535 <tr><td align="left" valign="top">&bull; <a href="#Hardware-security-modules-and-abstract-key-types" accesskey="5">Hardware security modules and abstract key types</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 536 </td></tr>
 537 <tr><td align="left" valign="top">&bull; <a href="#How-to-use-GnuTLS-in-applications" accesskey="6">How to use GnuTLS in applications</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 538 </td></tr>
 539 <tr><td align="left" valign="top">&bull; <a href="#GnuTLS-application-examples" accesskey="7">GnuTLS application examples</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 540 </td></tr>
 541 <tr><td align="left" valign="top">&bull; <a href="#Using-GnuTLS-as-a-cryptographic-library" accesskey="8">Using GnuTLS as a cryptographic library</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 542 </td></tr>
 543 <tr><td align="left" valign="top">&bull; <a href="#Other-included-programs" accesskey="9">Other included programs</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 544 </td></tr>
 545 <tr><td align="left" valign="top">&bull; <a href="#Internal-architecture-of-GnuTLS">Internal architecture of GnuTLS</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 546 </td></tr>
 547 <tr><td align="left" valign="top">&bull; <a href="#Upgrading-from-previous-versions">Upgrading from previous versions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 548 </td></tr>
 549 <tr><td align="left" valign="top">&bull; <a href="#Support">Support</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 550 </td></tr>
 551 <tr><td align="left" valign="top">&bull; <a href="#Error-codes">Error codes</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 552 </td></tr>
 553 <tr><td align="left" valign="top">&bull; <a href="#Supported-ciphersuites">Supported ciphersuites</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 554 </td></tr>
 555 <tr><td align="left" valign="top">&bull; <a href="#API-reference">API reference</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 556 </td></tr>
 557 <tr><td align="left" valign="top">&bull; <a href="#Copying-Information">Copying Information</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 558 </td></tr>
 559 <tr><td align="left" valign="top">&bull; <a href="#Bibliography">Bibliography</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 560 </td></tr>
 561 <tr><td align="left" valign="top">&bull; <a href="#Function-and-Data-Index">Function and Data Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 562 </td></tr>
 563 <tr><td align="left" valign="top">&bull; <a href="#Concept-Index">Concept Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 564 </td></tr>
 565 </table>
 566
 567 <hr>
 568 <a name="Preface"></a>
 569 <div class="header">
 570 <p>
 571 Next: <a href="#Introduction-to-GnuTLS" accesskey="n" rel="next">Introduction to GnuTLS</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
 572 </div>
 573 <a name="Preface-1"></a>
 574 <h2 class="chapter">1 Preface</h2>
 575
 576 <p>This document demonstrates and explains the <acronym>GnuTLS</acronym>
 577 library API.  A brief introduction to the protocols and the technology
 578 involved is also included so that an application programmer can
 579 better understand the <acronym>GnuTLS</acronym> purpose and actual offerings.
 580 Even if <acronym>GnuTLS</acronym> is a typical library software, it operates
 581 over several security and cryptographic protocols which require the
 582 programmer to make careful and correct usage of them. Otherwise it
 583 is likely to only obtain a false sense of security.
 584 The term of security is very broad even if restricted to computer
 585 software, and cannot be confined to a single cryptographic
 586 library.  For that reason, do not consider any program secure just
 587 because it uses <acronym>GnuTLS</acronym>; there are several ways to compromise
 588 a program or a communication line and <acronym>GnuTLS</acronym> only helps with
 589 some of them.
 590 </p>
 591 <p>Although this document tries to be self contained, basic network
 592 programming and public key infrastructure (PKI) knowledge is assumed
 593 in most of it. A good introduction to networking can be found
 594 in [<em>STEVENS</em>], to public key infrastructure in [<em>GUTPKI</em>]
 595 and to security engineering in [<em>ANDERSON</em>].
 596 </p>
 597 <p>Updated versions of the <acronym>GnuTLS</acronym> software and this document
 598 will be available from <a href="http://www.gnutls.org/">http://www.gnutls.org/</a>.
 599 </p>
 600 <hr>
 601 <a name="Introduction-to-GnuTLS"></a>
 602 <div class="header">
 603 <p>
 604 Next: <a href="#Introduction-to-TLS" accesskey="n" rel="next">Introduction to TLS</a>, Previous: <a href="#Preface" accesskey="p" rel="prev">Preface</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
 605 </div>
 606 <a name="Introduction-to-GnuTLS-1"></a>
 607 <h2 class="chapter">2 Introduction to GnuTLS</h2>
 608
 609 <p>In brief <acronym>GnuTLS</acronym> can be described as a library which offers an API
 610 to access secure communication protocols. These protocols provide
 611 privacy over insecure lines, and were designed to prevent
 612 eavesdropping, tampering, or message forgery.
 613 </p>
 614 <p>Technically <acronym>GnuTLS</acronym> is a portable ANSI C based library which
 615 implements the protocols ranging from SSL 3.0 to TLS 1.2 (see <a href="#Introduction-to-TLS">Introduction to TLS</a>,
 616 for a detailed description of the protocols), accompanied
 617 with the required framework for authentication and public key
 618 infrastructure.  Important features of the <acronym>GnuTLS</acronym> library
 619 include:
 620 </p>
 621 <ul>
 622 <li> Support for TLS 1.2, TLS 1.1, TLS 1.0 and SSL 3.0 protocols.
 623
 624 </li><li> Support for Datagram TLS 1.0 and 1.2.
 625
 626 </li><li> Support for handling and verification of <acronym>X.509</acronym> and <acronym>OpenPGP</acronym> certificates.
 627
 628 </li><li> Support for password authentication using <acronym>TLS-SRP</acronym>.
 629
 630 </li><li> Support for keyed authentication using <acronym>TLS-PSK</acronym>.
 631
 632 </li><li> Support for TPM, <acronym>PKCS</acronym> #11 tokens and smart-cards.
 633
 634 </li></ul>
 635
 636 <p>The <acronym>GnuTLS</acronym> library consists of three independent parts, namely the &ldquo;TLS
 637 protocol part&rdquo;, the &ldquo;Certificate part&rdquo;, and the &ldquo;Cryptographic
 638 back-end&rdquo; part.  The &ldquo;TLS protocol part&rdquo; is the actual protocol
 639 implementation, and is entirely implemented within the
 640 <acronym>GnuTLS</acronym> library.  The &ldquo;Certificate part&rdquo; consists of the
 641 certificate parsing, and verification functions and it uses
 642 functionality from the
 643 libtasn1 library.
 644 The &ldquo;Cryptographic back-end&rdquo; is provided by the nettle
 645 and gmplib libraries.
 646 </p>
 647 <table class="menu" border="0" cellspacing="0">
 648 <tr><td align="left" valign="top">&bull; <a href="#Downloading-and-installing" accesskey="1">Downloading and installing</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 649 </td></tr>
 650 <tr><td align="left" valign="top">&bull; <a href="#Document-overview" accesskey="2">Document overview</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 651 </td></tr>
 652 </table>
 653
 654 <hr>
 655 <a name="Downloading-and-installing"></a>
 656 <div class="header">
 657 <p>
 658 Next: <a href="#Document-overview" accesskey="n" rel="next">Document overview</a>, Up: <a href="#Introduction-to-GnuTLS" accesskey="u" rel="up">Introduction to GnuTLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
 659 </div>
 660 <a name="Downloading-and-installing-1"></a>
 661 <h3 class="section">2.1 Downloading and installing</h3>
 662 <a name="index-installation"></a>
 663 <a name="index-download"></a>
 664
 665 <p>GnuTLS is available for download at:
 666 <a href="http://www.gnutls.org/download.html">http://www.gnutls.org/download.html</a>
 667 </p>
 668 <p>GnuTLS uses a development cycle where even minor version numbers
 669 indicate a stable release and a odd minor version number indicate a
 670 development release.  For example, GnuTLS 1.6.3 denote a stable
 671 release since 6 is even, and GnuTLS 1.7.11 denote a development
 672 release since 7 is odd.
 673 </p>
 674 <p>GnuTLS depends on <code>nettle</code> and <code>gmplib</code>, and you will need to install it
 675 before installing GnuTLS.  The <code>nettle</code> library is available from
 676 <a href="http://www.lysator.liu.se/~nisse/nettle/">http://www.lysator.liu.se/~nisse/nettle/</a>, while <code>gmplib</code> is available
 677 from <a href="http://www.gmplib.org/">http://www.gmplib.org/</a>.
 678 Don&rsquo;t forget to verify the cryptographic signature after downloading
 679 source code packages.
 680 </p>
 681 <p>The package is then extracted, configured and built like many other
 682 packages that use Autoconf.  For detailed information on configuring
 683 and building it, refer to the <samp>INSTALL</samp> file that is part of the
 684 distribution archive.  Typically you invoke <code>./configure</code> and
 685 then <code>make check install</code>.  There are a number of compile-time
 686 parameters, as discussed below.
 687 </p>
 688 <p>Several parts of GnuTLS require ASN.1 functionality, which is provided by
 689 a library called libtasn1.  A copy of libtasn1 is included in GnuTLS.  If you
 690 want to install it separately (e.g., to make it possibly to use
 691 libtasn1 in other programs), you can get it from
 692 <a href="http://www.gnu.org/software/libtasn1/">http://www.gnu.org/software/libtasn1/</a>.
 693 </p>
 694 <p>The compression library, <code>libz</code>, the PKCS #11 helper library <code>p11-kit</code>, as well
 695 as the TPM library <code>trousers</code>, are
 696 optional dependencies. You may get libz from <a href="http://www.zlib.net/">http://www.zlib.net/</a>,
 697 p11-kit from <a href="http://p11-glue.freedesktop.org/">http://p11-glue.freedesktop.org/</a> and trousers from
 698 <a href="http://trousers.sourceforge.net/">http://trousers.sourceforge.net/</a>.
 699 </p>
 700 <p>A few <code>configure</code> options may be relevant, summarized below.
 701 They disable or enable particular features,
 702 to create a smaller library with only the required features.
 703 Note however, that although a smaller library is generated, the
 704 included programs are not guaranteed to compile if some of these
 705 options are given.
 706 </p>
 707 <pre class="verbatim">--disable-srp-authentication
 708 --disable-psk-authentication
 709 --disable-anon-authentication
 710 --disable-openpgp-authentication
 711 --disable-dhe
 712 --disable-ecdhe
 713 --disable-openssl-compatibility
 714 --disable-dtls-srtp-support
 715 --disable-alpn-support
 716 --disable-heartbeat-support
 717 --disable-libdane
 718 --without-p11-kit
 719 --without-tpm
 720 --without-zlib
 721
 722 </pre>
 723 <p>For the complete list, refer to the output from <code>configure --help</code>.
 724 </p>
 725 <hr>
 726 <a name="Document-overview"></a>
 727 <div class="header">
 728 <p>
 729 Previous: <a href="#Downloading-and-installing" accesskey="p" rel="prev">Downloading and installing</a>, Up: <a href="#Introduction-to-GnuTLS" accesskey="u" rel="up">Introduction to GnuTLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
 730 </div>
 731 <a name="Overview"></a>
 732 <h3 class="section">2.2 Overview</h3>
 733 <p>In this document we present an overview of the supported security protocols in <a href="#Introduction-to-TLS">Introduction to TLS</a>, and
 734 continue by providing more information on the certificate authentication in <a href="#Certificate-authentication">Certificate authentication</a>,
 735 and shared-key as well anonymous authentication in <a href="#Shared_002dkey-and-anonymous-authentication">Shared-key and anonymous authentication</a>. We
 736 elaborate on certificate authentication by demonstrating advanced usage of the API in <a href="#More-on-certificate-authentication">More on certificate authentication</a>.
 737 The core of the TLS library is presented in <a href="#How-to-use-GnuTLS-in-applications">How to use GnuTLS in applications</a> and example
 738 applications are listed in <a href="#GnuTLS-application-examples">GnuTLS application examples</a>.
 739 In <a href="#Other-included-programs">Other included programs</a> the usage of few included programs that
 740 may assist debugging is presented. The last chapter is <a href="#Internal-architecture-of-GnuTLS">Internal architecture of GnuTLS</a> that
 741 provides a short introduction to GnuTLS&rsquo; internal architecture.
 742 </p>
 743 <hr>
 744 <a name="Introduction-to-TLS"></a>
 745 <div class="header">
 746 <p>
 747 Next: <a href="#Authentication-methods" accesskey="n" rel="next">Authentication methods</a>, Previous: <a href="#Introduction-to-GnuTLS" accesskey="p" rel="prev">Introduction to GnuTLS</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
 748 </div>
 749 <a name="Introduction-to-TLS-and-DTLS"></a>
 750 <h2 class="chapter">3 Introduction to <acronym>TLS</acronym> and <acronym>DTLS</acronym></h2>
 751
 752 <p><acronym>TLS</acronym> stands for &ldquo;Transport Layer Security&rdquo; and is the
 753 successor of SSL, the Secure Sockets Layer protocol [<em>SSL3</em>]
 754 designed by Netscape.  <acronym>TLS</acronym> is an Internet protocol, defined
 755 by <acronym>IETF</acronym><a name="DOCF1" href="#FOOT1"><sup>1</sup></a>, described in [<em>RFC5246</em>].
 756 The protocol provides
 757 confidentiality, and authentication layers over any reliable transport
 758 layer.  The description, above, refers to <acronym>TLS</acronym> 1.0 but applies
 759 to all other TLS versions as the differences between the protocols are not major.
 760 </p>
 761 <p>The <acronym>DTLS</acronym> protocol, or &ldquo;Datagram <acronym>TLS</acronym>&rdquo; [<em>RFC4347</em>] is a
 762 protocol with identical goals as <acronym>TLS</acronym>, but can operate
 763 under unreliable transport layers such as <acronym>UDP</acronym>. The
 764 discussions below apply to this protocol as well, except when
 765 noted otherwise.
 766 </p>
 767 <table class="menu" border="0" cellspacing="0">
 768 <tr><td align="left" valign="top">&bull; <a href="#TLS-layers" accesskey="1">TLS layers</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 769 </td></tr>
 770 <tr><td align="left" valign="top">&bull; <a href="#The-transport-layer" accesskey="2">The transport layer</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 771 </td></tr>
 772 <tr><td align="left" valign="top">&bull; <a href="#The-TLS-record-protocol" accesskey="3">The TLS record protocol</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 773 </td></tr>
 774 <tr><td align="left" valign="top">&bull; <a href="#The-TLS-Alert-Protocol" accesskey="4">The TLS Alert Protocol</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 775 </td></tr>
 776 <tr><td align="left" valign="top">&bull; <a href="#The-TLS-Handshake-Protocol" accesskey="5">The TLS Handshake Protocol</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 777 </td></tr>
 778 <tr><td align="left" valign="top">&bull; <a href="#TLS-Extensions" accesskey="6">TLS Extensions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 779 </td></tr>
 780 <tr><td align="left" valign="top">&bull; <a href="#How-to-use-TLS-in-application-protocols" accesskey="7">How to use TLS in application protocols</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 781 </td></tr>
 782 <tr><td align="left" valign="top">&bull; <a href="#On-SSL-2-and-older-protocols" accesskey="8">On SSL 2 and older protocols</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 783 </td></tr>
 784 </table>
 785
 786 <hr>
 787 <a name="TLS-layers"></a>
 788 <div class="header">
 789 <p>
 790 Next: <a href="#The-transport-layer" accesskey="n" rel="next">The transport layer</a>, Up: <a href="#Introduction-to-TLS" accesskey="u" rel="up">Introduction to TLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
 791 </div>
 792 <a name="TLS-layers-1"></a>
 793 <h3 class="section">3.1 TLS layers</h3>
 794 <a name="index-TLS-layers"></a>
 795
 796 <p><acronym>TLS</acronym> is a layered protocol, and consists of the record
 797 protocol, the handshake protocol and the alert protocol. The record
 798 protocol is to serve all other protocols and is above the transport
 799 layer.  The record protocol offers symmetric encryption, data
 800 authenticity, and optionally compression.
 801 The alert protocol offers some signaling to the other protocols. It
 802 can help informing the peer for the cause of failures and other error
 803 conditions.  See <a href="#The-Alert-Protocol">The Alert Protocol</a>, for more information.  The
 804 alert protocol is above the record protocol.
 805 </p>
 806 <p>The handshake protocol is responsible for the security parameters&rsquo;
 807 negotiation, the initial key exchange and authentication.
 808 See <a href="#The-Handshake-Protocol">The Handshake Protocol</a>, for more information about the handshake
 809 protocol.  The protocol layering in TLS is shown in <a href="#fig_002dtls_002dlayers">Figure 3.1</a>.
 810 </p>
 811 <div class="float"><a name="fig_002dtls_002dlayers"></a>
 812 <img src="gnutls-layers.png" alt="gnutls-layers">
 813
 814 <div class="float-caption"><p><strong>Figure 3.1: </strong>The TLS protocol layers.</p></div></div>
 815 <hr>
 816 <a name="The-transport-layer"></a>
 817 <div class="header">
 818 <p>
 819 Next: <a href="#The-TLS-record-protocol" accesskey="n" rel="next">The TLS record protocol</a>, Previous: <a href="#TLS-layers" accesskey="p" rel="prev">TLS layers</a>, Up: <a href="#Introduction-to-TLS" accesskey="u" rel="up">Introduction to TLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
 820 </div>
 821 <a name="The-transport-layer-1"></a>
 822 <h3 class="section">3.2 The transport layer</h3>
 823 <a name="index-transport-protocol"></a>
 824 <a name="index-transport-layer"></a>
 825
 826 <p><acronym>TLS</acronym> is not limited to any transport layer and can be used
 827 above any transport layer, as long as it is a reliable one.  <acronym>DTLS</acronym>
 828 can be used over reliable and unreliable transport layers.
 829 <acronym>GnuTLS</acronym> supports TCP and UDP layers transparently using
 830 the Berkeley sockets API. However, any transport layer can be used
 831 by providing callbacks for <acronym>GnuTLS</acronym> to access the transport layer
 832 (for details see <a href="#Setting-up-the-transport-layer">Setting up the transport layer</a>).
 833 </p>
 834 <hr>
 835 <a name="The-TLS-record-protocol"></a>
 836 <div class="header">
 837 <p>
 838 Next: <a href="#The-TLS-Alert-Protocol" accesskey="n" rel="next">The TLS Alert Protocol</a>, Previous: <a href="#The-transport-layer" accesskey="p" rel="prev">The transport layer</a>, Up: <a href="#Introduction-to-TLS" accesskey="u" rel="up">Introduction to TLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
 839 </div>
 840 <a name="The-TLS-record-protocol-1"></a>
 841 <h3 class="section">3.3 The TLS record protocol</h3>
 842 <a name="index-record-protocol"></a>
 843
 844 <p>The record protocol is the secure communications provider. Its purpose
 845 is to encrypt, authenticate and &mdash;optionally&mdash; compress packets.
 846 The record layer functions can be called at any time after
 847 the handshake process is finished, when there is need to receive
 848 or send data. In <acronym>DTLS</acronym> however, due to re-transmission
 849 timers used in the handshake out-of-order handshake data might
 850 be received for some time (maximum 60 seconds) after the handshake
 851 process is finished.
 852 </p>
 853 <p>The functions to access the record protocol are limited to send
 854 and receive functions, which might, given
 855 the importance of this protocol in <acronym>TLS</acronym>, seem awkward.  This is because
 856 the record protocol&rsquo;s parameters are all set by the handshake protocol.
 857 The record protocol initially starts with NULL parameters, which means
 858 no encryption, and no MAC is used. Encryption and authentication begin
 859 just after the handshake protocol has finished.
 860 </p>
 861 <table class="menu" border="0" cellspacing="0">
 862 <tr><td align="left" valign="top">&bull; <a href="#Encryption-algorithms-used-in-the-record-layer" accesskey="1">Encryption algorithms used in the record layer</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 863 </td></tr>
 864 <tr><td align="left" valign="top">&bull; <a href="#Compression-algorithms-used-in-the-record-layer" accesskey="2">Compression algorithms used in the record layer</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 865 </td></tr>
 866 <tr><td align="left" valign="top">&bull; <a href="#Weaknesses-and-countermeasures" accesskey="3">Weaknesses and countermeasures</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 867 </td></tr>
 868 <tr><td align="left" valign="top">&bull; <a href="#On-Record-Padding" accesskey="4">On Record Padding</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 869 </td></tr>
 870 </table>
 871
 872 <hr>
 873 <a name="Encryption-algorithms-used-in-the-record-layer"></a>
 874 <div class="header">
 875 <p>
 876 Next: <a href="#Compression-algorithms-used-in-the-record-layer" accesskey="n" rel="next">Compression algorithms used in the record layer</a>, Up: <a href="#The-TLS-record-protocol" accesskey="u" rel="up">The TLS record protocol</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
 877 </div>
 878 <a name="Encryption-algorithms-used-in-the-record-layer-1"></a>
 879 <h4 class="subsection">3.3.1 Encryption algorithms used in the record layer</h4>
 880 <a name="index-symmetric-encryption-algorithms"></a>
 881
 882 <p>Confidentiality in the record layer is achieved by using symmetric
 883 block encryption algorithms like <code>3DES</code>, <code>AES</code>
 884 or stream algorithms like <code>ARCFOUR_128</code>.
 885  Ciphers are encryption algorithms that use a single, secret,
 886 key to encrypt and decrypt data. Block algorithms in CBC mode also provide
 887 protection against statistical analysis of the data.  Thus, if you&rsquo;re
 888 using the <acronym>TLS</acronym> protocol, a random number of blocks will be
 889 appended to data, to prevent eavesdroppers from guessing the actual
 890 data size.
 891 </p>
 892 <p>The supported in <acronym>GnuTLS</acronym> ciphers and MAC algorithms are shown in <a href="#tab_003aciphers">Table 3.1</a> and
 893 <a href="#tab_003amacs">Table 3.2</a>.
 894 </p>
 895 <div class="float"><a name="tab_003aciphers"></a>
 896 <table>
 897 <thead><tr><th width="20%">Algorithm</th><th width="70%">Description</th></tr></thead>
 898 <tr><td width="20%">3DES_CBC</td><td width="70%">This is the DES block cipher algorithm used with triple
 899 encryption (EDE). Has 64 bits block size and is used in CBC mode.</td></tr>
 900 <tr><td width="20%">ARCFOUR_128</td><td width="70%">ARCFOUR_128 is a compatible algorithm with RSA&rsquo;s RC4 algorithm, which is considered to be a trade
 901 secret. It is a fast cipher but considered weak today.</td></tr>
 902 <tr><td width="20%">AES_CBC</td><td width="70%">AES or RIJNDAEL is the block cipher algorithm that replaces the old
 903 DES algorithm.  Has 128 bits block size and is used in CBC mode.</td></tr>
 904 <tr><td width="20%">AES_GCM</td><td width="70%">This is the AES algorithm in the authenticated encryption GCM mode.
 905 This mode combines message authentication and encryption and can
 906 be extremely fast on CPUs that support hardware acceleration.</td></tr>
 907 <tr><td width="20%">CAMELLIA_CBC</td><td width="70%">This is an 128-bit block cipher developed by Mitsubishi and NTT. It
 908 is one of the approved ciphers of the European NESSIE and Japanese
 909 CRYPTREC projects.</td></tr>
 910 </table>
 911
 912 <div class="float-caption"><p><strong>Table 3.1: </strong>Supported ciphers.</p></div></div>
 913
 914 <div class="float"><a name="tab_003amacs"></a>
 915 <table>
 916 <thead><tr><th width="20%">Algorithm</th><th width="70%">Description</th></tr></thead>
 917 <tr><td width="20%">MAC_MD5</td><td width="70%">This is an HMAC based on MD5 a cryptographic hash algorithm designed
 918 by Ron Rivest. Outputs 128 bits of data.</td></tr>
 919 <tr><td width="20%">MAC_SHA1</td><td width="70%">An HMAC based on the SHA1 cryptographic hash algorithm
 920 designed by NSA. Outputs 160 bits of data.</td></tr>
 921 <tr><td width="20%">MAC_SHA256</td><td width="70%">An HMAC based on SHA256. Outputs 256 bits of data.</td></tr>
 922 <tr><td width="20%">MAC_AEAD</td><td width="70%">This indicates that an authenticated encryption algorithm, such as
 923 GCM, is in use.</td></tr>
 924 </table>
 925
 926 <div class="float-caption"><p><strong>Table 3.2: </strong>Supported MAC algorithms.</p></div></div>
 927
 928 <hr>
 929 <a name="Compression-algorithms-used-in-the-record-layer"></a>
 930 <div class="header">
 931 <p>
 932 Next: <a href="#Weaknesses-and-countermeasures" accesskey="n" rel="next">Weaknesses and countermeasures</a>, Previous: <a href="#Encryption-algorithms-used-in-the-record-layer" accesskey="p" rel="prev">Encryption algorithms used in the record layer</a>, Up: <a href="#The-TLS-record-protocol" accesskey="u" rel="up">The TLS record protocol</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
 933 </div>
 934 <a name="Compression-algorithms-used-in-the-record-layer-1"></a>
 935 <h4 class="subsection">3.3.2 Compression algorithms used in the record layer</h4>
 936 <a name="index-compression-algorithms"></a>
 937
 938 <p>The TLS record layer also supports compression.  The algorithms
 939 implemented in <acronym>GnuTLS</acronym> can be found in the table below.
 940 The included algorithms perform really good when text, or other
 941 compressible data are to be transferred, but offer nothing on already
 942 compressed data, such as compressed images, zipped archives etc.
 943 These compression algorithms, may be useful in high bandwidth TLS
 944 tunnels, and in cases where network usage has to be minimized. It
 945 should be noted however that compression increases latency.
 946 </p>
 947 <p>The record layer compression in <acronym>GnuTLS</acronym> is implemented based
 948 on [<em>RFC3749</em>]. The supported algorithms are shown below.
 949 </p>
 950 <div class="float"><a name="gnutls_005fcompression_005fmethod_005ft"></a>
 951
 952
 953 <dl compact="compact">
 954 <dt><code>GNUTLS_COMP_UNKNOWN</code></dt>
 955 <dd><p>Unknown compression method.
 956 </p></dd>
 957 <dt><code>GNUTLS_COMP_NULL</code></dt>
 958 <dd><p>The NULL compression method (no compression).
 959 </p></dd>
 960 <dt><code>GNUTLS_COMP_DEFLATE</code></dt>
 961 <dd><p>The DEFLATE compression method from zlib.
 962 </p></dd>
 963 <dt><code>GNUTLS_COMP_ZLIB</code></dt>
 964 <dd><p>Same as <code>GNUTLS_COMP_DEFLATE</code> .
 965 </p></dd>
 966 </dl>
 967
 968 <div class="float-caption"><p><strong>Figure 3.2: </strong>Supported compression algorithms</p></div></div>
 969 <p>Note that compression enables attacks such as traffic analysis, or even
 970 plaintext recovery under certain circumstances. To avoid some of these
 971 attacks GnuTLS allows each record to be compressed independently (i.e.,
 972 stateless compression), by using the &quot;%STATELESS_COMPRESSION&quot; priority string,
 973 in order to be used in cases where the attacker controlled data are
 974 pt in separate records.
 975 </p>
 976 <hr>
 977 <a name="Weaknesses-and-countermeasures"></a>
 978 <div class="header">
 979 <p>
 980 Next: <a href="#On-Record-Padding" accesskey="n" rel="next">On Record Padding</a>, Previous: <a href="#Compression-algorithms-used-in-the-record-layer" accesskey="p" rel="prev">Compression algorithms used in the record layer</a>, Up: <a href="#The-TLS-record-protocol" accesskey="u" rel="up">The TLS record protocol</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
 981 </div>
 982 <a name="Weaknesses-and-countermeasures-1"></a>
 983 <h4 class="subsection">3.3.3 Weaknesses and countermeasures</h4>
 984
 985 <p>Some weaknesses that may affect the security of the record layer have
 986 been found in <acronym>TLS</acronym> 1.0 protocol. These weaknesses can be
 987 exploited by active attackers, and exploit the facts that
 988 </p>
 989 <ol>
 990 <li> <acronym>TLS</acronym> has separate alerts for &ldquo;decryption_failed&rdquo; and
 991 &ldquo;bad_record_mac&rdquo;
 992
 993 </li><li> The decryption failure reason can be detected by timing the response
 994 time.
 995
 996 </li><li> The IV for CBC encrypted packets is the last block of the previous
 997 encrypted packet.
 998
 999 </li></ol>
1000
1001 <p>Those weaknesses were solved in <acronym>TLS</acronym> 1.1 [<em>RFC4346</em>]
1002 which is implemented in <acronym>GnuTLS</acronym>. For this reason we suggest
1003 to always negotiate the highest supported TLS version with the
1004 peer<a name="DOCF2" href="#FOOT2"><sup>2</sup></a>.
1005 For a detailed discussion of the issues see the archives of the TLS
1006 Working Group mailing list and [<em>CBCATT</em>].
1007 </p>
1008 <hr>
1009 <a name="On-Record-Padding"></a>
1010 <div class="header">
1011 <p>
1012 Previous: <a href="#Weaknesses-and-countermeasures" accesskey="p" rel="prev">Weaknesses and countermeasures</a>, Up: <a href="#The-TLS-record-protocol" accesskey="u" rel="up">The TLS record protocol</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1013 </div>
1014 <a name="On-record-padding"></a>
1015 <h4 class="subsection">3.3.4 On record padding</h4>
1016 <a name="index-record-padding"></a>
1017 <a name="index-bad_005frecord_005fmac"></a>
1018
1019 <p>The TLS protocol allows for extra padding of records in CBC ciphers, to prevent
1020 statistical analysis based on the length of exchanged messages (see [<em>RFC5246</em>] section 6.2.3.2).
1021 GnuTLS appears to be one of few implementations that take advantage of this feature:
1022 the user can provide some plaintext data with a range of lengths she wishes to hide,
1023 and GnuTLS adds extra padding to make sure the attacker cannot tell the real plaintext
1024 length is in a range smaller than the user-provided one.
1025 Use <a href="#gnutls_005frecord_005fsend_005frange">gnutls_record_send_range</a> to send length-hidden messages and
1026 <a href="#gnutls_005frecord_005fcan_005fuse_005flength_005fhiding">gnutls_record_can_use_length_hiding</a> to check whether the current
1027 session supports length hiding. Using the standard <a href="#gnutls_005frecord_005fsend">gnutls_record_send</a>
1028 will only add minimal padding.
1029 </p>
1030 <p>The TLS implementation in the Symbian operating system, frequently
1031 used by Nokia and Sony-Ericsson mobile phones, cannot handle
1032 non-minimal record padding.  What happens when one of these clients
1033 handshake with a GnuTLS server is that the client will fail to compute
1034 the correct MAC for the record.  The client sends a TLS alert
1035 (<code>bad_record_mac</code>) and disconnects.  Typically this will result
1036 in error messages such as &rsquo;A TLS fatal alert has been received&rsquo;, &rsquo;Bad
1037 record MAC&rsquo;, or both, on the GnuTLS server side.
1038 </p>
1039 <p>If compatibility with such devices is a concern, not sending length-hidden messages
1040 solves the problem by using minimal padding.
1041 </p>
1042 <p>If you implement an application that has a configuration file, we
1043 recommend that you make it possible for users or administrators to
1044 specify a GnuTLS protocol priority string, which is used by your
1045 application via <a href="#gnutls_005fpriority_005fset">gnutls_priority_set</a>.  To allow the best
1046 flexibility, make it possible to have a different priority string for
1047 different incoming IP addresses.
1048 </p>
1049
1050 <hr>
1051 <a name="The-TLS-Alert-Protocol"></a>
1052 <div class="header">
1053 <p>
1054 Next: <a href="#The-TLS-Handshake-Protocol" accesskey="n" rel="next">The TLS Handshake Protocol</a>, Previous: <a href="#The-TLS-record-protocol" accesskey="p" rel="prev">The TLS record protocol</a>, Up: <a href="#Introduction-to-TLS" accesskey="u" rel="up">Introduction to TLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1055 </div>
1056 <a name="The-TLS-alert-protocol"></a>
1057 <h3 class="section">3.4 The TLS alert protocol</h3>
1058 <a name="The-Alert-Protocol"></a><a name="index-alert-protocol"></a>
1059
1060 <p>The alert protocol is there to allow signals to be sent between peers.
1061 These signals are mostly used to inform the peer about the cause of a
1062 protocol failure. Some of these signals are used internally by the
1063 protocol and the application protocol does not have to cope with them
1064 (e.g. <code>GNUTLS_A_CLOSE_NOTIFY</code>), and others refer to the
1065 application protocol solely (e.g. <code>GNUTLS_A_USER_CANCELLED</code>).  An
1066 alert signal includes a level indication which may be either fatal or
1067 warning. Fatal alerts always terminate the current connection, and
1068 prevent future re-negotiations using the current session ID. All alert
1069 messages are summarized in the table below.
1070 </p>
1071 <p>The alert messages are protected by the record protocol, thus the
1072 information that is included does not leak. You must take extreme care
1073 for the alert information not to leak to a possible attacker, via
1074 public log files etc.
1075 </p>
1076 <table>
1077 <tr><td><a name="tab_003aalerts"></a></td></tr>
1078 <thead><tr><th width="55%">Alert</th><th width="10%">ID</th><th width="30%">Description</th></tr></thead>
1079 <tr><td width="55%">GNUTLS_A_CLOSE_NOTIFY</td><td width="10%">0</td><td width="30%">Close notify</td></tr>
1080 <tr><td width="55%">GNUTLS_A_UNEXPECTED_MESSAGE</td><td width="10%">10</td><td width="30%">Unexpected message</td></tr>
1081 <tr><td width="55%">GNUTLS_A_BAD_RECORD_MAC</td><td width="10%">20</td><td width="30%">Bad record MAC</td></tr>
1082 <tr><td width="55%">GNUTLS_A_DECRYPTION_FAILED</td><td width="10%">21</td><td width="30%">Decryption failed</td></tr>
1083 <tr><td width="55%">GNUTLS_A_RECORD_OVERFLOW</td><td width="10%">22</td><td width="30%">Record overflow</td></tr>
1084 <tr><td width="55%">GNUTLS_A_DECOMPRESSION_FAILURE</td><td width="10%">30</td><td width="30%">Decompression failed</td></tr>
1085 <tr><td width="55%">GNUTLS_A_HANDSHAKE_FAILURE</td><td width="10%">40</td><td width="30%">Handshake failed</td></tr>
1086 <tr><td width="55%">GNUTLS_A_SSL3_NO_CERTIFICATE</td><td width="10%">41</td><td width="30%">No certificate (SSL 3.0)</td></tr>
1087 <tr><td width="55%">GNUTLS_A_BAD_CERTIFICATE</td><td width="10%">42</td><td width="30%">Certificate is bad</td></tr>
1088 <tr><td width="55%">GNUTLS_A_UNSUPPORTED_CERTIFICATE</td><td width="10%">43</td><td width="30%">Certificate is not supported</td></tr>
1089 <tr><td width="55%">GNUTLS_A_CERTIFICATE_REVOKED</td><td width="10%">44</td><td width="30%">Certificate was revoked</td></tr>
1090 <tr><td width="55%">GNUTLS_A_CERTIFICATE_EXPIRED</td><td width="10%">45</td><td width="30%">Certificate is expired</td></tr>
1091 <tr><td width="55%">GNUTLS_A_CERTIFICATE_UNKNOWN</td><td width="10%">46</td><td width="30%">Unknown certificate</td></tr>
1092 <tr><td width="55%">GNUTLS_A_ILLEGAL_PARAMETER</td><td width="10%">47</td><td width="30%">Illegal parameter</td></tr>
1093 <tr><td width="55%">GNUTLS_A_UNKNOWN_CA</td><td width="10%">48</td><td width="30%">CA is unknown</td></tr>
1094 <tr><td width="55%">GNUTLS_A_ACCESS_DENIED</td><td width="10%">49</td><td width="30%">Access was denied</td></tr>
1095 <tr><td width="55%">GNUTLS_A_DECODE_ERROR</td><td width="10%">50</td><td width="30%">Decode error</td></tr>
1096 <tr><td width="55%">GNUTLS_A_DECRYPT_ERROR</td><td width="10%">51</td><td width="30%">Decrypt error</td></tr>
1097 <tr><td width="55%">GNUTLS_A_EXPORT_RESTRICTION</td><td width="10%">60</td><td width="30%">Export restriction</td></tr>
1098 <tr><td width="55%">GNUTLS_A_PROTOCOL_VERSION</td><td width="10%">70</td><td width="30%">Error in protocol version</td></tr>
1099 <tr><td width="55%">GNUTLS_A_INSUFFICIENT_SECURITY</td><td width="10%">71</td><td width="30%">Insufficient security</td></tr>
1100 <tr><td width="55%">GNUTLS_A_INTERNAL_ERROR</td><td width="10%">80</td><td width="30%">Internal error</td></tr>
1101 <tr><td width="55%">GNUTLS_A_USER_CANCELED</td><td width="10%">90</td><td width="30%">User canceled</td></tr>
1102 <tr><td width="55%">GNUTLS_A_NO_RENEGOTIATION</td><td width="10%">100</td><td width="30%">No renegotiation is allowed</td></tr>
1103 <tr><td width="55%">GNUTLS_A_UNSUPPORTED_EXTENSION</td><td width="10%">110</td><td width="30%">An unsupported extension was sent</td></tr>
1104 <tr><td width="55%">GNUTLS_A_CERTIFICATE_UNOBTAINABLE</td><td width="10%">111</td><td width="30%">Could not retrieve the specified certificate</td></tr>
1105 <tr><td width="55%">GNUTLS_A_UNRECOGNIZED_NAME</td><td width="10%">112</td><td width="30%">The server name sent was not recognized</td></tr>
1106 <tr><td width="55%">GNUTLS_A_UNKNOWN_PSK_IDENTITY</td><td width="10%">115</td><td width="30%">The SRP/PSK username is missing or not known</td></tr>
1107 <tr><td width="55%">GNUTLS_A_NO_APPLICATION_PROTOCOL</td><td width="10%">120</td><td width="30%">No supported application protocol could be negotiated</td></tr>
1108 </table>
1109
1110 <hr>
1111 <a name="The-TLS-Handshake-Protocol"></a>
1112 <div class="header">
1113 <p>
1114 Next: <a href="#TLS-Extensions" accesskey="n" rel="next">TLS Extensions</a>, Previous: <a href="#The-TLS-Alert-Protocol" accesskey="p" rel="prev">The TLS Alert Protocol</a>, Up: <a href="#Introduction-to-TLS" accesskey="u" rel="up">Introduction to TLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1115 </div>
1116 <a name="The-TLS-handshake-protocol"></a>
1117 <h3 class="section">3.5 The TLS handshake protocol</h3>
1118 <a name="The-Handshake-Protocol"></a><a name="index-handshake-protocol"></a>
1119
1120 <p>The handshake protocol is responsible for the ciphersuite negotiation,
1121 the initial key exchange, and the authentication of the two peers.
1122 This is fully controlled by the application layer, thus your program
1123 has to set up the required parameters. The main handshake function
1124 is <a href="#gnutls_005fhandshake">gnutls_handshake</a>. In the next paragraphs we elaborate on
1125 the handshake protocol, i.e., the ciphersuite negotiation.
1126 </p>
1127
1128 <table class="menu" border="0" cellspacing="0">
1129 <tr><td align="left" valign="top">&bull; <a href="#TLS-Cipher-Suites" accesskey="1">TLS Cipher Suites</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">TLS session parameters.
1130 </td></tr>
1131 <tr><td align="left" valign="top">&bull; <a href="#Authentication" accesskey="2">Authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">TLS authentication.
1132 </td></tr>
1133 <tr><td align="left" valign="top">&bull; <a href="#Client-Authentication" accesskey="3">Client Authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Requesting a certificate from the client.
1134 </td></tr>
1135 <tr><td align="left" valign="top">&bull; <a href="#Resuming-Sessions" accesskey="4">Resuming Sessions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Reusing previously established keys.
1136 </td></tr>
1137 </table>
1138
1139
1140 <hr>
1141 <a name="TLS-Cipher-Suites"></a>
1142 <div class="header">
1143 <p>
1144 Next: <a href="#Authentication" accesskey="n" rel="next">Authentication</a>, Up: <a href="#The-TLS-Handshake-Protocol" accesskey="u" rel="up">The TLS Handshake Protocol</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1145 </div>
1146 <a name="TLS-ciphersuites"></a>
1147 <h4 class="subsection">3.5.1 TLS ciphersuites</h4>
1148
1149 <p>The handshake protocol of <acronym>TLS</acronym> negotiates cipher suites of
1150 a special form illustrated by the <code>TLS_DHE_RSA_WITH_3DES_CBC_SHA</code> cipher suite name.  A typical cipher
1151 suite contains these parameters:
1152 </p>
1153 <ul>
1154 <li> The key exchange algorithm.
1155 <code>DHE_RSA</code> in the example.
1156
1157 </li><li> The Symmetric encryption algorithm and mode
1158 <code>3DES_CBC</code> in this example.
1159
1160 </li><li> The MAC<a name="DOCF3" href="#FOOT3"><sup>3</sup></a> algorithm used for authentication.
1161 <code>MAC_SHA</code> is used in the above example.
1162
1163 </li></ul>
1164
1165 <p>The cipher suite negotiated in the handshake protocol will affect the
1166 record protocol, by enabling encryption and data authentication.  Note
1167 that you should not over rely on <acronym>TLS</acronym> to negotiate the
1168 strongest available cipher suite. Do not enable ciphers and algorithms
1169 that you consider weak.
1170 </p>
1171 <p>All the supported ciphersuites are listed in <a href="#ciphersuites">ciphersuites</a>.
1172 </p>
1173 <hr>
1174 <a name="Authentication"></a>
1175 <div class="header">
1176 <p>
1177 Next: <a href="#Client-Authentication" accesskey="n" rel="next">Client Authentication</a>, Previous: <a href="#TLS-Cipher-Suites" accesskey="p" rel="prev">TLS Cipher Suites</a>, Up: <a href="#The-TLS-Handshake-Protocol" accesskey="u" rel="up">The TLS Handshake Protocol</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1178 </div>
1179 <a name="Authentication-1"></a>
1180 <h4 class="subsection">3.5.2 Authentication</h4>
1181
1182 <p>The key exchange algorithms of the <acronym>TLS</acronym> protocol offer
1183 authentication, which is a prerequisite for a secure connection.
1184 The available authentication methods in <acronym>GnuTLS</acronym> follow.
1185 </p>
1186 <ul>
1187 <li> Certificate authentication: Authenticated key exchange using public key infrastructure and certificates (X.509 or OpenPGP).
1188 </li><li> <acronym>SRP</acronym> authentication: Authenticated key exchange using a password.
1189 </li><li> <acronym>PSK</acronym> authentication: Authenticated key exchange using a pre-shared key.
1190 </li><li> Anonymous authentication: Key exchange without peer authentication.
1191
1192 </li></ul>
1193
1194 <hr>
1195 <a name="Client-Authentication"></a>
1196 <div class="header">
1197 <p>
1198 Next: <a href="#Resuming-Sessions" accesskey="n" rel="next">Resuming Sessions</a>, Previous: <a href="#Authentication" accesskey="p" rel="prev">Authentication</a>, Up: <a href="#The-TLS-Handshake-Protocol" accesskey="u" rel="up">The TLS Handshake Protocol</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1199 </div>
1200 <a name="Client-authentication"></a>
1201 <h4 class="subsection">3.5.3 Client authentication</h4>
1202 <a name="index-client-certificate-authentication"></a>
1203
1204 <p>In the case of ciphersuites that use certificate authentication, the
1205 authentication of the client is optional in <acronym>TLS</acronym>.  A server
1206 may request a certificate from the client using the
1207 <a href="#gnutls_005fcertificate_005fserver_005fset_005frequest">gnutls_certificate_server_set_request</a> function. We elaborate
1208 in <a href="#Certificate-credentials">Certificate credentials</a>.
1209 </p>
1210 <hr>
1211 <a name="Resuming-Sessions"></a>
1212 <div class="header">
1213 <p>
1214 Previous: <a href="#Client-Authentication" accesskey="p" rel="prev">Client Authentication</a>, Up: <a href="#The-TLS-Handshake-Protocol" accesskey="u" rel="up">The TLS Handshake Protocol</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1215 </div>
1216 <a name="Resuming-sessions"></a>
1217 <h4 class="subsection">3.5.4 Resuming sessions</h4>
1218 <a name="resume"></a><a name="index-resuming-sessions"></a>
1219 <a name="index-session-resumption"></a>
1220
1221 <p>The TLS handshake process performs expensive calculations
1222 and a busy server might easily be put under load. To
1223 reduce the load, session resumption may be used. This
1224 is a feature of the <acronym>TLS</acronym> protocol which allows a
1225 client to connect to a server after a successful handshake, without
1226 the expensive calculations.  This is achieved by re-using the previously
1227 established keys, meaning the server needs to store the state of established
1228 connections (unless session tickets are used &ndash; <a href="#Session-tickets">Session tickets</a>).
1229 </p>
1230 <p>Session resumption is an integral part of <acronym>GnuTLS</acronym>, and
1231 <a href="#Session-resumption">Session resumption</a>, <a href="#ex_002dresume_002dclient">ex-resume-client</a> illustrate typical
1232 uses of it.
1233 </p>
1234 <hr>
1235 <a name="TLS-Extensions"></a>
1236 <div class="header">
1237 <p>
1238 Next: <a href="#How-to-use-TLS-in-application-protocols" accesskey="n" rel="next">How to use TLS in application protocols</a>, Previous: <a href="#The-TLS-Handshake-Protocol" accesskey="p" rel="prev">The TLS Handshake Protocol</a>, Up: <a href="#Introduction-to-TLS" accesskey="u" rel="up">Introduction to TLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1239 </div>
1240 <a name="TLS-extensions"></a>
1241 <h3 class="section">3.6 TLS extensions</h3>
1242 <a name="index-TLS-extensions"></a>
1243
1244 <p>A number of extensions to the <acronym>TLS</acronym> protocol have been
1245 proposed mainly in [<em>TLSEXT</em>]. The extensions supported
1246 in <acronym>GnuTLS</acronym> are discussed in the subsections that follow.
1247 </p>
1248 <table class="menu" border="0" cellspacing="0">
1249 <tr><td align="left" valign="top">&bull; <a href="#Maximum-fragment-length-negotiation" accesskey="1">Maximum fragment length negotiation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1250 </td></tr>
1251 <tr><td align="left" valign="top">&bull; <a href="#Server-name-indication" accesskey="2">Server name indication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1252 </td></tr>
1253 <tr><td align="left" valign="top">&bull; <a href="#Session-tickets" accesskey="3">Session tickets</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1254 </td></tr>
1255 <tr><td align="left" valign="top">&bull; <a href="#HeartBeat" accesskey="4">HeartBeat</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1256 </td></tr>
1257 <tr><td align="left" valign="top">&bull; <a href="#Safe-renegotiation" accesskey="5">Safe renegotiation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1258 </td></tr>
1259 <tr><td align="left" valign="top">&bull; <a href="#OCSP-status-request" accesskey="6">OCSP status request</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1260 </td></tr>
1261 <tr><td align="left" valign="top">&bull; <a href="#SRTP" accesskey="7">SRTP</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1262 </td></tr>
1263 <tr><td align="left" valign="top">&bull; <a href="#Application-Layer-Protocol-Negotiation-_0028ALPN_0029" accesskey="8">Application Layer Protocol Negotiation (ALPN)</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1264 </td></tr>
1265 </table>
1266
1267 <hr>
1268 <a name="Maximum-fragment-length-negotiation"></a>
1269 <div class="header">
1270 <p>
1271 Next: <a href="#Server-name-indication" accesskey="n" rel="next">Server name indication</a>, Up: <a href="#TLS-Extensions" accesskey="u" rel="up">TLS Extensions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1272 </div>
1273 <a name="Maximum-fragment-length-negotiation-1"></a>
1274 <h4 class="subsection">3.6.1 Maximum fragment length negotiation</h4>
1275 <a name="index-TLS-extensions-1"></a>
1276 <a name="index-maximum-fragment-length"></a>
1277
1278 <p>This extension allows a <acronym>TLS</acronym> implementation to negotiate a
1279 smaller value for record packet maximum length. This extension may be
1280 useful to clients with constrained capabilities. The functions shown
1281 below can be used to control this extension.
1282 </p>
1283 <dl compact="compact">
1284 <dt><code><var>size_t</var> <a href="#gnutls_005frecord_005fget_005fmax_005fsize">gnutls_record_get_max_size</a> (gnutls_session_t <var>session</var>)</code></dt>
1285 <dt><code><var>ssize_t</var> <a href="#gnutls_005frecord_005fset_005fmax_005fsize">gnutls_record_set_max_size</a> (gnutls_session_t <var>session</var>, size_t <var>size</var>)</code></dt>
1286 </dl>
1287
1288 <hr>
1289 <a name="Server-name-indication"></a>
1290 <div class="header">
1291 <p>
1292 Next: <a href="#Session-tickets" accesskey="n" rel="next">Session tickets</a>, Previous: <a href="#Maximum-fragment-length-negotiation" accesskey="p" rel="prev">Maximum fragment length negotiation</a>, Up: <a href="#TLS-Extensions" accesskey="u" rel="up">TLS Extensions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1293 </div>
1294 <a name="Server-name-indication-1"></a>
1295 <h4 class="subsection">3.6.2 Server name indication</h4>
1296 <a name="serverind"></a><a name="index-TLS-extensions-2"></a>
1297 <a name="index-server-name-indication"></a>
1298
1299 <p>A common problem in <acronym>HTTPS</acronym> servers is the fact that the
1300 <acronym>TLS</acronym> protocol is not aware of the hostname that a client
1301 connects to, when the handshake procedure begins. For that reason the
1302 <acronym>TLS</acronym> server has no way to know which certificate to send.
1303 </p>
1304 <p>This extension solves that problem within the <acronym>TLS</acronym> protocol,
1305 and allows a client to send the HTTP hostname before the handshake
1306 begins within the first handshake packet.  The functions
1307 <a href="#gnutls_005fserver_005fname_005fset">gnutls_server_name_set</a> and <a href="#gnutls_005fserver_005fname_005fget">gnutls_server_name_get</a> can be
1308 used to enable this extension, or to retrieve the name sent by a
1309 client.
1310 </p>
1311 <dl compact="compact">
1312 <dt><code><var>int</var> <a href="#gnutls_005fserver_005fname_005fset">gnutls_server_name_set</a> (gnutls_session_t <var>session</var>, gnutls_server_name_type_t <var>type</var>, const void * <var>name</var>, size_t <var>name_length</var>)</code></dt>
1313 <dt><code><var>int</var> <a href="#gnutls_005fserver_005fname_005fget">gnutls_server_name_get</a> (gnutls_session_t <var>session</var>, void * <var>data</var>, size_t * <var>data_length</var>, unsigned int * <var>type</var>, unsigned int <var>indx</var>)</code></dt>
1314 </dl>
1315
1316 <hr>
1317 <a name="Session-tickets"></a>
1318 <div class="header">
1319 <p>
1320 Next: <a href="#HeartBeat" accesskey="n" rel="next">HeartBeat</a>, Previous: <a href="#Server-name-indication" accesskey="p" rel="prev">Server name indication</a>, Up: <a href="#TLS-Extensions" accesskey="u" rel="up">TLS Extensions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1321 </div>
1322 <a name="Session-tickets-1"></a>
1323 <h4 class="subsection">3.6.3 Session tickets</h4>
1324 <a name="index-TLS-extensions-3"></a>
1325 <a name="index-session-tickets"></a>
1326 <a name="index-tickets"></a>
1327
1328 <p>To resume a TLS session, the server normally stores session parameters.  This
1329 complicates deployment, and can be avoided by delegating the storage
1330 to the client. Because session parameters are sensitive they are encrypted
1331 and authenticated with a key only known to the server and then sent to the
1332 client. The Session Tickets extension is described in RFC 5077 [<em>TLSTKT</em>].
1333 </p>
1334 <p>A disadvantage of session tickets is that they eliminate the effects of
1335 forward secrecy when a server uses the same key for long time. That is,
1336 the secrecy of all sessions on a server using tickets depends on the ticket
1337 key being kept secret. For that reason server keys should be rotated and discarded
1338 regularly.
1339 </p>
1340 <p>Since version 3.1.3 GnuTLS clients transparently support session tickets.
1341 </p>
1342 <hr>
1343 <a name="HeartBeat"></a>
1344 <div class="header">
1345 <p>
1346 Next: <a href="#Safe-renegotiation" accesskey="n" rel="next">Safe renegotiation</a>, Previous: <a href="#Session-tickets" accesskey="p" rel="prev">Session tickets</a>, Up: <a href="#TLS-Extensions" accesskey="u" rel="up">TLS Extensions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1347 </div>
1348 <a name="HeartBeat-1"></a>
1349 <h4 class="subsection">3.6.4 HeartBeat</h4>
1350 <a name="index-TLS-extensions-4"></a>
1351 <a name="index-heartbeat"></a>
1352
1353 <p>This is a TLS extension that allows to ping and receive confirmation from the peer,
1354 and is described in [<em>RFC6520</em>]. The extension is disabled by default and
1355 <a href="#gnutls_005fheartbeat_005fenable">gnutls_heartbeat_enable</a> can be used to enable it. A policy
1356 may be negotiated to only allow sending heartbeat messages or sending and receiving.
1357 The current session policy can be checked with <a href="#gnutls_005fheartbeat_005fallowed">gnutls_heartbeat_allowed</a>.
1358 The requests coming from the peer result to <code>GNUTLS_E_HERTBEAT_PING_RECEIVED</code>
1359 being returned from the receive function. Ping requests to peer can be send via
1360 <a href="#gnutls_005fheartbeat_005fping">gnutls_heartbeat_ping</a>.
1361 </p>
1362 <dl compact="compact">
1363 <dt><code><var>int</var> <a href="#gnutls_005fheartbeat_005fallowed">gnutls_heartbeat_allowed</a> (gnutls_session_t <var>session</var>, unsigned int <var>type</var>)</code></dt>
1364 <dt><code><var>void</var> <a href="#gnutls_005fheartbeat_005fenable">gnutls_heartbeat_enable</a> (gnutls_session_t <var>session</var>, unsigned int <var>type</var>)</code></dt>
1365 </dl>
1366
1367 <dl compact="compact">
1368 <dt><code><var>int</var> <a href="#gnutls_005fheartbeat_005fping">gnutls_heartbeat_ping</a> (gnutls_session_t <var>session</var>, size_t <var>data_size</var>, unsigned int <var>max_tries</var>, unsigned int <var>flags</var>)</code></dt>
1369 <dt><code><var>int</var> <a href="#gnutls_005fheartbeat_005fpong">gnutls_heartbeat_pong</a> (gnutls_session_t <var>session</var>, unsigned int <var>flags</var>)</code></dt>
1370 <dt><code><var>void</var> <a href="#gnutls_005fheartbeat_005fset_005ftimeouts">gnutls_heartbeat_set_timeouts</a> (gnutls_session_t <var>session</var>, unsigned int <var>retrans_timeout</var>, unsigned int <var>total_timeout</var>)</code></dt>
1371 <dt><code><var>unsigned int</var> <a href="#gnutls_005fheartbeat_005fget_005ftimeout">gnutls_heartbeat_get_timeout</a> (gnutls_session_t <var>session</var>)</code></dt>
1372 </dl>
1373
1374 <hr>
1375 <a name="Safe-renegotiation"></a>
1376 <div class="header">
1377 <p>
1378 Next: <a href="#OCSP-status-request" accesskey="n" rel="next">OCSP status request</a>, Previous: <a href="#HeartBeat" accesskey="p" rel="prev">HeartBeat</a>, Up: <a href="#TLS-Extensions" accesskey="u" rel="up">TLS Extensions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1379 </div>
1380 <a name="Safe-renegotiation-1"></a>
1381 <h4 class="subsection">3.6.5 Safe renegotiation</h4>
1382 <a name="index-renegotiation"></a>
1383 <a name="index-safe-renegotiation"></a>
1384
1385 <p>TLS gives the option to two communicating parties to renegotiate
1386 and update their security parameters. One useful example of this feature
1387 was for a client to initially connect using anonymous negotiation to a
1388 server, and the renegotiate using some authenticated ciphersuite. This occurred
1389 to avoid having the client sending its credentials in the clear.
1390 </p>
1391 <p>However this renegotiation, as initially designed would not ensure that
1392 the party one is renegotiating is the same as the one in the initial negotiation.
1393 For example one server could forward all renegotiation traffic to an other
1394 server who will see this traffic as an initial negotiation attempt.
1395 </p>
1396 <p>This might be seen as a valid design decision, but it seems it was
1397 not widely known or understood, thus today some application protocols use the TLS
1398 renegotiation feature in a manner that enables a malicious server to insert
1399 content of his choice in the beginning of a TLS session.
1400 </p>
1401 <p>The most prominent vulnerability was with HTTPS. There servers request
1402 a renegotiation to enforce an anonymous user to use a certificate in order
1403 to access certain parts of a web site.  The
1404 attack works by having the attacker simulate a client and connect to a
1405 server, with server-only authentication, and send some data intended
1406 to cause harm.  The server will then require renegotiation from him
1407 in order to perform the request.
1408 When the proper client attempts to contact the server,
1409 the attacker hijacks that connection and forwards traffic to
1410 the initial server that requested renegotiation.  The
1411 attacker will not be able to read the data exchanged between the
1412 client and the server.  However, the server will (incorrectly) assume
1413 that the initial request sent by the attacker was sent by the now authenticated
1414 client.  The result is a prefix plain-text injection attack.
1415 </p>
1416 <p>The above is just one example.  Other vulnerabilities exists that do
1417 not rely on the TLS renegotiation to change the client&rsquo;s authenticated
1418 status (either TLS or application layer).
1419 </p>
1420 <p>While fixing these application protocols and implementations would be
1421 one natural reaction, an extension to TLS has been designed that
1422 cryptographically binds together any renegotiated handshakes with the
1423 initial negotiation.  When the extension is used, the attack is
1424 detected and the session can be terminated.  The extension is
1425 specified in [<em>RFC5746</em>].
1426 </p>
1427 <p>GnuTLS supports the safe renegotiation extension.  The default
1428 behavior is as follows.  Clients will attempt to negotiate the safe
1429 renegotiation extension when talking to servers.  Servers will accept
1430 the extension when presented by clients.  Clients and servers will
1431 permit an initial handshake to complete even when the other side does
1432 not support the safe renegotiation extension.  Clients and servers
1433 will refuse renegotiation attempts when the extension has not been
1434 negotiated.
1435 </p>
1436 <p>Note that permitting clients to connect to servers when the safe
1437 renegotiation extension is not enabled, is open up for attacks.
1438 Changing this default behavior would prevent interoperability against
1439 the majority of deployed servers out there.  We will reconsider this
1440 default behavior in the future when more servers have been upgraded.
1441 Note that it is easy to configure clients to always require the safe
1442 renegotiation extension from servers.
1443 </p>
1444 <p>To modify the default behavior, we have introduced some new priority
1445 strings (see <a href="#Priority-Strings">Priority Strings</a>).
1446 The <code>%UNSAFE_RENEGOTIATION</code> priority string permits
1447 (re-)handshakes even when the safe renegotiation extension was not
1448 negotiated. The default behavior is <code>%PARTIAL_RENEGOTIATION</code> that will
1449 prevent renegotiation with clients and servers not supporting the
1450 extension. This is secure for servers but leaves clients vulnerable
1451 to some attacks, but this is a trade-off between security and compatibility
1452 with old servers. The <code>%SAFE_RENEGOTIATION</code> priority string makes
1453 clients and servers require the extension for every handshake. The latter
1454 is the most secure option for clients, at the cost of not being able
1455 to connect to legacy servers. Servers will also deny clients that
1456 do not support the extension from connecting.
1457 </p>
1458 <p>It is possible to disable use of the extension completely, in both
1459 clients and servers, by using the <code>%DISABLE_SAFE_RENEGOTIATION</code>
1460 priority string however we strongly recommend you to only do this for
1461 debugging and test purposes.
1462 </p>
1463 <p>The default values if the flags above are not specified are:
1464 </p><dl compact="compact">
1465 <dt><code>Server:</code></dt>
1466 <dd><p>%PARTIAL_RENEGOTIATION
1467 </p>
1468 </dd>
1469 <dt><code>Client:</code></dt>
1470 <dd><p>%PARTIAL_RENEGOTIATION
1471 </p>
1472 </dd>
1473 </dl>
1474
1475 <p>For applications we have introduced a new API related to safe
1476 renegotiation.  The <a href="#gnutls_005fsafe_005frenegotiation_005fstatus">gnutls_safe_renegotiation_status</a> function is
1477 used to check if the extension has been negotiated on a session, and
1478 can be used both by clients and servers.
1479 </p>
1480 <hr>
1481 <a name="OCSP-status-request"></a>
1482 <div class="header">
1483 <p>
1484 Next: <a href="#SRTP" accesskey="n" rel="next">SRTP</a>, Previous: <a href="#Safe-renegotiation" accesskey="p" rel="prev">Safe renegotiation</a>, Up: <a href="#TLS-Extensions" accesskey="u" rel="up">TLS Extensions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1485 </div>
1486 <a name="OCSP-status-request-1"></a>
1487 <h4 class="subsection">3.6.6 OCSP status request</h4>
1488 <a name="index-OCSP-status-request"></a>
1489 <a name="index-Certificate-status-request"></a>
1490
1491 <p>The Online Certificate Status Protocol (OCSP) is a protocol that allows the
1492 client to verify the server certificate for revocation without messing with
1493 certificate revocation lists. Its drawback is that it requires the client
1494 to connect to the server&rsquo;s CA OCSP server and request the status of the
1495 certificate. This extension however, enables a TLS server to include
1496 its CA OCSP server response in the handshake. That is an HTTPS server
1497 may periodically run <code>ocsptool</code> (see <a href="#ocsptool-Invocation">ocsptool Invocation</a>) to obtain
1498 its certificate revocation status and serve it to the clients. That
1499 way a client avoids an additional connection to the OCSP server.
1500 </p>
1501 <dl compact="compact">
1502 <dt><code><var>void</var> <a href="#gnutls_005fcertificate_005fset_005focsp_005fstatus_005frequest_005ffunction">gnutls_certificate_set_ocsp_status_request_function</a> (gnutls_certificate_credentials_t <var>sc</var>, gnutls_status_request_ocsp_func <var>ocsp_func</var>, void * <var>ptr</var>)</code></dt>
1503 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005focsp_005fstatus_005frequest_005ffile">gnutls_certificate_set_ocsp_status_request_file</a> (gnutls_certificate_credentials_t <var>sc</var>, const char * <var>response_file</var>, unsigned int <var>flags</var>)</code></dt>
1504 <dt><code><var>int</var> <a href="#gnutls_005focsp_005fstatus_005frequest_005fenable_005fclient">gnutls_ocsp_status_request_enable_client</a> (gnutls_session_t <var>session</var>, gnutls_datum_t * <var>responder_id</var>, size_t <var>responder_id_size</var>, gnutls_datum_t * <var>extensions</var>)</code></dt>
1505 <dt><code><var>int</var> <a href="#gnutls_005focsp_005fstatus_005frequest_005fis_005fchecked">gnutls_ocsp_status_request_is_checked</a> (gnutls_session_t <var>session</var>, unsigned int <var>flags</var>)</code></dt>
1506 </dl>
1507
1508 <p>A server is required to provide the OCSP server&rsquo;s response using the <a href="#gnutls_005fcertificate_005fset_005focsp_005fstatus_005frequest_005ffile">gnutls_certificate_set_ocsp_status_request_file</a>.
1509 The response may be obtained periodically using the following command.
1510 </p>
1511 <div class="example">
1512 <pre class="example">ocsptool --ask --load-cert server_cert.pem --load-issuer the_issuer.pem
1513          --load-signer the_issuer.pem --outfile ocsp.response
1514 </pre></div>
1515
1516 <p>Since version 3.1.3 GnuTLS clients transparently support the certificate status
1517 request.
1518 </p>
1519 <hr>
1520 <a name="SRTP"></a>
1521 <div class="header">
1522 <p>
1523 Next: <a href="#Application-Layer-Protocol-Negotiation-_0028ALPN_0029" accesskey="n" rel="next">Application Layer Protocol Negotiation (ALPN)</a>, Previous: <a href="#OCSP-status-request" accesskey="p" rel="prev">OCSP status request</a>, Up: <a href="#TLS-Extensions" accesskey="u" rel="up">TLS Extensions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1524 </div>
1525 <a name="SRTP-1"></a>
1526 <h4 class="subsection">3.6.7 SRTP</h4>
1527 <a name="index-SRTP"></a>
1528 <a name="index-Secure-RTP"></a>
1529
1530 <p>The TLS protocol was extended in [<em>RFC5764</em>] to provide keying material to the
1531 Secure RTP (SRTP) protocol. The SRTP protocol provides an encapsulation of encrypted
1532 data that is optimized for voice data. With the SRTP TLS extension two peers can
1533 negotiate keys using TLS or DTLS and obtain keying material for use with SRTP. The
1534 available SRTP profiles are listed below.
1535 </p>
1536 <div class="float"><a name="gnutls_005fsrtp_005fprofile_005ft"></a>
1537
1538
1539 <dl compact="compact">
1540 <dt><code>GNUTLS_SRTP_AES128_CM_HMAC_SHA1_80</code></dt>
1541 <dd><p>128 bit AES with a 80 bit HMAC-SHA1
1542 </p></dd>
1543 <dt><code>GNUTLS_SRTP_AES128_CM_HMAC_SHA1_32</code></dt>
1544 <dd><p>128 bit AES with a 32 bit HMAC-SHA1
1545 </p></dd>
1546 <dt><code>GNUTLS_SRTP_NULL_HMAC_SHA1_80</code></dt>
1547 <dd><p>NULL cipher with a 80 bit HMAC-SHA1
1548 </p></dd>
1549 <dt><code>GNUTLS_SRTP_NULL_HMAC_SHA1_32</code></dt>
1550 <dd><p>NULL cipher with a 32 bit HMAC-SHA1
1551 </p></dd>
1552 </dl>
1553
1554 <div class="float-caption"><p><strong>Figure 3.3: </strong>Supported SRTP profiles</p></div></div>
1555 <p>To enable use the following functions.
1556 </p>
1557 <dl compact="compact">
1558 <dt><code><var>int</var> <a href="#gnutls_005fsrtp_005fset_005fprofile">gnutls_srtp_set_profile</a> (gnutls_session_t <var>session</var>, gnutls_srtp_profile_t <var>profile</var>)</code></dt>
1559 <dt><code><var>int</var> <a href="#gnutls_005fsrtp_005fset_005fprofile_005fdirect">gnutls_srtp_set_profile_direct</a> (gnutls_session_t <var>session</var>, const char * <var>profiles</var>, const char ** <var>err_pos</var>)</code></dt>
1560 </dl>
1561
1562 <p>To obtain the negotiated keys use the function below.
1563 </p>
1564
1565
1566
1567
1568 <dl>
1569 <dt><a name="index-gnutls_005fsrtp_005fget_005fkeys"></a>Function: <em>int</em> <strong>gnutls_srtp_get_keys</strong> <em>(gnutls_session_t <var>session</var>, void * <var>key_material</var>, unsigned int <var>key_material_size</var>, gnutls_datum_t * <var>client_key</var>, gnutls_datum_t * <var>client_salt</var>, gnutls_datum_t * <var>server_key</var>, gnutls_datum_t * <var>server_salt</var>)</em></dt>
1570 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
1571 </p>
1572 <p><var>key_material</var>: Space to hold the generated key material
1573 </p>
1574 <p><var>key_material_size</var>: The maximum size of the key material
1575 </p>
1576 <p><var>client_key</var>: The master client write key, pointing inside the key material
1577 </p>
1578 <p><var>client_salt</var>: The master client write salt, pointing inside the key material
1579 </p>
1580 <p><var>server_key</var>: The master server write key, pointing inside the key material
1581 </p>
1582 <p><var>server_salt</var>: The master server write salt, pointing inside the key material
1583 </p>
1584 <p>This is a helper function to generate the keying material for SRTP.
1585 It requires the space of the key material to be pre-allocated (should be at least
1586 2x the maximum key size and salt size). The  <code>client_key</code> ,  <code>client_salt</code> ,  <code>server_key</code> and  <code>server_salt</code> are convenience datums that point inside the key material. They may
1587 be <code>NULL</code> .
1588 </p>
1589 <p><strong>Returns:</strong> On success the size of the key material is returned,
1590 otherwise, <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the buffer given is not
1591 sufficient, or a negative error code.
1592 </p>
1593 <p>Since 3.1.4
1594 </p></dd></dl>
1595
1596 <p>Other helper functions are listed below.
1597 </p>
1598 <dl compact="compact">
1599 <dt><code><var>int</var> <a href="#gnutls_005fsrtp_005fget_005fselected_005fprofile">gnutls_srtp_get_selected_profile</a> (gnutls_session_t <var>session</var>, gnutls_srtp_profile_t * <var>profile</var>)</code></dt>
1600 <dt><code><var>const char *</var> <a href="#gnutls_005fsrtp_005fget_005fprofile_005fname">gnutls_srtp_get_profile_name</a> (gnutls_srtp_profile_t <var>profile</var>)</code></dt>
1601 <dt><code><var>int</var> <a href="#gnutls_005fsrtp_005fget_005fprofile_005fid">gnutls_srtp_get_profile_id</a> (const char * <var>name</var>, gnutls_srtp_profile_t * <var>profile</var>)</code></dt>
1602 </dl>
1603
1604 <hr>
1605 <a name="Application-Layer-Protocol-Negotiation-_0028ALPN_0029"></a>
1606 <div class="header">
1607 <p>
1608 Previous: <a href="#SRTP" accesskey="p" rel="prev">SRTP</a>, Up: <a href="#TLS-Extensions" accesskey="u" rel="up">TLS Extensions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1609 </div>
1610 <a name="Application-Layer-Protocol-Negotiation-_0028ALPN_0029-1"></a>
1611 <h4 class="subsection">3.6.8 Application Layer Protocol Negotiation (ALPN)</h4>
1612 <a name="index-ALPN"></a>
1613 <a name="index-Application-Layer-Protocol-Negotiation"></a>
1614
1615 <p>The TLS protocol was extended in <code>draft-ietf-tls-applayerprotoneg-00</code>
1616 to provide the application layer a method of
1617 negotiating the application protocol version. This allows for negotiation
1618 of the application protocol during the TLS handshake, thus reducing
1619 round-trips. The application protocol is described by an opaque
1620 string. To enable, use the following functions.
1621 </p>
1622 <dl compact="compact">
1623 <dt><code><var>int</var> <a href="#gnutls_005falpn_005fset_005fprotocols">gnutls_alpn_set_protocols</a> (gnutls_session_t <var>session</var>, const gnutls_datum_t * <var>protocols</var>, unsigned <var>protocols_size</var>, unsigned int <var>flags</var>)</code></dt>
1624 <dt><code><var>int</var> <a href="#gnutls_005falpn_005fget_005fselected_005fprotocol">gnutls_alpn_get_selected_protocol</a> (gnutls_session_t <var>session</var>, gnutls_datum_t * <var>protocol</var>)</code></dt>
1625 </dl>
1626
1627 <p>Note that these functions are intended to be used with protocols that are
1628 registered in the Application Layer Protocol Negotiation IANA registry. While
1629 you can use them for other protocols (at the risk of collisions), it is preferable
1630 to register them.
1631 </p>
1632 <hr>
1633 <a name="How-to-use-TLS-in-application-protocols"></a>
1634 <div class="header">
1635 <p>
1636 Next: <a href="#On-SSL-2-and-older-protocols" accesskey="n" rel="next">On SSL 2 and older protocols</a>, Previous: <a href="#TLS-Extensions" accesskey="p" rel="prev">TLS Extensions</a>, Up: <a href="#Introduction-to-TLS" accesskey="u" rel="up">Introduction to TLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1637 </div>
1638 <a name="How-to-use-TLS-in-application-protocols-1"></a>
1639 <h3 class="section">3.7 How to use <acronym>TLS</acronym> in application protocols</h3>
1640
1641 <p>This chapter is intended to provide some hints on how to use
1642 <acronym>TLS</acronym> over simple custom made application protocols.  The
1643 discussion below mainly refers to the <acronym>TCP/IP</acronym> transport layer
1644 but may be extended to other ones too.
1645 </p>
1646 <table class="menu" border="0" cellspacing="0">
1647 <tr><td align="left" valign="top">&bull; <a href="#Separate-ports" accesskey="1">Separate ports</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1648 </td></tr>
1649 <tr><td align="left" valign="top">&bull; <a href="#Upward-negotiation" accesskey="2">Upward negotiation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1650 </td></tr>
1651 </table>
1652
1653 <hr>
1654 <a name="Separate-ports"></a>
1655 <div class="header">
1656 <p>
1657 Next: <a href="#Upward-negotiation" accesskey="n" rel="next">Upward negotiation</a>, Up: <a href="#How-to-use-TLS-in-application-protocols" accesskey="u" rel="up">How to use TLS in application protocols</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1658 </div>
1659 <a name="Separate-ports-1"></a>
1660 <h4 class="subsection">3.7.1 Separate ports</h4>
1661
1662 <p>Traditionally <acronym>SSL</acronym> was used in application protocols by
1663 assigning a new port number for the secure services. By doing this two
1664 separate ports were assigned, one for the non-secure sessions, and one
1665 for the secure sessions. This method ensures that if a user requests a
1666 secure session then the client will attempt to connect to the secure port
1667 and fail otherwise. The only possible attack with this method is to perform
1668 a denial of service attack. The most famous example of this method is
1669 &ldquo;HTTP over TLS&rdquo; or <acronym>HTTPS</acronym> protocol [<em>RFC2818</em>].
1670 </p>
1671 <p>Despite its wide use, this method has several issues. This
1672 approach starts the <acronym>TLS</acronym> Handshake procedure just after the
1673 client connects on the &mdash;so called&mdash; secure port.  That way the
1674 <acronym>TLS</acronym> protocol does not know anything about the client, and
1675 popular methods like the host advertising in HTTP do not
1676 work<a name="DOCF4" href="#FOOT4"><sup>4</sup></a>.  There is no way for the client to say &ldquo;I
1677 connected to YYY server&rdquo; before the Handshake starts, so the server
1678 cannot possibly know which certificate to use.
1679 </p>
1680 <p>Other than that it requires two separate ports to run a single
1681 service, which is unnecessary complication. Due to the fact that there
1682 is a limitation on the available privileged ports, this approach was
1683 soon deprecated in favor of upward negotiation.
1684 </p>
1685 <hr>
1686 <a name="Upward-negotiation"></a>
1687 <div class="header">
1688 <p>
1689 Previous: <a href="#Separate-ports" accesskey="p" rel="prev">Separate ports</a>, Up: <a href="#How-to-use-TLS-in-application-protocols" accesskey="u" rel="up">How to use TLS in application protocols</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1690 </div>
1691 <a name="Upward-negotiation-1"></a>
1692 <h4 class="subsection">3.7.2 Upward negotiation</h4>
1693
1694 <p>Other application protocols<a name="DOCF5" href="#FOOT5"><sup>5</sup></a>  use a
1695 different approach to enable the secure layer.  They use something
1696 often called as the &ldquo;TLS upgrade&rdquo; method. This method is quite tricky but it
1697 is more flexible. The idea is to extend the application protocol to
1698 have a &ldquo;STARTTLS&rdquo; request, whose purpose it to start the TLS
1699 protocols just after the client requests it.  This approach
1700 does not require any extra port to be reserved.
1701 There is even an extension to HTTP protocol to support
1702 this method [<em>RFC2817</em>].
1703 </p>
1704 <p>The tricky part, in this method, is that the &ldquo;STARTTLS&rdquo; request is
1705 sent in the clear, thus is vulnerable to modifications.  A typical
1706 attack is to modify the messages in a way that the client is fooled
1707 and thinks that the server does not have the &ldquo;STARTTLS&rdquo; capability.
1708 See a typical conversation of a hypothetical protocol:
1709 </p>
1710 <blockquote>
1711 <p>(client connects to the server)
1712 </p>
1713 <p>CLIENT: HELLO I&rsquo;M MR. XXX
1714 </p>
1715 <p>SERVER: NICE TO MEET YOU XXX
1716 </p>
1717 <p>CLIENT: PLEASE START TLS
1718 </p>
1719 <p>SERVER: OK
1720 </p>
1721 <p>*** TLS STARTS
1722 </p>
1723 <p>CLIENT: HERE ARE SOME CONFIDENTIAL DATA
1724 </p></blockquote>
1725
1726 <p>And an example of a conversation where someone is acting
1727 in between:
1728 </p>
1729 <blockquote>
1730 <p>(client connects to the server)
1731 </p>
1732 <p>CLIENT: HELLO I&rsquo;M MR. XXX
1733 </p>
1734 <p>SERVER: NICE TO MEET YOU XXX
1735 </p>
1736 <p>CLIENT: PLEASE START TLS
1737 </p>
1738 <p>(here someone inserts this message)
1739 </p>
1740 <p>SERVER: SORRY I DON&rsquo;T HAVE THIS CAPABILITY
1741 </p>
1742 <p>CLIENT: HERE ARE SOME CONFIDENTIAL DATA
1743 </p></blockquote>
1744
1745 <p>As you can see above the client was fooled, and was na&iuml;ve enough to
1746 send the confidential data in the clear, despite the server telling the
1747 client that it does not support &ldquo;STARTTLS&rdquo;.
1748 </p>
1749 <p>How do we avoid the above attack? As you may have already noticed this
1750 situation is easy to avoid.  The client has to ask the user before it
1751 connects whether the user requests <acronym>TLS</acronym> or not.  If the user
1752 answered that he certainly wants the secure layer the last
1753 conversation should be:
1754 </p>
1755 <blockquote>
1756 <p>(client connects to the server)
1757 </p>
1758 <p>CLIENT: HELLO I&rsquo;M MR. XXX
1759 </p>
1760 <p>SERVER: NICE TO MEET YOU XXX
1761 </p>
1762 <p>CLIENT: PLEASE START TLS
1763 </p>
1764 <p>(here someone inserts this message)
1765 </p>
1766 <p>SERVER: SORRY I DON&rsquo;T HAVE THIS CAPABILITY
1767 </p>
1768 <p>CLIENT: BYE
1769 </p>
1770 <p>(the client notifies the user that the secure connection was not possible)
1771 </p></blockquote>
1772
1773 <p>This method, if implemented properly, is far better than the
1774 traditional method, and the security properties remain the same, since
1775 only denial of service is possible. The benefit is that the server may
1776 request additional data before the <acronym>TLS</acronym> Handshake protocol
1777 starts, in order to send the correct certificate, use the correct
1778 password file, or anything else!
1779 </p>
1780 <hr>
1781 <a name="On-SSL-2-and-older-protocols"></a>
1782 <div class="header">
1783 <p>
1784 Previous: <a href="#How-to-use-TLS-in-application-protocols" accesskey="p" rel="prev">How to use TLS in application protocols</a>, Up: <a href="#Introduction-to-TLS" accesskey="u" rel="up">Introduction to TLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1785 </div>
1786 <a name="On-SSL-2-and-older-protocols-1"></a>
1787 <h3 class="section">3.8 On SSL 2 and older protocols</h3>
1788 <a name="index-SSL-2"></a>
1789
1790 <p>One of the initial decisions in the <acronym>GnuTLS</acronym> development was
1791 to implement the known security protocols for the transport layer.
1792 Initially <acronym>TLS</acronym> 1.0 was implemented since it was the latest at
1793 that time, and was considered to be the most advanced in security
1794 properties.  Later the <acronym>SSL</acronym> 3.0 protocol was implemented
1795 since it is still the only protocol supported by several servers and
1796 there are no serious security vulnerabilities known.
1797 </p>
1798 <p>One question that may arise is why we didn&rsquo;t implement <acronym>SSL</acronym>
1799 2.0 in the library.  There are several reasons, most important being
1800 that it has serious security flaws, unacceptable for a modern security
1801 library.  Other than that, this protocol is barely used by anyone
1802 these days since it has been deprecated since 1996.  The security
1803 problems in <acronym>SSL</acronym> 2.0 include:
1804 </p>
1805 <ul>
1806 <li> Message integrity compromised.
1807 The <acronym>SSLv2</acronym> message authentication uses the MD5 function, and
1808 is insecure.
1809
1810 </li><li> Man-in-the-middle attack.
1811 There is no protection of the handshake in <acronym>SSLv2</acronym>, which
1812 permits a man-in-the-middle attack.
1813
1814 </li><li> Truncation attack.
1815 <acronym>SSLv2</acronym> relies on TCP FIN to close the session, so the
1816 attacker can forge a TCP FIN, and the peer cannot tell if it was a
1817 legitimate end of data or not.
1818
1819 </li><li> Weak message integrity for export ciphers.
1820 The cryptographic keys in <acronym>SSLv2</acronym> are used for both message
1821 authentication and encryption, so if weak encryption schemes are
1822 negotiated (say 40-bit keys) the message authentication code uses the
1823 same weak key, which isn&rsquo;t necessary.
1824
1825 </li></ul>
1826
1827 <a name="index-PCT"></a>
1828 <p>Other protocols such as Microsoft&rsquo;s <acronym>PCT</acronym> 1 and <acronym>PCT</acronym>
1829 2 were not implemented because they were also abandoned and deprecated
1830 by <acronym>SSL</acronym> 3.0 and later <acronym>TLS</acronym> 1.0.
1831 </p>
1832
1833
1834 <hr>
1835 <a name="Authentication-methods"></a>
1836 <div class="header">
1837 <p>
1838 Next: <a href="#Hardware-security-modules-and-abstract-key-types" accesskey="n" rel="next">Hardware security modules and abstract key types</a>, Previous: <a href="#Introduction-to-TLS" accesskey="p" rel="prev">Introduction to TLS</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1839 </div>
1840 <a name="Authentication-methods-1"></a>
1841 <h2 class="chapter">4 Authentication methods</h2>
1842 <a name="index-authentication-methods"></a>
1843
1844 <p>The initial key exchange of the TLS protocol performs authentication
1845 of the peers. In typical scenarios the server is authenticated to
1846 the client, and optionally the client to the server.
1847 </p>
1848 <p>While many associate TLS with X.509 certificates and public key
1849 authentication, the protocol supports various authentication methods,
1850 including pre-shared keys, and passwords. In this chapter a description
1851 of the existing authentication methods is provided, as well as some
1852 guidance on which use-cases each method can be used at.
1853 </p>
1854 <table class="menu" border="0" cellspacing="0">
1855 <tr><td align="left" valign="top">&bull; <a href="#Certificate-authentication" accesskey="1">Certificate authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1856 </td></tr>
1857 <tr><td align="left" valign="top">&bull; <a href="#More-on-certificate-authentication" accesskey="2">More on certificate authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1858 </td></tr>
1859 <tr><td align="left" valign="top">&bull; <a href="#Shared_002dkey-and-anonymous-authentication" accesskey="3">Shared-key and anonymous authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1860 </td></tr>
1861 <tr><td align="left" valign="top">&bull; <a href="#Selecting-an-appropriate-authentication-method" accesskey="4">Selecting an appropriate authentication method</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1862 </td></tr>
1863 </table>
1864
1865 <hr>
1866 <a name="Certificate-authentication"></a>
1867 <div class="header">
1868 <p>
1869 Next: <a href="#More-on-certificate-authentication" accesskey="n" rel="next">More on certificate authentication</a>, Up: <a href="#Authentication-methods" accesskey="u" rel="up">Authentication methods</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1870 </div>
1871 <a name="Certificate-authentication-1"></a>
1872 <h3 class="section">4.1 Certificate authentication</h3>
1873 <a name="index-certificate-authentication"></a>
1874
1875 <p>The most known authentication method of <acronym>TLS</acronym> are certificates.
1876 The PKIX [<em>PKIX</em>] public key infrastructure is daily used by anyone
1877 using a browser today. <acronym>GnuTLS</acronym> supports both
1878 <acronym>X.509</acronym> certificates [<em>PKIX</em>] and <acronym>OpenPGP</acronym>
1879 certificates using a common API.
1880 </p>
1881 <p>The key exchange algorithms supported by certificate authentication are
1882 shown in <a href="#tab_003akey_002dexchange">Table 4.1</a>.
1883 </p>
1884 <div class="float"><a name="tab_003akey_002dexchange"></a>
1885 <table>
1886 <thead><tr><th width="20%">Key exchange</th><th width="70%">Description</th></tr></thead>
1887 <tr><td width="20%">RSA</td><td width="70%">The RSA algorithm is used to encrypt a key and send it to the peer.
1888 The certificate must allow the key to be used for encryption.</td></tr>
1889 <tr><td width="20%">DHE_RSA</td><td width="70%">The RSA algorithm is used to sign ephemeral Diffie-Hellman parameters
1890 which are sent to the peer. The key in the certificate must allow the
1891 key to be used for signing. Note that key exchange algorithms which
1892 use ephemeral Diffie-Hellman parameters, offer perfect forward
1893 secrecy. That means that even if the private key used for signing is
1894 compromised, it cannot be used to reveal past session data.</td></tr>
1895 <tr><td width="20%">ECDHE_RSA</td><td width="70%">The RSA algorithm is used to sign ephemeral elliptic curve Diffie-Hellman
1896 parameters which are sent to the peer. The key in the certificate must allow
1897 the key to be used for signing. It also offers perfect forward
1898 secrecy. That means that even if the private key used for signing is
1899 compromised, it cannot be used to reveal past session data.</td></tr>
1900 <tr><td width="20%">DHE_DSS</td><td width="70%">The DSA algorithm is used to sign ephemeral Diffie-Hellman parameters
1901 which are sent to the peer. The certificate must contain DSA
1902 parameters to use this key exchange algorithm. DSA is the algorithm
1903 of the Digital Signature Standard (DSS).</td></tr>
1904 <tr><td width="20%">ECDHE_ECDSA</td><td width="70%">The Elliptic curve DSA algorithm is used to sign ephemeral elliptic
1905 curve Diffie-Hellman parameters which are sent to the peer. The
1906 certificate must contain ECDSA parameters (i.e., EC and marked for signing)
1907 to use this key exchange algorithm.</td></tr>
1908 </table>
1909
1910 <div class="float-caption"><p><strong>Table 4.1: </strong>Supported key exchange algorithms.</p></div></div>
1911 <table class="menu" border="0" cellspacing="0">
1912 <tr><td align="left" valign="top">&bull; <a href="#X_002e509-certificates" accesskey="1">X.509 certificates</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1913 </td></tr>
1914 <tr><td align="left" valign="top">&bull; <a href="#OpenPGP-certificates" accesskey="2">OpenPGP certificates</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1915 </td></tr>
1916 <tr><td align="left" valign="top">&bull; <a href="#Advanced-certificate-verification" accesskey="3">Advanced certificate verification</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1917 </td></tr>
1918 <tr><td align="left" valign="top">&bull; <a href="#Digital-signatures" accesskey="4">Digital signatures</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1919 </td></tr>
1920 </table>
1921
1922 <hr>
1923 <a name="X_002e509-certificates"></a>
1924 <div class="header">
1925 <p>
1926 Next: <a href="#OpenPGP-certificates" accesskey="n" rel="next">OpenPGP certificates</a>, Up: <a href="#Certificate-authentication" accesskey="u" rel="up">Certificate authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1927 </div>
1928 <a name="X_002e509-certificates-1"></a>
1929 <h4 class="subsection">4.1.1 <acronym>X.509</acronym> certificates</h4>
1930 <a name="index-X_002e509-certificates"></a>
1931
1932 <p>The <acronym>X.509</acronym> protocols rely on a hierarchical trust model. In
1933 this trust model Certification Authorities (CAs) are used to certify
1934 entities.  Usually more than one certification authorities exist, and
1935 certification authorities may certify other authorities to issue
1936 certificates as well, following a hierarchical model.
1937 </p>
1938 <div class="float"><a name="fig_002dx509"></a>
1939 <img src="gnutls-x509.png" alt="gnutls-x509">
1940
1941 <div class="float-caption"><p><strong>Figure 4.1: </strong>An example of the X.509 hierarchical trust model.</p></div></div>
1942 <p>One needs to trust one or more CAs for his secure communications. In
1943 that case only the certificates issued by the trusted authorities are
1944 acceptable.  The framework is illustrated on <a href="#fig_002dx509">Figure 4.1</a>.
1945 </p>
1946 <table class="menu" border="0" cellspacing="0">
1947 <tr><td align="left" valign="top">&bull; <a href="#X_002e509-certificate-structure" accesskey="1">X.509 certificate structure</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1948 </td></tr>
1949 <tr><td align="left" valign="top">&bull; <a href="#Importing-an-X_002e509-certificate" accesskey="2">Importing an X.509 certificate</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1950 </td></tr>
1951 <tr><td align="left" valign="top">&bull; <a href="#X_002e509-distinguished-names" accesskey="3">X.509 distinguished names</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1952 </td></tr>
1953 <tr><td align="left" valign="top">&bull; <a href="#X_002e509-extensions" accesskey="4">X.509 extensions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1954 </td></tr>
1955 <tr><td align="left" valign="top">&bull; <a href="#X_002e509-public-and-private-keys" accesskey="5">X.509 public and private keys</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1956 </td></tr>
1957 <tr><td align="left" valign="top">&bull; <a href="#Verifying-X_002e509-certificate-paths" accesskey="6">Verifying X.509 certificate paths</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1958 </td></tr>
1959 <tr><td align="left" valign="top">&bull; <a href="#Verifying-a-certificate-in-the-context-of-TLS-session" accesskey="7">Verifying a certificate in the context of TLS session</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1960 </td></tr>
1961 <tr><td align="left" valign="top">&bull; <a href="#Verification-using-PKCS11" accesskey="8">Verification using PKCS11</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1962 </td></tr>
1963 </table>
1964
1965 <hr>
1966 <a name="X_002e509-certificate-structure"></a>
1967 <div class="header">
1968 <p>
1969 Next: <a href="#Importing-an-X_002e509-certificate" accesskey="n" rel="next">Importing an X.509 certificate</a>, Up: <a href="#X_002e509-certificates" accesskey="u" rel="up">X.509 certificates</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
1970 </div>
1971 <a name="X_002e509-certificate-structure-1"></a>
1972 <h4 class="subsubsection">4.1.1.1 <acronym>X.509</acronym> certificate structure</h4>
1973
1974 <p>An <acronym>X.509</acronym> certificate usually contains information about the
1975 certificate holder, the signer, a unique serial number, expiration
1976 dates and some other fields [<em>PKIX</em>] as shown in <a href="#tab_003ax509">Table 4.2</a>.
1977 </p>
1978 <div class="float"><a name="tab_003ax509"></a>
1979 <table>
1980 <thead><tr><th width="20%">Field</th><th width="70%">Description</th></tr></thead>
1981 <tr><td width="20%">version</td><td width="70%">The field that indicates the version of the certificate.</td></tr>
1982 <tr><td width="20%">serialNumber</td><td width="70%">This field holds a unique serial number per certificate.</td></tr>
1983 <tr><td width="20%">signature</td><td width="70%">The issuing authority&rsquo;s signature.</td></tr>
1984 <tr><td width="20%">issuer</td><td width="70%">Holds the issuer&rsquo;s distinguished name.</td></tr>
1985 <tr><td width="20%">validity</td><td width="70%">The activation and expiration dates.</td></tr>
1986 <tr><td width="20%">subject</td><td width="70%">The subject&rsquo;s distinguished name of the certificate.</td></tr>
1987 <tr><td width="20%">extensions</td><td width="70%">The extensions are fields only present in version 3 certificates.</td></tr>
1988 </table>
1989
1990 <div class="float-caption"><p><strong>Table 4.2: </strong>X.509 certificate fields.</p></div></div>
1991 <p>The certificate&rsquo;s <em>subject or issuer name</em> is not just a single
1992 string.  It is a Distinguished name and in the <acronym>ASN.1</acronym>
1993 notation is a sequence of several object identifiers with their corresponding
1994 values. Some of available OIDs to be used in an <acronym>X.509</acronym>
1995 distinguished name are defined in <samp>gnutls/x509.h</samp>.
1996 </p>
1997 <p>The <em>Version</em> field in a certificate has values either 1 or 3 for
1998 version 3 certificates.  Version 1 certificates do not support the
1999 extensions field so it is not possible to distinguish a CA from a
2000 person, thus their usage should be avoided.
2001 </p>
2002 <p>The <em>validity</em> dates are there to indicate the date that the
2003 specific certificate was activated and the date the certificate&rsquo;s key
2004 would be considered invalid.
2005 </p>
2006
2007 <p>In <acronym>GnuTLS</acronym> the <acronym>X.509</acronym> certificate structures are
2008 handled using the <code>gnutls_x509_crt_t</code> type and the corresponding
2009 private keys with the <code>gnutls_x509_privkey_t</code> type.  All the
2010 available functions for <acronym>X.509</acronym> certificate handling have
2011 their prototypes in <samp>gnutls/x509.h</samp>. An example program to
2012 demonstrate the <acronym>X.509</acronym> parsing capabilities can be found in
2013 <a href="#ex_002dx509_002dinfo">ex-x509-info</a>.
2014 </p>
2015 <hr>
2016 <a name="Importing-an-X_002e509-certificate"></a>
2017 <div class="header">
2018 <p>
2019 Next: <a href="#X_002e509-distinguished-names" accesskey="n" rel="next">X.509 distinguished names</a>, Previous: <a href="#X_002e509-certificate-structure" accesskey="p" rel="prev">X.509 certificate structure</a>, Up: <a href="#X_002e509-certificates" accesskey="u" rel="up">X.509 certificates</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
2020 </div>
2021 <a name="Importing-an-X_002e509-certificate-1"></a>
2022 <h4 class="subsubsection">4.1.1.2 Importing an X.509 certificate</h4>
2023
2024 <p>The certificate structure should be initialized using <a href="#gnutls_005fx509_005fcrt_005finit">gnutls_x509_crt_init</a>, and
2025 a certificate structure can be imported using <a href="#gnutls_005fx509_005fcrt_005fimport">gnutls_x509_crt_import</a>.
2026 </p>
2027 <dl compact="compact">
2028 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005finit">gnutls_x509_crt_init</a> (gnutls_x509_crt_t * <var>cert</var>)</code></dt>
2029 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fimport">gnutls_x509_crt_import</a> (gnutls_x509_crt_t <var>cert</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>)</code></dt>
2030 <dt><code><var>void</var> <a href="#gnutls_005fx509_005fcrt_005fdeinit">gnutls_x509_crt_deinit</a> (gnutls_x509_crt_t <var>cert</var>)</code></dt>
2031 </dl>
2032
2033 <p>In several functions an array of certificates is required. To assist in initialization
2034 and import the following two functions are provided.
2035 </p>
2036 <dl compact="compact">
2037 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005flist_005fimport">gnutls_x509_crt_list_import</a> (gnutls_x509_crt_t * <var>certs</var>, unsigned int * <var>cert_max</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned int <var>flags</var>)</code></dt>
2038 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005flist_005fimport2">gnutls_x509_crt_list_import2</a> (gnutls_x509_crt_t ** <var>certs</var>, unsigned int * <var>size</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned int <var>flags</var>)</code></dt>
2039 </dl>
2040
2041 <p>In all cases after use a certificate must be deinitialized using <a href="#gnutls_005fx509_005fcrt_005fdeinit">gnutls_x509_crt_deinit</a>.
2042 Note that although the functions above apply to <code>gnutls_x509_crt_t</code> structure, similar functions
2043 exist for the CRL structure <code>gnutls_x509_crl_t</code>.
2044 </p>
2045 <hr>
2046 <a name="X_002e509-distinguished-names"></a>
2047 <div class="header">
2048 <p>
2049 Next: <a href="#X_002e509-extensions" accesskey="n" rel="next">X.509 extensions</a>, Previous: <a href="#Importing-an-X_002e509-certificate" accesskey="p" rel="prev">Importing an X.509 certificate</a>, Up: <a href="#X_002e509-certificates" accesskey="u" rel="up">X.509 certificates</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
2050 </div>
2051 <a name="X_002e509-distinguished-names-1"></a>
2052 <h4 class="subsubsection">4.1.1.3 X.509 distinguished names</h4>
2053 <a name="index-X_002e509-distinguished-name"></a>
2054
2055 <p>The &ldquo;subject&rdquo; of an X.509 certificate is not described by
2056 a single name, but rather with a distinguished name. This in
2057 X.509 terminology is a list of strings each associated an object
2058 identifier. To make things simple GnuTLS provides <a href="#gnutls_005fx509_005fcrt_005fget_005fdn2">gnutls_x509_crt_get_dn2</a>
2059 which follows the rules in [<em>RFC4514</em>] and returns a single
2060 string. Access to each string by individual object identifiers
2061 can be accessed using <a href="#gnutls_005fx509_005fcrt_005fget_005fdn_005fby_005foid">gnutls_x509_crt_get_dn_by_oid</a>.
2062 </p>
2063
2064
2065
2066
2067 <dl>
2068 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fdn2"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_dn2</strong> <em>(gnutls_x509_crt_t <var>cert</var>, gnutls_datum_t * <var>dn</var>)</em></dt>
2069 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
2070 </p>
2071 <p><var>dn</var>: a pointer to a structure to hold the name
2072 </p>
2073 <p>This function will allocate buffer and copy the name of the Certificate.
2074 The name will be in the form &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as
2075 described in RFC4514. The output string will be ASCII or UTF-8
2076 encoded, depending on the certificate data.
2077 </p>
2078 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
2079 negative error value. and a negative error code on error.
2080 </p>
2081 <p><strong>Since:</strong> 3.1.10
2082 </p></dd></dl>
2083 <dl compact="compact">
2084 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fdn">gnutls_x509_crt_get_dn</a> (gnutls_x509_crt_t <var>cert</var>, char * <var>buf</var>, size_t * <var>buf_size</var>)</code></dt>
2085 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fdn_005fby_005foid">gnutls_x509_crt_get_dn_by_oid</a> (gnutls_x509_crt_t <var>cert</var>, const char * <var>oid</var>, int <var>indx</var>, unsigned int <var>raw_flag</var>, void * <var>buf</var>, size_t * <var>buf_size</var>)</code></dt>
2086 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fdn_005foid">gnutls_x509_crt_get_dn_oid</a> (gnutls_x509_crt_t <var>cert</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>oid_size</var>)</code></dt>
2087 </dl>
2088
2089 <p>Similar functions exist to access the distinguished name
2090 of the issuer of the certificate.
2091 </p>
2092 <dl compact="compact">
2093 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn">gnutls_x509_crt_get_issuer_dn</a> (gnutls_x509_crt_t <var>cert</var>, char * <var>buf</var>, size_t * <var>buf_size</var>)</code></dt>
2094 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn2">gnutls_x509_crt_get_issuer_dn2</a> (gnutls_x509_crt_t <var>cert</var>, gnutls_datum_t * <var>dn</var>)</code></dt>
2095 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005fby_005foid">gnutls_x509_crt_get_issuer_dn_by_oid</a> (gnutls_x509_crt_t <var>cert</var>, const char * <var>oid</var>, int <var>indx</var>, unsigned int <var>raw_flag</var>, void * <var>buf</var>, size_t * <var>buf_size</var>)</code></dt>
2096 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005foid">gnutls_x509_crt_get_issuer_dn_oid</a> (gnutls_x509_crt_t <var>cert</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>oid_size</var>)</code></dt>
2097 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fissuer">gnutls_x509_crt_get_issuer</a> (gnutls_x509_crt_t <var>cert</var>, gnutls_x509_dn_t * <var>dn</var>)</code></dt>
2098 </dl>
2099
2100 <p>The more powerful <a href="#gnutls_005fx509_005fcrt_005fget_005fsubject">gnutls_x509_crt_get_subject</a> and
2101 <a href="#gnutls_005fx509_005fdn_005fget_005frdn_005fava">gnutls_x509_dn_get_rdn_ava</a> provide efficient but low-level access
2102 to the contents of the distinguished name structure.
2103 </p>
2104 <dl compact="compact">
2105 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fsubject">gnutls_x509_crt_get_subject</a> (gnutls_x509_crt_t <var>cert</var>, gnutls_x509_dn_t * <var>dn</var>)</code></dt>
2106 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fissuer">gnutls_x509_crt_get_issuer</a> (gnutls_x509_crt_t <var>cert</var>, gnutls_x509_dn_t * <var>dn</var>)</code></dt>
2107 </dl>
2108
2109
2110
2111
2112 <dl>
2113 <dt><a name="index-gnutls_005fx509_005fdn_005fget_005frdn_005fava"></a>Function: <em>int</em> <strong>gnutls_x509_dn_get_rdn_ava</strong> <em>(gnutls_x509_dn_t <var>dn</var>, int <var>irdn</var>, int <var>iava</var>, gnutls_x509_ava_st * <var>ava</var>)</em></dt>
2114 <dd><p><var>dn</var>: a pointer to DN
2115 </p>
2116 <p><var>irdn</var>: index of RDN
2117 </p>
2118 <p><var>iava</var>: index of AVA.
2119 </p>
2120 <p><var>ava</var>: Pointer to structure which will hold output information.
2121 </p>
2122 <p>Get pointers to data within the DN. The format of the  <code>ava</code> structure
2123 is shown below.
2124 </p>
2125 <p>struct gnutls_x509_ava_st {
2126 gnutls_datum_t oid;
2127 gnutls_datum_t value;
2128 unsigned long value_tag;
2129 };
2130 </p>
2131 <p>The X.509 distinguished name is a sequence of sequences of strings
2132 and this is what the  <code>irdn</code> and  <code>iava</code> indexes model.
2133 </p>
2134 <p>Note that  <code>ava</code> will contain pointers into the  <code>dn</code> structure which
2135 in turns points to the original certificate. Thus you should not
2136 modify any data or deallocate any of those.
2137 </p>
2138 <p>This is a low-level function that requires the caller to do the
2139 value conversions when necessary (e.g. from UCS-2).
2140 </p>
2141 <p><strong>Returns:</strong> Returns 0 on success, or an error code.
2142 </p></dd></dl>
2143
2144 <hr>
2145 <a name="X_002e509-extensions"></a>
2146 <div class="header">
2147 <p>
2148 Next: <a href="#X_002e509-public-and-private-keys" accesskey="n" rel="next">X.509 public and private keys</a>, Previous: <a href="#X_002e509-distinguished-names" accesskey="p" rel="prev">X.509 distinguished names</a>, Up: <a href="#X_002e509-certificates" accesskey="u" rel="up">X.509 certificates</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
2149 </div>
2150 <a name="X_002e509-extensions-1"></a>
2151 <h4 class="subsubsection">4.1.1.4 X.509 extensions</h4>
2152 <a name="index-X_002e509-extensions"></a>
2153
2154 <p>X.509 version 3 certificates include a list of extensions that can
2155 be used to obtain additional information on the subject or the issuer
2156 of the certificate. Those may be e-mail addresses, flags that indicate whether the
2157 belongs to a CA etc.  All the supported <acronym>X.509</acronym> version 3
2158 extensions are shown in <a href="#tab_003ax509_002dext">Table 4.3</a>.
2159 </p>
2160 <p>The certificate extensions access is split into two parts. The first
2161 requires to retrieve the extension, and the second is the parsing part.
2162 </p>
2163 <p>To enumerate and retrieve the DER-encoded extension data available in a certificate the following
2164 two functions are available.
2165 </p><dl compact="compact">
2166 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fextension_005finfo">gnutls_x509_crt_get_extension_info</a> (gnutls_x509_crt_t <var>cert</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>oid_size</var>, unsigned int * <var>critical</var>)</code></dt>
2167 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fextension_005fdata2">gnutls_x509_crt_get_extension_data2</a> (gnutls_x509_crt_t <var>cert</var>, unsigned <var>indx</var>, gnutls_datum_t * <var>data</var>)</code></dt>
2168 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fextension_005fby_005foid2">gnutls_x509_crt_get_extension_by_oid2</a> (gnutls_x509_crt_t <var>cert</var>, const char * <var>oid</var>, int <var>indx</var>, gnutls_datum_t * <var>output</var>, unsigned int * <var>critical</var>)</code></dt>
2169 </dl>
2170
2171 <p>After a supported DER-encoded extension is retrieved it can be parsed using the APIs in <code>x509-ext.h</code>.
2172 Complex extensions may require initializing an intermediate structure that holds the
2173 parsed extension data. Examples of simple parsing functions are shown below.
2174 </p><dl compact="compact">
2175 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fext_005fimport_005fbasic_005fconstraints">gnutls_x509_ext_import_basic_constraints</a> (const gnutls_datum_t * <var>ext</var>, unsigned int * <var>ca</var>, int * <var>pathlen</var>)</code></dt>
2176 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fext_005fexport_005fbasic_005fconstraints">gnutls_x509_ext_export_basic_constraints</a> (unsigned int <var>ca</var>, int <var>pathlen</var>, gnutls_datum_t * <var>ext</var>)</code></dt>
2177 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fext_005fimport_005fkey_005fusage">gnutls_x509_ext_import_key_usage</a> (const gnutls_datum_t * <var>ext</var>, unsigned int * <var>key_usage</var>)</code></dt>
2178 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fext_005fexport_005fkey_005fusage">gnutls_x509_ext_export_key_usage</a> (unsigned int <var>usage</var>, gnutls_datum_t * <var>ext</var>)</code></dt>
2179 </dl>
2180
2181 <p>More complex extensions, such as Name Constraints, require an intermediate structure, in that
2182 case <code>gnutls_x509_name_constraints_t</code> to be initialized in order to store the parsed
2183 extension data.
2184 </p><dl compact="compact">
2185 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fext_005fimport_005fname_005fconstraints">gnutls_x509_ext_import_name_constraints</a> (const gnutls_datum_t * <var>ext</var>, gnutls_x509_name_constraints_t <var>nc</var>, unsigned int <var>flags</var>)</code></dt>
2186 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fext_005fexport_005fname_005fconstraints">gnutls_x509_ext_export_name_constraints</a> (gnutls_x509_name_constraints_t <var>nc</var>, gnutls_datum_t * <var>ext</var>)</code></dt>
2187 </dl>
2188
2189 <p>After the name constraints are extracted in the structure, the following functions
2190 can be used to access them.
2191 </p>
2192 <dl compact="compact">
2193 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fname_005fconstraints_005fget_005fpermitted">gnutls_x509_name_constraints_get_permitted</a> (gnutls_x509_name_constraints_t <var>nc</var>, unsigned <var>idx</var>, unsigned * <var>type</var>, gnutls_datum_t * <var>name</var>)</code></dt>
2194 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fname_005fconstraints_005fget_005fexcluded">gnutls_x509_name_constraints_get_excluded</a> (gnutls_x509_name_constraints_t <var>nc</var>, unsigned <var>idx</var>, unsigned * <var>type</var>, gnutls_datum_t * <var>name</var>)</code></dt>
2195 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fname_005fconstraints_005fadd_005fpermitted">gnutls_x509_name_constraints_add_permitted</a> (gnutls_x509_name_constraints_t <var>nc</var>, gnutls_x509_subject_alt_name_t <var>type</var>, const gnutls_datum_t * <var>name</var>)</code></dt>
2196 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fname_005fconstraints_005fadd_005fexcluded">gnutls_x509_name_constraints_add_excluded</a> (gnutls_x509_name_constraints_t <var>nc</var>, gnutls_x509_subject_alt_name_t <var>type</var>, const gnutls_datum_t * <var>name</var>)</code></dt>
2197 </dl>
2198 <dl compact="compact">
2199 <dt><code><var>unsigned</var> <a href="#gnutls_005fx509_005fname_005fconstraints_005fcheck">gnutls_x509_name_constraints_check</a> (gnutls_x509_name_constraints_t <var>nc</var>, gnutls_x509_subject_alt_name_t <var>type</var>, const gnutls_datum_t * <var>name</var>)</code></dt>
2200 <dt><code><var>unsigned</var> <a href="#gnutls_005fx509_005fname_005fconstraints_005fcheck_005fcrt">gnutls_x509_name_constraints_check_crt</a> (gnutls_x509_name_constraints_t <var>nc</var>, gnutls_x509_subject_alt_name_t <var>type</var>, gnutls_x509_crt_t <var>cert</var>)</code></dt>
2201 </dl>
2202
2203 <p>Other utility functions are listed below.
2204 </p><dl compact="compact">
2205 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fname_005fconstraints_005finit">gnutls_x509_name_constraints_init</a> (gnutls_x509_name_constraints_t * <var>nc</var>)</code></dt>
2206 <dt><code><var>void</var> <a href="#gnutls_005fx509_005fname_005fconstraints_005fdeinit">gnutls_x509_name_constraints_deinit</a> (gnutls_x509_name_constraints_t <var>nc</var>)</code></dt>
2207 </dl>
2208
2209 <p>Similar functions exist for all of the other supported extensions, listed in <a href="#tab_003ax509_002dext">Table 4.3</a>.
2210 </p>
2211 <div class="float"><a name="tab_003ax509_002dext"></a>
2212 <table>
2213 <thead><tr><th width="30%">Extension</th><th width="20%">OID</th><th width="40%">Description</th></tr></thead>
2214 <tr><td width="30%">Subject key id</td><td width="20%">2.5.29.14</td><td width="40%">An identifier of the key of the subject.</td></tr>
2215 <tr><td width="30%">Key usage</td><td width="20%">2.5.29.15</td><td width="40%">Constraints the key&rsquo;s usage of the certificate.</td></tr>
2216 <tr><td width="30%">Private key usage period</td><td width="20%">2.5.29.16</td><td width="40%">Constraints the validity time of the private key.</td></tr>
2217 <tr><td width="30%">Subject alternative name</td><td width="20%">2.5.29.17</td><td width="40%">Alternative names to subject&rsquo;s distinguished name.</td></tr>
2218 <tr><td width="30%">Issuer alternative name</td><td width="20%">2.5.29.18</td><td width="40%">Alternative names to the issuer&rsquo;s distinguished name.</td></tr>
2219 <tr><td width="30%">Basic constraints</td><td width="20%">2.5.29.19</td><td width="40%">Indicates whether this is a CA certificate or not, and specify the
2220 maximum path lengths of certificate chains.</td></tr>
2221 <tr><td width="30%">Name constraints</td><td width="20%">2.5.29.30</td><td width="40%">A field in CA certificates that restricts the scope of the name of
2222 issued certificates.</td></tr>
2223 <tr><td width="30%">CRL distribution points</td><td width="20%">2.5.29.31</td><td width="40%">This extension is set by the CA, in order to inform about the issued
2224 CRLs.</td></tr>
2225 <tr><td width="30%">Certificate policy</td><td width="20%">2.5.29.32</td><td width="40%">This extension is set to indicate the certificate policy as object
2226 identifier and may contain a descriptive string or URL.</td></tr>
2227 <tr><td width="30%">Authority key identifier</td><td width="20%">2.5.29.35</td><td width="40%">An identifier of the key of the issuer of the certificate. That is
2228 used to distinguish between different keys of the same issuer.</td></tr>
2229 <tr><td width="30%">Extended key usage</td><td width="20%">2.5.29.37</td><td width="40%">Constraints the purpose of the certificate.</td></tr>
2230 <tr><td width="30%">Authority information access</td><td width="20%">1.3.6.1.5.5.7.1.1</td><td width="40%">Information on services by the issuer of the certificate.</td></tr>
2231 <tr><td width="30%">Proxy Certification Information</td><td width="20%">1.3.6.1.5.5.7.1.14</td><td width="40%">Proxy Certificates includes this extension that contains the OID of
2232 the proxy policy language used, and can specify limits on the maximum
2233 lengths of proxy chains.  Proxy Certificates are specified in
2234 [<em>RFC3820</em>].</td></tr>
2235 </table>
2236
2237 <div class="float-caption"><p><strong>Table 4.3: </strong>Supported X.509 certificate extensions.</p></div></div>
2238 <p>Note, that there are also direct APIs to access extensions that may
2239 be simpler to use for non-complex extensions. They are available
2240 in <code>x509.h</code> and some examples are listed below.
2241 </p><dl compact="compact">
2242 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fbasic_005fconstraints">gnutls_x509_crt_get_basic_constraints</a> (gnutls_x509_crt_t <var>cert</var>, unsigned int * <var>critical</var>, unsigned int * <var>ca</var>, int * <var>pathlen</var>)</code></dt>
2243 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fset_005fbasic_005fconstraints">gnutls_x509_crt_set_basic_constraints</a> (gnutls_x509_crt_t <var>crt</var>, unsigned int <var>ca</var>, int <var>pathLenConstraint</var>)</code></dt>
2244 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fkey_005fusage">gnutls_x509_crt_get_key_usage</a> (gnutls_x509_crt_t <var>cert</var>, unsigned int * <var>key_usage</var>, unsigned int * <var>critical</var>)</code></dt>
2245 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fset_005fkey_005fusage">gnutls_x509_crt_set_key_usage</a> (gnutls_x509_crt_t <var>crt</var>, unsigned int <var>usage</var>)</code></dt>
2246 </dl>
2247
2248
2249 <hr>
2250 <a name="X_002e509-public-and-private-keys"></a>
2251 <div class="header">
2252 <p>
2253 Next: <a href="#Verifying-X_002e509-certificate-paths" accesskey="n" rel="next">Verifying X.509 certificate paths</a>, Previous: <a href="#X_002e509-extensions" accesskey="p" rel="prev">X.509 extensions</a>, Up: <a href="#X_002e509-certificates" accesskey="u" rel="up">X.509 certificates</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
2254 </div>
2255 <a name="Accessing-public-and-private-keys"></a>
2256 <h4 class="subsubsection">4.1.1.5 Accessing public and private keys</h4>
2257
2258 <p>Each X.509 certificate contains a public key that corresponds to a private key. To
2259 get a unique identifier of the public key the <a href="#gnutls_005fx509_005fcrt_005fget_005fkey_005fid">gnutls_x509_crt_get_key_id</a>
2260 function is provided. To export the public key or its parameters you may need
2261 to convert the X.509 structure to a <code>gnutls_pubkey_t</code>. See
2262 <a href="#Abstract-public-keys">Abstract public keys</a> for more information.
2263 </p>
2264
2265
2266
2267
2268 <dl>
2269 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_key_id</strong> <em>(gnutls_x509_crt_t <var>crt</var>, unsigned int <var>flags</var>, unsigned char * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
2270 <dd><p><var>crt</var>: Holds the certificate
2271 </p>
2272 <p><var>flags</var>: should be 0 for now
2273 </p>
2274 <p><var>output_data</var>: will contain the key ID
2275 </p>
2276 <p><var>output_data_size</var>: holds the size of output_data (and will be
2277 replaced by the actual size of parameters)
2278 </p>
2279 <p>This function will return a unique ID that depends on the public
2280 key parameters. This ID can be used in checking whether a
2281 certificate corresponds to the given private key.
2282 </p>
2283 <p>If the buffer provided is not long enough to hold the output, then
2284 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
2285 be returned.  The output will normally be a SHA-1 hash output,
2286 which is 20 bytes.
2287 </p>
2288 <p><strong>Returns:</strong> In case of failure a negative error code will be
2289 returned, and 0 on success.
2290 </p></dd></dl>
2291
2292 <p>The private key parameters may be directly accessed by using one of the following functions.
2293 </p>
2294 <dl compact="compact">
2295 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fprivkey_005fget_005fpk_005falgorithm2">gnutls_x509_privkey_get_pk_algorithm2</a> (gnutls_x509_privkey_t <var>key</var>, unsigned int * <var>bits</var>)</code></dt>
2296 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fprivkey_005fexport_005frsa_005fraw2">gnutls_x509_privkey_export_rsa_raw2</a> (gnutls_x509_privkey_t <var>key</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>, gnutls_datum_t * <var>d</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>u</var>, gnutls_datum_t * <var>e1</var>, gnutls_datum_t * <var>e2</var>)</code></dt>
2297 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fprivkey_005fexport_005fecc_005fraw">gnutls_x509_privkey_export_ecc_raw</a> (gnutls_x509_privkey_t <var>key</var>, gnutls_ecc_curve_t * <var>curve</var>, gnutls_datum_t * <var>x</var>, gnutls_datum_t * <var>y</var>, gnutls_datum_t * <var>k</var>)</code></dt>
2298 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fprivkey_005fexport_005fdsa_005fraw">gnutls_x509_privkey_export_dsa_raw</a> (gnutls_x509_privkey_t <var>key</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>g</var>, gnutls_datum_t * <var>y</var>, gnutls_datum_t * <var>x</var>)</code></dt>
2299 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fprivkey_005fget_005fkey_005fid">gnutls_x509_privkey_get_key_id</a> (gnutls_x509_privkey_t <var>key</var>, unsigned int <var>flags</var>, unsigned char * <var>output_data</var>, size_t * <var>output_data_size</var>)</code></dt>
2300 </dl>
2301
2302 <hr>
2303 <a name="Verifying-X_002e509-certificate-paths"></a>
2304 <div class="header">
2305 <p>
2306 Next: <a href="#Verifying-a-certificate-in-the-context-of-TLS-session" accesskey="n" rel="next">Verifying a certificate in the context of TLS session</a>, Previous: <a href="#X_002e509-public-and-private-keys" accesskey="p" rel="prev">X.509 public and private keys</a>, Up: <a href="#X_002e509-certificates" accesskey="u" rel="up">X.509 certificates</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
2307 </div>
2308 <a name="Verifying-X_002e509-certificate-paths-1"></a>
2309 <h4 class="subsubsection">4.1.1.6 Verifying <acronym>X.509</acronym> certificate paths</h4>
2310 <a name="index-verifying-certificate-paths"></a>
2311
2312 <p>Verifying certificate paths is important in <acronym>X.509</acronym>
2313 authentication. For this purpose the following functions are
2314 provided.
2315 </p>
2316
2317
2318
2319
2320 <dl>
2321 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fadd_005fcas"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_add_cas</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, const gnutls_x509_crt_t * <var>clist</var>, unsigned <var>clist_size</var>, unsigned int <var>flags</var>)</em></dt>
2322 <dd><p><var>list</var>: The structure of the list
2323 </p>
2324 <p><var>clist</var>: A list of CAs
2325 </p>
2326 <p><var>clist_size</var>: The length of the CA list
2327 </p>
2328 <p><var>flags</var>: should be 0 or an or&rsquo;ed sequence of <code>GNUTLS_TL</code>  options.
2329 </p>
2330 <p>This function will add the given certificate authorities
2331 to the trusted list. The list of CAs must not be deinitialized
2332 during this structure&rsquo;s lifetime.
2333 </p>
2334 <p>If the flag <code>GNUTLS_TL_NO_DUPLICATES</code>  is specified, then
2335 the provided  <code>clist</code> entries that are duplicates will not be
2336 added to the list and will be deinitialized.
2337 </p>
2338 <p><strong>Returns:</strong> The number of added elements is returned.
2339 </p>
2340 <p><strong>Since:</strong> 3.0.0
2341 </p></dd></dl>
2342
2343
2344
2345
2346 <dl>
2347 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fadd_005fnamed_005fcrt"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_add_named_crt</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, gnutls_x509_crt_t <var>cert</var>, const void * <var>name</var>, size_t <var>name_size</var>, unsigned int <var>flags</var>)</em></dt>
2348 <dd><p><var>list</var>: The structure of the list
2349 </p>
2350 <p><var>cert</var>: A certificate
2351 </p>
2352 <p><var>name</var>: An identifier for the certificate
2353 </p>
2354 <p><var>name_size</var>: The size of the identifier
2355 </p>
2356 <p><var>flags</var>: should be 0.
2357 </p>
2358 <p>This function will add the given certificate to the trusted
2359 list and associate it with a name. The certificate will not be
2360 be used for verification with <code>gnutls_x509_trust_list_verify_crt()</code>
2361 but only with <code>gnutls_x509_trust_list_verify_named_crt()</code> .
2362 </p>
2363 <p>In principle this function can be used to set individual &quot;server&quot;
2364 certificates that are trusted by the user for that specific server
2365 but for no other purposes.
2366 </p>
2367 <p>The certificate must not be deinitialized during the lifetime
2368 of the trusted list.
2369 </p>
2370 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
2371 negative error value.
2372 </p>
2373 <p><strong>Since:</strong> 3.0.0
2374 </p></dd></dl>
2375
2376
2377
2378
2379 <dl>
2380 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fadd_005fcrls"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_add_crls</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, const gnutls_x509_crl_t * <var>crl_list</var>, int <var>crl_size</var>, unsigned int <var>flags</var>, unsigned int <var>verification_flags</var>)</em></dt>
2381 <dd><p><var>list</var>: The structure of the list
2382 </p>
2383 <p><var>crl_list</var>: A list of CRLs
2384 </p>
2385 <p><var>crl_size</var>: The length of the CRL list
2386 </p>
2387 <p><var>flags</var>: if GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified before being added.
2388 </p>
2389 <p><var>verification_flags</var>: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
2390 </p>
2391 <p>This function will add the given certificate revocation lists
2392 to the trusted list. The list of CRLs must not be deinitialized
2393 during this structure&rsquo;s lifetime.
2394 </p>
2395 <p>This function must be called after <code>gnutls_x509_trust_list_add_cas()</code>
2396 to allow verifying the CRLs for validity. If the flag <code>GNUTLS_TL_NO_DUPLICATES</code>
2397 is given, then any provided CRLs that are a duplicate, will be deinitialized
2398 and not added to the list (that assumes that <code>gnutls_x509_trust_list_deinit()</code>
2399 will be called with all=1).
2400 </p>
2401 <p><strong>Returns:</strong> The number of added elements is returned.
2402 </p>
2403 <p><strong>Since:</strong> 3.0
2404 </p></dd></dl>
2405
2406
2407
2408
2409 <dl>
2410 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_verify_crt</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, gnutls_x509_crt_t * <var>cert_list</var>, unsigned int <var>cert_list_size</var>, unsigned int <var>flags</var>, unsigned int * <var>voutput</var>, gnutls_verify_output_function <var>func</var>)</em></dt>
2411 <dd><p><var>list</var>: The structure of the list
2412 </p>
2413 <p><var>cert_list</var>: is the certificate list to be verified
2414 </p>
2415 <p><var>cert_list_size</var>: is the certificate list size
2416 </p>
2417 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
2418 </p>
2419 <p><var>voutput</var>: will hold the certificate verification output.
2420 </p>
2421 <p><var>func</var>: If non-null will be called on each chain element verification with the output.
2422 </p>
2423 <p>This function will try to verify the given certificate and return
2424 its status. The  <code>verify</code> parameter will hold an OR&rsquo;ed sequence of
2425 <code>gnutls_certificate_status_t</code>  flags.
2426 </p>
2427 <p>Additionally a certificate verification profile can be specified
2428 from the ones in <code>gnutls_certificate_verification_profiles_t</code>  by
2429 ORing the result of <code>GNUTLS_PROFILE_TO_VFLAGS()</code>  to the verification
2430 flags.
2431 </p>
2432 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
2433 negative error value.
2434 </p>
2435 <p><strong>Since:</strong> 3.0
2436 </p></dd></dl>
2437
2438
2439
2440
2441 <dl>
2442 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt2"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_verify_crt2</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, gnutls_x509_crt_t * <var>cert_list</var>, unsigned int <var>cert_list_size</var>, gnutls_typed_vdata_st * <var>data</var>, unsigned int <var>elements</var>, unsigned int <var>flags</var>, unsigned int * <var>voutput</var>, gnutls_verify_output_function <var>func</var>)</em></dt>
2443 <dd><p><var>list</var>: The structure of the list
2444 </p>
2445 <p><var>cert_list</var>: is the certificate list to be verified
2446 </p>
2447 <p><var>cert_list_size</var>: is the certificate list size
2448 </p>
2449 <p><var>data</var>: an array of typed data
2450 </p>
2451 <p><var>elements</var>: the number of data elements
2452 </p>
2453 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
2454 </p>
2455 <p><var>voutput</var>: will hold the certificate verification output.
2456 </p>
2457 <p><var>func</var>: If non-null will be called on each chain element verification with the output.
2458 </p>
2459 <p>This function will try to verify the given certificate and return
2460 its status. The  <code>verify</code> parameter will hold an OR&rsquo;ed sequence of
2461 <code>gnutls_certificate_status_t</code>  flags.
2462 </p>
2463 <p>Additionally a certificate verification profile can be specified
2464 from the ones in <code>gnutls_certificate_verification_profiles_t</code>  by
2465 ORing the result of <code>GNUTLS_PROFILE_TO_VFLAGS()</code>  to the verification
2466 flags.
2467 </p>
2468 <p>The acceptable  <code>data</code> types are <code>GNUTLS_DT_DNS_HOSTNAME</code>  and <code>GNUTLS_DT_KEY_PURPOSE_OID</code> .
2469 The former accepts as data a null-terminated hostname, and the latter a null-terminated
2470 object identifier (e.g., <code>GNUTLS_KP_TLS_WWW_SERVER</code> ).
2471 If a DNS hostname is provided then this function will compare
2472 the hostname in the certificate against the given. If names do not match the
2473 <code>GNUTLS_CERT_UNEXPECTED_OWNER</code>  status flag will be set.
2474 If a key purpose OID is provided and the end-certificate contains the extended key
2475 usage PKIX extension, it will be required to be have the provided key purpose
2476 or be marked for any purpose, otherwise verification will fail with <code>GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE</code>  status.
2477 </p>
2478 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
2479 negative error value. Note that verification failure will not result to an
2480 error code, only  <code>voutput</code> will be updated.
2481 </p>
2482 <p><strong>Since:</strong> 3.3.8
2483 </p></dd></dl>
2484
2485
2486
2487
2488 <dl>
2489 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fverify_005fnamed_005fcrt"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_verify_named_crt</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, gnutls_x509_crt_t <var>cert</var>, const void * <var>name</var>, size_t <var>name_size</var>, unsigned int <var>flags</var>, unsigned int * <var>voutput</var>, gnutls_verify_output_function <var>func</var>)</em></dt>
2490 <dd><p><var>list</var>: The structure of the list
2491 </p>
2492 <p><var>cert</var>: is the certificate to be verified
2493 </p>
2494 <p><var>name</var>: is the certificate&rsquo;s name
2495 </p>
2496 <p><var>name_size</var>: is the certificate&rsquo;s name size
2497 </p>
2498 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
2499 </p>
2500 <p><var>voutput</var>: will hold the certificate verification output.
2501 </p>
2502 <p><var>func</var>: If non-null will be called on each chain element verification with the output.
2503 </p>
2504 <p>This function will try to find a certificate that is associated with the provided
2505 name &ndash;see <code>gnutls_x509_trust_list_add_named_crt()</code> . If a match is found the certificate is considered valid.
2506 In addition to that this function will also check CRLs.
2507 The  <code>voutput</code> parameter will hold an OR&rsquo;ed sequence of <code>gnutls_certificate_status_t</code>  flags.
2508 </p>
2509 <p>Additionally a certificate verification profile can be specified
2510 from the ones in <code>gnutls_certificate_verification_profiles_t</code>  by
2511 ORing the result of <code>GNUTLS_PROFILE_TO_VFLAGS()</code>  to the verification
2512 flags.
2513 </p>
2514 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
2515 negative error value.
2516 </p>
2517 <p><strong>Since:</strong> 3.0.0
2518 </p></dd></dl>
2519
2520
2521
2522
2523
2524 <dl>
2525 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005ffile"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_add_trust_file</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, const char * <var>ca_file</var>, const char * <var>crl_file</var>, gnutls_x509_crt_fmt_t <var>type</var>, unsigned int <var>tl_flags</var>, unsigned int <var>tl_vflags</var>)</em></dt>
2526 <dd><p><var>list</var>: The structure of the list
2527 </p>
2528 <p><var>ca_file</var>: A file containing a list of CAs (optional)
2529 </p>
2530 <p><var>crl_file</var>: A file containing a list of CRLs (optional)
2531 </p>
2532 <p><var>type</var>: The format of the certificates
2533 </p>
2534 <p><var>tl_flags</var>: GNUTLS_TL_*
2535 </p>
2536 <p><var>tl_vflags</var>: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
2537 </p>
2538 <p>This function will add the given certificate authorities
2539 to the trusted list. PKCS <code>11</code>  URLs are also accepted, instead
2540 of files, by this function. A PKCS <code>11</code>  URL implies a trust
2541 database (a specially marked module in p11-kit); the URL &quot;pkcs11:&quot;
2542 implies all trust databases in the system. Only a single URL specifying
2543 trust databases can be set; they cannot be stacked with multiple calls.
2544 </p>
2545 <p><strong>Returns:</strong> The number of added elements is returned.
2546 </p>
2547 <p><strong>Since:</strong> 3.1
2548 </p></dd></dl>
2549
2550
2551
2552
2553 <dl>
2554 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005fmem"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_add_trust_mem</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, const gnutls_datum_t * <var>cas</var>, const gnutls_datum_t * <var>crls</var>, gnutls_x509_crt_fmt_t <var>type</var>, unsigned int <var>tl_flags</var>, unsigned int <var>tl_vflags</var>)</em></dt>
2555 <dd><p><var>list</var>: The structure of the list
2556 </p>
2557 <p><var>cas</var>: A buffer containing a list of CAs (optional)
2558 </p>
2559 <p><var>crls</var>: A buffer containing a list of CRLs (optional)
2560 </p>
2561 <p><var>type</var>: The format of the certificates
2562 </p>
2563 <p><var>tl_flags</var>: GNUTLS_TL_*
2564 </p>
2565 <p><var>tl_vflags</var>: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
2566 </p>
2567 <p>This function will add the given certificate authorities
2568 to the trusted list.
2569 </p>
2570 <p><strong>Returns:</strong> The number of added elements is returned.
2571 </p>
2572 <p><strong>Since:</strong> 3.1
2573 </p></dd></dl>
2574
2575
2576
2577
2578 <dl>
2579 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fadd_005fsystem_005ftrust"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_add_system_trust</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, unsigned int <var>tl_flags</var>, unsigned int <var>tl_vflags</var>)</em></dt>
2580 <dd><p><var>list</var>: The structure of the list
2581 </p>
2582 <p><var>tl_flags</var>: GNUTLS_TL_*
2583 </p>
2584 <p><var>tl_vflags</var>: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
2585 </p>
2586 <p>This function adds the system&rsquo;s default trusted certificate
2587 authorities to the trusted list. Note that on unsupported systems
2588 this function returns <code>GNUTLS_E_UNIMPLEMENTED_FEATURE</code> .
2589 </p>
2590 <p>This function implies the flag <code>GNUTLS_TL_NO_DUPLICATES</code> .
2591 </p>
2592 <p><strong>Returns:</strong> The number of added elements or a negative error code on error.
2593 </p>
2594 <p><strong>Since:</strong> 3.1
2595 </p></dd></dl>
2596
2597 <p>The verification function will verify a given certificate chain against a list of certificate
2598 authorities and certificate revocation lists, and output
2599 a bit-wise OR of elements of the <code>gnutls_certificate_status_t</code>
2600 enumeration shown in <a href="#gnutls_005fcertificate_005fstatus_005ft">Figure 4.2</a>. The <code>GNUTLS_CERT_INVALID</code> flag
2601 is always set on a verification error and more detailed flags will also be set when appropriate.
2602 </p>
2603 <div class="float"><a name="gnutls_005fcertificate_005fstatus_005ft"></a>
2604
2605
2606 <dl compact="compact">
2607 <dt><code>GNUTLS_CERT_INVALID</code></dt>
2608 <dd><p>The certificate is not signed by one of the
2609 known authorities or the signature is invalid (deprecated by the flags
2610 <code>GNUTLS_CERT_SIGNATURE_FAILURE</code>  and <code>GNUTLS_CERT_SIGNER_NOT_FOUND</code> ).
2611 </p></dd>
2612 <dt><code>GNUTLS_CERT_REVOKED</code></dt>
2613 <dd><p>Certificate is revoked by its authority.  In X.509 this will be
2614 set only if CRLs are checked.
2615 </p></dd>
2616 <dt><code>GNUTLS_CERT_SIGNER_NOT_FOUND</code></dt>
2617 <dd><p>The certificate&rsquo;s issuer is not known.
2618 This is the case if the issuer is not included in the trusted certificate list.
2619 </p></dd>
2620 <dt><code>GNUTLS_CERT_SIGNER_NOT_CA</code></dt>
2621 <dd><p>The certificate&rsquo;s signer was not a CA. This
2622 may happen if this was a version 1 certificate, which is common with
2623 some CAs, or a version 3 certificate without the basic constrains extension.
2624 </p></dd>
2625 <dt><code>GNUTLS_CERT_INSECURE_ALGORITHM</code></dt>
2626 <dd><p>The certificate was signed using an insecure
2627 algorithm such as MD2 or MD5. These algorithms have been broken and
2628 should not be trusted.
2629 </p></dd>
2630 <dt><code>GNUTLS_CERT_NOT_ACTIVATED</code></dt>
2631 <dd><p>The certificate is not yet activated.
2632 </p></dd>
2633 <dt><code>GNUTLS_CERT_EXPIRED</code></dt>
2634 <dd><p>The certificate has expired.
2635 </p></dd>
2636 <dt><code>GNUTLS_CERT_SIGNATURE_FAILURE</code></dt>
2637 <dd><p>The signature verification failed.
2638 </p></dd>
2639 <dt><code>GNUTLS_CERT_REVOCATION_DATA_SUPERSEDED</code></dt>
2640 <dd><p>The revocation data are old and have been superseded.
2641 </p></dd>
2642 <dt><code>GNUTLS_CERT_UNEXPECTED_OWNER</code></dt>
2643 <dd><p>The owner is not the expected one.
2644 </p></dd>
2645 <dt><code>GNUTLS_CERT_REVOCATION_DATA_ISSUED_IN_FUTURE</code></dt>
2646 <dd><p>The revocation data have a future issue date.
2647 </p></dd>
2648 <dt><code>GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE</code></dt>
2649 <dd><p>The certificate&rsquo;s signer constraints were
2650 violated.
2651 </p></dd>
2652 <dt><code>GNUTLS_CERT_MISMATCH</code></dt>
2653 <dd><p>The certificate presented isn&rsquo;t the expected one (TOFU)
2654 </p></dd>
2655 </dl>
2656
2657 <div class="float-caption"><p><strong>Figure 4.2: </strong>The <code>gnutls_certificate_status_t</code> enumeration.</p></div></div>
2658 <p>An example of certificate verification is shown in <a href="#ex_002dverify2">ex-verify2</a>.
2659 It is also possible to have a set of certificates that
2660 are trusted for a particular server but not to authorize other certificates.
2661 This purpose is served by the functions <a href="#gnutls_005fx509_005ftrust_005flist_005fadd_005fnamed_005fcrt">gnutls_x509_trust_list_add_named_crt</a> and <a href="#gnutls_005fx509_005ftrust_005flist_005fverify_005fnamed_005fcrt">gnutls_x509_trust_list_verify_named_crt</a>.
2662 </p>
2663 <hr>
2664 <a name="Verifying-a-certificate-in-the-context-of-TLS-session"></a>
2665 <div class="header">
2666 <p>
2667 Next: <a href="#Verification-using-PKCS11" accesskey="n" rel="next">Verification using PKCS11</a>, Previous: <a href="#Verifying-X_002e509-certificate-paths" accesskey="p" rel="prev">Verifying X.509 certificate paths</a>, Up: <a href="#X_002e509-certificates" accesskey="u" rel="up">X.509 certificates</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
2668 </div>
2669 <a name="Verifying-a-certificate-in-the-context-of-TLS-session-1"></a>
2670 <h4 class="subsubsection">4.1.1.7 Verifying a certificate in the context of TLS session</h4>
2671 <a name="index-verifying-certificate-paths-1"></a>
2672 <a name="index-gnutls_005fcertificate_005fverify_005fflags"></a>
2673
2674 <p>When operating in the context of a TLS session, the trusted certificate
2675 authority list may also be set using:
2676 </p><dl compact="compact">
2677 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fx509_005ftrust_005ffile">gnutls_certificate_set_x509_trust_file</a> (gnutls_certificate_credentials_t            <var>cred</var>, const char * <var>cafile</var>, gnutls_x509_crt_fmt_t <var>type</var>)</code></dt>
2678 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fx509_005ftrust_005fdir">gnutls_certificate_set_x509_trust_dir</a> (gnutls_certificate_credentials_t <var>cred</var>, const char * <var>ca_dir</var>, gnutls_x509_crt_fmt_t <var>type</var>)</code></dt>
2679 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fx509_005fcrl_005ffile">gnutls_certificate_set_x509_crl_file</a> (gnutls_certificate_credentials_t <var>res</var>, const char * <var>crlfile</var>, gnutls_x509_crt_fmt_t <var>type</var>)</code></dt>
2680 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fx509_005fsystem_005ftrust">gnutls_certificate_set_x509_system_trust</a> (gnutls_certificate_credentials_t       <var>cred</var>)</code></dt>
2681 </dl>
2682
2683 <p>These functions allow the specification of the trusted certificate authorities, either
2684 via a file, a directory or use the system-specified certificate authories.
2685 Unless the authorities are application specific, it is generally recommended
2686 to use the system trust storage (see <a href="#gnutls_005fcertificate_005fset_005fx509_005fsystem_005ftrust">gnutls_certificate_set_x509_system_trust</a>).
2687 </p>
2688 <p>Unlike the previous section it is not required to setup a trusted list, and
2689 the function <a href="#gnutls_005fcertificate_005fverify_005fpeers3">gnutls_certificate_verify_peers3</a>
2690 is used to verify the peer&rsquo;s certificate chain and identity. The reported
2691 verification status is identical to the verification functions described
2692 in the previous section.
2693 Note that in certain cases it is required to check the marked purpose of
2694 the end certificate (e.g. <code>GNUTLS_KP_TLS_WWW_SERVER</code>); in these cases
2695 the more advanced <a href="#gnutls_005fcertificate_005fverify_005fpeers">gnutls_certificate_verify_peers</a> should be used instead.
2696 </p>
2697 <p>There is also the possibility to pass some input to the verification
2698 functions in the form of flags. For <a href="#gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt2">gnutls_x509_trust_list_verify_crt2</a> the
2699 flags are passed directly, but for
2700 <a href="#gnutls_005fcertificate_005fverify_005fpeers3">gnutls_certificate_verify_peers3</a>, the flags are set using
2701 <a href="#gnutls_005fcertificate_005fset_005fverify_005fflags">gnutls_certificate_set_verify_flags</a>.  All the available
2702 flags are part of the enumeration
2703 <code>gnutls_certificate_verify_flags</code> shown in <a href="#gnutls_005fcertificate_005fverify_005fflags">Figure 4.3</a>.
2704 </p>
2705 <div class="float"><a name="gnutls_005fcertificate_005fverify_005fflags"></a>
2706
2707
2708 <dl compact="compact">
2709 <dt><code>GNUTLS_VERIFY_DISABLE_CA_SIGN</code></dt>
2710 <dd><p>If set a signer does not have to be
2711 a certificate authority. This flag should normally be disabled,
2712 unless you know what this means.
2713 </p></dd>
2714 <dt><code>GNUTLS_VERIFY_DO_NOT_ALLOW_SAME</code></dt>
2715 <dd><p>If a certificate is not signed by
2716 anyone trusted but exists in the trusted CA list do not treat it
2717 as trusted.
2718 </p></dd>
2719 <dt><code>GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT</code></dt>
2720 <dd><p>Allow CA certificates that
2721 have version 1 (both root and intermediate). This might be
2722 dangerous since those haven&rsquo;t the basicConstraints
2723 extension.
2724 </p></dd>
2725 <dt><code>GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2</code></dt>
2726 <dd><p>Allow certificates to be signed
2727 using the broken MD2 algorithm.
2728 </p></dd>
2729 <dt><code>GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5</code></dt>
2730 <dd><p>Allow certificates to be signed
2731 using the broken MD5 algorithm.
2732 </p></dd>
2733 <dt><code>GNUTLS_VERIFY_DISABLE_TIME_CHECKS</code></dt>
2734 <dd><p>Disable checking of activation
2735 and expiration validity periods of certificate chains. Don&rsquo;t set
2736 this unless you understand the security implications.
2737 </p></dd>
2738 <dt><code>GNUTLS_VERIFY_DISABLE_TRUSTED_TIME_CHECKS</code></dt>
2739 <dd><p>If set a signer in the trusted
2740 list is never checked for expiration or activation.
2741 </p></dd>
2742 <dt><code>GNUTLS_VERIFY_DO_NOT_ALLOW_X509_V1_CA_CRT</code></dt>
2743 <dd><p>Do not allow trusted CA
2744 certificates that have version 1.  This option is to be used
2745 to deprecate all certificates of version 1.
2746 </p></dd>
2747 <dt><code>GNUTLS_VERIFY_DISABLE_CRL_CHECKS</code></dt>
2748 <dd><p>Disable checking for validity
2749 using certificate revocation lists or the available OCSP data.
2750 </p></dd>
2751 <dt><code>GNUTLS_VERIFY_ALLOW_UNSORTED_CHAIN</code></dt>
2752 <dd><p>A certificate chain is tolerated
2753 if unsorted (the case with many TLS servers out there). This is the
2754 default since GnuTLS 3.1.4.
2755 </p></dd>
2756 <dt><code>GNUTLS_VERIFY_DO_NOT_ALLOW_UNSORTED_CHAIN</code></dt>
2757 <dd><p>Do not tolerate an unsorted
2758 certificate chain.
2759 </p></dd>
2760 <dt><code>GNUTLS_VERIFY_DO_NOT_ALLOW_WILDCARDS</code></dt>
2761 <dd><p>When including a hostname
2762 check in the verification, do not consider any wildcards.
2763 </p></dd>
2764 </dl>
2765
2766 <div class="float-caption"><p><strong>Figure 4.3: </strong>The <code>gnutls_certificate_verify_flags</code> enumeration.</p></div></div>
2767 <hr>
2768 <a name="Verification-using-PKCS11"></a>
2769 <div class="header">
2770 <p>
2771 Previous: <a href="#Verifying-a-certificate-in-the-context-of-TLS-session" accesskey="p" rel="prev">Verifying a certificate in the context of TLS session</a>, Up: <a href="#X_002e509-certificates" accesskey="u" rel="up">X.509 certificates</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
2772 </div>
2773 <a name="Verifying-a-certificate-using-PKCS-_002311"></a>
2774 <h4 class="subsubsection">4.1.1.8 Verifying a certificate using PKCS #11</h4>
2775 <a name="index-verifying-certificate-with-pkcs11"></a>
2776
2777 <p>Some systems provide a system wide trusted certificate storage accessible using
2778 the PKCS #11 API. That is, the trusted certificates are queried and accessed using the
2779 PKCS #11 API, and trusted certificate properties, such as purpose, are marked using
2780 attached extensions. One example is the p11-kit trust module<a name="DOCF6" href="#FOOT6"><sup>6</sup></a>.
2781 </p>
2782 <p>These special PKCS #11 modules can be used for GnuTLS certificate verification if marked as trust
2783 policy modules, i.e., with <code>trust-policy: yes</code> in the p11-kit module file.
2784 The way to use them is by specifying to the file verification function (e.g., <a href="#gnutls_005fcertificate_005fset_005fx509_005ftrust_005ffile">gnutls_certificate_set_x509_trust_file</a>),
2785 a pkcs11 URL, or simply <code>pkcs11:</code> to use all the marked with trust policy modules.
2786 </p>
2787 <p>The trust modules of p11-kit assign a purpose to trusted authorities using the extended
2788 key usage object identifiers. The common purposes are shown in <a href="#tab_003apurposes">Table 4.4</a>. Note
2789 that typically according to [<em>RFC5280</em>] the extended key usage object identifiers apply to end certificates. Their
2790 application to CA certificates is an extension used by the trust modules.
2791 </p>
2792 <div class="float"><a name="tab_003apurposes"></a>
2793 <table>
2794 <thead><tr><th width="20%">Purpose</th><th width="20%">OID</th><th width="60%">Description</th></tr></thead>
2795 <tr><td width="20%">GNUTLS_KP_TLS_WWW_SERVER</td><td width="20%">1.3.6.1.5.5.7.3.1</td><td width="60%">The certificate is to be used for TLS WWW authentication. When in a CA certificate, it
2796 indicates that the CA is allowed to sign certificates for TLS WWW authentication.</td></tr>
2797 <tr><td width="20%">GNUTLS_KP_TLS_WWW_CLIENT</td><td width="20%">1.3.6.1.5.5.7.3.2</td><td width="60%">The certificate is to be used for TLS WWW client authentication. When in a CA certificate, it
2798 indicates that the CA is allowed to sign certificates for TLS WWW client authentication.</td></tr>
2799 <tr><td width="20%">GNUTLS_KP_CODE_SIGNING</td><td width="20%">1.3.6.1.5.5.7.3.3</td><td width="60%">The certificate is to be used for code signing. When in a CA certificate, it
2800 indicates that the CA is allowed to sign certificates for code signing.</td></tr>
2801 <tr><td width="20%">GNUTLS_KP_EMAIL_PROTECTION</td><td width="20%">1.3.6.1.5.5.7.3.4</td><td width="60%">The certificate is to be used for email protection. When in a CA certificate, it
2802 indicates that the CA is allowed to sign certificates for email users.</td></tr>
2803 <tr><td width="20%">GNUTLS_KP_OCSP_SIGNING</td><td width="20%">1.3.6.1.5.5.7.3.9</td><td width="60%">The certificate is to be used for signing OCSP responses. When in a CA certificate, it
2804 indicates that the CA is allowed to sign certificates which sign OCSP reponses.</td></tr>
2805 <tr><td width="20%">GNUTLS_KP_ANY</td><td width="20%">2.5.29.37.0</td><td width="60%">The certificate is to be used for any purpose. When in a CA certificate, it
2806 indicates that the CA is allowed to sign any kind of certificates.</td></tr>
2807 </table>
2808
2809 <div class="float-caption"><p><strong>Table 4.4: </strong>Key purpose object identifiers.</p></div></div>
2810 <p>With such modules, it is recommended to use the verification functions <a href="#gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt2">gnutls_x509_trust_list_verify_crt2</a>,
2811 or <a href="#gnutls_005fcertificate_005fverify_005fpeers">gnutls_certificate_verify_peers</a>, which allow to explicitly specify the key purpose. The
2812 other verification functions which do not allow setting a purpose, would operate as if
2813 <code>GNUTLS_KP_TLS_WWW_SERVER</code> was requested from the trusted authorities.
2814 </p>
2815 <hr>
2816 <a name="OpenPGP-certificates"></a>
2817 <div class="header">
2818 <p>
2819 Next: <a href="#Advanced-certificate-verification" accesskey="n" rel="next">Advanced certificate verification</a>, Previous: <a href="#X_002e509-certificates" accesskey="p" rel="prev">X.509 certificates</a>, Up: <a href="#Certificate-authentication" accesskey="u" rel="up">Certificate authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
2820 </div>
2821 <a name="OpenPGP-certificates-1"></a>
2822 <h4 class="subsection">4.1.2 <acronym>OpenPGP</acronym> certificates</h4>
2823 <a name="index-OpenPGP-certificates"></a>
2824
2825 <p>The <acronym>OpenPGP</acronym> key authentication relies on a distributed trust
2826 model, called the &ldquo;web of trust&rdquo;. The &ldquo;web of trust&rdquo; uses a
2827 decentralized system of trusted introducers, which are the same as a
2828 CA. <acronym>OpenPGP</acronym> allows anyone to sign anyone else&rsquo;s public
2829 key. When Alice signs Bob&rsquo;s key, she is introducing Bob&rsquo;s key to
2830 anyone who trusts Alice. If someone trusts Alice to introduce keys,
2831 then Alice is a trusted introducer in the mind of that observer.
2832 For example in <a href="#fig_002dopenpgp">Figure 4.4</a>, David trusts Alice to be an introducer and Alice
2833 signed Bob&rsquo;s key thus Dave trusts Bob&rsquo;s key to be the real one.
2834 </p>
2835 <div class="float"><a name="fig_002dopenpgp"></a>
2836 <img src="gnutls-pgp.png" alt="gnutls-pgp">
2837
2838 <div class="float-caption"><p><strong>Figure 4.4: </strong>An example of the OpenPGP trust model.</p></div></div>
2839 <p>There are some key points that are important in that model. In the
2840 example Alice has to sign Bob&rsquo;s key, only if she is sure that the key
2841 belongs to Bob. Otherwise she may also make Dave falsely believe that
2842 this is Bob&rsquo;s key. Dave has also the responsibility to know who to
2843 trust.  This model is similar to real life relations.
2844 </p>
2845 <p>Just see how Charlie behaves in the previous example. Although he has
2846 signed Bob&rsquo;s key - because he knows, somehow, that it belongs to Bob -
2847 he does not trust Bob to be an introducer. Charlie decided to trust
2848 only Kevin, for some reason. A reason could be that Bob is lazy
2849 enough, and signs other people&rsquo;s keys without being sure that they
2850 belong to the actual owner.
2851 </p>
2852 <div class="float"><a name="tab_003aopenpgp_002dcertificate"></a>
2853 <table>
2854 <thead><tr><th width="20%">Field</th><th width="70%">Description</th></tr></thead>
2855 <tr><td width="20%">version</td><td width="70%">The field that indicates the version of the OpenPGP structure.</td></tr>
2856 <tr><td width="20%">user ID</td><td width="70%">An RFC 2822 string that identifies the owner of the key. There may be
2857 multiple user identifiers in a key.</td></tr>
2858 <tr><td width="20%">public key</td><td width="70%">The main public key of the certificate.</td></tr>
2859 <tr><td width="20%">expiration</td><td width="70%">The expiration time of the main public key.</td></tr>
2860 <tr><td width="20%">public subkey</td><td width="70%">An additional public key of the certificate. There may be multiple subkeys
2861 in a certificate.</td></tr>
2862 <tr><td width="20%">public subkey expiration</td><td width="70%">The expiration time of the subkey.</td></tr>
2863 </table>
2864
2865 <div class="float-caption"><p><strong>Table 4.5: </strong>OpenPGP certificate fields.</p></div></div>
2866
2867 <a name="OpenPGP-certificate-structure"></a>
2868 <h4 class="subsubsection">4.1.2.1 <acronym>OpenPGP</acronym> certificate structure</h4>
2869
2870 <p>In <acronym>GnuTLS</acronym> the <acronym>OpenPGP</acronym> certificate structures
2871 [<em>RFC2440</em>] are handled using the <code>gnutls_openpgp_crt_t</code> type.
2872 A typical certificate contains the user ID, which is an RFC 2822
2873 mail and name address, a public key, possibly a number of additional
2874 public keys (called subkeys), and a number of signatures. The various
2875 fields are shown in <a href="#tab_003aopenpgp_002dcertificate">Table 4.5</a>.
2876 </p>
2877 <p>The additional subkeys may provide key for various different purposes,
2878 e.g. one key to encrypt mail, and another to sign a TLS key exchange.
2879 Each subkey is identified by a unique key ID.
2880 The keys that are to be used in a TLS key exchange that requires
2881 signatures are called authentication keys in the OpenPGP jargon.
2882 The mapping of TLS key exchange methods to public keys is shown in
2883 <a href="#tab_003aopenpgp_002dkey_002dexchange">Table 4.6</a>.
2884 </p>
2885 <div class="float"><a name="tab_003aopenpgp_002dkey_002dexchange"></a>
2886 <table>
2887 <thead><tr><th width="20%">Key exchange</th><th width="70%">Public key requirements</th></tr></thead>
2888 <tr><td width="20%">RSA</td><td width="70%">An RSA public key that allows encryption.</td></tr>
2889 <tr><td width="20%">DHE_RSA</td><td width="70%">An RSA public key that is marked for authentication.</td></tr>
2890 <tr><td width="20%">ECDHE_RSA</td><td width="70%">An RSA public key that is marked for authentication.</td></tr>
2891 <tr><td width="20%">DHE_DSS</td><td width="70%">A DSA public key that is marked for authentication.</td></tr>
2892 </table>
2893
2894 <div class="float-caption"><p><strong>Table 4.6: </strong>The types of (sub)keys required for the various TLS key exchange methods.</p></div></div>
2895 <p>The corresponding private keys are stored in the
2896 <code>gnutls_openpgp_privkey_t</code> type. All the prototypes for the key
2897 handling functions can be found in <samp>gnutls/openpgp.h</samp>.
2898 </p>
2899 <a name="Verifying-an-OpenPGP-certificate"></a>
2900 <h4 class="subsubsection">4.1.2.2 Verifying an <acronym>OpenPGP</acronym> certificate</h4>
2901
2902 <p>The verification functions of <acronym>OpenPGP</acronym> keys, included in
2903 <acronym>GnuTLS</acronym>, are simple ones, and do not use the features of the
2904 &ldquo;web of trust&rdquo;.  For that reason, if the verification needs are
2905 complex, the assistance of external tools like <acronym>GnuPG</acronym> and
2906 GPGME<a name="DOCF7" href="#FOOT7"><sup>7</sup></a> is
2907 recommended.
2908 </p>
2909 <p>In GnuTLS there is a verification function for OpenPGP certificates,
2910 the <a href="#gnutls_005fopenpgp_005fcrt_005fverify_005fring">gnutls_openpgp_crt_verify_ring</a>.  This checks an
2911 <acronym>OpenPGP</acronym> key against a given set of public keys (keyring) and
2912 returns the key status. The key verification status is the same as in
2913 <acronym>X.509</acronym> certificates, although the meaning and interpretation
2914 are different. For example an <acronym>OpenPGP</acronym> key may be valid, if
2915 the self signature is ok, even if no signers were found.  The meaning
2916 of verification status flags is the same as in the <acronym>X.509</acronym> certificates
2917 (see <a href="#gnutls_005fcertificate_005fverify_005fflags">Figure 4.3</a>).
2918 </p>
2919
2920
2921
2922
2923 <dl>
2924 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fverify_005fring"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_verify_ring</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, gnutls_openpgp_keyring_t <var>keyring</var>, unsigned int <var>flags</var>, unsigned int * <var>verify</var>)</em></dt>
2925 <dd><p><var>key</var>: the structure that holds the key.
2926 </p>
2927 <p><var>keyring</var>: holds the keyring to check against
2928 </p>
2929 <p><var>flags</var>: unused (should be 0)
2930 </p>
2931 <p><var>verify</var>: will hold the certificate verification output.
2932 </p>
2933 <p>Verify all signatures in the key, using the given set of keys
2934 (keyring).
2935 </p>
2936 <p>The key verification output will be put in  <code>verify</code> and will be one
2937 or more of the <code>gnutls_certificate_status_t</code>  enumerated elements
2938 bitwise or&rsquo;d.
2939 </p>
2940 <p>Note that this function does not verify using any &quot;web of trust&quot;.
2941 You may use GnuPG for that purpose, or any other external PGP
2942 application.
2943 </p>
2944 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
2945 </p></dd></dl>
2946
2947
2948
2949
2950
2951 <dl>
2952 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fverify_005fself"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_verify_self</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, unsigned int <var>flags</var>, unsigned int * <var>verify</var>)</em></dt>
2953 <dd><p><var>key</var>: the structure that holds the key.
2954 </p>
2955 <p><var>flags</var>: unused (should be 0)
2956 </p>
2957 <p><var>verify</var>: will hold the key verification output.
2958 </p>
2959 <p>Verifies the self signature in the key.  The key verification
2960 output will be put in  <code>verify</code> and will be one or more of the
2961 gnutls_certificate_status_t enumerated elements bitwise or&rsquo;d.
2962 </p>
2963 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
2964 </p></dd></dl>
2965
2966 <a name="Verifying-a-certificate-in-the-context-of-a-TLS-session"></a>
2967 <h4 class="subsubsection">4.1.2.3 Verifying a certificate in the context of a TLS session</h4>
2968
2969 <p>Similarly with X.509 certificates, one needs to specify
2970 the OpenPGP keyring file in the credentials structure. The certificates
2971 in this file will be  used by <a href="#gnutls_005fcertificate_005fverify_005fpeers3">gnutls_certificate_verify_peers3</a>
2972 to verify the signatures in the certificate sent by the peer.
2973 </p>
2974
2975
2976
2977
2978 <dl>
2979 <dt><a name="index-gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005ffile"></a>Function: <em>int</em> <strong>gnutls_certificate_set_openpgp_keyring_file</strong> <em>(gnutls_certificate_credentials_t <var>c</var>, const char * <var>file</var>, gnutls_openpgp_crt_fmt_t <var>format</var>)</em></dt>
2980 <dd><p><var>c</var>: A certificate credentials structure
2981 </p>
2982 <p><var>file</var>: filename of the keyring.
2983 </p>
2984 <p><var>format</var>: format of keyring.
2985 </p>
2986 <p>The function is used to set keyrings that will be used internally
2987 by various OpenPGP functions. For example to find a key when it
2988 is needed for an operations. The keyring will also be used at the
2989 verification functions.
2990 </p>
2991 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
2992 negative error value.
2993 </p></dd></dl>
2994
2995 <hr>
2996 <a name="Advanced-certificate-verification"></a>
2997 <div class="header">
2998 <p>
2999 Next: <a href="#Digital-signatures" accesskey="n" rel="next">Digital signatures</a>, Previous: <a href="#OpenPGP-certificates" accesskey="p" rel="prev">OpenPGP certificates</a>, Up: <a href="#Certificate-authentication" accesskey="u" rel="up">Certificate authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
3000 </div>
3001 <a name="Advanced-certificate-verification-1"></a>
3002 <h4 class="subsection">4.1.3 Advanced certificate verification</h4>
3003 <a name="index-Certificate-verification"></a>
3004
3005 <p>The verification of X.509 certificates in the HTTPS and other Internet protocols is typically
3006 done by loading a trusted list of commercial Certificate Authorities
3007 (see <a href="#gnutls_005fcertificate_005fset_005fx509_005fsystem_005ftrust">gnutls_certificate_set_x509_system_trust</a>), and using them as trusted anchors.
3008 However, there are several examples (eg. the Diginotar incident) where one of these
3009 authorities was compromised. This risk can be mitigated by using in addition to CA certificate verification,
3010 other verification methods. In this section we list the available in GnuTLS methods.
3011 </p>
3012 <table class="menu" border="0" cellspacing="0">
3013 <tr><td align="left" valign="top">&bull; <a href="#Verifying-a-certificate-using-trust-on-first-use-authentication" accesskey="1">Verifying a certificate using trust on first use authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3014 </td></tr>
3015 <tr><td align="left" valign="top">&bull; <a href="#Verifying-a-certificate-using-DANE" accesskey="2">Verifying a certificate using DANE</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3016 </td></tr>
3017 </table>
3018
3019 <hr>
3020 <a name="Verifying-a-certificate-using-trust-on-first-use-authentication"></a>
3021 <div class="header">
3022 <p>
3023 Next: <a href="#Verifying-a-certificate-using-DANE" accesskey="n" rel="next">Verifying a certificate using DANE</a>, Up: <a href="#Advanced-certificate-verification" accesskey="u" rel="up">Advanced certificate verification</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
3024 </div>
3025 <a name="Verifying-a-certificate-using-trust-on-first-use-authentication-1"></a>
3026 <h4 class="subsubsection">4.1.3.1 Verifying a certificate using trust on first use authentication</h4>
3027 <a name="index-verifying-certificate-paths-2"></a>
3028 <a name="index-SSH_002dstyle-authentication"></a>
3029 <a name="index-Trust-on-first-use"></a>
3030 <a name="index-Key-pinning"></a>
3031
3032 <p>It is possible to use a trust on first use (TOFU) authentication
3033 method in GnuTLS. That is the concept used by the SSH programs, where the
3034 public key of the peer is not verified, or verified in an out-of-bound way,
3035 but subsequent connections to the same peer require the public key to
3036 remain the same.  Such a system in combination with the typical CA
3037 verification of a certificate, and OCSP revocation checks,
3038 can help to provide multiple factor verification, where a single point of
3039 failure is not enough to compromise the system. For example a server compromise
3040 may be detected using OCSP, and a CA compromise can be detected using
3041 the trust on first use method.
3042 Such a hybrid system with X.509 and trust on first use authentication is
3043 shown in <a href="#Simple-client-example-with-SSH_002dstyle-certificate-verification">Simple client example with SSH-style certificate verification</a>.
3044 </p>
3045 <p>See <a href="#Certificate-verification">Certificate verification</a> on how to use the available functionality.
3046 </p>
3047 <hr>
3048 <a name="Verifying-a-certificate-using-DANE"></a>
3049 <div class="header">
3050 <p>
3051 Previous: <a href="#Verifying-a-certificate-using-trust-on-first-use-authentication" accesskey="p" rel="prev">Verifying a certificate using trust on first use authentication</a>, Up: <a href="#Advanced-certificate-verification" accesskey="u" rel="up">Advanced certificate verification</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
3052 </div>
3053 <a name="Verifying-a-certificate-using-DANE-_0028DNSSEC_0029"></a>
3054 <h4 class="subsubsection">4.1.3.2 Verifying a certificate using DANE (DNSSEC)</h4>
3055 <a name="index-verifying-certificate-paths-3"></a>
3056 <a name="index-DANE"></a>
3057 <a name="index-DNSSEC"></a>
3058
3059 <p>The DANE protocol is a protocol that can be used to verify TLS certificates
3060 using the DNS (or better DNSSEC) protocols. The DNS security extensions (DNSSEC)
3061 provide an alternative public key infrastructure to the commercial CAs that
3062 are typically used to sign TLS certificates. The DANE protocol takes advantage
3063 of the DNSSEC infrastructure to verify TLS certificates. This can be
3064 in addition to the verification by CA infrastructure or
3065 may even replace it where DNSSEC is fully deployed. Note however, that DNSSEC deployment is
3066 fairly new and it would be better to use it as an additional verification
3067 method rather than the only one.
3068 </p>
3069 <p>The DANE functionality is provided by the <code>libgnutls-dane</code> library that is shipped
3070 with GnuTLS and the function prototypes are in <code>gnutls/dane.h</code>.
3071 See <a href="#Certificate-verification">Certificate verification</a> for information on how to use the library.
3072 </p>
3073 <p>Note however, that the DANE RFC mandates the verification methods
3074 one should use in addition to the validation via DNSSEC TLSA entries.
3075 GnuTLS doesn&rsquo;t follow that RFC requirement, and the term DANE verification
3076 in this manual refers to the TLSA entry verification. In GnuTLS any
3077 other verification methods can be used (e.g., PKIX or TOFU) on top of
3078 DANE.
3079 </p>
3080 <hr>
3081 <a name="Digital-signatures"></a>
3082 <div class="header">
3083 <p>
3084 Previous: <a href="#Advanced-certificate-verification" accesskey="p" rel="prev">Advanced certificate verification</a>, Up: <a href="#Certificate-authentication" accesskey="u" rel="up">Certificate authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
3085 </div>
3086 <a name="Digital-signatures-1"></a>
3087 <h4 class="subsection">4.1.4 Digital signatures</h4>
3088 <a name="index-digital-signatures"></a>
3089
3090 <p>In this section we will provide some information about digital
3091 signatures, how they work, and give the rationale for disabling some
3092 of the algorithms used.
3093 </p>
3094 <p>Digital signatures work by using somebody&rsquo;s secret key to sign some
3095 arbitrary data.  Then anybody else could use the public key of that
3096 person to verify the signature.  Since the data may be arbitrary it is
3097 not suitable input to a cryptographic digital signature algorithm. For
3098 this reason and also for performance cryptographic hash algorithms are
3099 used to preprocess the input to the signature algorithm. This works as
3100 long as it is difficult enough to generate two different messages with
3101 the same hash algorithm output. In that case the same signature could
3102 be used as a proof for both messages. Nobody wants to sign an innocent
3103 message of donating 1 euro to Greenpeace and find out that they
3104 donated 1.000.000 euros to Bad Inc.
3105 </p>
3106 <p>For a hash algorithm to be called cryptographic the following three
3107 requirements must hold:
3108 </p>
3109 <ol>
3110 <li> Preimage resistance.
3111 That means the algorithm must be one way and given the output of the
3112 hash function <em>H(x)</em>, it is impossible to calculate <em>x</em>.
3113
3114 </li><li> 2nd preimage resistance.
3115 That means that given a pair <em>x,y</em> with <em>y=H(x)</em> it is
3116 impossible to calculate an <em>x'</em> such that <em>y=H(x')</em>.
3117
3118 </li><li> Collision resistance.
3119 That means that it is impossible to calculate random <em>x</em> and
3120 <em>x'</em> such <em>H(x')=H(x)</em>.
3121 </li></ol>
3122
3123 <p>The last two requirements in the list are the most important in
3124 digital signatures. These protect against somebody who would like to
3125 generate two messages with the same hash output. When an algorithm is
3126 considered broken usually it means that the Collision resistance of
3127 the algorithm is less than brute force. Using the birthday paradox the
3128 brute force attack takes
3129 <em>2^{((hash size) / 2)}</em>
3130 operations. Today colliding certificates using the MD5 hash algorithm
3131 have been generated as shown in [<em>WEGER</em>].
3132 </p>
3133 <p>There has been cryptographic results for the SHA-1 hash algorithms as
3134 well, although they are not yet critical.  Before 2004, MD5 had a
3135 presumed collision strength of <em>2^{64}</em>, but it has been showed
3136 to have a collision strength well under <em>2^{50}</em>.  As of November
3137 2005, it is believed that SHA-1&rsquo;s collision strength is around
3138 <em>2^{63}</em>.  We consider this sufficiently hard so that we still
3139 support SHA-1.  We anticipate that SHA-256/386/512 will be used in
3140 publicly-distributed certificates in the future.  When <em>2^{63}</em>
3141 can be considered too weak compared to the computer power available
3142 sometime in the future, SHA-1 will be disabled as well.  The collision
3143 attacks on SHA-1 may also get better, given the new interest in tools
3144 for creating them.
3145 </p>
3146 <a name="Trading-security-for-interoperability"></a>
3147 <h4 class="subsubsection">4.1.4.1 Trading security for interoperability</h4>
3148
3149 <p>If you connect to a server and use GnuTLS&rsquo; functions to verify the
3150 certificate chain, and get a <code>GNUTLS_CERT_INSECURE_ALGORITHM</code>
3151 validation error (see <a href="#Verifying-X_002e509-certificate-paths">Verifying X.509 certificate paths</a>), it means
3152 that somewhere in the certificate chain there is a certificate signed
3153 using <code>RSA-MD2</code> or <code>RSA-MD5</code>.  These two digital signature
3154 algorithms are considered broken, so GnuTLS fails verifying
3155 the certificate.  In some situations, it may be useful to be
3156 able to verify the certificate chain anyway, assuming an attacker did
3157 not utilize the fact that these signatures algorithms are broken.
3158 This section will give help on how to achieve that.
3159 </p>
3160 <p>It is important to know that you do not have to enable any of
3161 the flags discussed here to be able to use trusted root CA
3162 certificates self-signed using <code>RSA-MD2</code> or <code>RSA-MD5</code>. The
3163 certificates in the trusted list are considered trusted irrespective
3164 of the signature.
3165 </p>
3166 <p>If you are using <a href="#gnutls_005fcertificate_005fverify_005fpeers3">gnutls_certificate_verify_peers3</a> to verify the
3167 certificate chain, you can call
3168 <a href="#gnutls_005fcertificate_005fset_005fverify_005fflags">gnutls_certificate_set_verify_flags</a> with the flags:
3169 </p><ul>
3170 <li> <code>GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2</code>
3171 </li><li> <code>GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5</code>
3172 </li></ul>
3173 <p>as in the following example:
3174 </p>
3175 <div class="example">
3176 <pre class="example">  gnutls_certificate_set_verify_flags (x509cred,
3177                                        GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5);
3178 </pre></div>
3179
3180 <p>This will signal the verifier algorithm to enable <code>RSA-MD5</code> when
3181 verifying the certificates.
3182 </p>
3183 <p>If you are using <a href="#gnutls_005fx509_005fcrt_005fverify">gnutls_x509_crt_verify</a> or
3184 <a href="#gnutls_005fx509_005fcrt_005flist_005fverify">gnutls_x509_crt_list_verify</a>, you can pass the
3185 <code>GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5</code> parameter directly in the
3186 <code>flags</code> parameter.
3187 </p>
3188 <p>If you are using these flags, it may also be a good idea to warn the
3189 user when verification failure occur for this reason.  The simplest is
3190 to not use the flags by default, and only fall back to using them
3191 after warning the user.  If you wish to inspect the certificate chain
3192 yourself, you can use <a href="#gnutls_005fcertificate_005fget_005fpeers">gnutls_certificate_get_peers</a> to extract
3193 the raw server&rsquo;s certificate chain, <a href="#gnutls_005fx509_005fcrt_005flist_005fimport">gnutls_x509_crt_list_import</a> to parse each of the certificates, and
3194 then <a href="#gnutls_005fx509_005fcrt_005fget_005fsignature_005falgorithm">gnutls_x509_crt_get_signature_algorithm</a> to find out the
3195 signing algorithm used for each certificate.  If any of the
3196 intermediary certificates are using <code>GNUTLS_SIGN_RSA_MD2</code> or
3197 <code>GNUTLS_SIGN_RSA_MD5</code>, you could present a warning.
3198 </p>
3199 <hr>
3200 <a name="More-on-certificate-authentication"></a>
3201 <div class="header">
3202 <p>
3203 Next: <a href="#Shared_002dkey-and-anonymous-authentication" accesskey="n" rel="next">Shared-key and anonymous authentication</a>, Previous: <a href="#Certificate-authentication" accesskey="p" rel="prev">Certificate authentication</a>, Up: <a href="#Authentication-methods" accesskey="u" rel="up">Authentication methods</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
3204 </div>
3205 <a name="More-on-certificate-authentication-1"></a>
3206 <h3 class="section">4.2 More on certificate authentication</h3>
3207 <a name="index-certificate-authentication-1"></a>
3208
3209 <p>Certificates are not the only structures involved in a public key
3210 infrastructure. Several other structures that are used for certificate
3211 requests, encrypted private keys, revocation lists, GnuTLS abstract key
3212 structures, etc., are discussed in this chapter.
3213 </p>
3214 <table class="menu" border="0" cellspacing="0">
3215 <tr><td align="left" valign="top">&bull; <a href="#PKCS-10-certificate-requests" accesskey="1">PKCS 10 certificate requests</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3216 </td></tr>
3217 <tr><td align="left" valign="top">&bull; <a href="#PKIX-certificate-revocation-lists" accesskey="2">PKIX certificate revocation lists</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3218 </td></tr>
3219 <tr><td align="left" valign="top">&bull; <a href="#OCSP-certificate-status-checking" accesskey="3">OCSP certificate status checking</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3220 </td></tr>
3221 <tr><td align="left" valign="top">&bull; <a href="#Managing-encrypted-keys" accesskey="4">Managing encrypted keys</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3222 </td></tr>
3223 <tr><td align="left" valign="top">&bull; <a href="#certtool-Invocation" accesskey="5">certtool Invocation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Invoking certtool
3224 </td></tr>
3225 <tr><td align="left" valign="top">&bull; <a href="#ocsptool-Invocation" accesskey="6">ocsptool Invocation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Invoking ocsptool
3226 </td></tr>
3227 <tr><td align="left" valign="top">&bull; <a href="#danetool-Invocation" accesskey="7">danetool Invocation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Invoking danetool
3228 </td></tr>
3229 </table>
3230
3231 <hr>
3232 <a name="PKCS-10-certificate-requests"></a>
3233 <div class="header">
3234 <p>
3235 Next: <a href="#PKIX-certificate-revocation-lists" accesskey="n" rel="next">PKIX certificate revocation lists</a>, Up: <a href="#More-on-certificate-authentication" accesskey="u" rel="up">More on certificate authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
3236 </div>
3237 <a name="PKCS-_002310-certificate-requests"></a>
3238 <h4 class="subsection">4.2.1 <acronym>PKCS</acronym> #10 certificate requests</h4>
3239 <a name="index-certificate-requests"></a>
3240 <a name="index-PKCS-_002310"></a>
3241
3242 <p>A certificate request is a structure, which contain information about
3243 an applicant of a certificate service.  It usually contains a private
3244 key, a distinguished name and secondary data such as a challenge
3245 password. <acronym>GnuTLS</acronym> supports the requests defined in
3246 <acronym>PKCS</acronym> #10 [<em>RFC2986</em>]. Other formats of certificate requests
3247 are not currently supported.
3248 </p>
3249 <p>A certificate request can be generated by
3250 associating it with a private key, setting the
3251 subject&rsquo;s information and finally self signing it.
3252 The last step ensures that the requester is in
3253 possession of the private key.
3254 </p>
3255 <dl compact="compact">
3256 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrq_005fset_005fversion">gnutls_x509_crq_set_version</a> (gnutls_x509_crq_t <var>crq</var>, unsigned int <var>version</var>)</code></dt>
3257 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrq_005fset_005fdn">gnutls_x509_crq_set_dn</a> (gnutls_x509_crq_t <var>crq</var>, const char * <var>dn</var>, const char ** <var>err</var>)</code></dt>
3258 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrq_005fset_005fdn_005fby_005foid">gnutls_x509_crq_set_dn_by_oid</a> (gnutls_x509_crq_t <var>crq</var>, const char * <var>oid</var>, unsigned int <var>raw_flag</var>, const void * <var>data</var>, unsigned int <var>sizeof_data</var>)</code></dt>
3259 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrq_005fset_005fkey_005fusage">gnutls_x509_crq_set_key_usage</a> (gnutls_x509_crq_t <var>crq</var>, unsigned int <var>usage</var>)</code></dt>
3260 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrq_005fset_005fkey_005fpurpose_005foid">gnutls_x509_crq_set_key_purpose_oid</a> (gnutls_x509_crq_t <var>crq</var>, const void * <var>oid</var>, unsigned int <var>critical</var>)</code></dt>
3261 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrq_005fset_005fbasic_005fconstraints">gnutls_x509_crq_set_basic_constraints</a> (gnutls_x509_crq_t <var>crq</var>, unsigned int <var>ca</var>, int <var>pathLenConstraint</var>)</code></dt>
3262 </dl>
3263
3264 <p>The <a href="#gnutls_005fx509_005fcrq_005fset_005fkey">gnutls_x509_crq_set_key</a> and <a href="#gnutls_005fx509_005fcrq_005fsign2">gnutls_x509_crq_sign2</a>
3265 functions associate the request with a private key and sign it. If a
3266 request is to be signed with a key residing in a PKCS #11 token it is recommended to use
3267 the signing functions shown in <a href="#Abstract-key-types">Abstract key types</a>.
3268 </p>
3269
3270
3271
3272
3273 <dl>
3274 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fkey"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_key</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_x509_privkey_t <var>key</var>)</em></dt>
3275 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
3276 </p>
3277 <p><var>key</var>: holds a private key
3278 </p>
3279 <p>This function will set the public parameters from the given private
3280 key to the request.
3281 </p>
3282 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
3283 negative error value.
3284 </p></dd></dl>
3285
3286
3287
3288
3289 <dl>
3290 <dt><a name="index-gnutls_005fx509_005fcrq_005fsign2"></a>Function: <em>int</em> <strong>gnutls_x509_crq_sign2</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_x509_privkey_t <var>key</var>, gnutls_digest_algorithm_t <var>dig</var>, unsigned int <var>flags</var>)</em></dt>
3291 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
3292 </p>
3293 <p><var>key</var>: holds a private key
3294 </p>
3295 <p><var>dig</var>: The message digest to use, i.e., <code>GNUTLS_DIG_SHA1</code>
3296 </p>
3297 <p><var>flags</var>: must be 0
3298 </p>
3299 <p>This function will sign the certificate request with a private key.
3300 This must be the same key as the one used in
3301 <code>gnutls_x509_crt_set_key()</code>  since a certificate request is self
3302 signed.
3303 </p>
3304 <p>This must be the last step in a certificate request generation
3305 since all the previously set parameters are now signed.
3306 </p>
3307 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
3308 <code>GNUTLS_E_ASN1_VALUE_NOT_FOUND</code>  is returned if you didn&rsquo;t set all
3309 information in the certificate request (e.g., the version using
3310 <code>gnutls_x509_crq_set_version()</code> ).
3311 </p></dd></dl>
3312
3313 <p>The following example is about generating a certificate request, and a
3314 private key. A certificate request can be later be processed by a CA
3315 which should return a signed certificate.
3316 </p>
3317 <a name="ex_002dcrq"></a><pre class="verbatim">/* This example code is placed in the public domain. */
3318
3319 #ifdef HAVE_CONFIG_H
3320 #include &lt;config.h&gt;
3321 #endif
3322
3323 #include &lt;stdio.h&gt;
3324 #include &lt;stdlib.h&gt;
3325 #include &lt;string.h&gt;
3326 #include &lt;gnutls/gnutls.h&gt;
3327 #include &lt;gnutls/x509.h&gt;
3328 #include &lt;gnutls/abstract.h&gt;
3329 #include &lt;time.h&gt;
3330
3331 /* This example will generate a private key and a certificate
3332  * request.
3333  */
3334
3335 int main(void)
3336 {
3337         gnutls_x509_crq_t crq;
3338         gnutls_x509_privkey_t key;
3339         unsigned char buffer[10 * 1024];
3340         size_t buffer_size = sizeof(buffer);
3341         unsigned int bits;
3342
3343         gnutls_global_init();
3344
3345         /* Initialize an empty certificate request, and
3346          * an empty private key.
3347          */
3348         gnutls_x509_crq_init(&amp;crq);
3349
3350         gnutls_x509_privkey_init(&amp;key);
3351
3352         /* Generate an RSA key of moderate security.
3353          */
3354         bits =
3355             gnutls_sec_param_to_pk_bits(GNUTLS_PK_RSA,
3356                                         GNUTLS_SEC_PARAM_MEDIUM);
3357         gnutls_x509_privkey_generate(key, GNUTLS_PK_RSA, bits, 0);
3358
3359         /* Add stuff to the distinguished name
3360          */
3361         gnutls_x509_crq_set_dn_by_oid(crq, GNUTLS_OID_X520_COUNTRY_NAME,
3362                                       0, &quot;GR&quot;, 2);
3363
3364         gnutls_x509_crq_set_dn_by_oid(crq, GNUTLS_OID_X520_COMMON_NAME,
3365                                       0, &quot;Nikos&quot;, strlen(&quot;Nikos&quot;));
3366
3367         /* Set the request version.
3368          */
3369         gnutls_x509_crq_set_version(crq, 1);
3370
3371         /* Set a challenge password.
3372          */
3373         gnutls_x509_crq_set_challenge_password(crq,
3374                                                &quot;something to remember here&quot;);
3375
3376         /* Associate the request with the private key
3377          */
3378         gnutls_x509_crq_set_key(crq, key);
3379
3380         /* Self sign the certificate request.
3381          */
3382         gnutls_x509_crq_sign2(crq, key, GNUTLS_DIG_SHA1, 0);
3383
3384         /* Export the PEM encoded certificate request, and
3385          * display it.
3386          */
3387         gnutls_x509_crq_export(crq, GNUTLS_X509_FMT_PEM, buffer,
3388                                &amp;buffer_size);
3389
3390         printf(&quot;Certificate Request: \n%s&quot;, buffer);
3391
3392
3393         /* Export the PEM encoded private key, and
3394          * display it.
3395          */
3396         buffer_size = sizeof(buffer);
3397         gnutls_x509_privkey_export(key, GNUTLS_X509_FMT_PEM, buffer,
3398                                    &amp;buffer_size);
3399
3400         printf(&quot;\n\nPrivate key: \n%s&quot;, buffer);
3401
3402         gnutls_x509_crq_deinit(crq);
3403         gnutls_x509_privkey_deinit(key);
3404
3405         return 0;
3406
3407 }
3408 </pre>
3409 <hr>
3410 <a name="PKIX-certificate-revocation-lists"></a>
3411 <div class="header">
3412 <p>
3413 Next: <a href="#OCSP-certificate-status-checking" accesskey="n" rel="next">OCSP certificate status checking</a>, Previous: <a href="#PKCS-10-certificate-requests" accesskey="p" rel="prev">PKCS 10 certificate requests</a>, Up: <a href="#More-on-certificate-authentication" accesskey="u" rel="up">More on certificate authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
3414 </div>
3415 <a name="PKIX-certificate-revocation-lists-1"></a>
3416 <h4 class="subsection">4.2.2 PKIX certificate revocation lists</h4>
3417 <a name="index-certificate-revocation-lists"></a>
3418 <a name="index-CRL"></a>
3419
3420 <p>A certificate revocation list (CRL) is a structure issued by an authority
3421 periodically containing a list of revoked certificates serial numbers.
3422 The CRL structure is signed with the issuing authorities&rsquo; keys. A typical
3423 CRL contains the fields as shown in <a href="#tab_003acrl">Table 4.7</a>.
3424 Certificate revocation lists are used to complement the expiration date of a certificate,
3425 in order to account for other reasons of revocation, such as compromised keys, etc.
3426 </p>
3427 <p>Each CRL is valid for limited amount of
3428 time and is required to provide, except for the current issuing time, also
3429 the issuing time of the next update.
3430 </p>
3431 <div class="float"><a name="tab_003acrl"></a>
3432 <table>
3433 <thead><tr><th width="20%">Field</th><th width="70%">Description</th></tr></thead>
3434 <tr><td width="20%">version</td><td width="70%">The field that indicates the version of the CRL structure.</td></tr>
3435 <tr><td width="20%">signature</td><td width="70%">A signature by the issuing authority.</td></tr>
3436 <tr><td width="20%">issuer</td><td width="70%">Holds the issuer&rsquo;s distinguished name.</td></tr>
3437 <tr><td width="20%">thisUpdate</td><td width="70%">The issuing time of the revocation list.</td></tr>
3438 <tr><td width="20%">nextUpdate</td><td width="70%">The issuing time of the revocation list that will update that one.</td></tr>
3439 <tr><td width="20%">revokedCertificates</td><td width="70%">List of revoked certificates serial numbers.</td></tr>
3440 <tr><td width="20%">extensions</td><td width="70%">Optional CRL structure extensions.</td></tr>
3441 </table>
3442
3443 <div class="float-caption"><p><strong>Table 4.7: </strong>Certificate revocation list fields.</p></div></div>
3444 <p>The basic CRL structure functions follow.
3445 </p>
3446 <dl compact="compact">
3447 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005finit">gnutls_x509_crl_init</a> (gnutls_x509_crl_t * <var>crl</var>)</code></dt>
3448 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fimport">gnutls_x509_crl_import</a> (gnutls_x509_crl_t <var>crl</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>)</code></dt>
3449 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fexport">gnutls_x509_crl_export</a> (gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crt_fmt_t <var>format</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</code></dt>
3450 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fexport">gnutls_x509_crl_export</a> (gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crt_fmt_t <var>format</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</code></dt>
3451 </dl>
3452
3453 <a name="Reading-a-CRL"></a>
3454 <h4 class="subsubheading">Reading a CRL</h4>
3455
3456 <p>The most important function that extracts the certificate revocation
3457 information from a CRL is <a href="#gnutls_005fx509_005fcrl_005fget_005fcrt_005fserial">gnutls_x509_crl_get_crt_serial</a>. Other
3458 functions that return other fields of the CRL structure are also provided.
3459 </p>
3460
3461
3462
3463
3464 <dl>
3465 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fcrt_005fserial"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_crt_serial</strong> <em>(gnutls_x509_crl_t <var>crl</var>, int <var>indx</var>, unsigned char * <var>serial</var>, size_t * <var>serial_size</var>, time_t * <var>t</var>)</em></dt>
3466 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
3467 </p>
3468 <p><var>indx</var>: the index of the certificate to extract (starting from 0)
3469 </p>
3470 <p><var>serial</var>: where the serial number will be copied
3471 </p>
3472 <p><var>serial_size</var>: initially holds the size of serial
3473 </p>
3474 <p><var>t</var>: if non null, will hold the time this certificate was revoked
3475 </p>
3476 <p>This function will retrieve the serial number of the specified, by
3477 the index, revoked certificate.
3478 </p>
3479 <p>Note that this function will have performance issues in large sequences
3480 of revoked certificates. In that case use <code>gnutls_x509_crl_iter_crt_serial()</code> .
3481 </p>
3482 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
3483 negative error value.
3484 </p></dd></dl>
3485
3486 <dl compact="compact">
3487 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fget_005fversion">gnutls_x509_crl_get_version</a> (gnutls_x509_crl_t <var>crl</var>)</code></dt>
3488 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn">gnutls_x509_crl_get_issuer_dn</a> (const gnutls_x509_crl_t <var>crl</var>, char * <var>buf</var>, size_t * <var>sizeof_buf</var>)</code></dt>
3489 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn2">gnutls_x509_crl_get_issuer_dn2</a> (gnutls_x509_crl_t <var>crl</var>, gnutls_datum_t * <var>dn</var>)</code></dt>
3490 <dt><code><var>time_t</var> <a href="#gnutls_005fx509_005fcrl_005fget_005fthis_005fupdate">gnutls_x509_crl_get_this_update</a> (gnutls_x509_crl_t <var>crl</var>)</code></dt>
3491 <dt><code><var>time_t</var> <a href="#gnutls_005fx509_005fcrl_005fget_005fnext_005fupdate">gnutls_x509_crl_get_next_update</a> (gnutls_x509_crl_t <var>crl</var>)</code></dt>
3492 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fget_005fcrt_005fcount">gnutls_x509_crl_get_crt_count</a> (gnutls_x509_crl_t <var>crl</var>)</code></dt>
3493 </dl>
3494
3495 <a name="Generation-of-a-CRL"></a>
3496 <h4 class="subsubheading">Generation of a CRL</h4>
3497
3498 <p>The following functions can be used to generate a CRL.
3499 </p>
3500 <dl compact="compact">
3501 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fset_005fversion">gnutls_x509_crl_set_version</a> (gnutls_x509_crl_t <var>crl</var>, unsigned int <var>version</var>)</code></dt>
3502 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fset_005fcrt_005fserial">gnutls_x509_crl_set_crt_serial</a> (gnutls_x509_crl_t <var>crl</var>, const void * <var>serial</var>, size_t <var>serial_size</var>, time_t <var>revocation_time</var>)</code></dt>
3503 </dl>
3504 <dl compact="compact">
3505 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fset_005fcrt">gnutls_x509_crl_set_crt</a> (gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crt_t <var>crt</var>, time_t <var>revocation_time</var>)</code></dt>
3506 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fset_005fnext_005fupdate">gnutls_x509_crl_set_next_update</a> (gnutls_x509_crl_t <var>crl</var>, time_t <var>exp_time</var>)</code></dt>
3507 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fset_005fthis_005fupdate">gnutls_x509_crl_set_this_update</a> (gnutls_x509_crl_t <var>crl</var>, time_t <var>act_time</var>)</code></dt>
3508 </dl>
3509
3510 <p>The <a href="#gnutls_005fx509_005fcrl_005fsign2">gnutls_x509_crl_sign2</a> and <a href="#gnutls_005fx509_005fcrl_005fprivkey_005fsign">gnutls_x509_crl_privkey_sign</a>
3511 functions sign the revocation list with a private key. The latter function
3512 can be used to sign with a key residing in a PKCS #11 token.
3513 </p>
3514
3515
3516
3517
3518 <dl>
3519 <dt><a name="index-gnutls_005fx509_005fcrl_005fsign2"></a>Function: <em>int</em> <strong>gnutls_x509_crl_sign2</strong> <em>(gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crt_t <var>issuer</var>, gnutls_x509_privkey_t <var>issuer_key</var>, gnutls_digest_algorithm_t <var>dig</var>, unsigned int <var>flags</var>)</em></dt>
3520 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
3521 </p>
3522 <p><var>issuer</var>: is the certificate of the certificate issuer
3523 </p>
3524 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
3525 </p>
3526 <p><var>dig</var>: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you&rsquo;re doing.
3527 </p>
3528 <p><var>flags</var>: must be 0
3529 </p>
3530 <p>This function will sign the CRL with the issuer&rsquo;s private key, and
3531 will copy the issuer&rsquo;s information into the CRL.
3532 </p>
3533 <p>This must be the last step in a certificate CRL since all
3534 the previously set parameters are now signed.
3535 </p>
3536 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
3537 negative error value.
3538 </p></dd></dl>
3539
3540
3541
3542
3543 <dl>
3544 <dt><a name="index-gnutls_005fx509_005fcrl_005fprivkey_005fsign"></a>Function: <em>int</em> <strong>gnutls_x509_crl_privkey_sign</strong> <em>(gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crt_t <var>issuer</var>, gnutls_privkey_t <var>issuer_key</var>, gnutls_digest_algorithm_t <var>dig</var>, unsigned int <var>flags</var>)</em></dt>
3545 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
3546 </p>
3547 <p><var>issuer</var>: is the certificate of the certificate issuer
3548 </p>
3549 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
3550 </p>
3551 <p><var>dig</var>: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you&rsquo;re doing.
3552 </p>
3553 <p><var>flags</var>: must be 0
3554 </p>
3555 <p>This function will sign the CRL with the issuer&rsquo;s private key, and
3556 will copy the issuer&rsquo;s information into the CRL.
3557 </p>
3558 <p>This must be the last step in a certificate CRL since all
3559 the previously set parameters are now signed.
3560 </p>
3561 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
3562 negative error value.
3563 </p>
3564 <p>Since 2.12.0
3565 </p></dd></dl>
3566
3567 <p>Few extensions on the CRL structure are supported, including the
3568 CRL number extension and the authority key identifier.
3569 </p>
3570 <dl compact="compact">
3571 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fset_005fnumber">gnutls_x509_crl_set_number</a> (gnutls_x509_crl_t <var>crl</var>, const void * <var>nr</var>, size_t <var>nr_size</var>)</code></dt>
3572 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fset_005fauthority_005fkey_005fid">gnutls_x509_crl_set_authority_key_id</a> (gnutls_x509_crl_t <var>crl</var>, const void * <var>id</var>, size_t <var>id_size</var>)</code></dt>
3573 </dl>
3574
3575 <hr>
3576 <a name="OCSP-certificate-status-checking"></a>
3577 <div class="header">
3578 <p>
3579 Next: <a href="#Managing-encrypted-keys" accesskey="n" rel="next">Managing encrypted keys</a>, Previous: <a href="#PKIX-certificate-revocation-lists" accesskey="p" rel="prev">PKIX certificate revocation lists</a>, Up: <a href="#More-on-certificate-authentication" accesskey="u" rel="up">More on certificate authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
3580 </div>
3581 <a name="OCSP-certificate-status-checking-1"></a>
3582 <h4 class="subsection">4.2.3 <acronym>OCSP</acronym> certificate status checking</h4>
3583 <a name="index-certificate-status"></a>
3584 <a name="index-Online-Certificate-Status-Protocol"></a>
3585 <a name="index-OCSP"></a>
3586
3587 <p>Certificates may be revoked before their expiration time has been
3588 reached.  There are several reasons for revoking certificates, but a
3589 typical situation is when the private key associated with a
3590 certificate has been compromised.  Traditionally, Certificate
3591 Revocation Lists (CRLs) have been used by application to implement
3592 revocation checking, however, several problems with CRLs have been
3593 identified [<em>RIVESTCRL</em>].
3594 </p>
3595 <p>The Online Certificate Status Protocol, or <acronym>OCSP</acronym> [<em>RFC2560</em>],
3596 is a widely implemented protocol which performs certificate revocation status
3597 checking.  An application that wish to verify the
3598 identity of a peer will verify the certificate against a set of
3599 trusted certificates and then check whether the certificate is listed
3600 in a CRL and/or perform an OCSP check for the certificate.
3601 </p>
3602 <p>Note that in the context of a TLS session the server may provide an
3603 OCSP response that will be used during the TLS certificate verification
3604 (see <a href="#gnutls_005fcertificate_005fverify_005fpeers2">gnutls_certificate_verify_peers2</a>).
3605 You may obtain this response using <a href="#gnutls_005focsp_005fstatus_005frequest_005fget">gnutls_ocsp_status_request_get</a>.
3606 </p>
3607 <p>Before performing the OCSP query, the application will need to figure
3608 out the address of the OCSP server.  The OCSP server address can be
3609 provided by the local user in manual configuration or may be stored
3610 in the certificate that is being checked.  When stored in a certificate
3611 the OCSP server is in the extension field called the Authority Information
3612 Access (AIA). The following function
3613 extracts this information from a certificate.
3614 </p>
3615 <dl compact="compact">
3616 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fget_005fauthority_005finfo_005faccess">gnutls_x509_crt_get_authority_info_access</a> (gnutls_x509_crt_t <var>crt</var>, unsigned int <var>seq</var>, int <var>what</var>, gnutls_datum_t * <var>data</var>, unsigned int * <var>critical</var>)</code></dt>
3617 </dl>
3618
3619 <p>There are several functions in GnuTLS for creating and manipulating
3620 OCSP requests and responses.  The general idea is that a client
3621 application creates an OCSP request object, stores some information
3622 about the certificate to check in the request, and then exports the
3623 request in DER format.  The request will then need to be sent to the
3624 OCSP responder, which needs to be done by the application (GnuTLS does
3625 not send and receive OCSP packets).  Normally an OCSP response is
3626 received that the application will need to import into an OCSP
3627 response object.  The digital signature in the OCSP response needs to
3628 be verified against a set of trust anchors before the information in
3629 the response can be trusted.
3630 </p>
3631 <p>The ASN.1 structure of OCSP requests are briefly as follows.  It is
3632 useful to review the structures to get an understanding of which
3633 fields are modified by GnuTLS functions.
3634 </p>
3635 <div class="example">
3636 <pre class="example">OCSPRequest     ::=     SEQUENCE {
3637     tbsRequest                  TBSRequest,
3638     optionalSignature   [0]     EXPLICIT Signature OPTIONAL }
3639
3640 TBSRequest      ::=     SEQUENCE {
3641     version             [0]     EXPLICIT Version DEFAULT v1,
3642     requestorName       [1]     EXPLICIT GeneralName OPTIONAL,
3643     requestList                 SEQUENCE OF Request,
3644     requestExtensions   [2]     EXPLICIT Extensions OPTIONAL }
3645
3646 Request         ::=     SEQUENCE {
3647     reqCert                     CertID,
3648     singleRequestExtensions     [0] EXPLICIT Extensions OPTIONAL }
3649
3650 CertID          ::=     SEQUENCE {
3651     hashAlgorithm       AlgorithmIdentifier,
3652     issuerNameHash      OCTET STRING, -- Hash of Issuer's DN
3653     issuerKeyHash       OCTET STRING, -- Hash of Issuers public key
3654     serialNumber        CertificateSerialNumber }
3655 </pre></div>
3656
3657 <p>The basic functions to initialize, import, export and deallocate OCSP
3658 requests are the following.
3659 </p>
3660 <dl compact="compact">
3661 <dt><code><var>int</var> <a href="#gnutls_005focsp_005freq_005finit">gnutls_ocsp_req_init</a> (gnutls_ocsp_req_t * <var>req</var>)</code></dt>
3662 <dt><code><var>void</var> <a href="#gnutls_005focsp_005freq_005fdeinit">gnutls_ocsp_req_deinit</a> (gnutls_ocsp_req_t <var>req</var>)</code></dt>
3663 <dt><code><var>int</var> <a href="#gnutls_005focsp_005freq_005fimport">gnutls_ocsp_req_import</a> (gnutls_ocsp_req_t <var>req</var>, const gnutls_datum_t * <var>data</var>)</code></dt>
3664 <dt><code><var>int</var> <a href="#gnutls_005focsp_005freq_005fexport">gnutls_ocsp_req_export</a> (gnutls_ocsp_req_t <var>req</var>, gnutls_datum_t * <var>data</var>)</code></dt>
3665 <dt><code><var>int</var> <a href="#gnutls_005focsp_005freq_005fprint">gnutls_ocsp_req_print</a> (gnutls_ocsp_req_t <var>req</var>, gnutls_ocsp_print_formats_t <var>format</var>, gnutls_datum_t * <var>out</var>)</code></dt>
3666 </dl>
3667
3668 <p>To generate an OCSP request the issuer name hash, issuer key hash, and
3669 the checked certificate&rsquo;s serial number are required. There are two
3670 interfaces available for setting those in an OCSP request.
3671 The is a low-level function when you have the
3672 issuer name hash, issuer key hash, and certificate serial number in
3673 binary form.  The second is more useful if you have the
3674 certificate (and its issuer) in a <code>gnutls_x509_crt_t</code> type.
3675 There is also a function to extract this information from existing an OCSP
3676 request.
3677 </p>
3678 <dl compact="compact">
3679 <dt><code><var>int</var> <a href="#gnutls_005focsp_005freq_005fadd_005fcert_005fid">gnutls_ocsp_req_add_cert_id</a> (gnutls_ocsp_req_t <var>req</var>, gnutls_digest_algorithm_t <var>digest</var>, const gnutls_datum_t * <var>issuer_name_hash</var>, const gnutls_datum_t * <var>issuer_key_hash</var>, const gnutls_datum_t * <var>serial_number</var>)</code></dt>
3680 <dt><code><var>int</var> <a href="#gnutls_005focsp_005freq_005fadd_005fcert">gnutls_ocsp_req_add_cert</a> (gnutls_ocsp_req_t <var>req</var>, gnutls_digest_algorithm_t <var>digest</var>, gnutls_x509_crt_t <var>issuer</var>, gnutls_x509_crt_t <var>cert</var>)</code></dt>
3681 <dt><code><var>int</var> <a href="#gnutls_005focsp_005freq_005fget_005fcert_005fid">gnutls_ocsp_req_get_cert_id</a> (gnutls_ocsp_req_t <var>req</var>, unsigned <var>indx</var>, gnutls_digest_algorithm_t * <var>digest</var>, gnutls_datum_t * <var>issuer_name_hash</var>, gnutls_datum_t * <var>issuer_key_hash</var>, gnutls_datum_t * <var>serial_number</var>)</code></dt>
3682 </dl>
3683
3684 <p>Each OCSP request may contain a number of extensions.  Extensions are
3685 identified by an Object Identifier (OID) and an opaque data buffer
3686 whose syntax and semantics is implied by the OID. You can extract or
3687 set those extensions using the following functions.
3688 </p>
3689 <dl compact="compact">
3690 <dt><code><var>int</var> <a href="#gnutls_005focsp_005freq_005fget_005fextension">gnutls_ocsp_req_get_extension</a> (gnutls_ocsp_req_t <var>req</var>, unsigned <var>indx</var>, gnutls_datum_t * <var>oid</var>, unsigned int * <var>critical</var>, gnutls_datum_t * <var>data</var>)</code></dt>
3691 <dt><code><var>int</var> <a href="#gnutls_005focsp_005freq_005fset_005fextension">gnutls_ocsp_req_set_extension</a> (gnutls_ocsp_req_t <var>req</var>, const char * <var>oid</var>, unsigned int <var>critical</var>, const gnutls_datum_t * <var>data</var>)</code></dt>
3692 </dl>
3693
3694 <p>A common OCSP Request extension is the nonce extension (OID
3695 1.3.6.1.5.5.7.48.1.2), which is used to avoid replay attacks of
3696 earlier recorded OCSP responses.  The nonce extension carries a value
3697 that is intended to be sufficiently random and unique so that an
3698 attacker will not be able to give a stale response for the same nonce.
3699 </p>
3700 <dl compact="compact">
3701 <dt><code><var>int</var> <a href="#gnutls_005focsp_005freq_005fget_005fnonce">gnutls_ocsp_req_get_nonce</a> (gnutls_ocsp_req_t <var>req</var>, unsigned int * <var>critical</var>, gnutls_datum_t * <var>nonce</var>)</code></dt>
3702 <dt><code><var>int</var> <a href="#gnutls_005focsp_005freq_005fset_005fnonce">gnutls_ocsp_req_set_nonce</a> (gnutls_ocsp_req_t <var>req</var>, unsigned int <var>critical</var>, const gnutls_datum_t * <var>nonce</var>)</code></dt>
3703 <dt><code><var>int</var> <a href="#gnutls_005focsp_005freq_005frandomize_005fnonce">gnutls_ocsp_req_randomize_nonce</a> (gnutls_ocsp_req_t <var>req</var>)</code></dt>
3704 </dl>
3705
3706 <p>The OCSP response structures is a complex structure. A simplified overview
3707 of it is in <a href="#tab_003aocsp_002dresponse">Table 4.8</a>. Note that a response may contain
3708 information on multiple certificates.
3709 </p>
3710 <div class="float"><a name="tab_003aocsp_002dresponse"></a>
3711 <table>
3712 <thead><tr><th width="20%">Field</th><th width="70%">Description</th></tr></thead>
3713 <tr><td width="20%">version</td><td width="70%">The OCSP response version number (typically 1).</td></tr>
3714 <tr><td width="20%">responder ID</td><td width="70%">An identifier of the responder (DN name or a hash of its key).</td></tr>
3715 <tr><td width="20%">issue time</td><td width="70%">The time the response was generated.</td></tr>
3716 <tr><td width="20%">thisUpdate</td><td width="70%">The issuing time of the revocation information.</td></tr>
3717 <tr><td width="20%">nextUpdate</td><td width="70%">The issuing time of the revocation information that will update that one.</td></tr>
3718 <tr><td width="20%"></td><td width="70%">Revoked certificates</td></tr>
3719 <tr><td width="20%">certificate status</td><td width="70%">The status of the certificate.</td></tr>
3720 <tr><td width="20%">certificate serial</td><td width="70%">The certificate&rsquo;s serial number.</td></tr>
3721 <tr><td width="20%">revocationTime</td><td width="70%">The time the certificate was revoked.</td></tr>
3722 <tr><td width="20%">revocationReason</td><td width="70%">The reason the certificate was revoked.</td></tr>
3723 </table>
3724
3725 <div class="float-caption"><p><strong>Table 4.8: </strong>The most important OCSP response fields.</p></div></div>
3726
3727 <p>We provide basic functions for initialization, importing, exporting
3728 and deallocating OCSP responses.
3729 </p>
3730 <dl compact="compact">
3731 <dt><code><var>int</var> <a href="#gnutls_005focsp_005fresp_005finit">gnutls_ocsp_resp_init</a> (gnutls_ocsp_resp_t * <var>resp</var>)</code></dt>
3732 <dt><code><var>void</var> <a href="#gnutls_005focsp_005fresp_005fdeinit">gnutls_ocsp_resp_deinit</a> (gnutls_ocsp_resp_t <var>resp</var>)</code></dt>
3733 <dt><code><var>int</var> <a href="#gnutls_005focsp_005fresp_005fimport">gnutls_ocsp_resp_import</a> (gnutls_ocsp_resp_t <var>resp</var>, const gnutls_datum_t * <var>data</var>)</code></dt>
3734 <dt><code><var>int</var> <a href="#gnutls_005focsp_005fresp_005fexport">gnutls_ocsp_resp_export</a> (gnutls_ocsp_resp_t <var>resp</var>, gnutls_datum_t * <var>data</var>)</code></dt>
3735 <dt><code><var>int</var> <a href="#gnutls_005focsp_005fresp_005fprint">gnutls_ocsp_resp_print</a> (gnutls_ocsp_resp_t <var>resp</var>, gnutls_ocsp_print_formats_t <var>format</var>, gnutls_datum_t * <var>out</var>)</code></dt>
3736 </dl>
3737
3738 <p>The utility function that extracts the revocation as well as other information
3739 from a response is shown below.
3740 </p>
3741
3742
3743
3744
3745 <dl>
3746 <dt><a name="index-gnutls_005focsp_005fresp_005fget_005fsingle"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_get_single</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, unsigned <var>indx</var>, gnutls_digest_algorithm_t * <var>digest</var>, gnutls_datum_t * <var>issuer_name_hash</var>, gnutls_datum_t * <var>issuer_key_hash</var>, gnutls_datum_t * <var>serial_number</var>, unsigned int * <var>cert_status</var>, time_t * <var>this_update</var>, time_t * <var>next_update</var>, time_t * <var>revocation_time</var>, unsigned int * <var>revocation_reason</var>)</em></dt>
3747 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
3748 </p>
3749 <p><var>indx</var>: Specifies response number to get. Use (0) to get the first one.
3750 </p>
3751 <p><var>digest</var>: output variable with <code>gnutls_digest_algorithm_t</code>  hash algorithm
3752 </p>
3753 <p><var>issuer_name_hash</var>: output buffer with hash of issuer&rsquo;s DN
3754 </p>
3755 <p><var>issuer_key_hash</var>: output buffer with hash of issuer&rsquo;s public key
3756 </p>
3757 <p><var>serial_number</var>: output buffer with serial number of certificate to check
3758 </p>
3759 <p><var>cert_status</var>: a certificate status, a <code>gnutls_ocsp_cert_status_t</code>  enum.
3760 </p>
3761 <p><var>this_update</var>: time at which the status is known to be correct.
3762 </p>
3763 <p><var>next_update</var>: when newer information will be available, or (time_t)-1 if unspecified
3764 </p>
3765 <p><var>revocation_time</var>: when  <code>cert_status</code> is <code>GNUTLS_OCSP_CERT_REVOKED</code> , holds time of revocation.
3766 </p>
3767 <p><var>revocation_reason</var>: revocation reason, a <code>gnutls_x509_crl_reason_t</code>  enum.
3768 </p>
3769 <p>This function will return the certificate information of the
3770  <code>indx</code> &rsquo;ed response in the Basic OCSP Response  <code>resp</code> .  The
3771 information returned corresponds to the OCSP SingleResponse structure
3772 except the final singleExtensions.
3773 </p>
3774 <p>Each of the pointers to output variables may be NULL to indicate
3775 that the caller is not interested in that value.
3776 </p>
3777 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
3778 negative error code is returned.  If you have reached the last
3779 CertID available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be
3780 returned.
3781 </p></dd></dl>
3782
3783 <p>The possible revocation reasons available in an OCSP response are shown
3784 below.
3785 </p>
3786 <div class="float"><a name="gnutls_005fx509_005fcrl_005freason_005ft"></a>
3787
3788
3789 <dl compact="compact">
3790 <dt><code>GNUTLS_X509_CRLREASON_UNSPECIFIED</code></dt>
3791 <dd><p>Unspecified reason.
3792 </p></dd>
3793 <dt><code>GNUTLS_X509_CRLREASON_KEYCOMPROMISE</code></dt>
3794 <dd><p>Private key compromised.
3795 </p></dd>
3796 <dt><code>GNUTLS_X509_CRLREASON_CACOMPROMISE</code></dt>
3797 <dd><p>CA compromised.
3798 </p></dd>
3799 <dt><code>GNUTLS_X509_CRLREASON_AFFILIATIONCHANGED</code></dt>
3800 <dd><p>Affiliation has changed.
3801 </p></dd>
3802 <dt><code>GNUTLS_X509_CRLREASON_SUPERSEDED</code></dt>
3803 <dd><p>Certificate superseded.
3804 </p></dd>
3805 <dt><code>GNUTLS_X509_CRLREASON_CESSATIONOFOPERATION</code></dt>
3806 <dd><p>Operation has ceased.
3807 </p></dd>
3808 <dt><code>GNUTLS_X509_CRLREASON_CERTIFICATEHOLD</code></dt>
3809 <dd><p>Certificate is on hold.
3810 </p></dd>
3811 <dt><code>GNUTLS_X509_CRLREASON_REMOVEFROMCRL</code></dt>
3812 <dd><p>Will be removed from delta CRL.
3813 </p></dd>
3814 <dt><code>GNUTLS_X509_CRLREASON_PRIVILEGEWITHDRAWN</code></dt>
3815 <dd><p>Privilege withdrawn.
3816 </p></dd>
3817 <dt><code>GNUTLS_X509_CRLREASON_AACOMPROMISE</code></dt>
3818 <dd><p>AA compromised.
3819 </p></dd>
3820 </dl>
3821
3822 <div class="float-caption"><p><strong>Figure 4.5: </strong>The revocation reasons</p></div></div>
3823 <p>Note, that the OCSP response needs to be verified against some set of trust
3824 anchors before it can be relied upon. It is also important to check
3825 whether the received OCSP response corresponds to the certificate being checked.
3826 </p>
3827 <dl compact="compact">
3828 <dt><code><var>int</var> <a href="#gnutls_005focsp_005fresp_005fverify">gnutls_ocsp_resp_verify</a> (gnutls_ocsp_resp_t <var>resp</var>, gnutls_x509_trust_list_t <var>trustlist</var>, unsigned int * <var>verify</var>, unsigned int <var>flags</var>)</code></dt>
3829 <dt><code><var>int</var> <a href="#gnutls_005focsp_005fresp_005fverify_005fdirect">gnutls_ocsp_resp_verify_direct</a> (gnutls_ocsp_resp_t <var>resp</var>, gnutls_x509_crt_t <var>issuer</var>, unsigned int * <var>verify</var>, unsigned int <var>flags</var>)</code></dt>
3830 <dt><code><var>int</var> <a href="#gnutls_005focsp_005fresp_005fcheck_005fcrt">gnutls_ocsp_resp_check_crt</a> (gnutls_ocsp_resp_t <var>resp</var>, unsigned int <var>indx</var>, gnutls_x509_crt_t <var>crt</var>)</code></dt>
3831 </dl>
3832
3833 <hr>
3834 <a name="Managing-encrypted-keys"></a>
3835 <div class="header">
3836 <p>
3837 Next: <a href="#certtool-Invocation" accesskey="n" rel="next">certtool Invocation</a>, Previous: <a href="#OCSP-certificate-status-checking" accesskey="p" rel="prev">OCSP certificate status checking</a>, Up: <a href="#More-on-certificate-authentication" accesskey="u" rel="up">More on certificate authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
3838 </div>
3839 <a name="Managing-encrypted-keys-1"></a>
3840 <h4 class="subsection">4.2.4 Managing encrypted keys</h4>
3841 <a name="index-Encrypted-keys"></a>
3842
3843 <p>Transferring or storing private keys in plain may not be a
3844 good idea, since any compromise is irreparable.
3845 Storing the keys in hardware security modules (see <a href="#Smart-cards-and-HSMs">Smart cards and HSMs</a>)
3846 could solve the storage problem but it is not always practical
3847 or efficient enough. This section describes ways to store and
3848 transfer encrypted private keys.
3849 </p>
3850 <p>There are methods for key encryption, namely the
3851 PKCS #8, PKCS #12 and OpenSSL&rsquo;s custom encrypted private key formats.
3852 The PKCS #8 and the OpenSSL&rsquo;s method allow encryption of the private key,
3853 while the PKCS #12 method allows, in addition, the bundling of accompanying
3854 data into the structure. That is typically the corresponding certificate, as
3855 well as a trusted CA certificate.
3856 </p>
3857 <a name="High-level-functionality"></a>
3858 <h4 class="subsubheading">High level functionality</h4>
3859 <p>Generic and higher level private key import functions are available, that
3860 import plain or encrypted keys and will auto-detect the encrypted key format.
3861 </p>
3862
3863
3864
3865
3866 <dl>
3867 <dt><a name="index-gnutls_005fprivkey_005fimport_005fx509_005fraw"></a>Function: <em>int</em> <strong>gnutls_privkey_import_x509_raw</strong> <em>(gnutls_privkey_t <var>pkey</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>)</em></dt>
3868 <dd><p><var>pkey</var>: The private key
3869 </p>
3870 <p><var>data</var>: The private key data to be imported
3871 </p>
3872 <p><var>format</var>: The format of the private key
3873 </p>
3874 <p><var>password</var>: A password (optional)
3875 </p>
3876 <p><var>flags</var>: an ORed sequence of gnutls_pkcs_encrypt_flags_t
3877 </p>
3878 <p>This function will import the given private key to the abstract
3879 <code>gnutls_privkey_t</code>  structure.
3880 </p>
3881 <p>The supported formats are basic unencrypted key, PKCS8, PKCS12,
3882 and the openssl format.
3883 </p>
3884 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
3885 negative error value.
3886 </p>
3887 <p><strong>Since:</strong> 3.1.0
3888 </p></dd></dl>
3889
3890
3891
3892
3893
3894 <dl>
3895 <dt><a name="index-gnutls_005fx509_005fprivkey_005fimport2"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_import2</strong> <em>(gnutls_x509_privkey_t <var>key</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>)</em></dt>
3896 <dd><p><var>key</var>: The structure to store the parsed key
3897 </p>
3898 <p><var>data</var>: The DER or PEM encoded key.
3899 </p>
3900 <p><var>format</var>: One of DER or PEM
3901 </p>
3902 <p><var>password</var>: A password (optional)
3903 </p>
3904 <p><var>flags</var>: an ORed sequence of gnutls_pkcs_encrypt_flags_t
3905 </p>
3906 <p>This function will import the given DER or PEM encoded key, to
3907 the native <code>gnutls_x509_privkey_t</code>  format, irrespective of the
3908 input format. The input format is auto-detected.
3909 </p>
3910 <p>The supported formats are basic unencrypted key, PKCS8, PKCS12,
3911 and the openssl format.
3912 </p>
3913 <p>If the provided key is encrypted but no password was given, then
3914 <code>GNUTLS_E_DECRYPTION_FAILED</code>  is returned.
3915 </p>
3916 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
3917 negative error value.
3918 </p></dd></dl>
3919
3920 <p>Any keys imported using those functions can be imported to a certificate
3921 credentials structure using <a href="#gnutls_005fcertificate_005fset_005fkey">gnutls_certificate_set_key</a>, or alternatively
3922 they can be directly imported using <a href="#gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile2">gnutls_certificate_set_x509_key_file2</a>.
3923 </p>
3924 <a name="PKCS-_00238-structures"></a>
3925 <h4 class="subsubheading"><acronym>PKCS</acronym> #8 structures</h4>
3926 <a name="index-PKCS-_00238"></a>
3927
3928 <p>PKCS #8 keys can be imported and exported as normal private keys using
3929 the functions below. An addition to the normal import functions, are
3930 a password and a flags argument. The flags can be any element of the <code>gnutls_pkcs_encrypt_flags_t</code>
3931 enumeration. Note however, that GnuTLS only supports the PKCS #5 PBES2
3932 encryption scheme. Keys encrypted with the obsolete PBES1 scheme cannot
3933 be decrypted.
3934 </p>
3935 <dl compact="compact">
3936 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fprivkey_005fimport_005fpkcs8">gnutls_x509_privkey_import_pkcs8</a> (gnutls_x509_privkey_t <var>key</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>)</code></dt>
3937 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fprivkey_005fexport_005fpkcs8">gnutls_x509_privkey_export_pkcs8</a> (gnutls_x509_privkey_t <var>key</var>, gnutls_x509_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</code></dt>
3938 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fprivkey_005fexport2_005fpkcs8">gnutls_x509_privkey_export2_pkcs8</a> (gnutls_x509_privkey_t <var>key</var>, gnutls_x509_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>, gnutls_datum_t * <var>out</var>)</code></dt>
3939 </dl>
3940
3941 <div class="float"><a name="gnutls_005fpkcs_005fencrypt_005fflags_005ft"></a>
3942
3943
3944 <dl compact="compact">
3945 <dt><code>GNUTLS_PKCS_PLAIN</code></dt>
3946 <dd><p>Unencrypted private key.
3947 </p></dd>
3948 <dt><code>GNUTLS_PKCS_PKCS12_3DES</code></dt>
3949 <dd><p>PKCS-12 3DES.
3950 </p></dd>
3951 <dt><code>GNUTLS_PKCS_PKCS12_ARCFOUR</code></dt>
3952 <dd><p>PKCS-12 ARCFOUR.
3953 </p></dd>
3954 <dt><code>GNUTLS_PKCS_PKCS12_RC2_40</code></dt>
3955 <dd><p>PKCS-12 RC2-40.
3956 </p></dd>
3957 <dt><code>GNUTLS_PKCS_PBES2_3DES</code></dt>
3958 <dd><p>PBES2 3DES.
3959 </p></dd>
3960 <dt><code>GNUTLS_PKCS_PBES2_AES_128</code></dt>
3961 <dd><p>PBES2 AES-128.
3962 </p></dd>
3963 <dt><code>GNUTLS_PKCS_PBES2_AES_192</code></dt>
3964 <dd><p>PBES2 AES-192.
3965 </p></dd>
3966 <dt><code>GNUTLS_PKCS_PBES2_AES_256</code></dt>
3967 <dd><p>PBES2 AES-256.
3968 </p></dd>
3969 <dt><code>GNUTLS_PKCS_NULL_PASSWORD</code></dt>
3970 <dd><p>Some schemas distinguish between an empty and a NULL password.
3971 </p></dd>
3972 <dt><code>GNUTLS_PKCS_PBES2_DES</code></dt>
3973 <dd><p>PBES2 single DES.
3974 </p></dd>
3975 </dl>
3976
3977 <div class="float-caption"><p><strong>Figure 4.6: </strong>Encryption flags</p></div></div>
3978 <a name="PKCS-_002312-structures"></a>
3979 <h4 class="subsubheading"><acronym>PKCS</acronym> #12 structures</h4>
3980 <a name="index-PKCS-_002312"></a>
3981
3982 <p>A <acronym>PKCS</acronym> #12 structure [<em>PKCS12</em>] usually contains a user&rsquo;s
3983 private keys and certificates. It is commonly used in browsers to
3984 export and import the user&rsquo;s identities. A file containing such a key can
3985 be directly imported to a certificate credentials structure by using
3986 <a href="#gnutls_005fcertificate_005fset_005fx509_005fsimple_005fpkcs12_005ffile">gnutls_certificate_set_x509_simple_pkcs12_file</a>.
3987 </p>
3988 <p>In <acronym>GnuTLS</acronym> the <acronym>PKCS</acronym> #12 structures are handled
3989 using the <code>gnutls_pkcs12_t</code> type. This is an abstract type that
3990 may hold several <code>gnutls_pkcs12_bag_t</code> types.  The bag types are
3991 the holders of the actual data, which may be certificates, private
3992 keys or encrypted data.  A bag of type encrypted should be decrypted
3993 in order for its data to be accessed.
3994 </p>
3995 <p>To reduce the complexity in parsing the structures the simple
3996 helper function <a href="#gnutls_005fpkcs12_005fsimple_005fparse">gnutls_pkcs12_simple_parse</a> is provided. For more
3997 advanced uses, manual parsing of the structure is required using the
3998 functions below.
3999 </p>
4000 <dl compact="compact">
4001 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fget_005fbag">gnutls_pkcs12_get_bag</a> (gnutls_pkcs12_t <var>pkcs12</var>, int <var>indx</var>, gnutls_pkcs12_bag_t <var>bag</var>)</code></dt>
4002 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fverify_005fmac">gnutls_pkcs12_verify_mac</a> (gnutls_pkcs12_t <var>pkcs12</var>, const char * <var>pass</var>)</code></dt>
4003 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fbag_005fdecrypt">gnutls_pkcs12_bag_decrypt</a> (gnutls_pkcs12_bag_t <var>bag</var>, const char * <var>pass</var>)</code></dt>
4004 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fbag_005fget_005fcount">gnutls_pkcs12_bag_get_count</a> (gnutls_pkcs12_bag_t <var>bag</var>)</code></dt>
4005 </dl>
4006
4007
4008
4009
4010
4011 <dl>
4012 <dt><a name="index-gnutls_005fpkcs12_005fsimple_005fparse"></a>Function: <em>int</em> <strong>gnutls_pkcs12_simple_parse</strong> <em>(gnutls_pkcs12_t <var>p12</var>, const char * <var>password</var>, gnutls_x509_privkey_t * <var>key</var>, gnutls_x509_crt_t ** <var>chain</var>, unsigned int * <var>chain_len</var>, gnutls_x509_crt_t ** <var>extra_certs</var>, unsigned int * <var>extra_certs_len</var>, gnutls_x509_crl_t * <var>crl</var>, unsigned int <var>flags</var>)</em></dt>
4013 <dd><p><var>p12</var>: should contain a gnutls_pkcs12_t structure
4014 </p>
4015 <p><var>password</var>: optional password used to decrypt the structure, bags and keys.
4016 </p>
4017 <p><var>key</var>: a structure to store the parsed private key.
4018 </p>
4019 <p><var>chain</var>: the corresponding to key certificate chain (may be <code>NULL</code> )
4020 </p>
4021 <p><var>chain_len</var>: will be updated with the number of additional (may be <code>NULL</code> )
4022 </p>
4023 <p><var>extra_certs</var>: optional pointer to receive an array of additional
4024 certificates found in the PKCS12 structure (may be <code>NULL</code> ).
4025 </p>
4026 <p><var>extra_certs_len</var>: will be updated with the number of additional
4027 certs (may be <code>NULL</code> ).
4028 </p>
4029 <p><var>crl</var>: an optional structure to store the parsed CRL (may be <code>NULL</code> ).
4030 </p>
4031 <p><var>flags</var>: should be zero or one of GNUTLS_PKCS12_SP_*
4032 </p>
4033 <p>This function parses a PKCS12 structure in  <code>pkcs12</code> and extracts the
4034 private key, the corresponding certificate chain, any additional
4035 certificates and a CRL.
4036 </p>
4037 <p>The  <code>extra_certs</code> and  <code>extra_certs_len</code> parameters are optional
4038 and both may be set to <code>NULL</code> . If either is non-<code>NULL</code> , then both must
4039 be set. The value for  <code>extra_certs</code> is allocated
4040 using <code>gnutls_malloc()</code> .
4041 </p>
4042 <p>Encrypted PKCS12 bags and PKCS8 private keys are supported, but
4043 only with password based security and the same password for all
4044 operations.
4045 </p>
4046 <p>Note that a PKCS12 structure may contain many keys and/or certificates,
4047 and there is no way to identify which key/certificate pair you want.
4048 For this reason this function is useful for PKCS12 files that contain
4049 only one key/certificate pair and/or one CRL.
4050 </p>
4051 <p>If the provided structure has encrypted fields but no password
4052 is provided then this function returns <code>GNUTLS_E_DECRYPTION_FAILED</code> .
4053 </p>
4054 <p>Note that normally the chain constructed does not include self signed
4055 certificates, to comply with TLS&rsquo; requirements. If, however, the flag
4056 <code>GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED</code>  is specified then
4057 self signed certificates will be included in the chain.
4058 </p>
4059 <p>Prior to using this function the PKCS <code>12</code>  structure integrity must
4060 be verified using <code>gnutls_pkcs12_verify_mac()</code> .
4061 </p>
4062 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
4063 negative error value.
4064 </p>
4065 <p><strong>Since:</strong> 3.1.0
4066 </p></dd></dl>
4067 <dl compact="compact">
4068 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fbag_005fget_005fdata">gnutls_pkcs12_bag_get_data</a> (gnutls_pkcs12_bag_t <var>bag</var>, int <var>indx</var>, gnutls_datum_t * <var>data</var>)</code></dt>
4069 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fbag_005fget_005fkey_005fid">gnutls_pkcs12_bag_get_key_id</a> (gnutls_pkcs12_bag_t <var>bag</var>, int <var>indx</var>, gnutls_datum_t * <var>id</var>)</code></dt>
4070 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fbag_005fget_005ffriendly_005fname">gnutls_pkcs12_bag_get_friendly_name</a> (gnutls_pkcs12_bag_t <var>bag</var>, int <var>indx</var>, char ** <var>name</var>)</code></dt>
4071 </dl>
4072
4073 <p>The functions below are used to generate a PKCS #12 structure. An example
4074 of their usage is shown at <a href="#PKCS12-structure-generation-example">PKCS12 structure generation example</a>.
4075 </p>
4076 <dl compact="compact">
4077 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fset_005fbag">gnutls_pkcs12_set_bag</a> (gnutls_pkcs12_t <var>pkcs12</var>, gnutls_pkcs12_bag_t <var>bag</var>)</code></dt>
4078 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fbag_005fencrypt">gnutls_pkcs12_bag_encrypt</a> (gnutls_pkcs12_bag_t <var>bag</var>, const char * <var>pass</var>, unsigned int <var>flags</var>)</code></dt>
4079 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fgenerate_005fmac">gnutls_pkcs12_generate_mac</a> (gnutls_pkcs12_t <var>pkcs12</var>, const char * <var>pass</var>)</code></dt>
4080 </dl>
4081 <dl compact="compact">
4082 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fbag_005fset_005fdata">gnutls_pkcs12_bag_set_data</a> (gnutls_pkcs12_bag_t <var>bag</var>, gnutls_pkcs12_bag_type_t <var>type</var>, const gnutls_datum_t * <var>data</var>)</code></dt>
4083 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fbag_005fset_005fcrl">gnutls_pkcs12_bag_set_crl</a> (gnutls_pkcs12_bag_t <var>bag</var>, gnutls_x509_crl_t <var>crl</var>)</code></dt>
4084 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fbag_005fset_005fcrt">gnutls_pkcs12_bag_set_crt</a> (gnutls_pkcs12_bag_t <var>bag</var>, gnutls_x509_crt_t <var>crt</var>)</code></dt>
4085 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fbag_005fset_005fkey_005fid">gnutls_pkcs12_bag_set_key_id</a> (gnutls_pkcs12_bag_t <var>bag</var>, int <var>indx</var>, const gnutls_datum_t * <var>id</var>)</code></dt>
4086 <dt><code><var>int</var> <a href="#gnutls_005fpkcs12_005fbag_005fset_005ffriendly_005fname">gnutls_pkcs12_bag_set_friendly_name</a> (gnutls_pkcs12_bag_t <var>bag</var>, int <var>indx</var>, const char * <var>name</var>)</code></dt>
4087 </dl>
4088
4089 <a name="OpenSSL-encrypted-keys"></a>
4090 <h4 class="subsubheading">OpenSSL encrypted keys</h4>
4091 <a name="index-OpenSSL-encrypted-keys"></a>
4092 <p>Unfortunately the structures discussed in the previous sections are
4093 not the only structures that may hold an encrypted private key. For example
4094 the OpenSSL library offers a custom key encryption method. Those structures
4095 are also supported in GnuTLS with <a href="#gnutls_005fx509_005fprivkey_005fimport_005fopenssl">gnutls_x509_privkey_import_openssl</a>.
4096 </p>
4097
4098
4099
4100
4101 <dl>
4102 <dt><a name="index-gnutls_005fx509_005fprivkey_005fimport_005fopenssl"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_import_openssl</strong> <em>(gnutls_x509_privkey_t <var>key</var>, const gnutls_datum_t * <var>data</var>, const char * <var>password</var>)</em></dt>
4103 <dd><p><var>key</var>: The structure to store the parsed key
4104 </p>
4105 <p><var>data</var>: The DER or PEM encoded key.
4106 </p>
4107 <p><var>password</var>: the password to decrypt the key (if it is encrypted).
4108 </p>
4109 <p>This function will convert the given PEM encrypted to
4110 the native gnutls_x509_privkey_t format. The
4111 output will be stored in  <code>key</code> .
4112 </p>
4113 <p>The  <code>password</code> should be in ASCII. If the password is not provided
4114 or wrong then <code>GNUTLS_E_DECRYPTION_FAILED</code>  will be returned.
4115 </p>
4116 <p>If the Certificate is PEM encoded it should have a header of
4117 &quot;PRIVATE KEY&quot; and the &quot;DEK-Info&quot; header.
4118 </p>
4119 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
4120 negative error value.
4121 </p></dd></dl>
4122
4123 <hr>
4124 <a name="certtool-Invocation"></a>
4125 <div class="header">
4126 <p>
4127 Next: <a href="#ocsptool-Invocation" accesskey="n" rel="next">ocsptool Invocation</a>, Previous: <a href="#Managing-encrypted-keys" accesskey="p" rel="prev">Managing encrypted keys</a>, Up: <a href="#More-on-certificate-authentication" accesskey="u" rel="up">More on certificate authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
4128 </div>
4129 <a name="Invoking-certtool"></a>
4130 <h4 class="subsection">4.2.5 Invoking certtool</h4>
4131 <a name="index-certtool"></a>
4132
4133
4134 <p>Tool to parse and generate X.509 certificates, requests and private keys.
4135 It can be used interactively or non interactively by
4136 specifying the template command line option.
4137 </p>
4138 <p>The tool accepts files or URLs supported by GnuTLS. In case PIN is required for the URL
4139 access you can provide it using the environment variables GNUTLS_PIN and GNUTLS_SO_PIN.
4140 </p>
4141
4142 <p>This section was generated by <strong>AutoGen</strong>,
4143 using the <code>agtexi-cmd</code> template and the option descriptions for the <code>certtool</code> program.
4144 This software is released under the GNU General Public License, version 3 or later.
4145 </p>
4146
4147 <a name="certtool-usage"></a><a name="certtool-help_002fusage-_0028_002d_002dhelp_0029"></a>
4148 <h4 class="subsubheading">certtool help/usage (<samp>--help</samp>)</h4>
4149 <a name="index-certtool-help"></a>
4150
4151 <p>This is the automatically generated usage text for certtool.
4152 </p>
4153 <p>The text printed is the same whether selected with the <code>help</code> option
4154 (<samp>--help</samp>) or the <code>more-help</code> option (<samp>--more-help</samp>).  <code>more-help</code> will print
4155 the usage text by passing it through a pager program.
4156 <code>more-help</code> is disabled on platforms without a working
4157 <code>fork(2)</code> function.  The <code>PAGER</code> environment variable is
4158 used to select the program, defaulting to <samp>more</samp>.  Both will exit
4159 with a status code of 0.
4160 </p>
4161 <div class="example">
4162 <pre class="example">certtool - GnuTLS certificate tool
4163 Usage:  certtool [ -&lt;flag&gt; [&lt;val&gt;] | --&lt;name&gt;[{=| }&lt;val&gt;] ]...
4164
4165    -d, --debug=num            Enable debugging
4166                                 - it must be in the range:
4167                                   0 to 9999
4168    -V, --verbose              More verbose output
4169                                 - may appear multiple times
4170        --infile=file          Input file
4171                                 - file must pre-exist
4172        --outfile=str          Output file
4173    -s, --generate-self-signed  Generate a self-signed certificate
4174    -c, --generate-certificate  Generate a signed certificate
4175        --generate-proxy       Generates a proxy certificate
4176        --generate-crl         Generate a CRL
4177    -u, --update-certificate   Update a signed certificate
4178    -p, --generate-privkey     Generate a private key
4179        --provable             Generate a private key or parameters from a seed using a provable method
4180        --verify-provable-privkey  Verify a private key generated from a seed using a provable method
4181        --seed=str             When generating a private key use the given hex-encoded seed
4182    -q, --generate-request     Generate a PKCS #10 certificate request
4183                                 - prohibits the option 'infile'
4184    -e, --verify-chain         Verify a PEM encoded certificate chain
4185        --verify               Verify a PEM encoded certificate chain using a trusted list
4186        --verify-crl           Verify a CRL using a trusted list
4187                                 - requires the option 'load-ca-certificate'
4188        --verify-hostname=str  Specify a hostname to be used for certificate chain verification
4189        --verify-email=str     Specify a email to be used for certificate chain verification
4190                                 - prohibits the option 'verify-hostname'
4191        --verify-purpose=str   Specify a purpose OID to be used for certificate chain verification
4192        --verify-allow-broken  Allow broken algorithms, such as MD5 for verification
4193        --generate-dh-params   Generate PKCS #3 encoded Diffie-Hellman parameters
4194        --get-dh-params        Get the included PKCS #3 encoded Diffie-Hellman parameters
4195        --dh-info              Print information PKCS #3 encoded Diffie-Hellman parameters
4196        --load-privkey=str     Loads a private key file
4197        --load-pubkey=str      Loads a public key file
4198        --load-request=str     Loads a certificate request file
4199        --load-certificate=str Loads a certificate file
4200        --load-ca-privkey=str  Loads the certificate authority's private key file
4201        --load-ca-certificate=str Loads the certificate authority's certificate file
4202        --load-crl=str         Loads the provided CRL
4203        --load-data=str        Loads auxiliary data
4204        --password=str         Password to use
4205        --null-password        Enforce a NULL password
4206        --empty-password       Enforce an empty password
4207        --hex-numbers          Print big number in an easier format to parse
4208        --cprint               In certain operations it prints the information in C-friendly format
4209    -i, --certificate-info     Print information on the given certificate
4210        --fingerprint          Print the fingerprint of the given certificate
4211        --key-id               Print the key ID of the given certificate
4212        --certificate-pubkey   Print certificate's public key
4213        --pgp-certificate-info  Print information on the given OpenPGP certificate
4214        --pgp-ring-info        Print information on the given OpenPGP keyring structure
4215    -l, --crl-info             Print information on the given CRL structure
4216        --crq-info             Print information on the given certificate request
4217        --no-crq-extensions    Do not use extensions in certificate requests
4218        --p12-info             Print information on a PKCS #12 structure
4219        --p12-name=str         The PKCS #12 friendly name to use
4220        --p7-generate          Generate a PKCS #7 structure
4221        --p7-sign              Signs using a PKCS #7 structure
4222        --p7-detached-sign     Signs using a detached PKCS #7 structure
4223        --p7-include-cert      The signer's certificate will be included in the cert list.
4224                                 - disabled as '--no-p7-include-cert'
4225                                 - enabled by default
4226        --p7-time              Will include a timestamp in the PKCS #7 structure
4227                                 - disabled as '--no-p7-time'
4228        --p7-show-data         Will show the embedded data in the PKCS #7 structure
4229                                 - disabled as '--no-p7-show-data'
4230        --p7-info              Print information on a PKCS #7 structure
4231        --p7-verify            Verify the provided PKCS #7 structure
4232        --p8-info              Print information on a PKCS #8 structure
4233        --smime-to-p7          Convert S/MIME to PKCS #7 structure
4234    -k, --key-info             Print information on a private key
4235        --pgp-key-info         Print information on an OpenPGP private key
4236        --pubkey-info          Print information on a public key
4237        --v1                   Generate an X.509 version 1 certificate (with no extensions)
4238        --to-p12               Generate a PKCS #12 structure
4239        --to-p8                Generate a PKCS #8 structure
4240    -8, --pkcs8                Use PKCS #8 format for private keys
4241        --rsa                  Generate RSA key
4242        --dsa                  Generate DSA key
4243        --ecc                  Generate ECC (ECDSA) key
4244        --ecdsa                an alias for the 'ecc' option
4245        --hash=str             Hash algorithm to use for signing
4246        --inder                Use DER format for input certificates, private keys, and DH parameters
4247                                 - disabled as '--no-inder'
4248        --inraw                an alias for the 'inder' option
4249        --outder               Use DER format for output certificates, private keys, and DH parameters
4250                                 - disabled as '--no-outder'
4251        --outraw               an alias for the 'outder' option
4252        --bits=num             Specify the number of bits for key generate
4253        --curve=str            Specify the curve used for EC key generation
4254        --sec-param=str        Specify the security level [low, legacy, medium, high, ultra]
4255        --disable-quick-random  No effect
4256        --template=str         Template file to use for non-interactive operation
4257        --stdout-info          Print information to stdout instead of stderr
4258        --ask-pass             Enable interaction for entering password when in batch mode.
4259        --pkcs-cipher=str      Cipher to use for PKCS #8 and #12 operations
4260        --provider=str         Specify the PKCS #11 provider library
4261    -v, --version[=arg]        output version information and exit
4262    -h, --help                 display extended usage information and exit
4263    -!, --more-help            extended usage information passed thru pager
4264
4265 Options are specified by doubled hyphens and their name or by a single
4266 hyphen and the flag character.
4267
4268 Tool to parse and generate X.509 certificates, requests and private keys.
4269 It can be used interactively or non interactively by specifying the
4270 template command line option.
4271
4272 The tool accepts files or URLs supported by GnuTLS.  In case PIN is
4273 required for the URL access you can provide it using the environment
4274 variables GNUTLS_PIN and GNUTLS_SO_PIN.
4275
4276 </pre></div>
4277
4278 <a name="certtool-debug"></a><a name="debug-option-_0028_002dd_0029-2"></a>
4279 <h4 class="subsubheading">debug option (-d)</h4>
4280
4281 <p>This is the &ldquo;enable debugging&rdquo; option.
4282 This option takes a number argument.
4283 Specifies the debug level.
4284 <a name="certtool-generate_002drequest"></a></p><a name="generate_002drequest-option-_0028_002dq_0029"></a>
4285 <h4 class="subsubheading">generate-request option (-q)</h4>
4286
4287 <p>This is the &ldquo;generate a pkcs #10 certificate request&rdquo; option.
4288 </p>
4289 <p>This option has some usage constraints.  It:
4290 </p><ul>
4291 <li> must not appear in combination with any of the following options:
4292 infile.
4293 </li></ul>
4294
4295 <p>Will generate a PKCS #10 certificate request. To specify a private key use &ndash;load-privkey.
4296 <a name="certtool-verify_002dchain"></a></p><a name="verify_002dchain-option-_0028_002de_0029"></a>
4297 <h4 class="subsubheading">verify-chain option (-e)</h4>
4298
4299 <p>This is the &ldquo;verify a pem encoded certificate chain&rdquo; option.
4300 The last certificate in the chain must be a self signed one.
4301 <a name="certtool-verify"></a></p><a name="verify-option"></a>
4302 <h4 class="subsubheading">verify option</h4>
4303
4304 <p>This is the &ldquo;verify a pem encoded certificate chain using a trusted list&rdquo; option.
4305 The trusted certificate list can be loaded with &ndash;load-ca-certificate. If no
4306 certificate list is provided, then the system&rsquo;s certificate list is used.
4307 <a name="certtool-verify_002dcrl"></a></p><a name="verify_002dcrl-option"></a>
4308 <h4 class="subsubheading">verify-crl option</h4>
4309
4310 <p>This is the &ldquo;verify a crl using a trusted list&rdquo; option.
4311 </p>
4312 <p>This option has some usage constraints.  It:
4313 </p><ul>
4314 <li> must appear in combination with the following options:
4315 load-ca-certificate.
4316 </li></ul>
4317
4318 <p>The trusted certificate list must be loaded with &ndash;load-ca-certificate.
4319 <a name="certtool-get_002ddh_002dparams"></a></p><a name="get_002ddh_002dparams-option"></a>
4320 <h4 class="subsubheading">get-dh-params option</h4>
4321
4322 <p>This is the &ldquo;get the included pkcs #3 encoded diffie-hellman parameters&rdquo; option.
4323 Returns stored DH parameters in GnuTLS. Those parameters are used in the SRP protocol. The parameters returned by fresh generation
4324 are more efficient since GnuTLS 3.0.9.
4325 <a name="certtool-load_002dprivkey"></a></p><a name="load_002dprivkey-option"></a>
4326 <h4 class="subsubheading">load-privkey option</h4>
4327
4328 <p>This is the &ldquo;loads a private key file&rdquo; option.
4329 This option takes a string argument.
4330 This can be either a file or a PKCS #11 URL
4331 <a name="certtool-load_002dpubkey"></a></p><a name="load_002dpubkey-option"></a>
4332 <h4 class="subsubheading">load-pubkey option</h4>
4333
4334 <p>This is the &ldquo;loads a public key file&rdquo; option.
4335 This option takes a string argument.
4336 This can be either a file or a PKCS #11 URL
4337 <a name="certtool-load_002drequest"></a></p><a name="load_002drequest-option"></a>
4338 <h4 class="subsubheading">load-request option</h4>
4339
4340 <p>This is the &ldquo;loads a certificate request file&rdquo; option.
4341 This option takes a string argument.
4342 This option can be used with a file
4343 <a name="certtool-load_002dcertificate"></a></p><a name="load_002dcertificate-option"></a>
4344 <h4 class="subsubheading">load-certificate option</h4>
4345
4346 <p>This is the &ldquo;loads a certificate file&rdquo; option.
4347 This option takes a string argument.
4348 This option can be used with a file
4349 <a name="certtool-load_002dca_002dprivkey"></a></p><a name="load_002dca_002dprivkey-option"></a>
4350 <h4 class="subsubheading">load-ca-privkey option</h4>
4351
4352 <p>This is the &ldquo;loads the certificate authority&rsquo;s private key file&rdquo; option.
4353 This option takes a string argument.
4354 This can be either a file or a PKCS #11 URL
4355 <a name="certtool-load_002dca_002dcertificate"></a></p><a name="load_002dca_002dcertificate-option"></a>
4356 <h4 class="subsubheading">load-ca-certificate option</h4>
4357
4358 <p>This is the &ldquo;loads the certificate authority&rsquo;s certificate file&rdquo; option.
4359 This option takes a string argument.
4360 This option can be used with a file
4361 <a name="certtool-password"></a></p><a name="password-option"></a>
4362 <h4 class="subsubheading">password option</h4>
4363
4364 <p>This is the &ldquo;password to use&rdquo; option.
4365 This option takes a string argument.
4366 You can use this option to specify the password in the command line instead of reading it from the tty. Note, that the command line arguments are available for view in others in the system. Specifying password as &rdquo; is the same as specifying no password.
4367 <a name="certtool-null_002dpassword"></a></p><a name="null_002dpassword-option"></a>
4368 <h4 class="subsubheading">null-password option</h4>
4369
4370 <p>This is the &ldquo;enforce a null password&rdquo; option.
4371 This option enforces a NULL password. This is different than the empty or no password in schemas like PKCS #8.
4372 <a name="certtool-empty_002dpassword"></a></p><a name="empty_002dpassword-option"></a>
4373 <h4 class="subsubheading">empty-password option</h4>
4374
4375 <p>This is the &ldquo;enforce an empty password&rdquo; option.
4376 This option enforces an empty password. This is different than the NULL or no password in schemas like PKCS #8.
4377 <a name="certtool-cprint"></a></p><a name="cprint-option"></a>
4378 <h4 class="subsubheading">cprint option</h4>
4379
4380 <p>This is the &ldquo;in certain operations it prints the information in c-friendly format&rdquo; option.
4381 In certain operations it prints the information in C-friendly format, suitable for including into C programs.
4382 <a name="certtool-p12_002dname"></a></p><a name="p12_002dname-option"></a>
4383 <h4 class="subsubheading">p12-name option</h4>
4384
4385 <p>This is the &ldquo;the pkcs #12 friendly name to use&rdquo; option.
4386 This option takes a string argument.
4387 The name to be used for the primary certificate and private key in a PKCS #12 file.
4388 <a name="certtool-pubkey_002dinfo"></a></p><a name="pubkey_002dinfo-option"></a>
4389 <h4 class="subsubheading">pubkey-info option</h4>
4390
4391 <p>This is the &ldquo;print information on a public key&rdquo; option.
4392 The option combined with &ndash;load-request, &ndash;load-pubkey, &ndash;load-privkey and &ndash;load-certificate will extract the public key of the object in question.
4393 <a name="certtool-to_002dp12"></a></p><a name="to_002dp12-option"></a>
4394 <h4 class="subsubheading">to-p12 option</h4>
4395
4396 <p>This is the &ldquo;generate a pkcs #12 structure&rdquo; option.
4397 </p>
4398 <p>This option has some usage constraints.  It:
4399 </p><ul>
4400 <li> must appear in combination with the following options:
4401 load-certificate.
4402 </li></ul>
4403
4404 <p>It requires a certificate, a private key and possibly a CA certificate to be specified.
4405 <a name="certtool-rsa"></a></p><a name="rsa-option"></a>
4406 <h4 class="subsubheading">rsa option</h4>
4407
4408 <p>This is the &ldquo;generate rsa key&rdquo; option.
4409 When combined with &ndash;generate-privkey generates an RSA private key.
4410 <a name="certtool-dsa"></a></p><a name="dsa-option"></a>
4411 <h4 class="subsubheading">dsa option</h4>
4412
4413 <p>This is the &ldquo;generate dsa key&rdquo; option.
4414 When combined with &ndash;generate-privkey generates a DSA private key.
4415 <a name="certtool-ecc"></a></p><a name="ecc-option"></a>
4416 <h4 class="subsubheading">ecc option</h4>
4417
4418 <p>This is the &ldquo;generate ecc (ecdsa) key&rdquo; option.
4419 When combined with &ndash;generate-privkey generates an elliptic curve private key to be used with ECDSA.
4420 <a name="certtool-ecdsa"></a></p><a name="ecdsa-option"></a>
4421 <h4 class="subsubheading">ecdsa option</h4>
4422
4423 <p>This is an alias for the <code>ecc</code> option,
4424 see <a href="#certtool-ecc">the ecc option documentation</a>.
4425 </p>
4426 <a name="certtool-hash"></a><a name="hash-option"></a>
4427 <h4 class="subsubheading">hash option</h4>
4428
4429 <p>This is the &ldquo;hash algorithm to use for signing&rdquo; option.
4430 This option takes a string argument.
4431 Available hash functions are SHA1, RMD160, SHA256, SHA384, SHA512.
4432 <a name="certtool-inder"></a></p><a name="inder-option-2"></a>
4433 <h4 class="subsubheading">inder option</h4>
4434
4435 <p>This is the &ldquo;use der format for input certificates, private keys, and dh parameters &rdquo; option.
4436 </p>
4437 <p>This option has some usage constraints.  It:
4438 </p><ul>
4439 <li> can be disabled with &ndash;no-inder.
4440 </li></ul>
4441
4442 <p>The input files will be assumed to be in DER or RAW format.
4443 Unlike options that in PEM input would allow multiple input data (e.g. multiple
4444 certificates), when reading in DER format a single data structure is read.
4445 <a name="certtool-inraw"></a></p><a name="inraw-option-1"></a>
4446 <h4 class="subsubheading">inraw option</h4>
4447
4448 <p>This is an alias for the <code>inder</code> option,
4449 see <a href="#certtool-inder">the inder option documentation</a>.
4450 </p>
4451 <a name="certtool-outder"></a><a name="outder-option-2"></a>
4452 <h4 class="subsubheading">outder option</h4>
4453
4454 <p>This is the &ldquo;use der format for output certificates, private keys, and dh parameters&rdquo; option.
4455 </p>
4456 <p>This option has some usage constraints.  It:
4457 </p><ul>
4458 <li> can be disabled with &ndash;no-outder.
4459 </li></ul>
4460
4461 <p>The output will be in DER or RAW format.
4462 <a name="certtool-outraw"></a></p><a name="outraw-option-1"></a>
4463 <h4 class="subsubheading">outraw option</h4>
4464
4465 <p>This is an alias for the <code>outder</code> option,
4466 see <a href="#certtool-outder">the outder option documentation</a>.
4467 </p>
4468 <a name="certtool-curve"></a><a name="curve-option-1"></a>
4469 <h4 class="subsubheading">curve option</h4>
4470
4471 <p>This is the &ldquo;specify the curve used for ec key generation&rdquo; option.
4472 This option takes a string argument.
4473 Supported values are secp192r1, secp224r1, secp256r1, secp384r1 and secp521r1.
4474 <a name="certtool-sec_002dparam"></a></p><a name="sec_002dparam-option-2"></a>
4475 <h4 class="subsubheading">sec-param option</h4>
4476
4477 <p>This is the &ldquo;specify the security level [low, legacy, medium, high, ultra]&rdquo; option.
4478 This option takes a string argument <samp>Security parameter</samp>.
4479 This is alternative to the bits option.
4480 <a name="certtool-ask_002dpass"></a></p><a name="ask_002dpass-option"></a>
4481 <h4 class="subsubheading">ask-pass option</h4>
4482
4483 <p>This is the &ldquo;enable interaction for entering password when in batch mode.&rdquo; option.
4484 This option will enable interaction to enter password when in batch mode. That is useful when the template option has been specified.
4485 <a name="certtool-pkcs_002dcipher"></a></p><a name="pkcs_002dcipher-option"></a>
4486 <h4 class="subsubheading">pkcs-cipher option</h4>
4487
4488 <p>This is the &ldquo;cipher to use for pkcs #8 and #12 operations&rdquo; option.
4489 This option takes a string argument <samp>Cipher</samp>.
4490 Cipher may be one of 3des, 3des-pkcs12, aes-128, aes-192, aes-256, rc2-40, arcfour.
4491 <a name="certtool-provider"></a></p><a name="provider-option-1"></a>
4492 <h4 class="subsubheading">provider option</h4>
4493
4494 <p>This is the &ldquo;specify the pkcs #11 provider library&rdquo; option.
4495 This option takes a string argument.
4496 This will override the default options in /etc/gnutls/pkcs11.conf
4497 <a name="certtool-exit-status"></a></p><a name="certtool-exit-status-1"></a>
4498 <h4 class="subsubheading">certtool exit status</h4>
4499
4500 <p>One of the following exit values will be returned:
4501 </p><dl compact="compact">
4502 <dt>&lsquo;<samp>0 (EXIT_SUCCESS)</samp>&rsquo;</dt>
4503 <dd><p>Successful program execution.
4504 </p></dd>
4505 <dt>&lsquo;<samp>1 (EXIT_FAILURE)</samp>&rsquo;</dt>
4506 <dd><p>The operation failed or the command syntax was not valid.
4507 </p></dd>
4508 </dl>
4509 <a name="certtool-See-Also"></a><a name="certtool-See-Also-1"></a>
4510 <h4 class="subsubheading">certtool See Also</h4>
4511 <p>p11tool (1)
4512 <a name="certtool-Examples"></a></p><a name="certtool-Examples-1"></a>
4513 <h4 class="subsubheading">certtool Examples</h4>
4514 <a name="Generating-private-keys"></a>
4515 <h4 class="subsubheading">Generating private keys</h4>
4516 <p>To create an RSA private key, run:
4517 </p><div class="example">
4518 <pre class="example">$ certtool --generate-privkey --outfile key.pem --rsa
4519 </pre></div>
4520
4521 <p>To create a DSA or elliptic curves (ECDSA) private key use the
4522 above command combined with &rsquo;dsa&rsquo; or &rsquo;ecc&rsquo; options.
4523 </p>
4524 <a name="Generating-certificate-requests"></a>
4525 <h4 class="subsubheading">Generating certificate requests</h4>
4526 <p>To create a certificate request (needed when the certificate is  issued  by
4527 another party), run:
4528 </p><div class="example">
4529 <pre class="example">certtool --generate-request --load-privkey key.pem \
4530    --outfile request.pem
4531 </pre></div>
4532
4533 <p>If the private key is stored in a smart card you can generate
4534 a request by specifying the private key object URL.
4535 </p><div class="example">
4536 <pre class="example">$ ./certtool --generate-request --load-privkey &quot;pkcs11:...&quot; \
4537   --load-pubkey &quot;pkcs11:...&quot; --outfile request.pem
4538 </pre></div>
4539
4540
4541 <a name="Generating-a-self_002dsigned-certificate"></a>
4542 <h4 class="subsubheading">Generating a self-signed certificate</h4>
4543 <p>To create a self signed certificate, use the command:
4544 </p><div class="example">
4545 <pre class="example">$ certtool --generate-privkey --outfile ca-key.pem
4546 $ certtool --generate-self-signed --load-privkey ca-key.pem \
4547    --outfile ca-cert.pem
4548 </pre></div>
4549
4550 <p>Note that a self-signed certificate usually belongs to a certificate
4551 authority, that signs other certificates.
4552 </p>
4553 <a name="Generating-a-certificate"></a>
4554 <h4 class="subsubheading">Generating a certificate</h4>
4555 <p>To generate a certificate using the previous request, use the command:
4556 </p><div class="example">
4557 <pre class="example">$ certtool --generate-certificate --load-request request.pem \
4558    --outfile cert.pem --load-ca-certificate ca-cert.pem \
4559    --load-ca-privkey ca-key.pem
4560 </pre></div>
4561
4562 <p>To generate a certificate using the private key only, use the command:
4563 </p><div class="example">
4564 <pre class="example">$ certtool --generate-certificate --load-privkey key.pem \
4565    --outfile cert.pem --load-ca-certificate ca-cert.pem \
4566    --load-ca-privkey ca-key.pem
4567 </pre></div>
4568
4569 <a name="Certificate-information"></a>
4570 <h4 class="subsubheading">Certificate information</h4>
4571 <p>To view the certificate information, use:
4572 </p><div class="example">
4573 <pre class="example">$ certtool --certificate-info --infile cert.pem
4574 </pre></div>
4575
4576 <a name="PKCS-_002312-structure-generation"></a>
4577 <h4 class="subsubheading">PKCS #12 structure generation</h4>
4578 <p>To generate a PKCS #12 structure using the previous key and certificate,
4579 use the command:
4580 </p><div class="example">
4581 <pre class="example">$ certtool --load-certificate cert.pem --load-privkey key.pem \
4582    --to-p12 --outder --outfile key.p12
4583 </pre></div>
4584
4585 <p>Some tools (reportedly web browsers) have problems with that file
4586 because it does not contain the CA certificate for the certificate.
4587 To work around that problem in the tool, you can use the
4588 &ndash;load-ca-certificate parameter as follows:
4589 </p>
4590 <div class="example">
4591 <pre class="example">$ certtool --load-ca-certificate ca.pem \
4592   --load-certificate cert.pem --load-privkey key.pem \
4593   --to-p12 --outder --outfile key.p12
4594 </pre></div>
4595
4596 <a name="Diffie_002dHellman-parameter-generation"></a>
4597 <h4 class="subsubheading">Diffie-Hellman parameter generation</h4>
4598 <p>To generate parameters for Diffie-Hellman key exchange, use the command:
4599 </p><div class="example">
4600 <pre class="example">$ certtool --generate-dh-params --outfile dh.pem --sec-param medium
4601 </pre></div>
4602
4603 <a name="Proxy-certificate-generation"></a>
4604 <h4 class="subsubheading">Proxy certificate generation</h4>
4605 <p>Proxy certificate can be used to delegate your credential to a
4606 temporary, typically short-lived, certificate.  To create one from the
4607 previously created certificate, first create a temporary key and then
4608 generate a proxy certificate for it, using the commands:
4609 </p>
4610 <div class="example">
4611 <pre class="example">$ certtool --generate-privkey &gt; proxy-key.pem
4612 $ certtool --generate-proxy --load-ca-privkey key.pem \
4613   --load-privkey proxy-key.pem --load-certificate cert.pem \
4614   --outfile proxy-cert.pem
4615 </pre></div>
4616
4617 <a name="Certificate-revocation-list-generation"></a>
4618 <h4 class="subsubheading">Certificate revocation list generation</h4>
4619 <p>To create an empty Certificate Revocation List (CRL) do:
4620 </p>
4621 <div class="example">
4622 <pre class="example">$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
4623            --load-ca-certificate x509-ca.pem
4624 </pre></div>
4625
4626 <p>To create a CRL that contains some revoked certificates, place the
4627 certificates in a file and use <code>--load-certificate</code> as follows:
4628 </p>
4629 <div class="example">
4630 <pre class="example">$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
4631   --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
4632 </pre></div>
4633
4634 <p>To verify a Certificate Revocation List (CRL) do:
4635 </p>
4636 <div class="example">
4637 <pre class="example">$ certtool --verify-crl --load-ca-certificate x509-ca.pem &lt; crl.pem
4638 </pre></div>
4639 <a name="certtool-Files"></a><a name="certtool-Files-1"></a>
4640 <h4 class="subsubheading">certtool Files</h4>
4641 <a name="Certtool_0027s-template-file-format"></a>
4642 <h4 class="subsubheading">Certtool&rsquo;s template file format</h4>
4643 <p>A template file can be used to avoid the interactive questions of
4644 certtool. Initially create a file named &rsquo;cert.cfg&rsquo; that contains the information
4645 about the certificate. The template can be used as below:
4646 </p>
4647 <div class="example">
4648 <pre class="example">$ certtool --generate-certificate --load-privkey key.pem  \
4649    --template cert.cfg --outfile cert.pem \
4650    --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
4651 </pre></div>
4652
4653 <p>An example certtool template file that can be used to generate a certificate
4654 request or a self signed certificate follows.
4655 </p>
4656 <div class="example">
4657 <pre class="example"># X.509 Certificate options
4658 #
4659 # DN options
4660
4661 # The organization of the subject.
4662 organization = &quot;Koko inc.&quot;
4663
4664 # The organizational unit of the subject.
4665 unit = &quot;sleeping dept.&quot;
4666
4667 # The locality of the subject.
4668 # locality =
4669
4670 # The state of the certificate owner.
4671 state = &quot;Attiki&quot;
4672
4673 # The country of the subject. Two letter code.
4674 country = GR
4675
4676 # The common name of the certificate owner.
4677 cn = &quot;Cindy Lauper&quot;
4678
4679 # A user id of the certificate owner.
4680 #uid = &quot;clauper&quot;
4681
4682 # Set domain components
4683 #dc = &quot;name&quot;
4684 #dc = &quot;domain&quot;
4685
4686 # If the supported DN OIDs are not adequate you can set
4687 # any OID here.
4688 # For example set the X.520 Title and the X.520 Pseudonym
4689 # by using OID and string pairs.
4690 #dn_oid = 2.5.4.12 Dr.
4691 #dn_oid = 2.5.4.65 jackal
4692
4693 # This is deprecated and should not be used in new
4694 # certificates.
4695 # pkcs9_email = &quot;none@none.org&quot;
4696
4697 # An alternative way to set the certificate's distinguished name directly
4698 # is with the &quot;dn&quot; option. The attribute names allowed are:
4699 # C (country), street, O (organization), OU (unit), title, CN (common name),
4700 # L (locality), ST (state), placeOfBirth, gender, countryOfCitizenship,
4701 # countryOfResidence, serialNumber, telephoneNumber, surName, initials,
4702 # generationQualifier, givenName, pseudonym, dnQualifier, postalCode, name,
4703 # businessCategory, DC, UID, jurisdictionOfIncorporationLocalityName,
4704 # jurisdictionOfIncorporationStateOrProvinceName,
4705 # jurisdictionOfIncorporationCountryName, XmppAddr, and numeric OIDs.
4706
4707 #dn = &quot;cn=Nik,st=Attiki,C=GR,surName=Mavrogiannopoulos,2.5.4.9=Arkadias&quot;
4708
4709 # The serial number of the certificate
4710 # Comment the field for a time-based serial number.
4711 serial = 007
4712
4713 # In how many days, counting from today, this certificate will expire.
4714 # Use -1 if there is no expiration date.
4715 expiration_days = 700
4716
4717 # Alternatively you may set concrete dates and time. The GNU date string
4718 # formats are accepted. See:
4719 # http://www.gnu.org/software/tar/manual/html_node/Date-input-formats.html
4720
4721 #activation_date = &quot;2004-02-29 16:21:42&quot;
4722 #expiration_date = &quot;2025-02-29 16:24:41&quot;
4723
4724 # X.509 v3 extensions
4725
4726 # A dnsname in case of a WWW server.
4727 #dns_name = &quot;www.none.org&quot;
4728 #dns_name = &quot;www.morethanone.org&quot;
4729
4730 # A subject alternative name URI
4731 #uri = &quot;http://www.example.com&quot;
4732
4733 # An IP address in case of a server.
4734 #ip_address = &quot;192.168.1.1&quot;
4735
4736 # An email in case of a person
4737 email = &quot;none@none.org&quot;
4738
4739 # Challenge password used in certificate requests
4740 challenge_password = 123456
4741
4742 # Password when encrypting a private key
4743 #password = secret
4744
4745 # An URL that has CRLs (certificate revocation lists)
4746 # available. Needed in CA certificates.
4747 #crl_dist_points = &quot;http://www.getcrl.crl/getcrl/&quot;
4748
4749 # Whether this is a CA certificate or not
4750 #ca
4751
4752 # Subject Unique ID (in hex)
4753 #subject_unique_id = 00153224
4754
4755 # Issuer Unique ID (in hex)
4756 #issuer_unique_id = 00153225
4757
4758 # for microsoft smart card logon
4759 # key_purpose_oid = 1.3.6.1.4.1.311.20.2.2
4760
4761 ### Other predefined key purpose OIDs
4762
4763 # Whether this certificate will be used for a TLS client
4764 #tls_www_client
4765
4766 # Whether this certificate will be used for a TLS server
4767 #tls_www_server
4768
4769 # Whether this certificate will be used to sign data (needed
4770 # in TLS DHE ciphersuites).
4771 signing_key
4772
4773 # Whether this certificate will be used to encrypt data (needed
4774 # in TLS RSA ciphersuites). Note that it is preferred to use different
4775 # keys for encryption and signing.
4776 encryption_key
4777
4778 # Whether this key will be used to sign other certificates.
4779 #cert_signing_key
4780
4781 # Whether this key will be used to sign CRLs.
4782 #crl_signing_key
4783
4784 # Whether this key will be used to sign code.
4785 #code_signing_key
4786
4787 # Whether this key will be used to sign OCSP data.
4788 #ocsp_signing_key
4789
4790 # Whether this key will be used for time stamping.
4791 #time_stamping_key
4792
4793 # Whether this key will be used for IPsec IKE operations.
4794 #ipsec_ike_key
4795
4796 ### end of key purpose OIDs
4797
4798 # When generating a certificate from a certificate
4799 # request, then honor the extensions stored in the request
4800 # and store them in the real certificate.
4801 #honor_crq_extensions
4802
4803 # Path length contraint. Sets the maximum number of
4804 # certificates that can be used to certify this certificate.
4805 # (i.e. the certificate chain length)
4806 #path_len = -1
4807 #path_len = 2
4808
4809 # OCSP URI
4810 # ocsp_uri = http://my.ocsp.server/ocsp
4811
4812 # CA issuers URI
4813 # ca_issuers_uri = http://my.ca.issuer
4814
4815 # Certificate policies
4816 #policy1 = 1.3.6.1.4.1.5484.1.10.99.1.0
4817 #policy1_txt = &quot;This is a long policy to summarize&quot;
4818 #policy1_url = http://www.example.com/a-policy-to-read
4819
4820 #policy2 = 1.3.6.1.4.1.5484.1.10.99.1.1
4821 #policy2_txt = &quot;This is a short policy&quot;
4822 #policy2_url = http://www.example.com/another-policy-to-read
4823
4824 # Name constraints
4825
4826 # DNS
4827 #nc_permit_dns = example.com
4828 #nc_exclude_dns = test.example.com
4829
4830 # EMAIL
4831 #nc_permit_email = &quot;nmav@ex.net&quot;
4832
4833 # Exclude subdomains of example.com
4834 #nc_exclude_email = .example.com
4835
4836 # Exclude all e-mail addresses of example.com
4837 #nc_exclude_email = example.com
4838
4839
4840 # Options for proxy certificates
4841 #proxy_policy_language = 1.3.6.1.5.5.7.21.1
4842
4843
4844 # Options for generating a CRL
4845
4846 # The number of days the next CRL update will be due.
4847 # next CRL update will be in 43 days
4848 #crl_next_update = 43
4849
4850 # this is the 5th CRL by this CA
4851 # Comment the field for a time-based number.
4852 #crl_number = 5
4853
4854 </pre></div>
4855
4856 <hr>
4857 <a name="ocsptool-Invocation"></a>
4858 <div class="header">
4859 <p>
4860 Next: <a href="#danetool-Invocation" accesskey="n" rel="next">danetool Invocation</a>, Previous: <a href="#certtool-Invocation" accesskey="p" rel="prev">certtool Invocation</a>, Up: <a href="#More-on-certificate-authentication" accesskey="u" rel="up">More on certificate authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
4861 </div>
4862 <a name="Invoking-ocsptool"></a>
4863 <h4 class="subsection">4.2.6 Invoking ocsptool</h4>
4864 <a name="index-ocsptool"></a>
4865
4866
4867 <p>Ocsptool is a program that can parse and print information about
4868 OCSP requests/responses, generate requests and verify responses.
4869 </p>
4870
4871 <p>This section was generated by <strong>AutoGen</strong>,
4872 using the <code>agtexi-cmd</code> template and the option descriptions for the <code>ocsptool</code> program.
4873 This software is released under the GNU General Public License, version 3 or later.
4874 </p>
4875
4876 <a name="ocsptool-usage"></a><a name="ocsptool-help_002fusage-_0028_002d_002dhelp_0029"></a>
4877 <h4 class="subsubheading">ocsptool help/usage (<samp>--help</samp>)</h4>
4878 <a name="index-ocsptool-help"></a>
4879
4880 <p>This is the automatically generated usage text for ocsptool.
4881 </p>
4882 <p>The text printed is the same whether selected with the <code>help</code> option
4883 (<samp>--help</samp>) or the <code>more-help</code> option (<samp>--more-help</samp>).  <code>more-help</code> will print
4884 the usage text by passing it through a pager program.
4885 <code>more-help</code> is disabled on platforms without a working
4886 <code>fork(2)</code> function.  The <code>PAGER</code> environment variable is
4887 used to select the program, defaulting to <samp>more</samp>.  Both will exit
4888 with a status code of 0.
4889 </p>
4890 <div class="example">
4891 <pre class="example">ocsptool - GnuTLS OCSP tool
4892 Usage:  ocsptool [ -&lt;flag&gt; [&lt;val&gt;] | --&lt;name&gt;[{=| }&lt;val&gt;] ]...
4893
4894    -d, --debug=num            Enable debugging
4895                                 - it must be in the range:
4896                                   0 to 9999
4897    -V, --verbose              More verbose output
4898                                 - may appear multiple times
4899        --infile=file          Input file
4900                                 - file must pre-exist
4901        --outfile=str          Output file
4902        --ask[=arg]            Ask an OCSP/HTTP server on a certificate validity
4903                                 - requires these options:
4904                                 load-cert
4905                                 load-issuer
4906    -e, --verify-response      Verify response
4907    -i, --request-info         Print information on a OCSP request
4908    -j, --response-info        Print information on a OCSP response
4909    -q, --generate-request     Generate an OCSP request
4910        --nonce                Use (or not) a nonce to OCSP request
4911                                 - disabled as '--no-nonce'
4912        --load-issuer=file     Read issuer certificate from file
4913                                 - file must pre-exist
4914        --load-cert=file       Read certificate to check from file
4915                                 - file must pre-exist
4916        --load-trust=file      Read OCSP trust anchors from file
4917                                 - prohibits the option 'load-signer'
4918                                 - file must pre-exist
4919        --load-signer=file     Read OCSP response signer from file
4920                                 - prohibits the option 'load-trust'
4921                                 - file must pre-exist
4922        --inder                Use DER format for input certificates and private keys
4923                                 - disabled as '--no-inder'
4924    -Q, --load-request=file    Read DER encoded OCSP request from file
4925                                 - file must pre-exist
4926    -S, --load-response=file   Read DER encoded OCSP response from file
4927                                 - file must pre-exist
4928    -v, --version[=arg]        output version information and exit
4929    -h, --help                 display extended usage information and exit
4930    -!, --more-help            extended usage information passed thru pager
4931
4932 Options are specified by doubled hyphens and their name or by a single
4933 hyphen and the flag character.
4934
4935 Ocsptool is a program that can parse and print information about OCSP
4936 requests/responses, generate requests and verify responses.
4937
4938 </pre></div>
4939
4940 <a name="ocsptool-debug"></a><a name="debug-option-_0028_002dd_0029-3"></a>
4941 <h4 class="subsubheading">debug option (-d)</h4>
4942
4943 <p>This is the &ldquo;enable debugging&rdquo; option.
4944 This option takes a number argument.
4945 Specifies the debug level.
4946 <a name="ocsptool-ask"></a></p><a name="ask-option"></a>
4947 <h4 class="subsubheading">ask option</h4>
4948
4949 <p>This is the &ldquo;ask an ocsp/http server on a certificate validity&rdquo; option.
4950 This option takes an optional string argument <samp>server name|url</samp>.
4951 </p>
4952 <p>This option has some usage constraints.  It:
4953 </p><ul>
4954 <li> must appear in combination with the following options:
4955 load-cert, load-issuer.
4956 </li></ul>
4957
4958 <p>Connects to the specified HTTP OCSP server and queries on the validity of the loaded certificate.
4959 <a name="ocsptool-exit-status"></a></p><a name="ocsptool-exit-status-1"></a>
4960 <h4 class="subsubheading">ocsptool exit status</h4>
4961
4962 <p>One of the following exit values will be returned:
4963 </p><dl compact="compact">
4964 <dt>&lsquo;<samp>0 (EXIT_SUCCESS)</samp>&rsquo;</dt>
4965 <dd><p>Successful program execution.
4966 </p></dd>
4967 <dt>&lsquo;<samp>1 (EXIT_FAILURE)</samp>&rsquo;</dt>
4968 <dd><p>The operation failed or the command syntax was not valid.
4969 </p></dd>
4970 </dl>
4971 <a name="ocsptool-See-Also"></a><a name="ocsptool-See-Also-1"></a>
4972 <h4 class="subsubheading">ocsptool See Also</h4>
4973 <p>certtool (1)
4974 <a name="ocsptool-Examples"></a></p><a name="ocsptool-Examples-1"></a>
4975 <h4 class="subsubheading">ocsptool Examples</h4>
4976 <a name="Print-information-about-an-OCSP-request"></a>
4977 <h4 class="subsubheading">Print information about an OCSP request</h4>
4978
4979 <p>To parse an OCSP request and print information about the content, the
4980 <code>-i</code> or <code>--request-info</code> parameter may be used as follows.
4981 The <code>-Q</code> parameter specify the name of the file containing the
4982 OCSP request, and it should contain the OCSP request in binary DER
4983 format.
4984 </p>
4985 <div class="example">
4986 <pre class="example">$ ocsptool -i -Q ocsp-request.der
4987 </pre></div>
4988
4989 <p>The input file may also be sent to standard input like this:
4990 </p>
4991 <div class="example">
4992 <pre class="example">$ cat ocsp-request.der | ocsptool --request-info
4993 </pre></div>
4994
4995 <a name="Print-information-about-an-OCSP-response"></a>
4996 <h4 class="subsubheading">Print information about an OCSP response</h4>
4997
4998 <p>Similar to parsing OCSP requests, OCSP responses can be parsed using
4999 the <code>-j</code> or <code>--response-info</code> as follows.
5000 </p>
5001 <div class="example">
5002 <pre class="example">$ ocsptool -j -Q ocsp-response.der
5003 $ cat ocsp-response.der | ocsptool --response-info
5004 </pre></div>
5005
5006 <a name="Generate-an-OCSP-request"></a>
5007 <h4 class="subsubheading">Generate an OCSP request</h4>
5008
5009 <p>The <code>-q</code> or <code>--generate-request</code> parameters are used to
5010 generate an OCSP request.  By default the OCSP request is written to
5011 standard output in binary DER format, but can be stored in a file
5012 using <code>--outfile</code>.  To generate an OCSP request the issuer of the
5013 certificate to check needs to be specified with <code>--load-issuer</code>
5014 and the certificate to check with <code>--load-cert</code>.  By default PEM
5015 format is used for these files, although <code>--inder</code> can be used to
5016 specify that the input files are in DER format.
5017 </p>
5018 <div class="example">
5019 <pre class="example">$ ocsptool -q --load-issuer issuer.pem --load-cert client.pem \
5020            --outfile ocsp-request.der
5021 </pre></div>
5022
5023 <p>When generating OCSP requests, the tool will add an OCSP extension
5024 containing a nonce.  This behaviour can be disabled by specifying
5025 <code>--no-nonce</code>.
5026 </p>
5027 <a name="Verify-signature-in-OCSP-response"></a>
5028 <h4 class="subsubheading">Verify signature in OCSP response</h4>
5029
5030 <p>To verify the signature in an OCSP response the <code>-e</code> or
5031 <code>--verify-response</code> parameter is used.  The tool will read an
5032 OCSP response in DER format from standard input, or from the file
5033 specified by <code>--load-response</code>.  The OCSP response is verified
5034 against a set of trust anchors, which are specified using
5035 <code>--load-trust</code>.  The trust anchors are concatenated certificates
5036 in PEM format.  The certificate that signed the OCSP response needs to
5037 be in the set of trust anchors, or the issuer of the signer
5038 certificate needs to be in the set of trust anchors and the OCSP
5039 Extended Key Usage bit has to be asserted in the signer certificate.
5040 </p>
5041 <div class="example">
5042 <pre class="example">$ ocsptool -e --load-trust issuer.pem \
5043            --load-response ocsp-response.der
5044 </pre></div>
5045
5046 <p>The tool will print status of verification.
5047 </p>
5048 <a name="Verify-signature-in-OCSP-response-against-given-certificate"></a>
5049 <h4 class="subsubheading">Verify signature in OCSP response against given certificate</h4>
5050
5051 <p>It is possible to override the normal trust logic if you know that a
5052 certain certificate is supposed to have signed the OCSP response, and
5053 you want to use it to check the signature.  This is achieved using
5054 <code>--load-signer</code> instead of <code>--load-trust</code>.  This will load
5055 one certificate and it will be used to verify the signature in the
5056 OCSP response.  It will not check the Extended Key Usage bit.
5057 </p>
5058 <div class="example">
5059 <pre class="example">$ ocsptool -e --load-signer ocsp-signer.pem \
5060            --load-response ocsp-response.der
5061 </pre></div>
5062
5063 <p>This approach is normally only relevant in two situations.  The first
5064 is when the OCSP response does not contain a copy of the signer
5065 certificate, so the <code>--load-trust</code> code would fail.  The second
5066 is if you want to avoid the indirect mode where the OCSP response
5067 signer certificate is signed by a trust anchor.
5068 </p>
5069 <a name="Real_002dworld-example"></a>
5070 <h4 class="subsubheading">Real-world example</h4>
5071
5072 <p>Here is an example of how to generate an OCSP request for a
5073 certificate and to verify the response.  For illustration we&rsquo;ll use
5074 the <code>blog.josefsson.org</code> host, which (as of writing) uses a
5075 certificate from CACert.  First we&rsquo;ll use <code>gnutls-cli</code> to get a
5076 copy of the server certificate chain.  The server is not required to
5077 send this information, but this particular one is configured to do so.
5078 </p>
5079 <div class="example">
5080 <pre class="example">$ echo | gnutls-cli -p 443 blog.josefsson.org --print-cert &gt; chain.pem
5081 </pre></div>
5082
5083 <p>Use a text editor on <code>chain.pem</code> to create three files for each
5084 separate certificates, called <code>cert.pem</code> for the first
5085 certificate for the domain itself, secondly <code>issuer.pem</code> for the
5086 intermediate certificate and <code>root.pem</code> for the final root
5087 certificate.
5088 </p>
5089 <p>The domain certificate normally contains a pointer to where the OCSP
5090 responder is located, in the Authority Information Access Information
5091 extension.  For example, from <code>certtool -i &lt; cert.pem</code> there is
5092 this information:
5093 </p>
5094 <div class="example">
5095 <pre class="example">Authority Information Access Information (not critical):
5096 Access Method: 1.3.6.1.5.5.7.48.1 (id-ad-ocsp)
5097 Access Location URI: http://ocsp.CAcert.org/
5098 </pre></div>
5099
5100 <p>This means the CA support OCSP queries over HTTP.  We are now ready to
5101 create a OCSP request for the certificate.
5102 </p>
5103 <div class="example">
5104 <pre class="example">$ ocsptool --ask ocsp.CAcert.org --load-issuer issuer.pem \
5105            --load-cert cert.pem --outfile ocsp-response.der
5106 </pre></div>
5107
5108 <p>The request is sent via HTTP to the OCSP server address specified. If the
5109 address is ommited ocsptool will use the address stored in the certificate.
5110 </p>
5111 <hr>
5112 <a name="danetool-Invocation"></a>
5113 <div class="header">
5114 <p>
5115 Previous: <a href="#ocsptool-Invocation" accesskey="p" rel="prev">ocsptool Invocation</a>, Up: <a href="#More-on-certificate-authentication" accesskey="u" rel="up">More on certificate authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
5116 </div>
5117 <a name="Invoking-danetool"></a>
5118 <h4 class="subsection">4.2.7 Invoking danetool</h4>
5119 <a name="index-danetool"></a>
5120
5121
5122 <p>Tool to generate and check DNS resource records for the DANE protocol.
5123 </p>
5124 <p>This section was generated by <strong>AutoGen</strong>,
5125 using the <code>agtexi-cmd</code> template and the option descriptions for the <code>danetool</code> program.
5126 This software is released under the GNU General Public License, version 3 or later.
5127 </p>
5128
5129 <a name="danetool-usage"></a><a name="danetool-help_002fusage-_0028_002d_002dhelp_0029"></a>
5130 <h4 class="subsubheading">danetool help/usage (<samp>--help</samp>)</h4>
5131 <a name="index-danetool-help"></a>
5132
5133 <p>This is the automatically generated usage text for danetool.
5134 </p>
5135 <p>The text printed is the same whether selected with the <code>help</code> option
5136 (<samp>--help</samp>) or the <code>more-help</code> option (<samp>--more-help</samp>).  <code>more-help</code> will print
5137 the usage text by passing it through a pager program.
5138 <code>more-help</code> is disabled on platforms without a working
5139 <code>fork(2)</code> function.  The <code>PAGER</code> environment variable is
5140 used to select the program, defaulting to <samp>more</samp>.  Both will exit
5141 with a status code of 0.
5142 </p>
5143 <div class="example">
5144 <pre class="example">danetool is unavailable - no --help
5145 </pre></div>
5146
5147 <a name="danetool-debug"></a><a name="debug-option-_0028_002dd_0029-4"></a>
5148 <h4 class="subsubheading">debug option (-d)</h4>
5149
5150 <p>This is the &ldquo;enable debugging&rdquo; option.
5151 This option takes a number argument.
5152 Specifies the debug level.
5153 <a name="danetool-load_002dpubkey"></a></p><a name="load_002dpubkey-option-1"></a>
5154 <h4 class="subsubheading">load-pubkey option</h4>
5155
5156 <p>This is the &ldquo;loads a public key file&rdquo; option.
5157 This option takes a string argument.
5158 This can be either a file or a PKCS #11 URL
5159 <a name="danetool-load_002dcertificate"></a></p><a name="load_002dcertificate-option-1"></a>
5160 <h4 class="subsubheading">load-certificate option</h4>
5161
5162 <p>This is the &ldquo;loads a certificate file&rdquo; option.
5163 This option takes a string argument.
5164 This can be either a file or a PKCS #11 URL
5165 <a name="danetool-dlv"></a></p><a name="dlv-option"></a>
5166 <h4 class="subsubheading">dlv option</h4>
5167
5168 <p>This is the &ldquo;sets a dlv file&rdquo; option.
5169 This option takes a string argument.
5170 This sets a DLV file to be used for DNSSEC verification.
5171 <a name="danetool-hash"></a></p><a name="hash-option-1"></a>
5172 <h4 class="subsubheading">hash option</h4>
5173
5174 <p>This is the &ldquo;hash algorithm to use for signing&rdquo; option.
5175 This option takes a string argument.
5176 Available hash functions are SHA1, RMD160, SHA256, SHA384, SHA512.
5177 <a name="danetool-check"></a></p><a name="check-option"></a>
5178 <h4 class="subsubheading">check option</h4>
5179
5180 <p>This is the &ldquo;check a host&rsquo;s dane tlsa entry&rdquo; option.
5181 This option takes a string argument.
5182 Obtains the DANE TLSA entry from the given hostname and prints information. Note that the actual certificate of the host can be provided using &ndash;load-certificate, otherwise danetool will connect to the server to obtain it. The exit code on verification success will be zero.
5183 <a name="danetool-check_002dee"></a></p><a name="check_002dee-option"></a>
5184 <h4 class="subsubheading">check-ee option</h4>
5185
5186 <p>This is the &ldquo;check only the end-entity&rsquo;s certificate&rdquo; option.
5187 Checks the end-entity&rsquo;s certificate only. Trust anchors or CAs are not considered.
5188 <a name="danetool-check_002dca"></a></p><a name="check_002dca-option"></a>
5189 <h4 class="subsubheading">check-ca option</h4>
5190
5191 <p>This is the &ldquo;check only the ca&rsquo;s certificate&rdquo; option.
5192 Checks the trust anchor&rsquo;s and CA&rsquo;s certificate only. End-entities are not considered.
5193 <a name="danetool-tlsa_002drr"></a></p><a name="tlsa_002drr-option"></a>
5194 <h4 class="subsubheading">tlsa-rr option</h4>
5195
5196 <p>This is the &ldquo;print the dane rr data on a certificate or public key&rdquo; option.
5197 </p>
5198 <p>This option has some usage constraints.  It:
5199 </p><ul>
5200 <li> must appear in combination with the following options:
5201 host.
5202 </li></ul>
5203
5204 <p>This command prints the DANE RR data needed to enable DANE on a DNS server.
5205 <a name="danetool-host"></a></p><a name="host-option"></a>
5206 <h4 class="subsubheading">host option</h4>
5207
5208 <p>This is the &ldquo;specify the hostname to be used in the dane rr&rdquo; option.
5209 This option takes a string argument <samp>Hostname</samp>.
5210 This command sets the hostname for the DANE RR.
5211 <a name="danetool-proto"></a></p><a name="proto-option"></a>
5212 <h4 class="subsubheading">proto option</h4>
5213
5214 <p>This is the &ldquo;the protocol set for dane data (tcp, udp etc.)&rdquo; option.
5215 This option takes a string argument <samp>Protocol</samp>.
5216 This command specifies the protocol for the service set in the DANE data.
5217 <a name="danetool-app_002dproto"></a></p><a name="app_002dproto-option"></a>
5218 <h4 class="subsubheading">app-proto option</h4>
5219
5220 <p>This is the &ldquo;the application protocol to be used to obtain the server&rsquo;s certificate (https, ftp, smtp, imap)&rdquo; option.
5221 This option takes a string argument.
5222 When the server&rsquo;s certificate isn&rsquo;t provided danetool will connect to the server to obtain the certificate. In that case it is required to known the protocol to talk with the server prior to initiating the TLS handshake.
5223 <a name="danetool-ca"></a></p><a name="ca-option-1"></a>
5224 <h4 class="subsubheading">ca option</h4>
5225
5226 <p>This is the &ldquo;whether the provided certificate or public key is a certificate authority&rdquo; option.
5227 Marks the DANE RR as a CA certificate if specified.
5228 <a name="danetool-x509"></a></p><a name="x509-option"></a>
5229 <h4 class="subsubheading">x509 option</h4>
5230
5231 <p>This is the &ldquo;use the hash of the x.509 certificate, rather than the public key&rdquo; option.
5232 This option forces the generated record to contain the hash of the full X.509 certificate. By default only the hash of the public key is used.
5233 <a name="danetool-local"></a></p><a name="local-option"></a>
5234 <h4 class="subsubheading">local option</h4>
5235
5236 <p>This is an alias for the <code>domain</code> option,
5237 see <a href="#danetool-domain">the domain option documentation</a>.
5238 </p>
5239 <a name="danetool-domain"></a><a name="domain-option"></a>
5240 <h4 class="subsubheading">domain option</h4>
5241
5242 <p>This is the &ldquo;the provided certificate or public key is issued by the local domain&rdquo; option.
5243 </p>
5244 <p>This option has some usage constraints.  It:
5245 </p><ul>
5246 <li> can be disabled with &ndash;no-domain.
5247 </li><li> It is enabled by default.
5248 </li></ul>
5249
5250 <p>DANE distinguishes certificates and public keys offered via the DNSSEC to trusted and local entities. This flag indicates that this is a domain-issued certificate, meaning that there could be no CA involved.
5251 <a name="danetool-local_002ddns"></a></p><a name="local_002ddns-option"></a>
5252 <h4 class="subsubheading">local-dns option</h4>
5253
5254 <p>This is the &ldquo;use the local dns server for dnssec resolving&rdquo; option.
5255 </p>
5256 <p>This option has some usage constraints.  It:
5257 </p><ul>
5258 <li> can be disabled with &ndash;no-local-dns.
5259 </li></ul>
5260
5261 <p>This option will use the local DNS server for DNSSEC.
5262 This is disabled by default due to many servers not allowing DNSSEC.
5263 <a name="danetool-insecure"></a></p><a name="insecure-option"></a>
5264 <h4 class="subsubheading">insecure option</h4>
5265
5266 <p>This is the &ldquo;do not verify any dnssec signature&rdquo; option.
5267 Ignores any DNSSEC signature verification results.
5268 <a name="danetool-inder"></a></p><a name="inder-option-3"></a>
5269 <h4 class="subsubheading">inder option</h4>
5270
5271 <p>This is the &ldquo;use der format for input certificates and private keys&rdquo; option.
5272 </p>
5273 <p>This option has some usage constraints.  It:
5274 </p><ul>
5275 <li> can be disabled with &ndash;no-inder.
5276 </li></ul>
5277
5278 <p>The input files will be assumed to be in DER or RAW format.
5279 Unlike options that in PEM input would allow multiple input data (e.g. multiple
5280 certificates), when reading in DER format a single data structure is read.
5281 <a name="danetool-inraw"></a></p><a name="inraw-option-2"></a>
5282 <h4 class="subsubheading">inraw option</h4>
5283
5284 <p>This is an alias for the <code>inder</code> option,
5285 see <a href="#danetool-inder">the inder option documentation</a>.
5286 </p>
5287 <a name="danetool-print_002draw"></a><a name="print_002draw-option"></a>
5288 <h4 class="subsubheading">print-raw option</h4>
5289
5290 <p>This is the &ldquo;print the received dane data in raw format&rdquo; option.
5291 </p>
5292 <p>This option has some usage constraints.  It:
5293 </p><ul>
5294 <li> can be disabled with &ndash;no-print-raw.
5295 </li></ul>
5296
5297 <p>This option will print the received DANE data.
5298 <a name="danetool-quiet"></a></p><a name="quiet-option"></a>
5299 <h4 class="subsubheading">quiet option</h4>
5300
5301 <p>This is the &ldquo;suppress several informational messages&rdquo; option.
5302 In that case on the exit code can be used as an indication of verification success
5303 <a name="danetool-exit-status"></a></p><a name="danetool-exit-status-1"></a>
5304 <h4 class="subsubheading">danetool exit status</h4>
5305
5306 <p>One of the following exit values will be returned:
5307 </p><dl compact="compact">
5308 <dt>&lsquo;<samp>0 (EXIT_SUCCESS)</samp>&rsquo;</dt>
5309 <dd><p>Successful program execution.
5310 </p></dd>
5311 <dt>&lsquo;<samp>1 (EXIT_FAILURE)</samp>&rsquo;</dt>
5312 <dd><p>The operation failed or the command syntax was not valid.
5313 </p></dd>
5314 </dl>
5315 <a name="danetool-See-Also"></a><a name="danetool-See-Also-1"></a>
5316 <h4 class="subsubheading">danetool See Also</h4>
5317 <p>certtool (1)
5318 <a name="danetool-Examples"></a></p><a name="danetool-Examples-1"></a>
5319 <h4 class="subsubheading">danetool Examples</h4>
5320 <a name="DANE-TLSA-RR-generation"></a>
5321 <h4 class="subsubheading">DANE TLSA RR generation</h4>
5322
5323 <p>To create a DANE TLSA resource record for a certificate (or public key)
5324 that was issued localy and may or may not be signed by a CA use the following command.
5325 </p><div class="example">
5326 <pre class="example">$ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem
5327 </pre></div>
5328
5329 <p>To create a DANE TLSA resource record for a CA signed certificate, which will
5330 be marked as such use the following command.
5331 </p><div class="example">
5332 <pre class="example">$ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem \
5333   --no-domain
5334 </pre></div>
5335
5336 <p>The former is useful to add in your DNS entry even if your certificate is signed
5337 by a CA. That way even users who do not trust your CA will be able to verify your
5338 certificate using DANE.
5339 </p>
5340 <p>In order to create a record for the CA signer of your certificate use the following.
5341 </p><div class="example">
5342 <pre class="example">$ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem \
5343   --ca --no-domain
5344 </pre></div>
5345
5346 <p>To read a server&rsquo;s DANE TLSA entry, use:
5347 </p><div class="example">
5348 <pre class="example">$ danetool --check www.example.com --proto tcp --port 443
5349 </pre></div>
5350
5351 <p>To verify a server&rsquo;s DANE TLSA entry, use:
5352 </p><div class="example">
5353 <pre class="example">$ danetool --check www.example.com --proto tcp --port 443 --load-certificate chain.pem
5354 </pre></div>
5355
5356 <hr>
5357 <a name="Shared_002dkey-and-anonymous-authentication"></a>
5358 <div class="header">
5359 <p>
5360 Next: <a href="#Selecting-an-appropriate-authentication-method" accesskey="n" rel="next">Selecting an appropriate authentication method</a>, Previous: <a href="#More-on-certificate-authentication" accesskey="p" rel="prev">More on certificate authentication</a>, Up: <a href="#Authentication-methods" accesskey="u" rel="up">Authentication methods</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
5361 </div>
5362 <a name="Shared_002dkey-and-anonymous-authentication-1"></a>
5363 <h3 class="section">4.3 Shared-key and anonymous authentication</h3>
5364
5365 <p>In addition to certificate authentication, the TLS protocol may be
5366 used with password, shared-key and anonymous authentication methods.
5367 The rest of this chapter discusses details of these methods.
5368 </p>
5369 <table class="menu" border="0" cellspacing="0">
5370 <tr><td align="left" valign="top">&bull; <a href="#SRP-authentication" accesskey="1">SRP authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
5371 </td></tr>
5372 <tr><td align="left" valign="top">&bull; <a href="#PSK-authentication" accesskey="2">PSK authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
5373 </td></tr>
5374 <tr><td align="left" valign="top">&bull; <a href="#Anonymous-authentication" accesskey="3">Anonymous authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
5375 </td></tr>
5376 </table>
5377
5378 <hr>
5379 <a name="SRP-authentication"></a>
5380 <div class="header">
5381 <p>
5382 Next: <a href="#PSK-authentication" accesskey="n" rel="next">PSK authentication</a>, Up: <a href="#Shared_002dkey-and-anonymous-authentication" accesskey="u" rel="up">Shared-key and anonymous authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
5383 </div>
5384 <a name="SRP-authentication-1"></a>
5385 <h4 class="subsection">4.3.1 SRP authentication</h4>
5386
5387 <table class="menu" border="0" cellspacing="0">
5388 <tr><td align="left" valign="top">&bull; <a href="#Authentication-using-SRP" accesskey="1">Authentication using SRP</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
5389 </td></tr>
5390 <tr><td align="left" valign="top">&bull; <a href="#srptool-Invocation" accesskey="2">srptool Invocation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Invoking srptool
5391 </td></tr>
5392 </table>
5393
5394 <hr>
5395 <a name="Authentication-using-SRP"></a>
5396 <div class="header">
5397 <p>
5398 Next: <a href="#srptool-Invocation" accesskey="n" rel="next">srptool Invocation</a>, Up: <a href="#SRP-authentication" accesskey="u" rel="up">SRP authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
5399 </div>
5400 <a name="Authentication-using-SRP-1"></a>
5401 <h4 class="subsubsection">4.3.1.1 Authentication using <acronym>SRP</acronym></h4>
5402 <a name="index-SRP-authentication"></a>
5403
5404 <p><acronym>GnuTLS</acronym> supports authentication via the Secure Remote Password
5405 or <acronym>SRP</acronym> protocol (see [<em>RFC2945,TOMSRP</em>] for a description).
5406 The <acronym>SRP</acronym> key exchange is an extension to the
5407 <acronym>TLS</acronym> protocol, and it provides an authenticated with a
5408 password key exchange. The peers can be identified using a single password,
5409 or there can be combinations where the client is authenticated using <acronym>SRP</acronym>
5410 and the server using a certificate.
5411 </p>
5412 <p>The advantage of <acronym>SRP</acronym> authentication, over other proposed
5413 secure password authentication schemes, is that <acronym>SRP</acronym> is not
5414 susceptible to off-line dictionary attacks.
5415 Moreover, SRP does not require the server to hold the user&rsquo;s password.
5416 This kind of protection is similar to the one used traditionally in the <acronym>UNIX</acronym>
5417 <samp>/etc/passwd</samp> file, where the contents of this file did not cause
5418 harm to the system security if they were revealed.  The <acronym>SRP</acronym>
5419 needs instead of the plain password something called a verifier, which
5420 is calculated using the user&rsquo;s password, and if stolen cannot be used
5421 to impersonate the user.
5422 </p>
5423 <p>Typical conventions in SRP are a password file, called <samp>tpasswd</samp> that
5424 holds the SRP verifiers (encoded passwords) and another file, <samp>tpasswd.conf</samp>,
5425 which holds the allowed SRP parameters.  The included in GnuTLS helper
5426 follow those conventions. The srptool program, discussed in the next section
5427 is a tool to manipulate the SRP parameters.
5428 </p>
5429 <p>The implementation in <acronym>GnuTLS</acronym> is based on [<em>TLSSRP</em>]. The
5430 supported key exchange methods are shown below.
5431 </p>
5432 <dl compact="compact">
5433 <dt><code>SRP:</code></dt>
5434 <dd><p>Authentication using the <acronym>SRP</acronym> protocol.
5435 </p>
5436 </dd>
5437 <dt><code>SRP_DSS:</code></dt>
5438 <dd><p>Client authentication using the <acronym>SRP</acronym> protocol. Server is
5439 authenticated using a certificate with DSA parameters.
5440 </p>
5441 </dd>
5442 <dt><code>SRP_RSA:</code></dt>
5443 <dd><p>Client authentication using the <acronym>SRP</acronym> protocol. Server is
5444 authenticated using a certificate with RSA parameters.
5445 </p>
5446 </dd>
5447 </dl>
5448
5449
5450
5451
5452
5453
5454 <dl>
5455 <dt><a name="index-gnutls_005fsrp_005fverifier"></a>Function: <em>int</em> <strong>gnutls_srp_verifier</strong> <em>(const char * <var>username</var>, const char * <var>password</var>, const gnutls_datum_t * <var>salt</var>, const gnutls_datum_t * <var>generator</var>, const gnutls_datum_t * <var>prime</var>, gnutls_datum_t * <var>res</var>)</em></dt>
5456 <dd><p><var>username</var>: is the user&rsquo;s name
5457 </p>
5458 <p><var>password</var>: is the user&rsquo;s password
5459 </p>
5460 <p><var>salt</var>: should be some randomly generated bytes
5461 </p>
5462 <p><var>generator</var>: is the generator of the group
5463 </p>
5464 <p><var>prime</var>: is the group&rsquo;s prime
5465 </p>
5466 <p><var>res</var>: where the verifier will be stored.
5467 </p>
5468 <p>This function will create an SRP verifier, as specified in
5469 RFC2945.  The  <code>prime</code> and  <code>generator</code> should be one of the static
5470 parameters defined in gnutls/gnutls.h or may be generated.
5471 </p>
5472 <p>The verifier will be allocated with  <code>gnutls_malloc</code> () and will be stored in
5473  <code>res</code> using binary format.
5474 </p>
5475 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or an
5476 error code.
5477 </p></dd></dl>
5478
5479 <dl compact="compact">
5480 <dt><code><var>int</var> <a href="#gnutls_005fsrp_005fbase64_005fencode_005falloc">gnutls_srp_base64_encode_alloc</a> (const gnutls_datum_t * <var>data</var>, gnutls_datum_t * <var>result</var>)</code></dt>
5481 <dt><code><var>int</var> <a href="#gnutls_005fsrp_005fbase64_005fdecode_005falloc">gnutls_srp_base64_decode_alloc</a> (const gnutls_datum_t * <var>b64_data</var>, gnutls_datum_t * <var>result</var>)</code></dt>
5482 </dl>
5483
5484 <hr>
5485 <a name="srptool-Invocation"></a>
5486 <div class="header">
5487 <p>
5488 Previous: <a href="#Authentication-using-SRP" accesskey="p" rel="prev">Authentication using SRP</a>, Up: <a href="#SRP-authentication" accesskey="u" rel="up">SRP authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
5489 </div>
5490 <a name="Invoking-srptool"></a>
5491 <h4 class="subsubsection">4.3.1.2 Invoking srptool</h4>
5492 <a name="index-srptool"></a>
5493
5494
5495 <p>Simple program that emulates the programs in the Stanford SRP (Secure
5496 Remote Password) libraries using GnuTLS.  It is intended for use in  places
5497 where you don&rsquo;t expect SRP authentication to be the used for system users.
5498 </p>
5499 <p>In  brief,  to use SRP you need to create two files. These are the password
5500 file that holds the users and the verifiers associated with  them  and  the
5501 configuration file to hold the group parameters (called tpasswd.conf).
5502 </p>
5503 <p>This section was generated by <strong>AutoGen</strong>,
5504 using the <code>agtexi-cmd</code> template and the option descriptions for the <code>srptool</code> program.
5505 This software is released under the GNU General Public License, version 3 or later.
5506 </p>
5507
5508 <a name="srptool-usage"></a><a name="srptool-help_002fusage-_0028_002d_002dhelp_0029"></a>
5509 <h4 class="subsubheading">srptool help/usage (<samp>--help</samp>)</h4>
5510 <a name="index-srptool-help"></a>
5511
5512 <p>This is the automatically generated usage text for srptool.
5513 </p>
5514 <p>The text printed is the same whether selected with the <code>help</code> option
5515 (<samp>--help</samp>) or the <code>more-help</code> option (<samp>--more-help</samp>).  <code>more-help</code> will print
5516 the usage text by passing it through a pager program.
5517 <code>more-help</code> is disabled on platforms without a working
5518 <code>fork(2)</code> function.  The <code>PAGER</code> environment variable is
5519 used to select the program, defaulting to <samp>more</samp>.  Both will exit
5520 with a status code of 0.
5521 </p>
5522 <div class="example">
5523 <pre class="example">srptool - GnuTLS SRP tool
5524 Usage:  srptool [ -&lt;flag&gt; [&lt;val&gt;] | --&lt;name&gt;[{=| }&lt;val&gt;] ]...
5525
5526    -d, --debug=num            Enable debugging
5527                                 - it must be in the range:
5528                                   0 to 9999
5529    -i, --index=num            specify the index of the group parameters in tpasswd.conf to use
5530    -u, --username=str         specify a username
5531    -p, --passwd=str           specify a password file
5532    -s, --salt=num             specify salt size
5533        --verify               just verify the password.
5534    -v, --passwd-conf=str      specify a password conf file.
5535        --create-conf=str      Generate a password configuration file.
5536    -v, --version[=arg]        output version information and exit
5537    -h, --help                 display extended usage information and exit
5538    -!, --more-help            extended usage information passed thru pager
5539
5540 Options are specified by doubled hyphens and their name or by a single
5541 hyphen and the flag character.
5542
5543 Simple program that emulates the programs in the Stanford SRP (Secure
5544 Remote Password) libraries using GnuTLS.  It is intended for use in places
5545 where you don't expect SRP authentication to be the used for system users.
5546
5547 In brief, to use SRP you need to create two files.  These are the password
5548 file that holds the users and the verifiers associated with them and the
5549 configuration file to hold the group parameters (called tpasswd.conf).
5550
5551 </pre></div>
5552
5553 <a name="srptool-debug"></a><a name="debug-option-_0028_002dd_0029-5"></a>
5554 <h4 class="subsubheading">debug option (-d)</h4>
5555
5556 <p>This is the &ldquo;enable debugging&rdquo; option.
5557 This option takes a number argument.
5558 Specifies the debug level.
5559 <a name="srptool-verify"></a></p><a name="verify-option-1"></a>
5560 <h4 class="subsubheading">verify option</h4>
5561
5562 <p>This is the &ldquo;just verify the password.&rdquo; option.
5563 Verifies the password provided against the password file.
5564 <a name="srptool-passwd_002dconf"></a></p><a name="passwd_002dconf-option-_0028_002dv_0029"></a>
5565 <h4 class="subsubheading">passwd-conf option (-v)</h4>
5566
5567 <p>This is the &ldquo;specify a password conf file.&rdquo; option.
5568 This option takes a string argument.
5569 Specify a filename or a PKCS #11 URL to read the CAs from.
5570 <a name="srptool-create_002dconf"></a></p><a name="create_002dconf-option"></a>
5571 <h4 class="subsubheading">create-conf option</h4>
5572
5573 <p>This is the &ldquo;generate a password configuration file.&rdquo; option.
5574 This option takes a string argument.
5575 This generates a password configuration file (tpasswd.conf)
5576 containing the required for TLS parameters.
5577 <a name="srptool-exit-status"></a></p><a name="srptool-exit-status-1"></a>
5578 <h4 class="subsubheading">srptool exit status</h4>
5579
5580 <p>One of the following exit values will be returned:
5581 </p><dl compact="compact">
5582 <dt>&lsquo;<samp>0 (EXIT_SUCCESS)</samp>&rsquo;</dt>
5583 <dd><p>Successful program execution.
5584 </p></dd>
5585 <dt>&lsquo;<samp>1 (EXIT_FAILURE)</samp>&rsquo;</dt>
5586 <dd><p>The operation failed or the command syntax was not valid.
5587 </p></dd>
5588 </dl>
5589 <a name="srptool-See-Also"></a><a name="srptool-See-Also-1"></a>
5590 <h4 class="subsubheading">srptool See Also</h4>
5591 <p>gnutls-cli-debug (1), gnutls-serv (1), srptool (1), psktool (1), certtool (1)
5592 <a name="srptool-Examples"></a></p><a name="srptool-Examples-1"></a>
5593 <h4 class="subsubheading">srptool Examples</h4>
5594 <p>To create <samp>tpasswd.conf</samp> which holds the g and n values for SRP protocol
5595 (generator and a large prime), run:
5596 </p><div class="example">
5597 <pre class="example">$ srptool --create-conf /etc/tpasswd.conf
5598 </pre></div>
5599
5600 <p>This command will create <samp>/etc/tpasswd</samp> and will add user &rsquo;test&rsquo; (you
5601 will also be prompted for a password). Verifiers are stored by default
5602 in the way libsrp expects.
5603 </p><div class="example">
5604 <pre class="example">$ srptool --passwd /etc/tpasswd --passwd-conf /etc/tpasswd.conf -u test
5605 </pre></div>
5606
5607
5608 <p>This command will check against a password. If the password matches
5609 the one in <samp>/etc/tpasswd</samp> you will get an ok.
5610 </p><div class="example">
5611 <pre class="example">$ srptool --passwd /etc/tpasswd --passwd\-conf /etc/tpasswd.conf --verify -u test
5612 </pre></div>
5613
5614 <hr>
5615 <a name="PSK-authentication"></a>
5616 <div class="header">
5617 <p>
5618 Next: <a href="#Anonymous-authentication" accesskey="n" rel="next">Anonymous authentication</a>, Previous: <a href="#SRP-authentication" accesskey="p" rel="prev">SRP authentication</a>, Up: <a href="#Shared_002dkey-and-anonymous-authentication" accesskey="u" rel="up">Shared-key and anonymous authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
5619 </div>
5620 <a name="PSK-authentication-1"></a>
5621 <h4 class="subsection">4.3.2 PSK authentication</h4>
5622
5623 <table class="menu" border="0" cellspacing="0">
5624 <tr><td align="left" valign="top">&bull; <a href="#Authentication-using-PSK" accesskey="1">Authentication using PSK</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
5625 </td></tr>
5626 <tr><td align="left" valign="top">&bull; <a href="#psktool-Invocation" accesskey="2">psktool Invocation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Invoking psktool
5627 </td></tr>
5628 </table>
5629
5630 <hr>
5631 <a name="Authentication-using-PSK"></a>
5632 <div class="header">
5633 <p>
5634 Next: <a href="#psktool-Invocation" accesskey="n" rel="next">psktool Invocation</a>, Up: <a href="#PSK-authentication" accesskey="u" rel="up">PSK authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
5635 </div>
5636 <a name="Authentication-using-PSK-1"></a>
5637 <h4 class="subsubsection">4.3.2.1 Authentication using <acronym>PSK</acronym></h4>
5638 <a name="index-PSK-authentication"></a>
5639
5640 <p>Authentication using Pre-shared keys is a method to authenticate using
5641 usernames and binary keys. This protocol avoids making use of public
5642 key infrastructure and expensive calculations, thus it is suitable for
5643 constraint clients.
5644 </p>
5645 <p>The implementation in <acronym>GnuTLS</acronym> is based on [<em>TLSPSK</em>].
5646 The supported <acronym>PSK</acronym> key exchange methods are:
5647 </p>
5648 <dl compact="compact">
5649 <dt><code>PSK:</code></dt>
5650 <dd><p>Authentication using the <acronym>PSK</acronym> protocol.
5651 </p>
5652 </dd>
5653 <dt><code>DHE-PSK:</code></dt>
5654 <dd><p>Authentication using the <acronym>PSK</acronym> protocol and Diffie-Hellman key
5655 exchange.  This method offers perfect forward secrecy.
5656 </p>
5657 </dd>
5658 <dt><code>ECDHE-PSK:</code></dt>
5659 <dd><p>Authentication using the <acronym>PSK</acronym> protocol and Elliptic curve Diffie-Hellman key
5660 exchange.  This method offers perfect forward secrecy.
5661 </p>
5662 </dd>
5663 <dt><code>RSA-PSK:</code></dt>
5664 <dd><p>Authentication using the <acronym>PSK</acronym> protocol for the client and an RSA certificate
5665 for the server.
5666 </p>
5667 </dd>
5668 </dl>
5669
5670
5671 <p>Helper functions to generate and maintain <acronym>PSK</acronym> keys are also included
5672 in <acronym>GnuTLS</acronym>.
5673 </p>
5674 <dl compact="compact">
5675 <dt><code><var>int</var> <a href="#gnutls_005fkey_005fgenerate">gnutls_key_generate</a> (gnutls_datum_t * <var>key</var>, unsigned int <var>key_size</var>)</code></dt>
5676 <dt><code><var>int</var> <a href="#gnutls_005fhex_005fencode">gnutls_hex_encode</a> (const gnutls_datum_t * <var>data</var>, char * <var>result</var>, size_t * <var>result_size</var>)</code></dt>
5677 <dt><code><var>int</var> <a href="#gnutls_005fhex_005fdecode">gnutls_hex_decode</a> (const gnutls_datum_t * <var>hex_data</var>, void * <var>result</var>, size_t * <var>result_size</var>)</code></dt>
5678 </dl>
5679
5680 <hr>
5681 <a name="psktool-Invocation"></a>
5682 <div class="header">
5683 <p>
5684 Previous: <a href="#Authentication-using-PSK" accesskey="p" rel="prev">Authentication using PSK</a>, Up: <a href="#PSK-authentication" accesskey="u" rel="up">PSK authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
5685 </div>
5686 <a name="Invoking-psktool"></a>
5687 <h4 class="subsubsection">4.3.2.2 Invoking psktool</h4>
5688 <a name="index-psktool"></a>
5689
5690
5691 <p>Program  that generates random keys for use with TLS-PSK. The
5692 keys are stored in hexadecimal format in a key file.
5693 </p>
5694 <p>This section was generated by <strong>AutoGen</strong>,
5695 using the <code>agtexi-cmd</code> template and the option descriptions for the <code>psktool</code> program.
5696 This software is released under the GNU General Public License, version 3 or later.
5697 </p>
5698
5699 <a name="psktool-usage"></a><a name="psktool-help_002fusage-_0028_002d_002dhelp_0029"></a>
5700 <h4 class="subsubheading">psktool help/usage (<samp>--help</samp>)</h4>
5701 <a name="index-psktool-help"></a>
5702
5703 <p>This is the automatically generated usage text for psktool.
5704 </p>
5705 <p>The text printed is the same whether selected with the <code>help</code> option
5706 (<samp>--help</samp>) or the <code>more-help</code> option (<samp>--more-help</samp>).  <code>more-help</code> will print
5707 the usage text by passing it through a pager program.
5708 <code>more-help</code> is disabled on platforms without a working
5709 <code>fork(2)</code> function.  The <code>PAGER</code> environment variable is
5710 used to select the program, defaulting to <samp>more</samp>.  Both will exit
5711 with a status code of 0.
5712 </p>
5713 <div class="example">
5714 <pre class="example">psktool - GnuTLS PSK tool
5715 Usage:  psktool [ -&lt;flag&gt; [&lt;val&gt;] | --&lt;name&gt;[{=| }&lt;val&gt;] ]...
5716
5717    -d, --debug=num            Enable debugging
5718                                 - it must be in the range:
5719                                   0 to 9999
5720    -s, --keysize=num          specify the key size in bytes
5721                                 - it must be in the range:
5722                                   0 to 512
5723    -u, --username=str         specify a username
5724    -p, --passwd=str           specify a password file
5725    -v, --version[=arg]        output version information and exit
5726    -h, --help                 display extended usage information and exit
5727    -!, --more-help            extended usage information passed thru pager
5728
5729 Options are specified by doubled hyphens and their name or by a single
5730 hyphen and the flag character.
5731
5732 Program that generates random keys for use with TLS-PSK.  The keys are
5733 stored in hexadecimal format in a key file.
5734
5735 </pre></div>
5736
5737 <a name="psktool-debug"></a><a name="debug-option-_0028_002dd_0029-6"></a>
5738 <h4 class="subsubheading">debug option (-d)</h4>
5739
5740 <p>This is the &ldquo;enable debugging&rdquo; option.
5741 This option takes a number argument.
5742 Specifies the debug level.
5743 <a name="psktool-exit-status"></a></p><a name="psktool-exit-status-1"></a>
5744 <h4 class="subsubheading">psktool exit status</h4>
5745
5746 <p>One of the following exit values will be returned:
5747 </p><dl compact="compact">
5748 <dt>&lsquo;<samp>0 (EXIT_SUCCESS)</samp>&rsquo;</dt>
5749 <dd><p>Successful program execution.
5750 </p></dd>
5751 <dt>&lsquo;<samp>1 (EXIT_FAILURE)</samp>&rsquo;</dt>
5752 <dd><p>The operation failed or the command syntax was not valid.
5753 </p></dd>
5754 </dl>
5755 <a name="psktool-See-Also"></a><a name="psktool-See-Also-1"></a>
5756 <h4 class="subsubheading">psktool See Also</h4>
5757 <p>gnutls-cli-debug (1), gnutls-serv (1), srptool (1), certtool (1)
5758 <a name="psktool-Examples"></a></p><a name="psktool-Examples-1"></a>
5759 <h4 class="subsubheading">psktool Examples</h4>
5760 <p>To add a user &rsquo;psk_identity&rsquo; in <samp>passwd.psk</samp> for use with GnuTLS run:
5761 </p><div class="example">
5762 <pre class="example">$ ./psktool -u psk_identity -p passwd.psk
5763 Generating a random key for user 'psk_identity'
5764 Key stored to passwd.psk
5765 $ cat psks.txt
5766 psk_identity:88f3824b3e5659f52d00e959bacab954b6540344
5767 $
5768 </pre></div>
5769
5770 <p>This command will create <samp>passwd.psk</samp> if it does not exist
5771 and will add user &rsquo;psk_identity&rsquo; (you will also be prompted for a password).
5772 </p>
5773 <hr>
5774 <a name="Anonymous-authentication"></a>
5775 <div class="header">
5776 <p>
5777 Previous: <a href="#PSK-authentication" accesskey="p" rel="prev">PSK authentication</a>, Up: <a href="#Shared_002dkey-and-anonymous-authentication" accesskey="u" rel="up">Shared-key and anonymous authentication</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
5778 </div>
5779 <a name="Anonymous-authentication-1"></a>
5780 <h4 class="subsection">4.3.3 Anonymous authentication</h4>
5781 <a name="index-anonymous-authentication"></a>
5782
5783 <p>The anonymous key exchange offers encryption without any
5784 indication of the peer&rsquo;s identity.  This kind of authentication
5785 is vulnerable to a man in the middle attack, but can be
5786 used even if there is no prior communication or shared trusted parties
5787 with the peer. It is useful to establish a session over which certificate
5788 authentication will occur in order to hide the indentities of the participants
5789 from passive eavesdroppers.
5790 </p>
5791 <p>Unless in the above case, it is not recommended to use anonymous authentication.
5792 In the cases where there is no prior communication with the peers,
5793 an alternative with better properties, such as key continuity, is trust on first use
5794 (see <a href="#Verifying-a-certificate-using-trust-on-first-use-authentication">Verifying a certificate using trust on first use authentication</a>).
5795 </p>
5796 <p>The available key exchange algorithms for anonymous authentication are
5797 shown below, but note that few public servers support them, and they
5798 have to be explicitly enabled.
5799 </p>
5800 <dl compact="compact">
5801 <dt><code>ANON_DH:</code></dt>
5802 <dd><p>This algorithm exchanges Diffie-Hellman parameters.
5803 </p>
5804 </dd>
5805 <dt><code>ANON_ECDH:</code></dt>
5806 <dd><p>This algorithm exchanges elliptic curve Diffie-Hellman parameters. It is more
5807 efficient than ANON_DH on equivalent security levels.
5808 </p>
5809 </dd>
5810 </dl>
5811
5812 <hr>
5813 <a name="Selecting-an-appropriate-authentication-method"></a>
5814 <div class="header">
5815 <p>
5816 Previous: <a href="#Shared_002dkey-and-anonymous-authentication" accesskey="p" rel="prev">Shared-key and anonymous authentication</a>, Up: <a href="#Authentication-methods" accesskey="u" rel="up">Authentication methods</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
5817 </div>
5818 <a name="Selecting-an-appropriate-authentication-method-1"></a>
5819 <h3 class="section">4.4 Selecting an appropriate authentication method</h3>
5820
5821 <p>This section provides some guidance on how to use the available authentication
5822 methods in <acronym>GnuTLS</acronym> in various scenarios.
5823 </p>
5824 <a name="Two-peers-with-an-out_002dof_002dband-channel"></a>
5825 <h4 class="subsection">4.4.1 Two peers with an out-of-band channel</h4>
5826
5827 <p>Let&rsquo;s consider two peers who need to communicate over an untrusted channel
5828 (the Internet), but have an out-of-band channel available. The latter
5829 channel is considered safe from eavesdropping and message modification and thus
5830 can be used for an initial bootstrapping of the protocol. The options
5831 available are:
5832 </p><ul>
5833 <li> Pre-shared keys (see <a href="#PSK-authentication">PSK authentication</a>). The server and a
5834 client communicate a shared randomly generated key over the trusted
5835 channel and use it to negotiate further sessions over the untrusted channel.
5836
5837 </li><li> Passwords (see <a href="#SRP-authentication">SRP authentication</a>). The client communicates
5838 to the server its username and password of choice and uses it to
5839 negotiate further sessions over the untrusted channel.
5840
5841 </li><li> Public keys (see <a href="#Certificate-authentication">Certificate authentication</a>). The client
5842 and the server exchange their public keys (or fingerprints of them)
5843 over the trusted channel.
5844 On future sessions over the untrusted channel they verify the key
5845 being the same (similar to <a href="#Verifying-a-certificate-using-trust-on-first-use-authentication">Verifying a certificate using trust on first use authentication</a>).
5846 </li></ul>
5847
5848 <p>Provided that the out-of-band channel is trusted all of the above provide
5849 a similar level of protection. An out-of-band channel may be the initial
5850 bootstrapping of a user&rsquo;s PC in a corporate environment, in-person
5851 communication, communication over an alternative network (e.g. the phone
5852 network), etc.
5853 </p>
5854 <a name="Two-peers-without-an-out_002dof_002dband-channel"></a>
5855 <h4 class="subsection">4.4.2 Two peers without an out-of-band channel</h4>
5856
5857 <p>When an out-of-band channel is not available a peer cannot be reliably
5858 authenticated. What can be done, however, is to allow some form of
5859 registration of users connecting for the first time and ensure that their
5860 keys remain the same after that initial connection. This is termed
5861 key continuity or trust on first use (TOFU).
5862 </p>
5863 <p>The available option is to use public key authentication (see <a href="#Certificate-authentication">Certificate authentication</a>).
5864 The client and the server store each other&rsquo;s public keys (or fingerprints of them)
5865 and associate them with their identity.
5866 On future sessions over the untrusted channel they verify the keys
5867 being the same (see <a href="#Verifying-a-certificate-using-trust-on-first-use-authentication">Verifying a certificate using trust on first use authentication</a>).
5868 </p>
5869 <p>To mitigate the uncertainty of the information exchanged in the first
5870 connection other channels over the Internet may be used, e.g., <acronym>DNSSEC</acronym>
5871 (see <a href="#Verifying-a-certificate-using-DANE">Verifying a certificate using DANE</a>).
5872 </p>
5873 <a name="Two-peers-and-a-trusted-third-party"></a>
5874 <h4 class="subsection">4.4.3 Two peers and a trusted third party</h4>
5875
5876 <p>When a trusted third party is available (or a certificate authority)
5877 the most suitable option is to use
5878 certificate authentication (see <a href="#Certificate-authentication">Certificate authentication</a>).
5879 The client and the server obtain certificates that associate their identity
5880 and public keys using a digital signature by the trusted party and use
5881 them to on the subsequent communications with each other.
5882 Each party verifies the peer&rsquo;s certificate using the trusted third party&rsquo;s
5883 signature. The parameters of the third party&rsquo;s signature are present
5884 in its certificate which must be available to all communicating parties.
5885 </p>
5886 <p>While the above is the typical authentication method for servers in the
5887 Internet by using the commercial CAs, the users that act as clients in the
5888 protocol rarely possess such certificates. In that case a hybrid method
5889 can be used where the server is authenticated by the client using the
5890 commercial CAs and the client is authenticated based on some information
5891 the client provided over the initial server-authenticated channel. The
5892 available options are:
5893 </p><ul>
5894 <li> Passwords (see <a href="#SRP-authentication">SRP authentication</a>). The client communicates
5895 to the server its username and password of choice on the initial
5896 server-authenticated connection and uses it to negotiate further sessions.
5897 This is possible because the SRP protocol allows for the server to be
5898 authenticated using a certificate and the client using the
5899 password.
5900
5901 </li><li> Public keys (see <a href="#Certificate-authentication">Certificate authentication</a>). The client
5902 sends its public key to the server (or a fingerprint of it) over the
5903 initial server-authenticated connection.
5904 On future sessions the client verifies the server using the third party
5905 certificate and the server verifies that the client&rsquo;s public key remained
5906 the same (see <a href="#Verifying-a-certificate-using-trust-on-first-use-authentication">Verifying a certificate using trust on first use authentication</a>).
5907 </li></ul>
5908
5909
5910 <hr>
5911 <a name="Hardware-security-modules-and-abstract-key-types"></a>
5912 <div class="header">
5913 <p>
5914 Next: <a href="#How-to-use-GnuTLS-in-applications" accesskey="n" rel="next">How to use GnuTLS in applications</a>, Previous: <a href="#Authentication-methods" accesskey="p" rel="prev">Authentication methods</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
5915 </div>
5916 <a name="Hardware-security-modules-and-abstract-key-types-1"></a>
5917 <h2 class="chapter">5 Hardware security modules and abstract key types</h2>
5918
5919 <p>In several cases storing the long term cryptographic keys in a hard disk or
5920 even in memory poses a significant risk. Once the system they are stored
5921 is compromised the keys must be replaced as the secrecy of future sessions
5922 is no longer guarranteed. Moreover, past sessions that were not protected by a
5923 perfect forward secrecy offering ciphersuite are also to be assumed compromised.
5924 </p>
5925 <p>If such threats need to be addressed, then it may be wise storing the keys in a security
5926 module such as a smart card, an HSM or the TPM chip. Those modules ensure the
5927 protection of the cryptographic keys by only allowing operations on them and
5928 preventing their extraction. The purpose of the abstract key API is to provide
5929 an API that will allow the handle of keys in memory and files, as well as keys
5930 stored in such modules.
5931 </p>
5932 <p>In GnuTLS the approach is to handle all keys transparently by the high level API, e.g.,
5933 the API that loads a key or certificate from a file.
5934 The high-level API will accept URIs in addition to files that specify keys on an HSM or in TPM,
5935 and a callback function will be used to obtain any required keys. The URI format is defined in
5936 [<em>TPMURI</em>] and [<em>PKCS11URI</em>], and is in the process of being standardized across systems.
5937 </p>
5938 <p>More information on the API is provided in the next sections. Examples of a URI of a certificate
5939 stored in an HSM, as well as a key stored in the TPM chip are shown below. To discover the URIs
5940 of the objects the <code>p11tool</code> (see <a href="#p11tool-Invocation">p11tool Invocation</a>),
5941 or <code>tpmtool</code> (see <a href="#tpmtool-Invocation">tpmtool Invocation</a>) may be used.
5942 </p>
5943 <div class="example">
5944 <pre class="example">pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
5945 manufacturer=EnterSafe;object=test1;objecttype=cert
5946
5947 tpmkey:uuid=42309df8-d101-11e1-a89a-97bb33c23ad1;storage=user
5948 </pre></div>
5949
5950
5951 <table class="menu" border="0" cellspacing="0">
5952 <tr><td align="left" valign="top">&bull; <a href="#Abstract-key-types" accesskey="1">Abstract key types</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
5953 </td></tr>
5954 <tr><td align="left" valign="top">&bull; <a href="#Smart-cards-and-HSMs" accesskey="2">Smart cards and HSMs</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
5955 </td></tr>
5956 <tr><td align="left" valign="top">&bull; <a href="#Trusted-Platform-Module" accesskey="3">Trusted Platform Module</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
5957 </td></tr>
5958 </table>
5959
5960 <hr>
5961 <a name="Abstract-key-types"></a>
5962 <div class="header">
5963 <p>
5964 Next: <a href="#Smart-cards-and-HSMs" accesskey="n" rel="next">Smart cards and HSMs</a>, Up: <a href="#Hardware-security-modules-and-abstract-key-types" accesskey="u" rel="up">Hardware security modules and abstract key types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
5965 </div>
5966 <a name="Abstract-key-types-1"></a>
5967 <h3 class="section">5.1 Abstract key types</h3>
5968 <a name="index-abstract-types"></a>
5969
5970 <p>Since there are many forms of a public or private keys supported by <acronym>GnuTLS</acronym> such as
5971 <acronym>X.509</acronym>, <acronym>OpenPGP</acronym>, <acronym>PKCS</acronym> #11 or TPM it is desirable to allow common operations
5972 on them. For these reasons the abstract <code>gnutls_privkey_t</code> and <code>gnutls_pubkey_t</code> were
5973 introduced in <code>gnutls/abstract.h</code> header. Those types are initialized using a specific type of
5974 key and then can be used to perform operations in an abstract way. For example in order
5975 to sign an X.509 certificate with a key that resides in a token the following steps can be
5976 used.
5977 </p>
5978 <div class="example">
5979 <pre class="example">#inlude &lt;gnutls/abstract.h&gt;
5980
5981 void sign_cert( gnutls_x509_crt_t to_be_signed)
5982 {
5983 gnutls_x509_crt_t ca_cert;
5984 gnutls_privkey_t abs_key;
5985
5986   /* initialize the abstract key */
5987   gnutls_privkey_init(&amp;abs_key);
5988
5989   /* keys stored in tokens are identified by URLs */
5990   gnutls_privkey_import_url(abs_key, key_url);
5991
5992   gnutls_x509_crt_init(&amp;ca_cert);
5993   gnutls_x509_crt_import_pkcs11_url(&amp;ca_cert, cert_url);
5994
5995   /* sign the certificate to be signed */
5996   gnutls_x509_crt_privkey_sign(to_be_signed, ca_cert, abs_key,
5997                                GNUTLS_DIG_SHA256, 0);
5998 }
5999 </pre></div>
6000
6001 <table class="menu" border="0" cellspacing="0">
6002 <tr><td align="left" valign="top">&bull; <a href="#Abstract-public-keys" accesskey="1">Abstract public keys</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
6003 </td></tr>
6004 <tr><td align="left" valign="top">&bull; <a href="#Abstract-private-keys" accesskey="2">Abstract private keys</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
6005 </td></tr>
6006 <tr><td align="left" valign="top">&bull; <a href="#Operations" accesskey="3">Operations</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
6007 </td></tr>
6008 </table>
6009
6010 <hr>
6011 <a name="Abstract-public-keys"></a>
6012 <div class="header">
6013 <p>
6014 Next: <a href="#Abstract-private-keys" accesskey="n" rel="next">Abstract private keys</a>, Up: <a href="#Abstract-key-types" accesskey="u" rel="up">Abstract key types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
6015 </div>
6016 <a name="Public-keys"></a>
6017 <h4 class="subsection">5.1.1 Public keys</h4>
6018 <p>An abstract <code>gnutls_pubkey_t</code> can be initialized
6019 using the functions below. It can be imported through
6020 an existing structure like <code>gnutls_x509_crt_t</code>,
6021 or through an ASN.1 encoding of the X.509 <code>SubjectPublicKeyInfo</code>
6022 sequence.
6023 </p>
6024 <dl compact="compact">
6025 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fimport_005fx509">gnutls_pubkey_import_x509</a> (gnutls_pubkey_t <var>key</var>, gnutls_x509_crt_t <var>crt</var>, unsigned int <var>flags</var>)</code></dt>
6026 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fimport_005fopenpgp">gnutls_pubkey_import_openpgp</a> (gnutls_pubkey_t <var>key</var>, gnutls_openpgp_crt_t <var>crt</var>, unsigned int <var>flags</var>)</code></dt>
6027 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fimport_005fpkcs11">gnutls_pubkey_import_pkcs11</a> (gnutls_pubkey_t <var>key</var>, gnutls_pkcs11_obj_t <var>obj</var>, unsigned int <var>flags</var>)</code></dt>
6028 </dl>
6029
6030 <dl compact="compact">
6031 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fimport_005furl">gnutls_pubkey_import_url</a> (gnutls_pubkey_t <var>key</var>, const char * <var>url</var>, unsigned int <var>flags</var>)</code></dt>
6032 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fimport_005fprivkey">gnutls_pubkey_import_privkey</a> (gnutls_pubkey_t <var>key</var>, gnutls_privkey_t <var>pkey</var>, unsigned int <var>usage</var>, unsigned int <var>flags</var>)</code></dt>
6033 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fimport">gnutls_pubkey_import</a> (gnutls_pubkey_t <var>key</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>)</code></dt>
6034 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fexport">gnutls_pubkey_export</a> (gnutls_pubkey_t <var>key</var>, gnutls_x509_crt_fmt_t <var>format</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</code></dt>
6035 </dl>
6036
6037
6038
6039
6040
6041 <dl>
6042 <dt><a name="index-gnutls_005fpubkey_005fexport2"></a>Function: <em>int</em> <strong>gnutls_pubkey_export2</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_x509_crt_fmt_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
6043 <dd><p><var>key</var>: Holds the certificate
6044 </p>
6045 <p><var>format</var>: the format of output params. One of PEM or DER.
6046 </p>
6047 <p><var>out</var>: will contain a certificate PEM or DER encoded
6048 </p>
6049 <p>This function will export the public key to DER or PEM format.
6050 The contents of the exported data is the SubjectPublicKeyInfo
6051 X.509 structure.
6052 </p>
6053 <p>The output buffer will be allocated using <code>gnutls_malloc()</code> .
6054 </p>
6055 <p>If the structure is PEM encoded, it will have a header
6056 of &quot;BEGIN CERTIFICATE&quot;.
6057 </p>
6058 <p><strong>Returns:</strong> In case of failure a negative error code will be
6059 returned, and 0 on success.
6060 </p>
6061 <p><strong>Since:</strong> 3.1.3
6062 </p></dd></dl>
6063
6064 <p>Other helper functions that allow directly importing from raw X.509 or
6065 OpenPGP structures are shown below.
6066 </p>
6067 <dl compact="compact">
6068 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fimport_005fx509_005fraw">gnutls_pubkey_import_x509_raw</a> (gnutls_pubkey_t <var>pkey</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned int <var>flags</var>)</code></dt>
6069 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fimport_005fopenpgp_005fraw">gnutls_pubkey_import_openpgp_raw</a> (gnutls_pubkey_t <var>pkey</var>, const gnutls_datum_t * <var>data</var>, gnutls_openpgp_crt_fmt_t <var>format</var>, const gnutls_openpgp_keyid_t <var>keyid</var>, unsigned int <var>flags</var>)</code></dt>
6070 </dl>
6071
6072 <p>An important function is <a href="#gnutls_005fpubkey_005fimport_005furl">gnutls_pubkey_import_url</a> which will import
6073 public keys from URLs that identify objects stored in tokens (see <a href="#Smart-cards-and-HSMs">Smart cards and HSMs</a> and <a href="#Trusted-Platform-Module">Trusted Platform Module</a>).
6074 A function to check for a supported by GnuTLS URL is <a href="#gnutls_005furl_005fis_005fsupported">gnutls_url_is_supported</a>.
6075 </p>
6076
6077
6078
6079
6080 <dl>
6081 <dt><a name="index-gnutls_005furl_005fis_005fsupported"></a>Function: <em>int</em> <strong>gnutls_url_is_supported</strong> <em>(const char * <var>url</var>)</em></dt>
6082 <dd><p><var>url</var>: A PKCS 11 url
6083 </p>
6084 <p>Check whether url is supported.  Depending on the system libraries
6085 GnuTLS may support pkcs11 or tpmkey URLs.
6086 </p>
6087 <p><strong>Returns:</strong> return non-zero if the given URL is supported, and zero if
6088 it is not known.
6089 </p>
6090 <p><strong>Since:</strong> 3.1.0
6091 </p></dd></dl>
6092
6093 <p>Additional functions are available that will return
6094 information over a public key, such as a unique key ID, as well as a function
6095 that given a public key fingerprint would provide a memorable sketch.
6096 </p>
6097 <p>Note that <a href="#gnutls_005fpubkey_005fget_005fkey_005fid">gnutls_pubkey_get_key_id</a> calculates a SHA1 digest of the
6098 public key as a DER-formatted, subjectPublicKeyInfo object.  Other implementations
6099 use different approaches, e.g., some use the &ldquo;common method&rdquo; described in
6100 section 4.2.1.2 of [<em>RFC5280</em>] which calculates a digest on a part of the
6101 subjectPublicKeyInfo object.
6102 </p>
6103 <dl compact="compact">
6104 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fget_005fpk_005falgorithm">gnutls_pubkey_get_pk_algorithm</a> (gnutls_pubkey_t <var>key</var>, unsigned int * <var>bits</var>)</code></dt>
6105 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fget_005fpreferred_005fhash_005falgorithm">gnutls_pubkey_get_preferred_hash_algorithm</a> (gnutls_pubkey_t <var>key</var>, gnutls_digest_algorithm_t *         <var>hash</var>, unsigned int * <var>mand</var>)</code></dt>
6106 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fget_005fkey_005fid">gnutls_pubkey_get_key_id</a> (gnutls_pubkey_t <var>key</var>, unsigned int <var>flags</var>, unsigned char * <var>output_data</var>, size_t * <var>output_data_size</var>)</code></dt>
6107 <dt><code><var>int</var> <a href="#gnutls_005frandom_005fart">gnutls_random_art</a> (gnutls_random_art_t <var>type</var>, const char * <var>key_type</var>, unsigned int <var>key_size</var>, void * <var>fpr</var>, size_t <var>fpr_size</var>, gnutls_datum_t * <var>art</var>)</code></dt>
6108 </dl>
6109
6110 <p>To export the key-specific parameters, or obtain a unique key ID the following functions are provided.
6111 </p>
6112 <dl compact="compact">
6113 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fexport_005frsa_005fraw">gnutls_pubkey_export_rsa_raw</a> (gnutls_pubkey_t <var>key</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>)</code></dt>
6114 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fexport_005fdsa_005fraw">gnutls_pubkey_export_dsa_raw</a> (gnutls_pubkey_t <var>key</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>g</var>, gnutls_datum_t * <var>y</var>)</code></dt>
6115 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fexport_005fecc_005fraw">gnutls_pubkey_export_ecc_raw</a> (gnutls_pubkey_t <var>key</var>, gnutls_ecc_curve_t * <var>curve</var>, gnutls_datum_t * <var>x</var>, gnutls_datum_t * <var>y</var>)</code></dt>
6116 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fexport_005fecc_005fx962">gnutls_pubkey_export_ecc_x962</a> (gnutls_pubkey_t <var>key</var>, gnutls_datum_t * <var>parameters</var>, gnutls_datum_t * <var>ecpoint</var>)</code></dt>
6117 </dl>
6118
6119 <hr>
6120 <a name="Abstract-private-keys"></a>
6121 <div class="header">
6122 <p>
6123 Next: <a href="#Operations" accesskey="n" rel="next">Operations</a>, Previous: <a href="#Abstract-public-keys" accesskey="p" rel="prev">Abstract public keys</a>, Up: <a href="#Abstract-key-types" accesskey="u" rel="up">Abstract key types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
6124 </div>
6125 <a name="Private-keys"></a>
6126 <h4 class="subsection">5.1.2 Private keys</h4>
6127 <p>An abstract <code>gnutls_privkey_t</code> can be initialized
6128 using the functions below. It can be imported through
6129 an existing structure like <code>gnutls_x509_privkey_t</code>,
6130 but unlike public keys it cannot be exported. That is
6131 to allow abstraction over keys stored in hardware that
6132 makes available only operations.
6133 </p>
6134 <dl compact="compact">
6135 <dt><code><var>int</var> <a href="#gnutls_005fprivkey_005fimport_005fx509">gnutls_privkey_import_x509</a> (gnutls_privkey_t <var>pkey</var>, gnutls_x509_privkey_t <var>key</var>, unsigned int <var>flags</var>)</code></dt>
6136 <dt><code><var>int</var> <a href="#gnutls_005fprivkey_005fimport_005fopenpgp">gnutls_privkey_import_openpgp</a> (gnutls_privkey_t <var>pkey</var>, gnutls_openpgp_privkey_t <var>key</var>, unsigned int <var>flags</var>)</code></dt>
6137 <dt><code><var>int</var> <a href="#gnutls_005fprivkey_005fimport_005fpkcs11">gnutls_privkey_import_pkcs11</a> (gnutls_privkey_t <var>pkey</var>, gnutls_pkcs11_privkey_t <var>key</var>, unsigned int <var>flags</var>)</code></dt>
6138 </dl>
6139
6140 <p>Other helper functions that allow directly importing from raw X.509 or
6141 OpenPGP structures are shown below. Again, as with public keys, private keys
6142 can be imported from a hardware module using URLs.
6143 </p>
6144 <dl compact="compact">
6145 <dt><code><var>int</var> <a href="#gnutls_005fprivkey_005fimport_005fx509_005fraw">gnutls_privkey_import_x509_raw</a> (gnutls_privkey_t <var>pkey</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>)</code></dt>
6146 <dt><code><var>int</var> <a href="#gnutls_005fprivkey_005fimport_005fopenpgp_005fraw">gnutls_privkey_import_openpgp_raw</a> (gnutls_privkey_t <var>pkey</var>, const gnutls_datum_t * <var>data</var>, gnutls_openpgp_crt_fmt_t <var>format</var>, const gnutls_openpgp_keyid_t <var>keyid</var>, const char * <var>password</var>)</code></dt>
6147 </dl>
6148
6149
6150
6151
6152
6153 <dl>
6154 <dt><a name="index-gnutls_005fprivkey_005fimport_005furl"></a>Function: <em>int</em> <strong>gnutls_privkey_import_url</strong> <em>(gnutls_privkey_t <var>key</var>, const char * <var>url</var>, unsigned int <var>flags</var>)</em></dt>
6155 <dd><p><var>key</var>: A key of type <code>gnutls_privkey_t</code>
6156 </p>
6157 <p><var>url</var>: A PKCS 11 url
6158 </p>
6159 <p><var>flags</var>: should be zero
6160 </p>
6161 <p>This function will import a PKCS11 or TPM URL as a
6162 private key. The supported URL types can be checked
6163 using <code>gnutls_url_is_supported()</code> .
6164 </p>
6165 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
6166 negative error value.
6167 </p>
6168 <p><strong>Since:</strong> 3.1.0
6169 </p></dd></dl>
6170
6171 <dl compact="compact">
6172 <dt><code><var>int</var> <a href="#gnutls_005fprivkey_005fget_005fpk_005falgorithm">gnutls_privkey_get_pk_algorithm</a> (gnutls_privkey_t <var>key</var>, unsigned int * <var>bits</var>)</code></dt>
6173 <dt><code><var>gnutls_privkey_type_t</var> <a href="#gnutls_005fprivkey_005fget_005ftype">gnutls_privkey_get_type</a> (gnutls_privkey_t <var>key</var>)</code></dt>
6174 <dt><code><var>int</var> <a href="#gnutls_005fprivkey_005fstatus">gnutls_privkey_status</a> (gnutls_privkey_t <var>key</var>)</code></dt>
6175 </dl>
6176
6177 <p>In order to support cryptographic operations using
6178 an external API, the following function is provided.
6179 This allows for a simple extensibility API without
6180 resorting to <acronym>PKCS</acronym> #11.
6181 </p>
6182
6183
6184
6185
6186 <dl>
6187 <dt><a name="index-gnutls_005fprivkey_005fimport_005fext2"></a>Function: <em>int</em> <strong>gnutls_privkey_import_ext2</strong> <em>(gnutls_privkey_t <var>pkey</var>, gnutls_pk_algorithm_t <var>pk</var>, void * <var>userdata</var>, gnutls_privkey_sign_func <var>sign_func</var>, gnutls_privkey_decrypt_func <var>decrypt_func</var>, gnutls_privkey_deinit_func <var>deinit_func</var>, unsigned int <var>flags</var>)</em></dt>
6188 <dd><p><var>pkey</var>: The private key
6189 </p>
6190 <p><var>pk</var>: The public key algorithm
6191 </p>
6192 <p><var>userdata</var>: private data to be provided to the callbacks
6193 </p>
6194 <p><var>sign_func</var>: callback for signature operations
6195 </p>
6196 <p><var>decrypt_func</var>: callback for decryption operations
6197 </p>
6198 <p><var>deinit_func</var>: a deinitialization function
6199 </p>
6200 <p><var>flags</var>: Flags for the import
6201 </p>
6202 <p>This function will associate the given callbacks with the
6203 <code>gnutls_privkey_t</code>  structure. At least one of the two callbacks
6204 must be non-null. If a deinitialization function is provided
6205 then flags is assumed to contain <code>GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE</code> .
6206 </p>
6207 <p>Note that the signing function is supposed to &quot;raw&quot; sign data, i.e.,
6208 without any hashing or preprocessing. In case of RSA the DigestInfo
6209 will be provided, and the signing function is expected to do the PKCS <code>1</code>
6210 1.5 padding and the exponentiation.
6211 </p>
6212 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
6213 negative error value.
6214 </p>
6215 <p><strong>Since:</strong> 3.1
6216 </p></dd></dl>
6217
6218 <hr>
6219 <a name="Operations"></a>
6220 <div class="header">
6221 <p>
6222 Previous: <a href="#Abstract-private-keys" accesskey="p" rel="prev">Abstract private keys</a>, Up: <a href="#Abstract-key-types" accesskey="u" rel="up">Abstract key types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
6223 </div>
6224 <a name="Operations-1"></a>
6225 <h4 class="subsection">5.1.3 Operations</h4>
6226 <p>The abstract key types can be used to access signing and
6227 signature verification operations with the underlying keys.
6228 </p>
6229
6230
6231
6232
6233 <dl>
6234 <dt><a name="index-gnutls_005fpubkey_005fverify_005fdata2"></a>Function: <em>int</em> <strong>gnutls_pubkey_verify_data2</strong> <em>(gnutls_pubkey_t <var>pubkey</var>, gnutls_sign_algorithm_t <var>algo</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>data</var>, const gnutls_datum_t * <var>signature</var>)</em></dt>
6235 <dd><p><var>pubkey</var>: Holds the public key
6236 </p>
6237 <p><var>algo</var>: The signature algorithm used
6238 </p>
6239 <p><var>flags</var>: Zero or one of <code>gnutls_pubkey_flags_t</code>
6240 </p>
6241 <p><var>data</var>: holds the signed data
6242 </p>
6243 <p><var>signature</var>: contains the signature
6244 </p>
6245 <p>This function will verify the given signed data, using the
6246 parameters from the certificate.
6247 </p>
6248 <p><strong>Returns:</strong> In case of a verification failure <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
6249 is returned, and zero or positive code on success.
6250 </p>
6251 <p><strong>Since:</strong> 3.0
6252 </p></dd></dl>
6253
6254
6255
6256
6257 <dl>
6258 <dt><a name="index-gnutls_005fpubkey_005fverify_005fhash2"></a>Function: <em>int</em> <strong>gnutls_pubkey_verify_hash2</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_sign_algorithm_t <var>algo</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>hash</var>, const gnutls_datum_t * <var>signature</var>)</em></dt>
6259 <dd><p><var>key</var>: Holds the public key
6260 </p>
6261 <p><var>algo</var>: The signature algorithm used
6262 </p>
6263 <p><var>flags</var>: Zero or one of <code>gnutls_pubkey_flags_t</code>
6264 </p>
6265 <p><var>hash</var>: holds the hash digest to be verified
6266 </p>
6267 <p><var>signature</var>: contains the signature
6268 </p>
6269 <p>This function will verify the given signed digest, using the
6270 parameters from the public key. Note that unlike <code>gnutls_privkey_sign_hash()</code> ,
6271 this function accepts a signature algorithm instead of a digest algorithm.
6272 You can use <code>gnutls_pk_to_sign()</code>  to get the appropriate value.
6273 </p>
6274 <p><strong>Returns:</strong> In case of a verification failure <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
6275 is returned, and zero or positive code on success.
6276 </p>
6277 <p><strong>Since:</strong> 3.0
6278 </p></dd></dl>
6279
6280
6281
6282
6283 <dl>
6284 <dt><a name="index-gnutls_005fpubkey_005fencrypt_005fdata"></a>Function: <em>int</em> <strong>gnutls_pubkey_encrypt_data</strong> <em>(gnutls_pubkey_t <var>key</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>plaintext</var>, gnutls_datum_t * <var>ciphertext</var>)</em></dt>
6285 <dd><p><var>key</var>: Holds the public key
6286 </p>
6287 <p><var>flags</var>: should be 0 for now
6288 </p>
6289 <p><var>plaintext</var>: The data to be encrypted
6290 </p>
6291 <p><var>ciphertext</var>: contains the encrypted data
6292 </p>
6293 <p>This function will encrypt the given data, using the public
6294 key.
6295 </p>
6296 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
6297 negative error value.
6298 </p>
6299 <p><strong>Since:</strong> 3.0
6300 </p></dd></dl>
6301
6302
6303
6304
6305
6306 <dl>
6307 <dt><a name="index-gnutls_005fprivkey_005fsign_005fdata"></a>Function: <em>int</em> <strong>gnutls_privkey_sign_data</strong> <em>(gnutls_privkey_t <var>signer</var>, gnutls_digest_algorithm_t <var>hash</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>data</var>, gnutls_datum_t * <var>signature</var>)</em></dt>
6308 <dd><p><var>signer</var>: Holds the key
6309 </p>
6310 <p><var>hash</var>: should be a digest algorithm
6311 </p>
6312 <p><var>flags</var>: Zero or one of <code>gnutls_privkey_flags_t</code>
6313 </p>
6314 <p><var>data</var>: holds the data to be signed
6315 </p>
6316 <p><var>signature</var>: will contain the signature allocate with <code>gnutls_malloc()</code>
6317 </p>
6318 <p>This function will sign the given data using a signature algorithm
6319 supported by the private key. Signature algorithms are always used
6320 together with a hash functions.  Different hash functions may be
6321 used for the RSA algorithm, but only the SHA family for the DSA keys.
6322 </p>
6323 <p>You may use <code>gnutls_pubkey_get_preferred_hash_algorithm()</code>  to determine
6324 the hash algorithm.
6325 </p>
6326 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
6327 negative error value.
6328 </p>
6329 <p><strong>Since:</strong> 2.12.0
6330 </p></dd></dl>
6331
6332
6333
6334
6335 <dl>
6336 <dt><a name="index-gnutls_005fprivkey_005fsign_005fhash"></a>Function: <em>int</em> <strong>gnutls_privkey_sign_hash</strong> <em>(gnutls_privkey_t <var>signer</var>, gnutls_digest_algorithm_t <var>hash_algo</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>hash_data</var>, gnutls_datum_t * <var>signature</var>)</em></dt>
6337 <dd><p><var>signer</var>: Holds the signer&rsquo;s key
6338 </p>
6339 <p><var>hash_algo</var>: The hash algorithm used
6340 </p>
6341 <p><var>flags</var>: Zero or one of <code>gnutls_privkey_flags_t</code>
6342 </p>
6343 <p><var>hash_data</var>: holds the data to be signed
6344 </p>
6345 <p><var>signature</var>: will contain newly allocated signature
6346 </p>
6347 <p>This function will sign the given hashed data using a signature algorithm
6348 supported by the private key. Signature algorithms are always used
6349 together with a hash functions.  Different hash functions may be
6350 used for the RSA algorithm, but only SHA-XXX for the DSA keys.
6351 </p>
6352 <p>You may use <code>gnutls_pubkey_get_preferred_hash_algorithm()</code>  to determine
6353 the hash algorithm.
6354 </p>
6355 <p>Note that if <code>GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA</code>  flag is specified this function
6356 will ignore  <code>hash_algo</code> and perform a raw PKCS1 signature.
6357 </p>
6358 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
6359 negative error value.
6360 </p>
6361 <p><strong>Since:</strong> 2.12.0
6362 </p></dd></dl>
6363
6364
6365
6366
6367 <dl>
6368 <dt><a name="index-gnutls_005fprivkey_005fdecrypt_005fdata"></a>Function: <em>int</em> <strong>gnutls_privkey_decrypt_data</strong> <em>(gnutls_privkey_t <var>key</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>ciphertext</var>, gnutls_datum_t * <var>plaintext</var>)</em></dt>
6369 <dd><p><var>key</var>: Holds the key
6370 </p>
6371 <p><var>flags</var>: zero for now
6372 </p>
6373 <p><var>ciphertext</var>: holds the data to be decrypted
6374 </p>
6375 <p><var>plaintext</var>: will contain the decrypted data, allocated with <code>gnutls_malloc()</code>
6376 </p>
6377 <p>This function will decrypt the given data using the algorithm
6378 supported by the private key.
6379 </p>
6380 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
6381 negative error value.
6382 </p>
6383 <p><strong>Since:</strong> 2.12.0
6384 </p></dd></dl>
6385
6386 <p>Signing existing structures, such as certificates, CRLs,
6387 or certificate requests, as well as associating public
6388 keys with structures is also possible using the
6389 key abstractions.
6390 </p>
6391
6392
6393
6394
6395 <dl>
6396 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fpubkey"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_pubkey</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_pubkey_t <var>key</var>)</em></dt>
6397 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
6398 </p>
6399 <p><var>key</var>: holds a public key
6400 </p>
6401 <p>This function will set the public parameters from the given public
6402 key to the request.
6403 </p>
6404 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
6405 negative error value.
6406 </p>
6407 <p><strong>Since:</strong> 2.12.0
6408 </p></dd></dl>
6409
6410
6411
6412
6413 <dl>
6414 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fpubkey"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_pubkey</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_pubkey_t <var>key</var>)</em></dt>
6415 <dd><p><var>crt</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
6416 </p>
6417 <p><var>key</var>: holds a public key
6418 </p>
6419 <p>This function will set the public parameters from the given public
6420 key to the request.
6421 </p>
6422 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
6423 negative error value.
6424 </p>
6425 <p><strong>Since:</strong> 2.12.0
6426 </p></dd></dl>
6427 <dl compact="compact">
6428 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fprivkey_005fsign">gnutls_x509_crt_privkey_sign</a> (gnutls_x509_crt_t <var>crt</var>, gnutls_x509_crt_t <var>issuer</var>, gnutls_privkey_t <var>issuer_key</var>, gnutls_digest_algorithm_t <var>dig</var>, unsigned int <var>flags</var>)</code></dt>
6429 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrl_005fprivkey_005fsign">gnutls_x509_crl_privkey_sign</a> (gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crt_t <var>issuer</var>, gnutls_privkey_t <var>issuer_key</var>, gnutls_digest_algorithm_t <var>dig</var>, unsigned int <var>flags</var>)</code></dt>
6430 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrq_005fprivkey_005fsign">gnutls_x509_crq_privkey_sign</a> (gnutls_x509_crq_t <var>crq</var>, gnutls_privkey_t <var>key</var>, gnutls_digest_algorithm_t <var>dig</var>, unsigned int <var>flags</var>)</code></dt>
6431 </dl>
6432
6433 <hr>
6434 <a name="Smart-cards-and-HSMs"></a>
6435 <div class="header">
6436 <p>
6437 Next: <a href="#Trusted-Platform-Module" accesskey="n" rel="next">Trusted Platform Module</a>, Previous: <a href="#Abstract-key-types" accesskey="p" rel="prev">Abstract key types</a>, Up: <a href="#Hardware-security-modules-and-abstract-key-types" accesskey="u" rel="up">Hardware security modules and abstract key types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
6438 </div>
6439 <a name="Smart-cards-and-HSMs-1"></a>
6440 <h3 class="section">5.2 Smart cards and HSMs</h3>
6441 <a name="index-PKCS-_002311-tokens"></a>
6442 <a name="index-hardware-tokens"></a>
6443 <a name="index-hardware-security-modules"></a>
6444 <a name="index-smart-cards"></a>
6445
6446 <p>In this section we present the smart-card and hardware security module (HSM) support
6447 in <acronym>GnuTLS</acronym> using <acronym>PKCS</acronym> #11 [<em>PKCS11</em>]. Hardware security
6448 modules and smart cards provide a way to store private keys and perform
6449 operations on them without exposing them. This decouples cryptographic
6450 keys from the applications that use them and provide an additional
6451 security layer against cryptographic key extraction.
6452 Since this can also be achieved in software components such as in Gnome keyring,
6453 we will use the term security module to describe any cryptographic key
6454 separation subsystem.
6455 </p>
6456 <p><acronym>PKCS</acronym> #11 is plugin API allowing applications to access cryptographic
6457 operations on a security module, as well as to objects residing on it. PKCS
6458 #11 modules exist for hardware tokens such as smart cards<a name="DOCF8" href="#FOOT8"><sup>8</sup></a>,
6459 cryptographic tokens, as well as for software modules like <acronym>Gnome Keyring</acronym>.
6460 The objects residing on a security module may be certificates, public keys,
6461 private keys or secret keys. Of those certificates and public/private key
6462 pairs can be used with <acronym>GnuTLS</acronym>. PKCS #11&rsquo;s main advantage is that
6463 it allows operations on private key objects such as decryption
6464 and signing without exposing the key. In GnuTLS the PKCS #11 functionality is
6465 available in <code>gnutls/pkcs11.h</code>.
6466 </p>
6467 <p>Moreover <acronym>PKCS</acronym> #11 can be (ab)used to allow all applications in the same operating system to access
6468 shared cryptographic keys and certificates in a uniform way, as in <a href="#fig_002dpkcs11_002dvision">Figure 5.1</a>.
6469 That way applications could load their trusted certificate list, as well as user
6470 certificates from a common PKCS #11 module. Such a provider is the p11-kit trust
6471 storage module<a name="DOCF9" href="#FOOT9"><sup>9</sup></a>.
6472 </p>
6473 <div class="float"><a name="fig_002dpkcs11_002dvision"></a>
6474 <img src="pkcs11-vision.png" alt="pkcs11-vision">
6475
6476 <div class="float-caption"><p><strong>Figure 5.1: </strong>PKCS #11 module usage.</p></div></div>
6477 <table class="menu" border="0" cellspacing="0">
6478 <tr><td align="left" valign="top">&bull; <a href="#PKCS11-Initialization" accesskey="1">PKCS11 Initialization</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
6479 </td></tr>
6480 <tr><td align="left" valign="top">&bull; <a href="#Accessing-objects-that-require-a-PIN" accesskey="2">Accessing objects that require a PIN</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
6481 </td></tr>
6482 <tr><td align="left" valign="top">&bull; <a href="#Reading-objects" accesskey="3">Reading objects</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
6483 </td></tr>
6484 <tr><td align="left" valign="top">&bull; <a href="#Writing-objects" accesskey="4">Writing objects</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
6485 </td></tr>
6486 <tr><td align="left" valign="top">&bull; <a href="#Using-a-PKCS11-token-with-TLS" accesskey="5">Using a PKCS11 token with TLS</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
6487 </td></tr>
6488 <tr><td align="left" valign="top">&bull; <a href="#p11tool-Invocation" accesskey="6">p11tool Invocation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
6489 </td></tr>
6490 </table>
6491
6492 <hr>
6493 <a name="PKCS11-Initialization"></a>
6494 <div class="header">
6495 <p>
6496 Next: <a href="#Accessing-objects-that-require-a-PIN" accesskey="n" rel="next">Accessing objects that require a PIN</a>, Up: <a href="#Smart-cards-and-HSMs" accesskey="u" rel="up">Smart cards and HSMs</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
6497 </div>
6498 <a name="Initialization-1"></a>
6499 <h4 class="subsection">5.2.1 Initialization</h4>
6500 <p>To allow all <acronym>GnuTLS</acronym> applications to transparently access smard cards
6501 and tokens, <acronym>PKCS</acronym> #11 is automatically initialized during the global
6502 initialization (see <a href="#gnutls_005fglobal_005finit">gnutls_global_init</a>). The initialization function, to select
6503 which modules to load reads certain module configuration files.
6504 Those are stored in <code>/etc/pkcs11/modules/</code> and
6505 are the configuration files of <acronym>p11-kit</acronym><a name="DOCF10" href="#FOOT10"><sup>10</sup></a>.
6506 For example a file that will load the <acronym>OpenSC</acronym> module, could be named
6507 <code>/etc/pkcs11/modules/opensc.module</code> and contain the following:
6508 </p>
6509 <div class="example">
6510 <pre class="example">module: /usr/lib/opensc-pkcs11.so
6511 </pre></div>
6512
6513 <p>If you use these configuration files, then there is no need for other initialization in
6514 <acronym>GnuTLS</acronym>, except for the PIN and token functions (see next section).
6515 In several cases, however, it is desirable to limit badly behaving modules
6516 (e.g., modules that add an unacceptable delay on initialization)
6517 to single applications. That can be done using the &ldquo;enable-in:&rdquo; option
6518 followed by the base name of applications that this module should be used.
6519 </p>
6520 <p>In all cases, you can also manually initialize the PKCS #11 subsystem if the
6521 default settings are not desirable. To completely disable PKCS #11 support you
6522 need to call <a href="#gnutls_005fpkcs11_005finit">gnutls_pkcs11_init</a> with the flag <code>GNUTLS_PKCS11_FLAG_MANUAL</code>
6523 prior to <a href="#gnutls_005fglobal_005finit">gnutls_global_init</a>.
6524 </p>
6525
6526
6527
6528
6529 <dl>
6530 <dt><a name="index-gnutls_005fpkcs11_005finit"></a>Function: <em>int</em> <strong>gnutls_pkcs11_init</strong> <em>(unsigned int <var>flags</var>, const char * <var>deprecated_config_file</var>)</em></dt>
6531 <dd><p><var>flags</var>: An ORed sequence of <code>GNUTLS_PKCS11_FLAG_</code> *
6532 </p>
6533 <p><var>deprecated_config_file</var>: either NULL or the location of a deprecated
6534 configuration file
6535 </p>
6536 <p>This function will initialize the PKCS 11 subsystem in gnutls. It will
6537 read configuration files if <code>GNUTLS_PKCS11_FLAG_AUTO</code>  is used or allow
6538 you to independently load PKCS 11 modules using <code>gnutls_pkcs11_add_provider()</code>
6539 if <code>GNUTLS_PKCS11_FLAG_MANUAL</code>  is specified.
6540 </p>
6541 <p>Normally you don&rsquo;t need to call this function since it is being called
6542 when the first PKCS 11 operation is requested using the <code>GNUTLS_PKCS11_FLAG_AUTO</code>
6543 flag. If another flags are required then it must be called independently
6544 prior to any PKCS 11 operation.
6545 </p>
6546 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
6547 negative error value.
6548 </p>
6549 <p><strong>Since:</strong> 2.12.0
6550 </p></dd></dl>
6551
6552 <p>Note that PKCS #11 modules must be reinitialized on the child processes
6553 after a <code>fork</code>. In older versions of <acronym>GnuTLS</acronym> it was
6554 required to call <a href="#gnutls_005fpkcs11_005freinit">gnutls_pkcs11_reinit</a>; since 3.3.0 this is no
6555 longer required, as reinitialization occurs automatically.
6556 </p>
6557 <hr>
6558 <a name="Accessing-objects-that-require-a-PIN"></a>
6559 <div class="header">
6560 <p>
6561 Next: <a href="#Reading-objects" accesskey="n" rel="next">Reading objects</a>, Previous: <a href="#PKCS11-Initialization" accesskey="p" rel="prev">PKCS11 Initialization</a>, Up: <a href="#Smart-cards-and-HSMs" accesskey="u" rel="up">Smart cards and HSMs</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
6562 </div>
6563 <a name="Accessing-objects-that-require-a-PIN-1"></a>
6564 <h4 class="subsection">5.2.2 Accessing objects that require a PIN</h4>
6565
6566 <p>Objects stored in token such as a private keys are typically protected
6567 from access by a PIN or password. This PIN may be required to either read
6568 the object (if allowed) or to perform operations with it. To allow obtaining
6569 the PIN when accessing a protected object, as well as probe
6570 the user to insert the token the following functions allow to set a callback.
6571 </p>
6572 <dl compact="compact">
6573 <dt><code><var>void</var> <a href="#gnutls_005fpkcs11_005fset_005ftoken_005ffunction">gnutls_pkcs11_set_token_function</a> (gnutls_pkcs11_token_callback_t <var>fn</var>, void * <var>userdata</var>)</code></dt>
6574 <dt><code><var>void</var> <a href="#gnutls_005fpkcs11_005fset_005fpin_005ffunction">gnutls_pkcs11_set_pin_function</a> (gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</code></dt>
6575 <dt><code><var>int</var> <a href="#gnutls_005fpkcs11_005fadd_005fprovider">gnutls_pkcs11_add_provider</a> (const char * <var>name</var>, const char * <var>params</var>)</code></dt>
6576 <dt><code><var>gnutls_pin_callback_t</var> <a href="#gnutls_005fpkcs11_005fget_005fpin_005ffunction">gnutls_pkcs11_get_pin_function</a> (void ** <var>userdata</var>)</code></dt>
6577 </dl>
6578
6579 <p>The callback is of type <code>gnutls_pin_callback_t</code> and will have as
6580 input the provided userdata, the PIN attempt number, a URL describing the
6581 token, a label describing the object and flags. The PIN must be at most
6582 of <code>pin_max</code> size and must be copied to pin variable. The function must
6583 return 0 on success or a negative error code otherwise.
6584 </p>
6585 <pre class="verbatim">typedef int (*gnutls_pin_callback_t) (void *userdata, int attempt,
6586                                       const char *token_url,
6587                                       const char *token_label,
6588                                       unsigned int flags,
6589                                       char *pin, size_t pin_max);
6590 </pre>
6591 <p>The flags are of <code>gnutls_pin_flag_t</code> type and are explained below.
6592 </p>
6593 <div class="float"><a name="gnutls_005fpin_005fflag_005ft"></a>
6594
6595
6596 <dl compact="compact">
6597 <dt><code>GNUTLS_PIN_USER</code></dt>
6598 <dd><p>The PIN for the user.
6599 </p></dd>
6600 <dt><code>GNUTLS_PIN_SO</code></dt>
6601 <dd><p>The PIN for the security officer (admin).
6602 </p></dd>
6603 <dt><code>GNUTLS_PIN_FINAL_TRY</code></dt>
6604 <dd><p>This is the final try before blocking.
6605 </p></dd>
6606 <dt><code>GNUTLS_PIN_COUNT_LOW</code></dt>
6607 <dd><p>Few tries remain before token blocks.
6608 </p></dd>
6609 <dt><code>GNUTLS_PIN_CONTEXT_SPECIFIC</code></dt>
6610 <dd><p>The PIN is for a specific action and key like signing.
6611 </p></dd>
6612 <dt><code>GNUTLS_PIN_WRONG</code></dt>
6613 <dd><p>Last given PIN was not correct.
6614 </p></dd>
6615 </dl>
6616
6617 <div class="float-caption"><p><strong>Figure 5.2: </strong>The <code>gnutls_pin_flag_t</code> enumeration.</p></div></div>
6618 <p>Note that due to limitations of <acronym>PKCS</acronym> #11 there are issues when multiple libraries
6619 are sharing a module. To avoid this problem GnuTLS uses <acronym>p11-kit</acronym>
6620 that provides a middleware to control access to resources over the
6621 multiple users.
6622 </p>
6623 <p>To avoid conflicts with multiple registered callbacks for PIN functions,
6624 <a href="#gnutls_005fpkcs11_005fget_005fpin_005ffunction">gnutls_pkcs11_get_pin_function</a> may be used to check for any previously
6625 set functions. In addition context specific PIN functions are allowed, e.g., by
6626 using functions below.
6627 </p>
6628 <dl compact="compact">
6629 <dt><code><var>void</var> <a href="#gnutls_005fcertificate_005fset_005fpin_005ffunction">gnutls_certificate_set_pin_function</a> (gnutls_certificate_credentials_t       <var>cred</var>, gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</code></dt>
6630 <dt><code><var>void</var> <a href="#gnutls_005fpubkey_005fset_005fpin_005ffunction">gnutls_pubkey_set_pin_function</a> (gnutls_pubkey_t <var>key</var>, gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</code></dt>
6631 <dt><code><var>void</var> <a href="#gnutls_005fprivkey_005fset_005fpin_005ffunction">gnutls_privkey_set_pin_function</a> (gnutls_privkey_t <var>key</var>, gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</code></dt>
6632 <dt><code><var>void</var> <a href="#gnutls_005fpkcs11_005fobj_005fset_005fpin_005ffunction">gnutls_pkcs11_obj_set_pin_function</a> (gnutls_pkcs11_obj_t <var>obj</var>, gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</code></dt>
6633 <dt><code><var>void</var> <a href="#gnutls_005fx509_005fcrt_005fset_005fpin_005ffunction">gnutls_x509_crt_set_pin_function</a> (gnutls_x509_crt_t <var>crt</var>, gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</code></dt>
6634 </dl>
6635
6636 <hr>
6637 <a name="Reading-objects"></a>
6638 <div class="header">
6639 <p>
6640 Next: <a href="#Writing-objects" accesskey="n" rel="next">Writing objects</a>, Previous: <a href="#Accessing-objects-that-require-a-PIN" accesskey="p" rel="prev">Accessing objects that require a PIN</a>, Up: <a href="#Smart-cards-and-HSMs" accesskey="u" rel="up">Smart cards and HSMs</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
6641 </div>
6642 <a name="Reading-objects-1"></a>
6643 <h4 class="subsection">5.2.3 Reading objects</h4>
6644
6645 <p>All <acronym>PKCS</acronym> #11 objects are referenced by <acronym>GnuTLS</acronym> functions by
6646 URLs as described in [<em>PKCS11URI</em>].
6647 This allows for a consistent naming of objects across systems and applications
6648 in the same system. For example a public
6649 key on a smart card may be referenced as:
6650 </p>
6651 <div class="example">
6652 <pre class="example">pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
6653 manufacturer=EnterSafe;object=test1;objecttype=public;\
6654 id=32f153f3e37990b08624141077ca5dec2d15faed
6655 </pre></div>
6656
6657 <p>while the smart card itself can be referenced as:
6658 </p><div class="example">
6659 <pre class="example">pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
6660 </pre></div>
6661
6662 <p>Objects stored in a <acronym>PKCS</acronym> #11 token can be extracted
6663 if they are not marked as sensitive. Usually only private keys are marked as
6664 sensitive and cannot be extracted, while certificates and other data can
6665 be retrieved. The functions that can be used to access objects
6666 are shown below.
6667 </p>
6668 <dl compact="compact">
6669 <dt><code><var>int</var> <a href="#gnutls_005fpkcs11_005fobj_005fimport_005furl">gnutls_pkcs11_obj_import_url</a> (gnutls_pkcs11_obj_t <var>obj</var>, const char * <var>url</var>, unsigned int <var>flags</var>)</code></dt>
6670 <dt><code><var>int</var> <a href="#gnutls_005fpkcs11_005fobj_005fexport_005furl">gnutls_pkcs11_obj_export_url</a> (gnutls_pkcs11_obj_t <var>obj</var>, gnutls_pkcs11_url_type_t <var>detailed</var>, char ** <var>url</var>)</code></dt>
6671 </dl>
6672
6673
6674
6675
6676
6677 <dl>
6678 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fget_005finfo"></a>Function: <em>int</em> <strong>gnutls_pkcs11_obj_get_info</strong> <em>(gnutls_pkcs11_obj_t <var>obj</var>, gnutls_pkcs11_obj_info_t <var>itype</var>, void * <var>output</var>, size_t * <var>output_size</var>)</em></dt>
6679 <dd><p><var>obj</var>: should contain a <code>gnutls_pkcs11_obj_t</code>  structure
6680 </p>
6681 <p><var>itype</var>: Denotes the type of information requested
6682 </p>
6683 <p><var>output</var>: where output will be stored
6684 </p>
6685 <p><var>output_size</var>: contains the maximum size of the output and will be overwritten with actual
6686 </p>
6687 <p>This function will return information about the PKCS11 certificate
6688 such as the label, id as well as token information where the key is
6689 stored. When output is text it returns null terminated string
6690 although  <code>output_size</code> contains the size of the actual data only.
6691 </p>
6692 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success or a negative error code on error.
6693 </p>
6694 <p><strong>Since:</strong> 2.12.0
6695 </p></dd></dl>
6696
6697 <dl compact="compact">
6698 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fimport_005fpkcs11">gnutls_x509_crt_import_pkcs11</a> (gnutls_x509_crt_t <var>crt</var>, gnutls_pkcs11_obj_t <var>pkcs11_crt</var>)</code></dt>
6699 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005fimport_005fpkcs11_005furl">gnutls_x509_crt_import_pkcs11_url</a> (gnutls_x509_crt_t <var>crt</var>, const char * <var>url</var>, unsigned int <var>flags</var>)</code></dt>
6700 <dt><code><var>int</var> <a href="#gnutls_005fx509_005fcrt_005flist_005fimport_005fpkcs11">gnutls_x509_crt_list_import_pkcs11</a> (gnutls_x509_crt_t * <var>certs</var>, unsigned int <var>cert_max</var>, gnutls_pkcs11_obj_t * const <var>objs</var>, unsigned int <var>flags</var>)</code></dt>
6701 </dl>
6702
6703 <p>Properties of the physical token can also be accessed and altered with <acronym>GnuTLS</acronym>.
6704 For example data in a token can be erased (initialized), PIN can be altered, etc.
6705 </p>
6706 <dl compact="compact">
6707 <dt><code><var>int</var> <a href="#gnutls_005fpkcs11_005ftoken_005finit">gnutls_pkcs11_token_init</a> (const char * <var>token_url</var>, const char * <var>so_pin</var>, const char * <var>label</var>)</code></dt>
6708 <dt><code><var>int</var> <a href="#gnutls_005fpkcs11_005ftoken_005fget_005furl">gnutls_pkcs11_token_get_url</a> (unsigned int <var>seq</var>, gnutls_pkcs11_url_type_t <var>detailed</var>, char ** <var>url</var>)</code></dt>
6709 <dt><code><var>int</var> <a href="#gnutls_005fpkcs11_005ftoken_005fget_005finfo">gnutls_pkcs11_token_get_info</a> (const char * <var>url</var>, gnutls_pkcs11_token_info_t <var>ttype</var>, void * <var>output</var>, size_t * <var>output_size</var>)</code></dt>
6710 <dt><code><var>int</var> <a href="#gnutls_005fpkcs11_005ftoken_005fget_005fflags">gnutls_pkcs11_token_get_flags</a> (const char * <var>url</var>, unsigned int * <var>flags</var>)</code></dt>
6711 <dt><code><var>int</var> <a href="#gnutls_005fpkcs11_005ftoken_005fset_005fpin">gnutls_pkcs11_token_set_pin</a> (const char * <var>token_url</var>, const char * <var>oldpin</var>, const char * <var>newpin</var>, unsigned int <var>flags</var>)</code></dt>
6712 </dl>
6713
6714 <p>The following examples demonstrate the usage of the API. The first example
6715 will list all available PKCS #11 tokens in a system and the latter will
6716 list all certificates in a token that have a corresponding private key.
6717 </p>
6718 <div class="example">
6719 <pre class="example">int i;
6720 char* url;
6721
6722 gnutls_global_init();
6723
6724 for (i=0;;i++)
6725   {
6726     ret = gnutls_pkcs11_token_get_url(i, &amp;url);
6727     if (ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
6728       break;
6729
6730     if (ret &lt; 0)
6731       exit(1);
6732
6733     fprintf(stdout, &quot;Token[%d]: URL: %s\n&quot;, i, url);
6734     gnutls_free(url);
6735   }
6736 gnutls_global_deinit();
6737 </pre></div>
6738
6739 <pre class="verbatim">/* This example code is placed in the public domain. */
6740
6741 #include &lt;config.h&gt;
6742 #include &lt;gnutls/gnutls.h&gt;
6743 #include &lt;gnutls/pkcs11.h&gt;
6744 #include &lt;stdio.h&gt;
6745 #include &lt;stdlib.h&gt;
6746
6747 #define URL &quot;pkcs11:URL&quot;
6748
6749 int main(int argc, char **argv)
6750 {
6751         gnutls_pkcs11_obj_t *obj_list;
6752         gnutls_x509_crt_t xcrt;
6753         unsigned int obj_list_size = 0;
6754         gnutls_datum_t cinfo;
6755         int ret;
6756         unsigned int i;
6757
6758         obj_list_size = 0;
6759         ret = gnutls_pkcs11_obj_list_import_url(NULL, &amp;obj_list_size, URL,
6760                                                 GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY,
6761                                                 0);
6762         if (ret &lt; 0 &amp;&amp; ret != GNUTLS_E_SHORT_MEMORY_BUFFER)
6763                 return -1;
6764
6765 /* no error checking from now on */
6766         obj_list = malloc(sizeof(*obj_list) * obj_list_size);
6767
6768         gnutls_pkcs11_obj_list_import_url(obj_list, &amp;obj_list_size, URL,
6769                                           GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY,
6770                                           0);
6771
6772 /* now all certificates are in obj_list */
6773         for (i = 0; i &lt; obj_list_size; i++) {
6774
6775                 gnutls_x509_crt_init(&amp;xcrt);
6776
6777                 gnutls_x509_crt_import_pkcs11(xcrt, obj_list[i]);
6778
6779                 gnutls_x509_crt_print(xcrt, GNUTLS_CRT_PRINT_FULL, &amp;cinfo);
6780
6781                 fprintf(stdout, &quot;cert[%d]:\n %s\n\n&quot;, i, cinfo.data);
6782
6783                 gnutls_free(cinfo.data);
6784                 gnutls_x509_crt_deinit(xcrt);
6785         }
6786
6787         return 0;
6788 }
6789 </pre>
6790 <hr>
6791 <a name="Writing-objects"></a>
6792 <div class="header">
6793 <p>
6794 Next: <a href="#Using-a-PKCS11-token-with-TLS" accesskey="n" rel="next">Using a PKCS11 token with TLS</a>, Previous: <a href="#Reading-objects" accesskey="p" rel="prev">Reading objects</a>, Up: <a href="#Smart-cards-and-HSMs" accesskey="u" rel="up">Smart cards and HSMs</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
6795 </div>
6796 <a name="Writing-objects-1"></a>
6797 <h4 class="subsection">5.2.4 Writing objects</h4>
6798
6799 <p>With <acronym>GnuTLS</acronym> you can copy existing private keys and certificates
6800 to a token. Note that when copying private keys it is recommended to mark
6801 them as sensitive using the <code>GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE</code>
6802 to prevent its extraction. An object can be marked as private using the flag
6803 <code>GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE</code>, to require PIN to be
6804 entered before accessing the object (for operations or otherwise).
6805 </p>
6806
6807
6808
6809
6810 <dl>
6811 <dt><a name="index-gnutls_005fpkcs11_005fcopy_005fx509_005fprivkey"></a>Function: <em>int</em> <strong>gnutls_pkcs11_copy_x509_privkey</strong> <em>(const char * <var>token_url</var>, gnutls_x509_privkey_t <var>key</var>, const char * <var>label</var>, unsigned int <var>key_usage</var>, unsigned int <var>flags</var>)</em></dt>
6812 <dd><p><var>token_url</var>: A PKCS <code>11</code>  URL specifying a token
6813 </p>
6814 <p><var>key</var>: A private key
6815 </p>
6816 <p><var>label</var>: A name to be used for the stored data
6817 </p>
6818 <p><var>key_usage</var>: One of GNUTLS_KEY_*
6819 </p>
6820 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
6821 </p>
6822 <p>This function will copy a private key into a PKCS <code>11</code>  token specified by
6823 a URL. It is highly recommended flags to contain <code>GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE</code>
6824 unless there is a strong reason not to.
6825 </p>
6826 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
6827 negative error value.
6828 </p>
6829 <p><strong>Since:</strong> 2.12.0
6830 </p></dd></dl>
6831
6832
6833
6834
6835
6836 <dl>
6837 <dt><a name="index-gnutls_005fpkcs11_005fcopy_005fx509_005fcrt"></a>Function: <em>int</em> <strong>gnutls_pkcs11_copy_x509_crt</strong> <em>(const char * <var>token_url</var>, gnutls_x509_crt_t <var>crt</var>, const char * <var>label</var>, unsigned int <var>flags</var>)</em></dt>
6838 <dd><p><var>token_url</var>: A PKCS <code>11</code>  URL specifying a token
6839 </p>
6840 <p><var>crt</var>: The certificate to copy
6841 </p>
6842 <p><var>label</var>: The name to be used for the stored data
6843 </p>
6844 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_FLAG_*
6845 </p>
6846 <p>This function will copy a certificate into a PKCS <code>11</code>  token specified by
6847 a URL. The certificate can be marked as trusted or not.
6848 </p>
6849 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
6850 negative error value.
6851 </p>
6852 <p><strong>Since:</strong> 2.12.0
6853 </p></dd></dl>
6854
6855
6856
6857
6858 <dl>
6859 <dt><a name="index-gnutls_005fpkcs11_005fdelete_005furl"></a>Function: <em>int</em> <strong>gnutls_pkcs11_delete_url</strong> <em>(const char * <var>object_url</var>, unsigned int <var>flags</var>)</em></dt>
6860 <dd><p><var>object_url</var>: The URL of the object to delete.
6861 </p>
6862 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
6863 </p>
6864 <p>This function will delete objects matching the given URL.
6865 Note that not all tokens support the delete operation.
6866 </p>
6867 <p><strong>Returns:</strong> On success, the number of objects deleted is returned, otherwise a
6868 negative error value.
6869 </p>
6870 <p><strong>Since:</strong> 2.12.0
6871 </p></dd></dl>
6872
6873
6874 <hr>
6875 <a name="Using-a-PKCS11-token-with-TLS"></a>
6876 <div class="header">
6877 <p>
6878 Next: <a href="#p11tool-Invocation" accesskey="n" rel="next">p11tool Invocation</a>, Previous: <a href="#Writing-objects" accesskey="p" rel="prev">Writing objects</a>, Up: <a href="#Smart-cards-and-HSMs" accesskey="u" rel="up">Smart cards and HSMs</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
6879 </div>
6880 <a name="Using-a-PKCS-_002311-token-with-TLS"></a>
6881 <h4 class="subsection">5.2.5 Using a <acronym>PKCS</acronym> #11 token with TLS</h4>
6882
6883 <p>It is possible to use a <acronym>PKCS</acronym> #11 token to a TLS
6884 session, as shown in <a href="#ex_002dpkcs11_002dclient">ex-pkcs11-client</a>. In addition
6885 the following functions can be used to load PKCS #11 key and
6886 certificates by specifying a PKCS #11 URL instead of a filename.
6887 </p>
6888 <dl compact="compact">
6889 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fx509_005ftrust_005ffile">gnutls_certificate_set_x509_trust_file</a> (gnutls_certificate_credentials_t            <var>cred</var>, const char * <var>cafile</var>, gnutls_x509_crt_fmt_t <var>type</var>)</code></dt>
6890 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile2">gnutls_certificate_set_x509_key_file2</a> (gnutls_certificate_credentials_t <var>res</var>, const char * <var>certfile</var>, const char * <var>keyfile</var>, gnutls_x509_crt_fmt_t <var>type</var>, const char * <var>pass</var>, unsigned int <var>flags</var>)</code></dt>
6891 </dl>
6892
6893
6894
6895
6896 <dl>
6897 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005fsystem_005ftrust"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_system_trust</strong> <em>(gnutls_certificate_credentials_t       <var>cred</var>)</em></dt>
6898 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
6899 </p>
6900 <p>This function adds the system&rsquo;s default trusted CAs in order to
6901 verify client or server certificates.
6902 </p>
6903 <p>In the case the system is currently unsupported <code>GNUTLS_E_UNIMPLEMENTED_FEATURE</code>
6904 is returned.
6905 </p>
6906 <p><strong>Returns:</strong> the number of certificates processed or a negative error code
6907 on error.
6908 </p>
6909 <p><strong>Since:</strong> 3.0.20
6910 </p></dd></dl>
6911
6912 <hr>
6913 <a name="p11tool-Invocation"></a>
6914 <div class="header">
6915 <p>
6916 Previous: <a href="#Using-a-PKCS11-token-with-TLS" accesskey="p" rel="prev">Using a PKCS11 token with TLS</a>, Up: <a href="#Smart-cards-and-HSMs" accesskey="u" rel="up">Smart cards and HSMs</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
6917 </div>
6918 <a name="Invoking-p11tool"></a>
6919 <h4 class="subsection">5.2.6 Invoking p11tool</h4>
6920 <a name="index-p11tool"></a>
6921
6922
6923 <p>Program that allows operations on PKCS #11 smart cards
6924 and security modules.
6925 </p>
6926 <p>To use PKCS #11 tokens with GnuTLS the p11-kit configuration files need to be setup.
6927 That is create a .module file in /etc/pkcs11/modules with the contents &rsquo;module: /path/to/pkcs11.so&rsquo;.
6928 Alternatively the configuration file /etc/gnutls/pkcs11.conf has to exist and contain a number
6929 of lines of the form &rsquo;load=/usr/lib/opensc-pkcs11.so&rsquo;.
6930 </p>
6931 <p>You can provide the PIN to be used for the PKCS #11 operations with the environment variables
6932 GNUTLS_PIN and GNUTLS_SO_PIN.
6933 </p>
6934
6935 <p>This section was generated by <strong>AutoGen</strong>,
6936 using the <code>agtexi-cmd</code> template and the option descriptions for the <code>p11tool</code> program.
6937 This software is released under the GNU General Public License, version 3 or later.
6938 </p>
6939
6940 <a name="p11tool-usage"></a><a name="p11tool-help_002fusage-_0028_002d_002dhelp_0029"></a>
6941 <h4 class="subsection">5.2.7 p11tool help/usage (<samp>--help</samp>)</h4>
6942 <a name="index-p11tool-help"></a>
6943
6944 <p>This is the automatically generated usage text for p11tool.
6945 </p>
6946 <p>The text printed is the same whether selected with the <code>help</code> option
6947 (<samp>--help</samp>) or the <code>more-help</code> option (<samp>--more-help</samp>).  <code>more-help</code> will print
6948 the usage text by passing it through a pager program.
6949 <code>more-help</code> is disabled on platforms without a working
6950 <code>fork(2)</code> function.  The <code>PAGER</code> environment variable is
6951 used to select the program, defaulting to <samp>more</samp>.  Both will exit
6952 with a status code of 0.
6953 </p>
6954 <div class="example">
6955 <pre class="example">p11tool - GnuTLS PKCS #11 tool
6956 Usage:  p11tool [ -&lt;flag&gt; [&lt;val&gt;] | --&lt;name&gt;[{=| }&lt;val&gt;] ]... [url]
6957
6958
6959 Tokens:
6960
6961        --list-tokens          List all available tokens
6962        --list-token-urls      List the URLs available tokens
6963        --list-mechanisms      List all available mechanisms in a token
6964        --initialize           Initializes a PKCS #11 token
6965        --set-pin=str          Specify the PIN to use on token initialization
6966        --set-so-pin=str       Specify the Security Officer's PIN to use on token initialization
6967
6968 Object listing:
6969
6970        --list-all             List all available objects in a token
6971        --list-all-certs       List all available certificates in a token
6972        --list-certs           List all certificates that have an associated private key
6973        --list-all-privkeys    List all available private keys in a token
6974        --list-privkeys        an alias for the 'list-all-privkeys' option
6975        --list-keys            an alias for the 'list-all-privkeys' option
6976        --list-all-trusted     List all available certificates marked as trusted
6977        --export               Export the object specified by the URL
6978                                 - prohibits these options:
6979                                 export-stapled
6980                                 export-chain
6981                                 export-pubkey
6982        --export-stapled       Export the certificate object specified by the URL
6983                                 - prohibits these options:
6984                                 export
6985                                 export-chain
6986                                 export-pubkey
6987        --export-chain         Export the certificate specified by the URL and its chain of trust
6988                                 - prohibits these options:
6989                                 export-stapled
6990                                 export
6991                                 export-pubkey
6992        --export-pubkey        Export the public key for a private key
6993                                 - prohibits these options:
6994                                 export-stapled
6995                                 export
6996                                 export-chain
6997        --info                 List information on an available object in a token
6998        --trusted              an alias for the 'mark-trusted' option
6999        --distrusted           an alias for the 'mark-distrusted' option
7000
7001 Key generation:
7002
7003        --generate-rsa         Generate an RSA private-public key pair
7004        --generate-dsa         Generate a DSA private-public key pair
7005        --generate-ecc         Generate an ECDSA private-public key pair
7006        --bits=num             Specify the number of bits for the key generate
7007        --curve=str            Specify the curve used for EC key generation
7008        --sec-param=str        Specify the security level
7009
7010 Writing objects:
7011
7012        --set-id=str           Set the CKA_ID (in hex) for the specified by the URL object
7013                                 - prohibits the option 'write'
7014        --set-label=str        Set the CKA_LABEL for the specified by the URL object
7015                                 - prohibits these options:
7016                                 write
7017                                 set-id
7018        --write                Writes the loaded objects to a PKCS #11 token
7019        --delete               Deletes the objects matching the given PKCS #11 URL
7020        --label=str            Sets a label for the write operation
7021        --id=str               Sets an ID for the write operation
7022        --mark-wrap            Marks the generated key to be a wrapping key
7023                                 - disabled as '--no-mark-wrap'
7024        --mark-trusted         Marks the object to be written as trusted
7025                                 - prohibits the option 'mark-distrusted'
7026                                 - disabled as '--no-mark-trusted'
7027        --mark-distrusted      When retrieving objects, it requires the objects to be distrusted
7028 (blacklisted)
7029                                 - prohibits the option 'mark-trusted'
7030        --mark-decrypt         Marks the object to be written for decryption
7031                                 - disabled as '--no-mark-decrypt'
7032        --mark-sign            Marks the object to be written for signature generation
7033                                 - disabled as '--no-mark-sign'
7034        --mark-ca              Marks the object to be written as a CA
7035                                 - disabled as '--no-mark-ca'
7036        --mark-private         Marks the object to be written as private
7037                                 - disabled as '--no-mark-private'
7038        --ca                   an alias for the 'mark-ca' option
7039        --private              an alias for the 'mark-private' option
7040        --secret-key=str       Provide a hex encoded secret key
7041        --load-privkey=file    Private key file to use
7042                                 - file must pre-exist
7043        --load-pubkey=file     Public key file to use
7044                                 - file must pre-exist
7045        --load-certificate=file Certificate file to use
7046                                 - file must pre-exist
7047
7048 Other options:
7049
7050    -d, --debug=num            Enable debugging
7051                                 - it must be in the range:
7052                                   0 to 9999
7053        --outfile=str          Output file
7054        --login                Force (user) login to token
7055                                 - disabled as '--no-login'
7056        --so-login             Force security officer login to token
7057                                 - disabled as '--no-so-login'
7058        --admin-login          an alias for the 'so-login' option
7059        --test-sign            Tests the signature operation of the provided object
7060        --generate-random=num  Generate random data
7061    -8, --pkcs8                Use PKCS #8 format for private keys
7062        --inder                Use DER/RAW format for input
7063                                 - disabled as '--no-inder'
7064        --inraw                an alias for the 'inder' option
7065        --outder               Use DER format for output certificates, private keys, and DH parameters
7066                                 - disabled as '--no-outder'
7067        --outraw               an alias for the 'outder' option
7068        --provider=file        Specify the PKCS #11 provider library
7069        --detailed-url         Print detailed URLs
7070                                 - disabled as '--no-detailed-url'
7071        --only-urls            Print a compact listing using only the URLs
7072        --batch                Disable all interaction with the tool
7073
7074 Version, usage and configuration options:
7075
7076    -v, --version[=arg]        output version information and exit
7077    -h, --help                 display extended usage information and exit
7078    -!, --more-help            extended usage information passed thru pager
7079
7080 Options are specified by doubled hyphens and their name or by a single
7081 hyphen and the flag character.
7082 Operands and options may be intermixed.  They will be reordered.
7083
7084 Program that allows operations on PKCS #11 smart cards and security
7085 modules.
7086
7087 To use PKCS #11 tokens with GnuTLS the p11-kit configuration files need to
7088 be setup.  That is create a .module file in /etc/pkcs11/modules with the
7089 contents 'module: /path/to/pkcs11.so'.  Alternatively the configuration
7090 file /etc/gnutls/pkcs11.conf has to exist and contain a number of lines of
7091 the form 'load=/usr/lib/opensc-pkcs11.so'.
7092
7093 You can provide the PIN to be used for the PKCS #11 operations with the
7094 environment variables GNUTLS_PIN and GNUTLS_SO_PIN.
7095
7096 </pre></div>
7097
7098 <a name="p11tool-debug"></a><a name="debug-option-_0028_002dd_0029"></a>
7099 <h4 class="subsection">5.2.8 debug option (-d)</h4>
7100
7101 <p>This is the &ldquo;enable debugging&rdquo; option.
7102 This option takes a number argument.
7103 Specifies the debug level.
7104 <a name="p11tool-export_002dchain"></a></p><a name="export_002dchain-option"></a>
7105 <h4 class="subsection">5.2.9 export-chain option</h4>
7106
7107 <p>This is the &ldquo;export the certificate specified by the url and its chain of trust&rdquo; option.
7108 Exports the certificate specified by the URL and generates its chain of trust based on the stored certificates in the module.
7109 <a name="p11tool-list_002dall_002dprivkeys"></a></p><a name="list_002dall_002dprivkeys-option"></a>
7110 <h4 class="subsection">5.2.10 list-all-privkeys option</h4>
7111
7112 <p>This is the &ldquo;list all available private keys in a token&rdquo; option.
7113 Lists all the private keys in a token that match the specified URL.
7114 <a name="p11tool-list_002dprivkeys"></a></p><a name="list_002dprivkeys-option"></a>
7115 <h4 class="subsection">5.2.11 list-privkeys option</h4>
7116
7117 <p>This is an alias for the <code>list-all-privkeys</code> option,
7118 see <a href="#p11tool-list_002dall_002dprivkeys">the list-all-privkeys option documentation</a>.
7119 </p>
7120 <a name="p11tool-list_002dkeys"></a><a name="list_002dkeys-option"></a>
7121 <h4 class="subsection">5.2.12 list-keys option</h4>
7122
7123 <p>This is an alias for the <code>list-all-privkeys</code> option,
7124 see <a href="#p11tool-list_002dall_002dprivkeys">the list-all-privkeys option documentation</a>.
7125 </p>
7126 <a name="p11tool-write"></a><a name="write-option"></a>
7127 <h4 class="subsection">5.2.13 write option</h4>
7128
7129 <p>This is the &ldquo;writes the loaded objects to a pkcs #11 token&rdquo; option.
7130 It can be used to write private keys, certificates or secret keys to a token.
7131 <a name="p11tool-generate_002drandom"></a></p><a name="generate_002drandom-option"></a>
7132 <h4 class="subsection">5.2.14 generate-random option</h4>
7133
7134 <p>This is the &ldquo;generate random data&rdquo; option.
7135 This option takes a number argument.
7136 Asks the token to generate a number of bytes of random bytes.
7137 <a name="p11tool-generate_002drsa"></a></p><a name="generate_002drsa-option"></a>
7138 <h4 class="subsection">5.2.15 generate-rsa option</h4>
7139
7140 <p>This is the &ldquo;generate an rsa private-public key pair&rdquo; option.
7141 Generates an RSA private-public key pair on the specified token.
7142 <a name="p11tool-generate_002ddsa"></a></p><a name="generate_002ddsa-option"></a>
7143 <h4 class="subsection">5.2.16 generate-dsa option</h4>
7144
7145 <p>This is the &ldquo;generate a dsa private-public key pair&rdquo; option.
7146 Generates a DSA private-public key pair on the specified token.
7147 <a name="p11tool-generate_002decc"></a></p><a name="generate_002decc-option"></a>
7148 <h4 class="subsection">5.2.17 generate-ecc option</h4>
7149
7150 <p>This is the &ldquo;generate an ecdsa private-public key pair&rdquo; option.
7151 Generates an ECDSA private-public key pair on the specified token.
7152 <a name="p11tool-export_002dpubkey"></a></p><a name="export_002dpubkey-option"></a>
7153 <h4 class="subsection">5.2.18 export-pubkey option</h4>
7154
7155 <p>This is the &ldquo;export the public key for a private key&rdquo; option.
7156 Exports the public key for the specified private key
7157 <a name="p11tool-set_002did"></a></p><a name="set_002did-option"></a>
7158 <h4 class="subsection">5.2.19 set-id option</h4>
7159
7160 <p>This is the &ldquo;set the cka_id (in hex) for the specified by the url object&rdquo; option.
7161 This option takes a string argument.
7162 Sets the CKA_ID in the specified by the URL object. The ID should be specified in hexadecimal format without a &rsquo;0x&rsquo; prefix.
7163 <a name="p11tool-set_002dlabel"></a></p><a name="set_002dlabel-option"></a>
7164 <h4 class="subsection">5.2.20 set-label option</h4>
7165
7166 <p>This is the &ldquo;set the cka_label for the specified by the url object&rdquo; option.
7167 This option takes a string argument.
7168 Sets the CKA_LABEL in the specified by the URL object
7169 <a name="p11tool-id"></a></p><a name="id-option"></a>
7170 <h4 class="subsection">5.2.21 id option</h4>
7171
7172 <p>This is the &ldquo;sets an id for the write operation&rdquo; option.
7173 This option takes a string argument.
7174 Sets the CKA_ID to be set by the write operation. The ID should be specified in hexadecimal format without a &rsquo;0x&rsquo; prefix.
7175 <a name="p11tool-mark_002dwrap"></a></p><a name="mark_002dwrap-option"></a>
7176 <h4 class="subsection">5.2.22 mark-wrap option</h4>
7177
7178 <p>This is the &ldquo;marks the generated key to be a wrapping key&rdquo; option.
7179 </p>
7180 <p>This option has some usage constraints.  It:
7181 </p><ul>
7182 <li> can be disabled with &ndash;no-mark-wrap.
7183 </li></ul>
7184
7185 <p>Marks the generated key with the CKA_WRAP flag.
7186 <a name="p11tool-mark_002dtrusted"></a></p><a name="mark_002dtrusted-option"></a>
7187 <h4 class="subsection">5.2.23 mark-trusted option</h4>
7188
7189 <p>This is the &ldquo;marks the object to be written as trusted&rdquo; option.
7190 </p>
7191 <p>This option has some usage constraints.  It:
7192 </p><ul>
7193 <li> can be disabled with &ndash;no-mark-trusted.
7194 </li></ul>
7195
7196 <p>Marks the object to be generated/copied with the CKA_TRUST flag.
7197 <a name="p11tool-mark_002dca"></a></p><a name="mark_002dca-option"></a>
7198 <h4 class="subsection">5.2.24 mark-ca option</h4>
7199
7200 <p>This is the &ldquo;marks the object to be written as a ca&rdquo; option.
7201 </p>
7202 <p>This option has some usage constraints.  It:
7203 </p><ul>
7204 <li> can be disabled with &ndash;no-mark-ca.
7205 </li></ul>
7206
7207 <p>Marks the object to be generated/copied with the CKA_CERTIFICATE_CATEGORY as CA.
7208 <a name="p11tool-mark_002dprivate"></a></p><a name="mark_002dprivate-option"></a>
7209 <h4 class="subsection">5.2.25 mark-private option</h4>
7210
7211 <p>This is the &ldquo;marks the object to be written as private&rdquo; option.
7212 </p>
7213 <p>This option has some usage constraints.  It:
7214 </p><ul>
7215 <li> can be disabled with &ndash;no-mark-private.
7216 </li><li> It is enabled by default.
7217 </li></ul>
7218
7219 <p>Marks the object to be generated/copied with the CKA_PRIVATE flag. The written object will require a PIN to be used.
7220 <a name="p11tool-trusted"></a></p><a name="trusted-option"></a>
7221 <h4 class="subsection">5.2.26 trusted option</h4>
7222
7223 <p>This is an alias for the <code>mark-trusted</code> option,
7224 see <a href="#p11tool-mark_002dtrusted">the mark-trusted option documentation</a>.
7225 </p>
7226 <a name="p11tool-ca"></a><a name="ca-option"></a>
7227 <h4 class="subsection">5.2.27 ca option</h4>
7228
7229 <p>This is an alias for the <code>mark-ca</code> option,
7230 see <a href="#p11tool-mark_002dca">the mark-ca option documentation</a>.
7231 </p>
7232 <a name="p11tool-private"></a><a name="private-option"></a>
7233 <h4 class="subsection">5.2.28 private option</h4>
7234
7235 <p>This is an alias for the <code>mark-private</code> option,
7236 see <a href="#p11tool-mark_002dprivate">the mark-private option documentation</a>.
7237 </p>
7238 <a name="p11tool-so_002dlogin"></a><a name="so_002dlogin-option"></a>
7239 <h4 class="subsection">5.2.29 so-login option</h4>
7240
7241 <p>This is the &ldquo;force security officer login to token&rdquo; option.
7242 </p>
7243 <p>This option has some usage constraints.  It:
7244 </p><ul>
7245 <li> can be disabled with &ndash;no-so-login.
7246 </li></ul>
7247
7248 <p>Forces login to the token as security officer (admin).
7249 <a name="p11tool-admin_002dlogin"></a></p><a name="admin_002dlogin-option"></a>
7250 <h4 class="subsection">5.2.30 admin-login option</h4>
7251
7252 <p>This is an alias for the <code>so-login</code> option,
7253 see <a href="#p11tool-so_002dlogin">the so-login option documentation</a>.
7254 </p>
7255 <a name="p11tool-curve"></a><a name="curve-option"></a>
7256 <h4 class="subsection">5.2.31 curve option</h4>
7257
7258 <p>This is the &ldquo;specify the curve used for ec key generation&rdquo; option.
7259 This option takes a string argument.
7260 Supported values are secp192r1, secp224r1, secp256r1, secp384r1 and secp521r1.
7261 <a name="p11tool-sec_002dparam"></a></p><a name="sec_002dparam-option"></a>
7262 <h4 class="subsection">5.2.32 sec-param option</h4>
7263
7264 <p>This is the &ldquo;specify the security level&rdquo; option.
7265 This option takes a string argument <samp>Security parameter</samp>.
7266 This is alternative to the bits option. Available options are [low, legacy, medium, high, ultra].
7267 <a name="p11tool-inder"></a></p><a name="inder-option"></a>
7268 <h4 class="subsection">5.2.33 inder option</h4>
7269
7270 <p>This is the &ldquo;use der/raw format for input&rdquo; option.
7271 </p>
7272 <p>This option has some usage constraints.  It:
7273 </p><ul>
7274 <li> can be disabled with &ndash;no-inder.
7275 </li></ul>
7276
7277 <p>Use DER/RAW format for input certificates and private keys.
7278 <a name="p11tool-inraw"></a></p><a name="inraw-option"></a>
7279 <h4 class="subsection">5.2.34 inraw option</h4>
7280
7281 <p>This is an alias for the <code>inder</code> option,
7282 see <a href="#p11tool-inder">the inder option documentation</a>.
7283 </p>
7284 <a name="p11tool-outder"></a><a name="outder-option"></a>
7285 <h4 class="subsection">5.2.35 outder option</h4>
7286
7287 <p>This is the &ldquo;use der format for output certificates, private keys, and dh parameters&rdquo; option.
7288 </p>
7289 <p>This option has some usage constraints.  It:
7290 </p><ul>
7291 <li> can be disabled with &ndash;no-outder.
7292 </li></ul>
7293
7294 <p>The output will be in DER or RAW format.
7295 <a name="p11tool-outraw"></a></p><a name="outraw-option"></a>
7296 <h4 class="subsection">5.2.36 outraw option</h4>
7297
7298 <p>This is an alias for the <code>outder</code> option,
7299 see <a href="#p11tool-outder">the outder option documentation</a>.
7300 </p>
7301 <a name="p11tool-set_002dpin"></a><a name="set_002dpin-option"></a>
7302 <h4 class="subsection">5.2.37 set-pin option</h4>
7303
7304 <p>This is the &ldquo;specify the pin to use on token initialization&rdquo; option.
7305 This option takes a string argument.
7306 Alternatively the GNUTLS_PIN environment variable may be used.
7307 <a name="p11tool-set_002dso_002dpin"></a></p><a name="set_002dso_002dpin-option"></a>
7308 <h4 class="subsection">5.2.38 set-so-pin option</h4>
7309
7310 <p>This is the &ldquo;specify the security officer&rsquo;s pin to use on token initialization&rdquo; option.
7311 This option takes a string argument.
7312 Alternatively the GNUTLS_SO_PIN environment variable may be used.
7313 <a name="p11tool-provider"></a></p><a name="provider-option"></a>
7314 <h4 class="subsection">5.2.39 provider option</h4>
7315
7316 <p>This is the &ldquo;specify the pkcs #11 provider library&rdquo; option.
7317 This option takes a file argument.
7318 This will override the default options in /etc/gnutls/pkcs11.conf
7319 <a name="p11tool-exit-status"></a></p><a name="p11tool-exit-status-1"></a>
7320 <h4 class="subsection">5.2.40 p11tool exit status</h4>
7321
7322 <p>One of the following exit values will be returned:
7323 </p><dl compact="compact">
7324 <dt>&lsquo;<samp>0 (EXIT_SUCCESS)</samp>&rsquo;</dt>
7325 <dd><p>Successful program execution.
7326 </p></dd>
7327 <dt>&lsquo;<samp>1 (EXIT_FAILURE)</samp>&rsquo;</dt>
7328 <dd><p>The operation failed or the command syntax was not valid.
7329 </p></dd>
7330 </dl>
7331 <a name="p11tool-See-Also"></a><a name="p11tool-See-Also-1"></a>
7332 <h4 class="subsection">5.2.41 p11tool See Also</h4>
7333 <p>certtool (1)
7334 <a name="p11tool-Examples"></a></p><a name="p11tool-Examples-1"></a>
7335 <h4 class="subsection">5.2.42 p11tool Examples</h4>
7336 <p>To view all tokens in your system use:
7337 </p><div class="example">
7338 <pre class="example">$ p11tool --list-tokens
7339 </pre></div>
7340
7341 <p>To view all objects in a token use:
7342 </p><div class="example">
7343 <pre class="example">$ p11tool --login --list-all &quot;pkcs11:TOKEN-URL&quot;
7344 </pre></div>
7345
7346 <p>To store a private key and a certificate in a token run:
7347 </p><div class="example">
7348 <pre class="example">$ p11tool --login --write &quot;pkcs11:URL&quot; --load-privkey key.pem \
7349           --label &quot;Mykey&quot;
7350 $ p11tool --login --write &quot;pkcs11:URL&quot; --load-certificate cert.pem \
7351           --label &quot;Mykey&quot;
7352 </pre></div>
7353 <p>Note that some tokens require the same label to be used for the certificate
7354 and its corresponding private key.
7355 </p>
7356 <p>To generate an RSA private key inside the token use:
7357 </p><div class="example">
7358 <pre class="example">$ p11tool --login --generate-rsa --bits 1024 --label &quot;MyNewKey&quot; \
7359           --outfile MyNewKey.pub &quot;pkcs11:TOKEN-URL&quot;
7360 </pre></div>
7361 <p>The bits parameter in the above example is explicitly set because some
7362 tokens only support limited choices in the bit length. The output file is the
7363 corresponding public key. This key can be used to general a certificate
7364 request with certtool.
7365 </p><div class="example">
7366 <pre class="example">certtool --generate-request --load-privkey &quot;pkcs11:KEY-URL&quot; \
7367    --load-pubkey MyNewKey.pub --outfile request.pem
7368 </pre></div>
7369
7370 <hr>
7371 <a name="Trusted-Platform-Module"></a>
7372 <div class="header">
7373 <p>
7374 Previous: <a href="#Smart-cards-and-HSMs" accesskey="p" rel="prev">Smart cards and HSMs</a>, Up: <a href="#Hardware-security-modules-and-abstract-key-types" accesskey="u" rel="up">Hardware security modules and abstract key types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
7375 </div>
7376 <a name="Trusted-Platform-Module-_0028TPM_0029"></a>
7377 <h3 class="section">5.3 Trusted Platform Module (TPM)</h3>
7378 <a name="index-trusted-platform-module"></a>
7379 <a name="index-TPM"></a>
7380
7381 <p>In this section we present the Trusted Platform Module (TPM) support
7382 in <acronym>GnuTLS</acronym>.
7383 </p>
7384 <p>There was a big hype when the TPM chip was introduced into
7385 computers. Briefly it is a co-processor in your PC that allows it to perform
7386 calculations independently of the main processor. This has good and bad
7387 side-effects. In this section we focus on the good ones; these are the fact that
7388 you can use the TPM chip to perform cryptographic operations on keys stored in it, without
7389 accessing them. That is very similar to the operation of a <acronym>PKCS</acronym> #11 smart card.
7390 The chip allows for storage and usage of RSA keys, but has quite some
7391 operational differences from <acronym>PKCS</acronym> #11 module, and thus require different handling.
7392 The basic TPM operations supported and used by GnuTLS, are key generation and signing.
7393 </p>
7394 <p>The next sections assume that the TPM chip in the system is already initialized and
7395 in a operational state.
7396 </p>
7397 <p>In GnuTLS the TPM functionality is available in <code>gnutls/tpm.h</code>.
7398 </p>
7399 <table class="menu" border="0" cellspacing="0">
7400 <tr><td align="left" valign="top">&bull; <a href="#Keys-in-TPM" accesskey="1">Keys in TPM</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7401 </td></tr>
7402 <tr><td align="left" valign="top">&bull; <a href="#Key-generation" accesskey="2">Key generation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7403 </td></tr>
7404 <tr><td align="left" valign="top">&bull; <a href="#Using-keys" accesskey="3">Using keys</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7405 </td></tr>
7406 <tr><td align="left" valign="top">&bull; <a href="#tpmtool-Invocation" accesskey="4">tpmtool Invocation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7407 </td></tr>
7408 </table>
7409
7410 <hr>
7411 <a name="Keys-in-TPM"></a>
7412 <div class="header">
7413 <p>
7414 Next: <a href="#Key-generation" accesskey="n" rel="next">Key generation</a>, Up: <a href="#Trusted-Platform-Module" accesskey="u" rel="up">Trusted Platform Module</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
7415 </div>
7416 <a name="Keys-in-TPM-1"></a>
7417 <h4 class="subsection">5.3.1 Keys in TPM</h4>
7418
7419 <p>The RSA keys in the TPM module may either be stored in a flash memory
7420 within TPM or stored in a file in disk. In the former case the key can
7421 provide operations as with <acronym>PKCS</acronym> #11 and is identified by
7422 a URL. The URL is described in [<em>TPMURI</em>] and is of the following form.
7423 </p><pre class="verbatim">tpmkey:uuid=42309df8-d101-11e1-a89a-97bb33c23ad1;storage=user
7424 </pre>
7425 <p>It consists from a unique identifier of the key as well as the part of the
7426 flash memory the key is stored at. The two options for the storage field are
7427 &lsquo;user&rsquo; and &lsquo;system&rsquo;. The user keys are typically only available to the generating
7428 user and the system keys to all users. The stored in TPM keys are called
7429 registered keys.
7430 </p>
7431 <p>The keys that are stored in the disk are exported from the TPM but in an
7432 encrypted form. To access them two passwords are required. The first is the TPM
7433 Storage Root Key (SRK), and the other is a key-specific password. Also those keys are
7434 identified by a URL of the form:
7435 </p><pre class="verbatim">tpmkey:file=/path/to/file
7436 </pre>
7437 <p>When objects require a PIN to be accessed the same callbacks as with PKCS #11
7438 objects are expected (see <a href="#Accessing-objects-that-require-a-PIN">Accessing objects that require a PIN</a>). Note
7439 that the PIN function may be called multiple times to unlock the SRK and
7440 the specific key in use. The label in the key function will then be set to
7441 &lsquo;SRK&rsquo; when unlocking the SRK key, or to &lsquo;TPM&rsquo; when unlocking any other key.
7442 </p>
7443 <hr>
7444 <a name="Key-generation"></a>
7445 <div class="header">
7446 <p>
7447 Next: <a href="#Using-keys" accesskey="n" rel="next">Using keys</a>, Previous: <a href="#Keys-in-TPM" accesskey="p" rel="prev">Keys in TPM</a>, Up: <a href="#Trusted-Platform-Module" accesskey="u" rel="up">Trusted Platform Module</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
7448 </div>
7449 <a name="Key-generation-1"></a>
7450 <h4 class="subsection">5.3.2 Key generation</h4>
7451
7452 <p>All keys used by the TPM must be generated by the TPM. This can be
7453 done using <a href="#gnutls_005ftpm_005fprivkey_005fgenerate">gnutls_tpm_privkey_generate</a>.
7454 </p>
7455
7456
7457
7458
7459 <dl>
7460 <dt><a name="index-gnutls_005ftpm_005fprivkey_005fgenerate"></a>Function: <em>int</em> <strong>gnutls_tpm_privkey_generate</strong> <em>(gnutls_pk_algorithm_t <var>pk</var>, unsigned int <var>bits</var>, const char * <var>srk_password</var>, const char * <var>key_password</var>, gnutls_tpmkey_fmt_t <var>format</var>, gnutls_x509_crt_fmt_t <var>pub_format</var>, gnutls_datum_t * <var>privkey</var>, gnutls_datum_t * <var>pubkey</var>, unsigned int <var>flags</var>)</em></dt>
7461 <dd><p><var>pk</var>: the public key algorithm
7462 </p>
7463 <p><var>bits</var>: the security bits
7464 </p>
7465 <p><var>srk_password</var>: a password to protect the exported key (optional)
7466 </p>
7467 <p><var>key_password</var>: the password for the TPM (optional)
7468 </p>
7469 <p><var>format</var>: the format of the private key
7470 </p>
7471 <p><var>pub_format</var>: the format of the public key
7472 </p>
7473 <p><var>privkey</var>: the generated key
7474 </p>
7475 <p><var>pubkey</var>: the corresponding public key (may be null)
7476 </p>
7477 <p><var>flags</var>: should be a list of GNUTLS_TPM_* flags
7478 </p>
7479 <p>This function will generate a private key in the TPM
7480 chip. The private key will be generated within the chip
7481 and will be exported in a wrapped with TPM&rsquo;s master key
7482 form. Furthermore the wrapped key can be protected with
7483 the provided  <code>password</code> .
7484 </p>
7485 <p>Note that bits in TPM is quantized value. If the input value
7486 is not one of the allowed values, then it will be quantized to
7487 one of 512, 1024, 2048, 4096, 8192 and 16384.
7488 </p>
7489 <p>Allowed flags are:
7490 </p>
7491 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
7492 negative error value.
7493 </p>
7494 <p><strong>Since:</strong> 3.1.0
7495 </p></dd></dl>
7496
7497 <dl compact="compact">
7498 <dt><code><var>int</var> <a href="#gnutls_005ftpm_005fget_005fregistered">gnutls_tpm_get_registered</a> (gnutls_tpm_key_list_t * <var>list</var>)</code></dt>
7499 <dt><code><var>void</var> <a href="#gnutls_005ftpm_005fkey_005flist_005fdeinit">gnutls_tpm_key_list_deinit</a> (gnutls_tpm_key_list_t <var>list</var>)</code></dt>
7500 <dt><code><var>int</var> <a href="#gnutls_005ftpm_005fkey_005flist_005fget_005furl">gnutls_tpm_key_list_get_url</a> (gnutls_tpm_key_list_t <var>list</var>, unsigned int <var>idx</var>, char ** <var>url</var>, unsigned int <var>flags</var>)</code></dt>
7501 </dl>
7502
7503
7504
7505
7506
7507 <dl>
7508 <dt><a name="index-gnutls_005ftpm_005fprivkey_005fdelete"></a>Function: <em>int</em> <strong>gnutls_tpm_privkey_delete</strong> <em>(const char * <var>url</var>, const char * <var>srk_password</var>)</em></dt>
7509 <dd><p><var>url</var>: the URL describing the key
7510 </p>
7511 <p><var>srk_password</var>: a password for the SRK key
7512 </p>
7513 <p>This function will unregister the private key from the TPM
7514 chip.
7515 </p>
7516 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
7517 negative error value.
7518 </p>
7519 <p><strong>Since:</strong> 3.1.0
7520 </p></dd></dl>
7521
7522 <hr>
7523 <a name="Using-keys"></a>
7524 <div class="header">
7525 <p>
7526 Next: <a href="#tpmtool-Invocation" accesskey="n" rel="next">tpmtool Invocation</a>, Previous: <a href="#Key-generation" accesskey="p" rel="prev">Key generation</a>, Up: <a href="#Trusted-Platform-Module" accesskey="u" rel="up">Trusted Platform Module</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
7527 </div>
7528 <a name="Using-keys-1"></a>
7529 <h4 class="subsection">5.3.3 Using keys</h4>
7530
7531 <a name="Importing-keys"></a>
7532 <h4 class="subsubheading">Importing keys</h4>
7533
7534 <p>The TPM keys can be used directly by the abstract key types and do not require
7535 any special structures. Moreover functions like <a href="#gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile2">gnutls_certificate_set_x509_key_file2</a>
7536 can access TPM URLs.
7537 </p>
7538 <dl compact="compact">
7539 <dt><code><var>int</var> <a href="#gnutls_005fprivkey_005fimport_005ftpm_005fraw">gnutls_privkey_import_tpm_raw</a> (gnutls_privkey_t <var>pkey</var>, const gnutls_datum_t * <var>fdata</var>, gnutls_tpmkey_fmt_t <var>format</var>, const char * <var>srk_password</var>, const char * <var>key_password</var>, unsigned int <var>flags</var>)</code></dt>
7540 <dt><code><var>int</var> <a href="#gnutls_005fpubkey_005fimport_005ftpm_005fraw">gnutls_pubkey_import_tpm_raw</a> (gnutls_pubkey_t <var>pkey</var>, const gnutls_datum_t * <var>fdata</var>, gnutls_tpmkey_fmt_t <var>format</var>, const char * <var>srk_password</var>, unsigned int <var>flags</var>)</code></dt>
7541 </dl>
7542
7543
7544
7545
7546
7547 <dl>
7548 <dt><a name="index-gnutls_005fprivkey_005fimport_005ftpm_005furl"></a>Function: <em>int</em> <strong>gnutls_privkey_import_tpm_url</strong> <em>(gnutls_privkey_t <var>pkey</var>, const char * <var>url</var>, const char * <var>srk_password</var>, const char * <var>key_password</var>, unsigned int <var>flags</var>)</em></dt>
7549 <dd><p><var>pkey</var>: The private key
7550 </p>
7551 <p><var>url</var>: The URL of the TPM key to be imported
7552 </p>
7553 <p><var>srk_password</var>: The password for the SRK key (optional)
7554 </p>
7555 <p><var>key_password</var>: A password for the key (optional)
7556 </p>
7557 <p><var>flags</var>: One of the GNUTLS_PRIVKEY_* flags
7558 </p>
7559 <p>This function will import the given private key to the abstract
7560 <code>gnutls_privkey_t</code>  structure.
7561 </p>
7562 <p>Note that unless <code>GNUTLS_PRIVKEY_DISABLE_CALLBACKS</code>
7563 is specified, if incorrect (or NULL) passwords are given
7564 the PKCS11 callback functions will be used to obtain the
7565 correct passwords. Otherwise if the SRK password is wrong
7566 <code>GNUTLS_E_TPM_SRK_PASSWORD_ERROR</code>  is returned and if the key password
7567 is wrong or not provided then <code>GNUTLS_E_TPM_KEY_PASSWORD_ERROR</code>
7568 is returned.
7569 </p>
7570 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
7571 negative error value.
7572 </p>
7573 <p><strong>Since:</strong> 3.1.0
7574 </p></dd></dl>
7575
7576
7577
7578
7579 <dl>
7580 <dt><a name="index-gnutls_005fpubkey_005fimport_005ftpm_005furl"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_tpm_url</strong> <em>(gnutls_pubkey_t <var>pkey</var>, const char * <var>url</var>, const char * <var>srk_password</var>, unsigned int <var>flags</var>)</em></dt>
7581 <dd><p><var>pkey</var>: The public key
7582 </p>
7583 <p><var>url</var>: The URL of the TPM key to be imported
7584 </p>
7585 <p><var>srk_password</var>: The password for the SRK key (optional)
7586 </p>
7587 <p><var>flags</var>: should be zero
7588 </p>
7589 <p>This function will import the given private key to the abstract
7590 <code>gnutls_privkey_t</code>  structure.
7591 </p>
7592 <p>Note that unless <code>GNUTLS_PUBKEY_DISABLE_CALLBACKS</code>
7593 is specified, if incorrect (or NULL) passwords are given
7594 the PKCS11 callback functions will be used to obtain the
7595 correct passwords. Otherwise if the SRK password is wrong
7596 <code>GNUTLS_E_TPM_SRK_PASSWORD_ERROR</code>  is returned.
7597 </p>
7598 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
7599 negative error value.
7600 </p>
7601 <p><strong>Since:</strong> 3.1.0
7602 </p></dd></dl>
7603
7604 <a name="Listing-and-deleting-keys"></a>
7605 <h4 class="subsubheading">Listing and deleting keys</h4>
7606
7607 <p>The registered keys (that are stored in the TPM) can be listed using one of
7608 the following functions. Those keys are unfortunately only identified by
7609 their UUID and have no label or other human friendly identifier.
7610 Keys can be deleted from permament storage using <a href="#gnutls_005ftpm_005fprivkey_005fdelete">gnutls_tpm_privkey_delete</a>.
7611 </p>
7612 <dl compact="compact">
7613 <dt><code><var>int</var> <a href="#gnutls_005ftpm_005fget_005fregistered">gnutls_tpm_get_registered</a> (gnutls_tpm_key_list_t * <var>list</var>)</code></dt>
7614 <dt><code><var>void</var> <a href="#gnutls_005ftpm_005fkey_005flist_005fdeinit">gnutls_tpm_key_list_deinit</a> (gnutls_tpm_key_list_t <var>list</var>)</code></dt>
7615 <dt><code><var>int</var> <a href="#gnutls_005ftpm_005fkey_005flist_005fget_005furl">gnutls_tpm_key_list_get_url</a> (gnutls_tpm_key_list_t <var>list</var>, unsigned int <var>idx</var>, char ** <var>url</var>, unsigned int <var>flags</var>)</code></dt>
7616 </dl>
7617
7618
7619
7620
7621
7622 <dl>
7623 <dt><a name="index-gnutls_005ftpm_005fprivkey_005fdelete-1"></a>Function: <em>int</em> <strong>gnutls_tpm_privkey_delete</strong> <em>(const char * <var>url</var>, const char * <var>srk_password</var>)</em></dt>
7624 <dd><p><var>url</var>: the URL describing the key
7625 </p>
7626 <p><var>srk_password</var>: a password for the SRK key
7627 </p>
7628 <p>This function will unregister the private key from the TPM
7629 chip.
7630 </p>
7631 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
7632 negative error value.
7633 </p>
7634 <p><strong>Since:</strong> 3.1.0
7635 </p></dd></dl>
7636
7637
7638 <hr>
7639 <a name="tpmtool-Invocation"></a>
7640 <div class="header">
7641 <p>
7642 Previous: <a href="#Using-keys" accesskey="p" rel="prev">Using keys</a>, Up: <a href="#Trusted-Platform-Module" accesskey="u" rel="up">Trusted Platform Module</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
7643 </div>
7644 <a name="Invoking-tpmtool"></a>
7645 <h4 class="subsection">5.3.4 Invoking tpmtool</h4>
7646 <a name="index-tpmtool"></a>
7647
7648
7649 <p>Program that allows handling cryptographic data from the TPM chip.
7650 </p>
7651 <p>This section was generated by <strong>AutoGen</strong>,
7652 using the <code>agtexi-cmd</code> template and the option descriptions for the <code>tpmtool</code> program.
7653 This software is released under the GNU General Public License, version 3 or later.
7654 </p>
7655
7656 <a name="tpmtool-usage"></a><a name="tpmtool-help_002fusage-_0028_002d_002dhelp_0029"></a>
7657 <h4 class="subsection">5.3.5 tpmtool help/usage (<samp>--help</samp>)</h4>
7658 <a name="index-tpmtool-help"></a>
7659
7660 <p>This is the automatically generated usage text for tpmtool.
7661 </p>
7662 <p>The text printed is the same whether selected with the <code>help</code> option
7663 (<samp>--help</samp>) or the <code>more-help</code> option (<samp>--more-help</samp>).  <code>more-help</code> will print
7664 the usage text by passing it through a pager program.
7665 <code>more-help</code> is disabled on platforms without a working
7666 <code>fork(2)</code> function.  The <code>PAGER</code> environment variable is
7667 used to select the program, defaulting to <samp>more</samp>.  Both will exit
7668 with a status code of 0.
7669 </p>
7670 <div class="example">
7671 <pre class="example">tpmtool is unavailable - no --help
7672 </pre></div>
7673
7674 <a name="tpmtool-debug"></a><a name="debug-option-_0028_002dd_0029-1"></a>
7675 <h4 class="subsection">5.3.6 debug option (-d)</h4>
7676
7677 <p>This is the &ldquo;enable debugging&rdquo; option.
7678 This option takes a number argument.
7679 Specifies the debug level.
7680 <a name="tpmtool-generate_002drsa"></a></p><a name="generate_002drsa-option-1"></a>
7681 <h4 class="subsection">5.3.7 generate-rsa option</h4>
7682
7683 <p>This is the &ldquo;generate an rsa private-public key pair&rdquo; option.
7684 Generates an RSA private-public key pair in the TPM chip.
7685 The key may be stored in filesystem and protected by a PIN, or stored (registered)
7686 in the TPM chip flash.
7687 <a name="tpmtool-user"></a></p><a name="user-option"></a>
7688 <h4 class="subsection">5.3.8 user option</h4>
7689
7690 <p>This is the &ldquo;any registered key will be a user key&rdquo; option.
7691 </p>
7692 <p>This option has some usage constraints.  It:
7693 </p><ul>
7694 <li> must appear in combination with the following options:
7695 register.
7696 </li><li> must not appear in combination with any of the following options:
7697 system.
7698 </li></ul>
7699
7700 <p>The generated key will be stored in a user specific persistent storage.
7701 <a name="tpmtool-system"></a></p><a name="system-option"></a>
7702 <h4 class="subsection">5.3.9 system option</h4>
7703
7704 <p>This is the &ldquo;any registred key will be a system key&rdquo; option.
7705 </p>
7706 <p>This option has some usage constraints.  It:
7707 </p><ul>
7708 <li> must appear in combination with the following options:
7709 register.
7710 </li><li> must not appear in combination with any of the following options:
7711 user.
7712 </li></ul>
7713
7714 <p>The generated key will be stored in system persistent storage.
7715 <a name="tpmtool-test_002dsign"></a></p><a name="test_002dsign-option"></a>
7716 <h4 class="subsection">5.3.10 test-sign option</h4>
7717
7718 <p>This is the &ldquo;tests the signature operation of the provided object&rdquo; option.
7719 This option takes a string argument <samp>url</samp>.
7720 It can be used to test the correct operation of the signature operation.
7721 This operation will sign and verify the signed data.
7722 <a name="tpmtool-sec_002dparam"></a></p><a name="sec_002dparam-option-1"></a>
7723 <h4 class="subsection">5.3.11 sec-param option</h4>
7724
7725 <p>This is the &ldquo;specify the security level [low, legacy, medium, high, ultra].&rdquo; option.
7726 This option takes a string argument <samp>Security parameter</samp>.
7727 This is alternative to the bits option. Note however that the
7728 values allowed by the TPM chip are quantized and given values may be rounded up.
7729 <a name="tpmtool-inder"></a></p><a name="inder-option-1"></a>
7730 <h4 class="subsection">5.3.12 inder option</h4>
7731
7732 <p>This is the &ldquo;use the der format for keys.&rdquo; option.
7733 </p>
7734 <p>This option has some usage constraints.  It:
7735 </p><ul>
7736 <li> can be disabled with &ndash;no-inder.
7737 </li></ul>
7738
7739 <p>The input files will be assumed to be in the portable
7740 DER format of TPM. The default format is a custom format used by various
7741 TPM tools
7742 <a name="tpmtool-outder"></a></p><a name="outder-option-1"></a>
7743 <h4 class="subsection">5.3.13 outder option</h4>
7744
7745 <p>This is the &ldquo;use der format for output keys&rdquo; option.
7746 </p>
7747 <p>This option has some usage constraints.  It:
7748 </p><ul>
7749 <li> can be disabled with &ndash;no-outder.
7750 </li></ul>
7751
7752 <p>The output will be in the TPM portable DER format.
7753 <a name="tpmtool-exit-status"></a></p><a name="tpmtool-exit-status-1"></a>
7754 <h4 class="subsection">5.3.14 tpmtool exit status</h4>
7755
7756 <p>One of the following exit values will be returned:
7757 </p><dl compact="compact">
7758 <dt>&lsquo;<samp>0 (EXIT_SUCCESS)</samp>&rsquo;</dt>
7759 <dd><p>Successful program execution.
7760 </p></dd>
7761 <dt>&lsquo;<samp>1 (EXIT_FAILURE)</samp>&rsquo;</dt>
7762 <dd><p>The operation failed or the command syntax was not valid.
7763 </p></dd>
7764 </dl>
7765 <a name="tpmtool-See-Also"></a><a name="tpmtool-See-Also-1"></a>
7766 <h4 class="subsection">5.3.15 tpmtool See Also</h4>
7767 <p>p11tool (1), certtool (1)
7768 <a name="tpmtool-Examples"></a></p><a name="tpmtool-Examples-1"></a>
7769 <h4 class="subsection">5.3.16 tpmtool Examples</h4>
7770 <p>To generate a key that is to be stored in filesystem use:
7771 </p><div class="example">
7772 <pre class="example">$ tpmtool --generate-rsa --bits 2048 --outfile tpmkey.pem
7773 </pre></div>
7774
7775 <p>To generate a key that is to be stored in TPM&rsquo;s flash use:
7776 </p><div class="example">
7777 <pre class="example">$ tpmtool --generate-rsa --bits 2048 --register --user
7778 </pre></div>
7779
7780 <p>To get the public key of a TPM key use:
7781 </p><div class="example">
7782 <pre class="example">$ tpmtool --pubkey tpmkey:uuid=58ad734b-bde6-45c7-89d8-756a55ad1891;storage=user \
7783           --outfile pubkey.pem
7784 </pre></div>
7785
7786 <p>or if the key is stored in the filesystem:
7787 </p><div class="example">
7788 <pre class="example">$ tpmtool --pubkey tpmkey:file=tmpkey.pem --outfile pubkey.pem
7789 </pre></div>
7790
7791 <p>To list all keys stored in TPM use:
7792 </p><div class="example">
7793 <pre class="example">$ tpmtool --list
7794 </pre></div>
7795
7796
7797 <hr>
7798 <a name="How-to-use-GnuTLS-in-applications"></a>
7799 <div class="header">
7800 <p>
7801 Next: <a href="#GnuTLS-application-examples" accesskey="n" rel="next">GnuTLS application examples</a>, Previous: <a href="#Hardware-security-modules-and-abstract-key-types" accesskey="p" rel="prev">Hardware security modules and abstract key types</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
7802 </div>
7803 <a name="How-to-use-GnuTLS-in-applications-1"></a>
7804 <h2 class="chapter">6 How to use <acronym>GnuTLS</acronym> in applications</h2>
7805
7806 <table class="menu" border="0" cellspacing="0">
7807 <tr><td align="left" valign="top">&bull; <a href="#Introduction-to-the-library" accesskey="1">Introduction to the library</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7808 </td></tr>
7809 <tr><td align="left" valign="top">&bull; <a href="#Preparation" accesskey="2">Preparation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7810 </td></tr>
7811 <tr><td align="left" valign="top">&bull; <a href="#Session-initialization" accesskey="3">Session initialization</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7812 </td></tr>
7813 <tr><td align="left" valign="top">&bull; <a href="#Associating-the-credentials" accesskey="4">Associating the credentials</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7814 </td></tr>
7815 <tr><td align="left" valign="top">&bull; <a href="#Setting-up-the-transport-layer" accesskey="5">Setting up the transport layer</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7816 </td></tr>
7817 <tr><td align="left" valign="top">&bull; <a href="#TLS-handshake" accesskey="6">TLS handshake</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7818 </td></tr>
7819 <tr><td align="left" valign="top">&bull; <a href="#Data-transfer-and-termination" accesskey="7">Data transfer and termination</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7820 </td></tr>
7821 <tr><td align="left" valign="top">&bull; <a href="#Buffered-data-transfer" accesskey="8">Buffered data transfer</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7822 </td></tr>
7823 <tr><td align="left" valign="top">&bull; <a href="#Handling-alerts" accesskey="9">Handling alerts</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7824 </td></tr>
7825 <tr><td align="left" valign="top">&bull; <a href="#Priority-Strings">Priority Strings</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7826 </td></tr>
7827 <tr><td align="left" valign="top">&bull; <a href="#Selecting-cryptographic-key-sizes">Selecting cryptographic key sizes</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7828 </td></tr>
7829 <tr><td align="left" valign="top">&bull; <a href="#Advanced-topics">Advanced topics</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7830 </td></tr>
7831 </table>
7832
7833 <hr>
7834 <a name="Introduction-to-the-library"></a>
7835 <div class="header">
7836 <p>
7837 Next: <a href="#Preparation" accesskey="n" rel="next">Preparation</a>, Up: <a href="#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
7838 </div>
7839 <a name="Introduction"></a>
7840 <h3 class="section">6.1 Introduction</h3>
7841
7842 <p>This chapter tries to explain the basic functionality of the current GnuTLS
7843 library. Note that there may be additional functionality not discussed here
7844 but included in the library. Checking the header files in <samp>/usr/include/gnutls/</samp>
7845 and the manpages is recommended.
7846 </p>
7847 <table class="menu" border="0" cellspacing="0">
7848 <tr><td align="left" valign="top">&bull; <a href="#General-idea" accesskey="1">General idea</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7849 </td></tr>
7850 <tr><td align="left" valign="top">&bull; <a href="#Error-handling" accesskey="2">Error handling</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7851 </td></tr>
7852 <tr><td align="left" valign="top">&bull; <a href="#Common-types" accesskey="3">Common types</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7853 </td></tr>
7854 <tr><td align="left" valign="top">&bull; <a href="#Debugging-and-auditing" accesskey="4">Debugging and auditing</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7855 </td></tr>
7856 <tr><td align="left" valign="top">&bull; <a href="#Thread-safety" accesskey="5">Thread safety</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7857 </td></tr>
7858 <tr><td align="left" valign="top">&bull; <a href="#Sessions-and-fork" accesskey="6">Sessions and fork</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7859 </td></tr>
7860 <tr><td align="left" valign="top">&bull; <a href="#Callback-functions" accesskey="7">Callback functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7861 </td></tr>
7862 </table>
7863
7864 <hr>
7865 <a name="General-idea"></a>
7866 <div class="header">
7867 <p>
7868 Next: <a href="#Error-handling" accesskey="n" rel="next">Error handling</a>, Up: <a href="#Introduction-to-the-library" accesskey="u" rel="up">Introduction to the library</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
7869 </div>
7870 <a name="General-idea-1"></a>
7871 <h4 class="subsection">6.1.1 General idea</h4>
7872
7873 <p>A brief description of how <acronym>GnuTLS</acronym> sessions operate is shown
7874 at <a href="#fig_002dgnutls_002ddesign">Figure 6.1</a>. This section will become more clear when it
7875 is completely read.
7876 As shown in the figure, there is a read-only global state that is
7877 initialized once by the global initialization function.  This global
7878 structure, among others, contains the memory allocation functions
7879 used, structures needed for the <acronym>ASN.1</acronym> parser and depending
7880 on the system&rsquo;s CPU, pointers to hardware accelerated encryption functions.  This
7881 structure is never modified by any <acronym>GnuTLS</acronym> function, except
7882 for the deinitialization function which frees all allocated memory
7883 and must be called after the program has permanently
7884 finished using <acronym>GnuTLS</acronym>.
7885 </p>
7886 <div class="float"><a name="fig_002dgnutls_002ddesign"></a>
7887 <img src="gnutls-internals.png" alt="gnutls-internals">
7888
7889 <div class="float-caption"><p><strong>Figure 6.1: </strong>High level design of GnuTLS.</p></div></div>
7890 <p>The credentials structures are used by the authentication methods, such
7891 as certificate authentication. They store certificates, privates keys,
7892 and other information that is needed to prove the identity to the peer,
7893 and/or verify the indentity of the peer. The information stored in
7894 the credentials structures is initialized once and then can be
7895 shared by many <acronym>TLS</acronym> sessions.
7896 </p>
7897 <p>A <acronym>GnuTLS</acronym> session contains all the required state and
7898 information to handle one secure connection. The session communicates with the
7899 peers using the provided functions of the transport layer.
7900 Every session has a unique session ID shared with the peer.
7901 </p>
7902 <p>Since TLS sessions can be resumed, servers need a
7903 database back-end to hold the session&rsquo;s parameters.  Every
7904 <acronym>GnuTLS</acronym> session after a successful handshake calls the
7905 appropriate back-end function (see <a href="#resume">resume</a>)
7906 to store the newly negotiated session. The session
7907 database is examined by the server just after having received the
7908 client hello<a name="DOCF11" href="#FOOT11"><sup>11</sup></a>,
7909 and if the session ID sent by the client, matches a stored session,
7910 the stored session will be retrieved, and the new session will be a
7911 resumed one, and will share the same session ID with the previous one.
7912 </p>
7913 <hr>
7914 <a name="Error-handling"></a>
7915 <div class="header">
7916 <p>
7917 Next: <a href="#Common-types" accesskey="n" rel="next">Common types</a>, Previous: <a href="#General-idea" accesskey="p" rel="prev">General idea</a>, Up: <a href="#Introduction-to-the-library" accesskey="u" rel="up">Introduction to the library</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
7918 </div>
7919 <a name="Error-handling-1"></a>
7920 <h4 class="subsection">6.1.2 Error handling</h4>
7921
7922 <p>In <acronym>GnuTLS</acronym> most functions return an integer type as a result.
7923 In almost all cases a zero or a positive number means success, and a
7924 negative number indicates failure, or a situation that some action has
7925 to be taken. Thus negative error codes may be fatal or not.
7926 </p>
7927 <p>Fatal errors terminate the connection immediately and further sends
7928 and receives will be disallowed.  Such an example is
7929 <code>GNUTLS_E_DECRYPTION_FAILED</code>. Non-fatal errors may warn about
7930 something, i.e., a warning alert was received, or indicate the some
7931 action has to be taken. This is the case with the error code
7932 <code>GNUTLS_E_REHANDSHAKE</code> returned by <a href="#gnutls_005frecord_005frecv">gnutls_record_recv</a>.
7933 This error code indicates that the server requests a re-handshake. The
7934 client may ignore this request, or may reply with an alert.  You can
7935 test if an error code is a fatal one by using the
7936 <a href="#gnutls_005ferror_005fis_005ffatal">gnutls_error_is_fatal</a>.
7937 All errors can be converted to a descriptive string using <a href="#gnutls_005fstrerror">gnutls_strerror</a>.
7938 </p>
7939 <p>If any non fatal errors, that require an action, are to be returned by
7940 a function, these error codes will be documented in the function&rsquo;s
7941 reference. For example the error codes <code>GNUTLS_E_WARNING_ALERT_RECEIVED</code> and <code>GNUTLS_E_FATAL_ALERT_RECEIVED</code>
7942 that may returned when receiving data, should be handled by notifying the
7943 user of the alert (as explained in <a href="#Handling-alerts">Handling alerts</a>).
7944 See <a href="#Error-codes">Error codes</a>, for a description of the available error codes.
7945 </p>
7946 <hr>
7947 <a name="Common-types"></a>
7948 <div class="header">
7949 <p>
7950 Next: <a href="#Debugging-and-auditing" accesskey="n" rel="next">Debugging and auditing</a>, Previous: <a href="#Error-handling" accesskey="p" rel="prev">Error handling</a>, Up: <a href="#Introduction-to-the-library" accesskey="u" rel="up">Introduction to the library</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
7951 </div>
7952 <a name="Common-types-1"></a>
7953 <h4 class="subsection">6.1.3 Common types</h4>
7954
7955 <p>All strings that are to provided as input to <acronym>GnuTLS</acronym> functions
7956 should be in UTF-8 unless otherwise specified. Output strings are also
7957 in UTF-8 format unless otherwise specified.
7958 </p>
7959 <p>When data of a fixed size are provided to <acronym>GnuTLS</acronym> functions then
7960 the helper structure <code>gnutls_datum_t</code> is often used. Its definition is
7961 shown below.
7962 </p><pre class="verbatim">  typedef struct
7963   {
7964     unsigned char *data;
7965     unsigned int size;
7966   } gnutls_datum_t;
7967 </pre>
7968 <p>Other functions that require data for scattered read use a structure similar
7969 to <code>struct iovec</code> typically used by <code>readv</code>. It is shown
7970 below.
7971 </p><pre class="verbatim">  typedef struct
7972   {
7973     void *iov_base;             /* Starting address */
7974     size_t iov_len;             /* Number of bytes to transfer */
7975   } giovec_t;
7976 </pre>
7977
7978 <hr>
7979 <a name="Debugging-and-auditing"></a>
7980 <div class="header">
7981 <p>
7982 Next: <a href="#Thread-safety" accesskey="n" rel="next">Thread safety</a>, Previous: <a href="#Common-types" accesskey="p" rel="prev">Common types</a>, Up: <a href="#Introduction-to-the-library" accesskey="u" rel="up">Introduction to the library</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
7983 </div>
7984 <a name="Debugging-and-auditing-1"></a>
7985 <h4 class="subsection">6.1.4 Debugging and auditing</h4>
7986
7987 <p>In many cases things may not go as expected and further information,
7988 to assist debugging, from <acronym>GnuTLS</acronym> is desired.
7989 Those are the cases where the <a href="#gnutls_005fglobal_005fset_005flog_005flevel">gnutls_global_set_log_level</a> and
7990 <a href="#gnutls_005fglobal_005fset_005flog_005ffunction">gnutls_global_set_log_function</a> are to be used. Those will print
7991 verbose information on the <acronym>GnuTLS</acronym> functions internal flow.
7992 </p>
7993 <dl compact="compact">
7994 <dt><code><var>void</var> <a href="#gnutls_005fglobal_005fset_005flog_005flevel">gnutls_global_set_log_level</a> (int <var>level</var>)</code></dt>
7995 <dt><code><var>void</var> <a href="#gnutls_005fglobal_005fset_005flog_005ffunction">gnutls_global_set_log_function</a> (gnutls_log_func <var>log_func</var>)</code></dt>
7996 </dl>
7997
7998 <p>Alternatively the environment variable <code>GNUTLS_DEBUG_LEVEL</code> can be
7999 set to a logging level and GnuTLS will output debugging output to standard
8000 error. Other available environment variables are shown in <a href="#tab_003aenvironment">Table 6.1</a>.
8001 </p>
8002 <div class="float"><a name="tab_003aenvironment"></a>
8003 <table>
8004 <thead><tr><th width="30%">Variable</th><th width="70%">Purpose</th></tr></thead>
8005 <tr><td width="30%"><code>GNUTLS_DEBUG_LEVEL</code></td><td width="70%">When set to a numeric value, it sets the default debugging level for GnuTLS applications.</td></tr>
8006 <tr><td width="30%"><code>GNUTLS_CPUID_OVERRIDE</code></td><td width="70%">That environment variable can be used to
8007 explicitly enable/disable the use of certain CPU capabilities. Note that CPU
8008 detection cannot be overriden, i.e., VIA options cannot be enabled on an Intel
8009 CPU. The currently available options are:
8010 <ul>
8011 <li> 0x1: Disable all run-time detected optimizations
8012 </li><li> 0x2: Enable AES-NI
8013 </li><li> 0x4: Enable SSSE3
8014 </li><li> 0x8: Enable PCLMUL
8015 </li><li> 0x100000: Enable VIA padlock
8016 </li><li> 0x200000: Enable VIA PHE
8017 </li><li> 0x400000: Enable VIA PHE SHA512
8018 </li></ul></td></tr>
8019 <tr><td width="30%"><code>GNUTLS_FORCE_FIPS_MODE</code></td><td width="70%">In setups where GnuTLS is compiled with support for FIPS140-2 (see &ndash;enable-fips140-mode in configure), that option if set to one enforces the FIPS140 mode.</td></tr>
8020 </table>
8021
8022 <div class="float-caption"><p><strong>Table 6.1: </strong>Environment variables used by the library.</p></div></div>
8023
8024 <p>When debugging is not required, important issues, such as detected
8025 attacks on the protocol still need to be logged. This is provided
8026 by the logging function set by
8027 <a href="#gnutls_005fglobal_005fset_005faudit_005flog_005ffunction">gnutls_global_set_audit_log_function</a>. The provided function
8028 will receive an message and the corresponding
8029 TLS session. The session information might be used to derive IP addresses
8030 or other information about the peer involved.
8031 </p>
8032
8033
8034
8035
8036 <dl>
8037 <dt><a name="index-gnutls_005fglobal_005fset_005faudit_005flog_005ffunction"></a>Function: <em>void</em> <strong>gnutls_global_set_audit_log_function</strong> <em>(gnutls_audit_log_func <var>log_func</var>)</em></dt>
8038 <dd><p><var>log_func</var>: it is the audit log function
8039 </p>
8040 <p>This is the function to set the audit logging function. This
8041 is a function to report important issues, such as possible
8042 attacks in the protocol. This is different from <code>gnutls_global_set_log_function()</code>
8043 because it will report also session-specific events. The session
8044 parameter will be null if there is no corresponding TLS session.
8045 </p>
8046 <p><code>gnutls_audit_log_func</code> is of the form,
8047 void (*gnutls_audit_log_func)( gnutls_session_t, const char*);
8048 </p>
8049 <p><strong>Since:</strong> 3.0
8050 </p></dd></dl>
8051
8052 <hr>
8053 <a name="Thread-safety"></a>
8054 <div class="header">
8055 <p>
8056 Next: <a href="#Sessions-and-fork" accesskey="n" rel="next">Sessions and fork</a>, Previous: <a href="#Debugging-and-auditing" accesskey="p" rel="prev">Debugging and auditing</a>, Up: <a href="#Introduction-to-the-library" accesskey="u" rel="up">Introduction to the library</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8057 </div>
8058 <a name="Thread-safety-1"></a>
8059 <h4 class="subsection">6.1.5 Thread safety</h4>
8060 <a name="index-thread-safety"></a>
8061
8062 <p>The <acronym>GnuTLS</acronym> library is thread safe by design, meaning that
8063 objects of the library such as TLS sessions, can be safely divided across
8064 threads as long as a single thread accesses a single object. This is
8065 sufficient to support a server which handles several sessions per thread.
8066 If, however, an object needs to be shared across threads then access must be
8067 protected with a mutex. Read-only access to objects, for example the
8068 credentials holding structures, is also thread-safe.
8069 </p>
8070 <p>A <code>gnutls_session_t</code> object can be shared by two threads, one sending,
8071 the other receiving. In that case rehandshakes, if required,
8072 must only be handled by a single thread being active. The termination of a session
8073 should be handled, either by a single thread being active, or by the sender thread
8074 using <a href="#gnutls_005fbye">gnutls_bye</a> with <code>GNUTLS_SHUT_WR</code> and the receiving thread
8075 waiting for a return value of zero.
8076 </p>
8077 <p>The random generator of the cryptographic back-end, utilizes mutex locks (e.g., pthreads on GNU/Linux and CriticalSection on Windows)
8078 which are setup by <acronym>GnuTLS</acronym> on library initialization. Prior to version 3.3.0
8079 they were setup by calling <a href="#gnutls_005fglobal_005finit">gnutls_global_init</a>. On special systems
8080 you could manually specify the locking system using
8081 the function <a href="#gnutls_005fglobal_005fset_005fmutex">gnutls_global_set_mutex</a> before calling any other
8082 GnuTLS function. Setting mutexes manually is not recommended.
8083 An example of non-native thread usage is shown below.
8084 </p>
8085 <div class="example">
8086 <pre class="example">#include &lt;gnutls/gnutls.h&gt;
8087
8088 int main()
8089 {
8090    /* When the system mutexes are not to be used
8091     * gnutls_global_set_mutex() must be called explicitly
8092     */
8093    gnutls_global_set_mutex (mutex_init, mutex_deinit,
8094                             mutex_lock, mutex_unlock);
8095 }
8096 </pre></div>
8097
8098
8099
8100
8101
8102 <dl>
8103 <dt><a name="index-gnutls_005fglobal_005fset_005fmutex"></a>Function: <em>void</em> <strong>gnutls_global_set_mutex</strong> <em>(mutex_init_func <var>init</var>, mutex_deinit_func <var>deinit</var>, mutex_lock_func <var>lock</var>, mutex_unlock_func <var>unlock</var>)</em></dt>
8104 <dd><p><var>init</var>: mutex initialization function
8105 </p>
8106 <p><var>deinit</var>: mutex deinitialization function
8107 </p>
8108 <p><var>lock</var>: mutex locking function
8109 </p>
8110 <p><var>unlock</var>: mutex unlocking function
8111 </p>
8112 <p>With this function you are allowed to override the default mutex
8113 locks used in some parts of gnutls and dependent libraries. This function
8114 should be used if you have complete control of your program and libraries.
8115 Do not call this function from a library, or preferrably from any application
8116 unless really needed to. GnuTLS will use the appropriate locks for the running
8117 system.
8118 </p>
8119 <p>This function must be called prior to any other gnutls function.
8120 </p>
8121 <p><strong>Since:</strong> 2.12.0
8122 </p></dd></dl>
8123
8124 <hr>
8125 <a name="Sessions-and-fork"></a>
8126 <div class="header">
8127 <p>
8128 Next: <a href="#Callback-functions" accesskey="n" rel="next">Callback functions</a>, Previous: <a href="#Thread-safety" accesskey="p" rel="prev">Thread safety</a>, Up: <a href="#Introduction-to-the-library" accesskey="u" rel="up">Introduction to the library</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8129 </div>
8130 <a name="Sessions-and-fork-1"></a>
8131 <h4 class="subsection">6.1.6 Sessions and fork</h4>
8132 <a name="index-fork"></a>
8133
8134 <p>A <code>gnutls_session_t</code> object can be shared by two processes after a fork,
8135 one sending, the other receiving. In that case rehandshakes,
8136 cannot and must not be performed. As with threads, the termination of a session should be
8137 handled by the sender process using <a href="#gnutls_005fbye">gnutls_bye</a> with <code>GNUTLS_SHUT_WR</code>
8138 and the receiving process waiting for a return value of zero.
8139 </p>
8140
8141 <hr>
8142 <a name="Callback-functions"></a>
8143 <div class="header">
8144 <p>
8145 Previous: <a href="#Sessions-and-fork" accesskey="p" rel="prev">Sessions and fork</a>, Up: <a href="#Introduction-to-the-library" accesskey="u" rel="up">Introduction to the library</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8146 </div>
8147 <a name="Callback-functions-1"></a>
8148 <h4 class="subsection">6.1.7 Callback functions</h4>
8149 <a name="index-callback-functions"></a>
8150
8151 <p>There are several cases where <acronym>GnuTLS</acronym> may need out of
8152 band input from your program. This is now implemented using some
8153 callback functions, which your program is expected to register.
8154 </p>
8155 <p>An example of this type of functions are the push and pull callbacks
8156 which are used to specify the functions that will retrieve and send
8157 data to the transport layer.
8158 </p>
8159 <dl compact="compact">
8160 <dt><code><var>void</var> <a href="#gnutls_005ftransport_005fset_005fpush_005ffunction">gnutls_transport_set_push_function</a> (gnutls_session_t <var>session</var>, gnutls_push_func <var>push_func</var>)</code></dt>
8161 <dt><code><var>void</var> <a href="#gnutls_005ftransport_005fset_005fpull_005ffunction">gnutls_transport_set_pull_function</a> (gnutls_session_t <var>session</var>, gnutls_pull_func <var>pull_func</var>)</code></dt>
8162 </dl>
8163
8164 <p>Other callback functions may require more complicated input and data
8165 to be allocated. Such an example is
8166 <a href="#gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffunction">gnutls_srp_set_server_credentials_function</a>.
8167 All callbacks should allocate and free memory using
8168 <code>gnutls_malloc</code> and <code>gnutls_free</code>.
8169 </p>
8170
8171 <hr>
8172 <a name="Preparation"></a>
8173 <div class="header">
8174 <p>
8175 Next: <a href="#Session-initialization" accesskey="n" rel="next">Session initialization</a>, Previous: <a href="#Introduction-to-the-library" accesskey="p" rel="prev">Introduction to the library</a>, Up: <a href="#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8176 </div>
8177 <a name="Preparation-1"></a>
8178 <h3 class="section">6.2 Preparation</h3>
8179
8180 <p>To use <acronym>GnuTLS</acronym>, you have to perform some changes to your
8181 sources and your build system. The necessary changes are explained in
8182 the following subsections.
8183 </p>
8184 <table class="menu" border="0" cellspacing="0">
8185 <tr><td align="left" valign="top">&bull; <a href="#Headers" accesskey="1">Headers</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8186 </td></tr>
8187 <tr><td align="left" valign="top">&bull; <a href="#Initialization" accesskey="2">Initialization</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8188 </td></tr>
8189 <tr><td align="left" valign="top">&bull; <a href="#Version-check" accesskey="3">Version check</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8190 </td></tr>
8191 <tr><td align="left" valign="top">&bull; <a href="#Building-the-source" accesskey="4">Building the source</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8192 </td></tr>
8193 </table>
8194
8195 <hr>
8196 <a name="Headers"></a>
8197 <div class="header">
8198 <p>
8199 Next: <a href="#Initialization" accesskey="n" rel="next">Initialization</a>, Up: <a href="#Preparation" accesskey="u" rel="up">Preparation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8200 </div>
8201 <a name="Headers-1"></a>
8202 <h4 class="subsection">6.2.1 Headers</h4>
8203
8204 <p>All the data types and functions of the <acronym>GnuTLS</acronym> library are
8205 defined in the header file <samp>gnutls/gnutls.h</samp>.  This must be
8206 included in all programs that make use of the <acronym>GnuTLS</acronym>
8207 library.
8208 </p>
8209 <hr>
8210 <a name="Initialization"></a>
8211 <div class="header">
8212 <p>
8213 Next: <a href="#Version-check" accesskey="n" rel="next">Version check</a>, Previous: <a href="#Headers" accesskey="p" rel="prev">Headers</a>, Up: <a href="#Preparation" accesskey="u" rel="up">Preparation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8214 </div>
8215 <a name="Initialization-2"></a>
8216 <h4 class="subsection">6.2.2 Initialization</h4>
8217
8218 <p>The GnuTLS library is initialized on load; prior to 3.3.0 was initialized by calling <a href="#gnutls_005fglobal_005finit">gnutls_global_init</a><a name="DOCF12" href="#FOOT12"><sup>12</sup></a>.
8219 The initialization typically enables CPU-specific acceleration, performs any required
8220 precalculations needed, opens any required system devices (e.g., /dev/urandom on Linux)
8221 and initializes subsystems that could be used later.
8222 </p>
8223 <p>The resources allocated by the initialization process will be released
8224 on library deinitialization, or explictly by calling <a href="#gnutls_005fglobal_005fdeinit">gnutls_global_deinit</a>.
8225 </p>
8226 <p>Note that during initialization file descriptors may be kept open by
8227 GnuTLS (e.g. /dev/urandom) on library load. Applications closing all unknown file
8228 descriptors must immediately call <a href="#gnutls_005fglobal_005finit">gnutls_global_init</a>, after that, to
8229 ensure they don&rsquo;t disrupt GnuTLS&rsquo; operation.
8230 </p>
8231
8232 <hr>
8233 <a name="Version-check"></a>
8234 <div class="header">
8235 <p>
8236 Next: <a href="#Building-the-source" accesskey="n" rel="next">Building the source</a>, Previous: <a href="#Initialization" accesskey="p" rel="prev">Initialization</a>, Up: <a href="#Preparation" accesskey="u" rel="up">Preparation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8237 </div>
8238 <a name="Version-check-1"></a>
8239 <h4 class="subsection">6.2.3 Version check</h4>
8240
8241 <p>It is often desirable to check that the version of &lsquo;gnutls&rsquo; used is
8242 indeed one which fits all requirements.  Even with binary
8243 compatibility new features may have been introduced but due to problem
8244 with the dynamic linker an old version is actually used.  So you may
8245 want to check that the version is okay right after program start-up.
8246 See the function <a href="#gnutls_005fcheck_005fversion">gnutls_check_version</a>.
8247 </p>
8248 <p>On the other hand, it is often desirable to support more than one
8249 versions of the library. In that case you could utilize compile-time
8250 feature checks using the the <code>GNUTLS_VERSION_NUMBER</code> macro.
8251 For example, to conditionally add code for GnuTLS 3.2.1 or later, you may use:
8252 </p><div class="example">
8253 <pre class="example">#if GNUTLS_VERSION_NUMBER &gt;= 0x030201
8254  ...
8255 #endif
8256 </pre></div>
8257
8258 <hr>
8259 <a name="Building-the-source"></a>
8260 <div class="header">
8261 <p>
8262 Previous: <a href="#Version-check" accesskey="p" rel="prev">Version check</a>, Up: <a href="#Preparation" accesskey="u" rel="up">Preparation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8263 </div>
8264 <a name="Building-the-source-1"></a>
8265 <h4 class="subsection">6.2.4 Building the source</h4>
8266
8267 <p>If you want to compile a source file including the
8268 <samp>gnutls/gnutls.h</samp> header file, you must make sure that the
8269 compiler can find it in the directory hierarchy.  This is accomplished
8270 by adding the path to the directory in which the header file is
8271 located to the compilers include file search path (via the <samp>-I</samp>
8272 option).
8273 </p>
8274 <p>However, the path to the include file is determined at the time the
8275 source is configured.  To solve this problem, the library uses the
8276 external package <code>pkg-config</code> that knows the path to the
8277 include file and other configuration options.  The options that need
8278 to be added to the compiler invocation at compile time are output by
8279 the <samp>--cflags</samp> option to <code>pkg-config gnutls</code>.  The
8280 following example shows how it can be used at the command line:
8281 </p>
8282 <div class="example">
8283 <pre class="example">gcc -c foo.c `pkg-config gnutls --cflags`
8284 </pre></div>
8285
8286 <p>Adding the output of &lsquo;<samp>pkg-config gnutls --cflags</samp>&rsquo; to the
8287 compilers command line will ensure that the compiler can find the
8288 <samp>gnutls/gnutls.h</samp> header file.
8289 </p>
8290 <p>A similar problem occurs when linking the program with the library.
8291 Again, the compiler has to find the library files.  For this to work,
8292 the path to the library files has to be added to the library search
8293 path (via the <samp>-L</samp> option).  For this, the option
8294 <samp>--libs</samp> to <code>pkg-config gnutls</code> can be used.  For
8295 convenience, this option also outputs all other options that are
8296 required to link the program with the library (for instance, the
8297 &lsquo;<samp>-ltasn1</samp>&rsquo; option).  The example shows how to link <samp>foo.o</samp>
8298 with the library to a program <code>foo</code>.
8299 </p>
8300 <div class="example">
8301 <pre class="example">gcc -o foo foo.o `pkg-config gnutls --libs`
8302 </pre></div>
8303
8304 <p>Of course you can also combine both examples to a single command by
8305 specifying both options to <code>pkg-config</code>:
8306 </p>
8307 <div class="example">
8308 <pre class="example">gcc -o foo foo.c `pkg-config gnutls --cflags --libs`
8309 </pre></div>
8310
8311 <p>When a program uses the GNU autoconf system, then the following
8312 line or similar can be used to detect the presence of GnuTLS.
8313 </p>
8314 <div class="example">
8315 <pre class="example">PKG_CHECK_MODULES([LIBGNUTLS], [gnutls &gt;= 3.3.0])
8316
8317 AC_SUBST([LIBGNUTLS_CFLAGS])
8318 AC_SUBST([LIBGNUTLS_LIBS])
8319 </pre></div>
8320
8321 <hr>
8322 <a name="Session-initialization"></a>
8323 <div class="header">
8324 <p>
8325 Next: <a href="#Associating-the-credentials" accesskey="n" rel="next">Associating the credentials</a>, Previous: <a href="#Preparation" accesskey="p" rel="prev">Preparation</a>, Up: <a href="#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8326 </div>
8327 <a name="Session-initialization-1"></a>
8328 <h3 class="section">6.3 Session initialization</h3>
8329
8330 <p>In the previous sections we have discussed the global initialization
8331 required for GnuTLS as well as the initialization required for each
8332 authentication method&rsquo;s credentials (see <a href="#Authentication">Authentication</a>).
8333 In this section we elaborate on the TLS or DTLS session initiation.
8334 Each session is initialized using <a href="#gnutls_005finit">gnutls_init</a> which among
8335 others is used to specify the type of the connection (server or client),
8336 and the underlying protocol type, i.e., datagram (UDP) or reliable (TCP).
8337 </p>
8338
8339
8340
8341
8342 <dl>
8343 <dt><a name="index-gnutls_005finit"></a>Function: <em>int</em> <strong>gnutls_init</strong> <em>(gnutls_session_t * <var>session</var>, unsigned int <var>flags</var>)</em></dt>
8344 <dd><p><var>session</var>: is a pointer to a <code>gnutls_session_t</code>  structure.
8345 </p>
8346 <p><var>flags</var>: indicate if this session is to be used for server or client.
8347 </p>
8348 <p>This function initializes the current session to null. Every
8349 session must be initialized before use, so internal structures can
8350 be allocated.  This function allocates structures which can only
8351 be free&rsquo;d by calling <code>gnutls_deinit()</code> .  Returns <code>GNUTLS_E_SUCCESS</code>  (0) on success.
8352 </p>
8353 <p><code>flags</code> can be one of <code>GNUTLS_CLIENT</code>  and <code>GNUTLS_SERVER</code> . For a DTLS
8354 entity, the flags <code>GNUTLS_DATAGRAM</code>  and  <code>GNUTLS_NONBLOCK</code>  are
8355 also available. The latter flag will enable a non-blocking
8356 operation of the DTLS timers.
8357 </p>
8358 <p>The flag <code>GNUTLS_NO_REPLAY_PROTECTION</code>  will disable any
8359 replay protection in DTLS mode. That must only used when
8360 replay protection is achieved using other means.
8361 </p>
8362 <p>Note that since version 3.1.2 this function enables some common
8363 TLS extensions such as session tickets and OCSP certificate status
8364 request in client side by default. To prevent that use the <code>GNUTLS_NO_EXTENSIONS</code>
8365 flag.
8366 </p>
8367 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
8368 </p></dd></dl>
8369
8370 <p>After the session initialization details on the allowed ciphersuites
8371 and protocol versions should be set using the priority functions
8372 such as <a href="#gnutls_005fpriority_005fset_005fdirect">gnutls_priority_set_direct</a>. We elaborate on them
8373 in <a href="#Priority-Strings">Priority Strings</a>.
8374 The credentials used for the key exchange method, such as certificates
8375 or usernames and passwords should also be associated with the session
8376 current session using <a href="#gnutls_005fcredentials_005fset">gnutls_credentials_set</a>.
8377 </p>
8378
8379
8380
8381
8382 <dl>
8383 <dt><a name="index-gnutls_005fcredentials_005fset"></a>Function: <em>int</em> <strong>gnutls_credentials_set</strong> <em>(gnutls_session_t <var>session</var>, gnutls_credentials_type_t <var>type</var>, void * <var>cred</var>)</em></dt>
8384 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
8385 </p>
8386 <p><var>type</var>: is the type of the credentials
8387 </p>
8388 <p><var>cred</var>: is a pointer to a structure.
8389 </p>
8390 <p>Sets the needed credentials for the specified type.  Eg username,
8391 password - or public and private keys etc.  The  <code>cred</code> parameter is
8392 a structure that depends on the specified type and on the current
8393 session (client or server).
8394 </p>
8395 <p>In order to minimize memory usage, and share credentials between
8396 several threads gnutls keeps a pointer to cred, and not the whole
8397 cred structure.  Thus you will have to keep the structure allocated
8398 until you call <code>gnutls_deinit()</code> .
8399 </p>
8400 <p>For <code>GNUTLS_CRD_ANON</code> ,  <code>cred</code> should be
8401 <code>gnutls_anon_client_credentials_t</code>  in case of a client.  In case of
8402 a server it should be <code>gnutls_anon_server_credentials_t</code> .
8403 </p>
8404 <p>For <code>GNUTLS_CRD_SRP</code> ,  <code>cred</code> should be <code>gnutls_srp_client_credentials_t</code>
8405 in case of a client, and <code>gnutls_srp_server_credentials_t</code> , in case
8406 of a server.
8407 </p>
8408 <p>For <code>GNUTLS_CRD_CERTIFICATE</code> ,  <code>cred</code> should be
8409 <code>gnutls_certificate_credentials_t</code> .
8410 </p>
8411 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
8412 otherwise a negative error code is returned.
8413 </p></dd></dl>
8414
8415 <hr>
8416 <a name="Associating-the-credentials"></a>
8417 <div class="header">
8418 <p>
8419 Next: <a href="#Setting-up-the-transport-layer" accesskey="n" rel="next">Setting up the transport layer</a>, Previous: <a href="#Session-initialization" accesskey="p" rel="prev">Session initialization</a>, Up: <a href="#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8420 </div>
8421 <a name="Associating-the-credentials-1"></a>
8422 <h3 class="section">6.4 Associating the credentials</h3>
8423
8424 <table class="menu" border="0" cellspacing="0">
8425 <tr><td align="left" valign="top">&bull; <a href="#Certificate-credentials" accesskey="1">Certificate credentials</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8426 </td></tr>
8427 <tr><td align="left" valign="top">&bull; <a href="#SRP-credentials" accesskey="2">SRP credentials</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8428 </td></tr>
8429 <tr><td align="left" valign="top">&bull; <a href="#PSK-credentials" accesskey="3">PSK credentials</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8430 </td></tr>
8431 <tr><td align="left" valign="top">&bull; <a href="#Anonymous-credentials" accesskey="4">Anonymous credentials</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8432 </td></tr>
8433 </table>
8434
8435 <p>Each authentication method is associated with a key exchange method, and a credentials type.
8436 The contents of the credentials is method-dependent, e.g. certificates
8437 for certificate authentication and should be initialized and associated
8438 with a session (see <a href="#gnutls_005fcredentials_005fset">gnutls_credentials_set</a>).  A mapping of the key exchange methods
8439 with the credential types is shown in <a href="#tab_003akey_002dexchange_002dcred">Table 6.2</a>.
8440 </p>
8441 <div class="float"><a name="tab_003akey_002dexchange_002dcred"></a>
8442 <table>
8443 <thead><tr><th width="25%">Authentication method</th><th width="25%">Key exchange</th><th width="20%">Client credentials</th><th width="20%">Server credentials</th></tr></thead>
8444 <tr><td width="25%">Certificate</td><td width="25%"><code>KX_RSA</code>,
8445 <code>KX_DHE_RSA</code>,
8446 <code>KX_DHE_DSS</code>,
8447 <code>KX_ECDHE_RSA</code>,
8448 <code>KX_ECDHE_ECDSA</code>,
8449 <code>KX_RSA_EXPORT</code></td><td width="20%"><code>CRD_CERTIFICATE</code></td><td width="20%"><code>CRD_CERTIFICATE</code></td></tr>
8450 <tr><td width="25%">Password and certificate</td><td width="25%"><code>KX_SRP_RSA</code>, <code>KX_SRP_DSS</code></td><td width="20%"><code>CRD_SRP</code></td><td width="20%"><code>CRD_CERTIFICATE</code>, <code>CRD_SRP</code></td></tr>
8451 <tr><td width="25%">Password</td><td width="25%"><code>KX_SRP</code></td><td width="20%"><code>CRD_SRP</code></td><td width="20%"><code>CRD_SRP</code></td></tr>
8452 <tr><td width="25%">Anonymous</td><td width="25%"><code>KX_ANON_DH</code>,
8453 <code>KX_ANON_ECDH</code></td><td width="20%"><code>CRD_ANON</code></td><td width="20%"><code>CRD_ANON</code></td></tr>
8454 <tr><td width="25%">Pre-shared key</td><td width="25%"><code>KX_PSK</code>,
8455 <code>KX_DHE_PSK</code>, <code>KX_ECDHE_PSK</code></td><td width="20%"><code>CRD_PSK</code></td><td width="20%"><code>CRD_PSK</code></td></tr>
8456 </table>
8457
8458 <div class="float-caption"><p><strong>Table 6.2: </strong>Key exchange algorithms and the corresponding credential types.</p></div></div>
8459 <hr>
8460 <a name="Certificate-credentials"></a>
8461 <div class="header">
8462 <p>
8463 Next: <a href="#SRP-credentials" accesskey="n" rel="next">SRP credentials</a>, Up: <a href="#Associating-the-credentials" accesskey="u" rel="up">Associating the credentials</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8464 </div>
8465 <a name="Certificates"></a>
8466 <h4 class="subsection">6.4.1 Certificates</h4>
8467 <a name="Server-certificate-authentication"></a>
8468 <h4 class="subsubheading">Server certificate authentication</h4>
8469
8470 <p>When using certificates the server is required to have at least one
8471 certificate and private key pair. Clients may not hold such
8472 a pair, but a server could require it. In this section we discuss
8473 general issues applying to both client and server certificates. The next
8474 section will elaborate on issues arising from client authentication only.
8475 </p>
8476 <dl compact="compact">
8477 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fallocate_005fcredentials">gnutls_certificate_allocate_credentials</a> (gnutls_certificate_credentials_t *      <var>res</var>)</code></dt>
8478 <dt><code><var>void</var> <a href="#gnutls_005fcertificate_005ffree_005fcredentials">gnutls_certificate_free_credentials</a> (gnutls_certificate_credentials_t <var>sc</var>)</code></dt>
8479 </dl>
8480
8481 <p>After the credentials structures are initialized, the certificate
8482 and key pair must be loaded. This occurs before any <acronym>TLS</acronym>
8483 session is initialized, and the same structures are reused for multiple sessions.
8484 Depending on the certificate type different loading functions
8485 are available, as shown below.
8486 For <acronym>X.509</acronym> certificates, the functions will
8487 accept and use a certificate chain that leads to a trusted
8488 authority. The certificate chain must be ordered in such way that every
8489 certificate certifies the one before it. The trusted authority&rsquo;s
8490 certificate need not to be included since the peer should possess it
8491 already.
8492 </p>
8493 <dl compact="compact">
8494 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fx509_005fkey_005fmem2">gnutls_certificate_set_x509_key_mem2</a> (gnutls_certificate_credentials_t <var>res</var>, const gnutls_datum_t * <var>cert</var>, const gnutls_datum_t * <var>key</var>, gnutls_x509_crt_fmt_t <var>type</var>, const char * <var>pass</var>, unsigned int <var>flags</var>)</code></dt>
8495 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fx509_005fkey">gnutls_certificate_set_x509_key</a> (gnutls_certificate_credentials_t <var>res</var>, gnutls_x509_crt_t * <var>cert_list</var>, int <var>cert_list_size</var>, gnutls_x509_privkey_t <var>key</var>)</code></dt>
8496 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile2">gnutls_certificate_set_x509_key_file2</a> (gnutls_certificate_credentials_t <var>res</var>, const char * <var>certfile</var>, const char * <var>keyfile</var>, gnutls_x509_crt_fmt_t <var>type</var>, const char * <var>pass</var>, unsigned int <var>flags</var>)</code></dt>
8497 </dl>
8498
8499 <dl compact="compact">
8500 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005fmem">gnutls_certificate_set_openpgp_key_mem</a> (gnutls_certificate_credentials_t            <var>res</var>, const gnutls_datum_t * <var>cert</var>, const gnutls_datum_t * <var>key</var>, gnutls_openpgp_crt_fmt_t <var>format</var>)</code></dt>
8501 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fopenpgp_005fkey">gnutls_certificate_set_openpgp_key</a> (gnutls_certificate_credentials_t <var>res</var>, gnutls_openpgp_crt_t <var>crt</var>, gnutls_openpgp_privkey_t <var>pkey</var>)</code></dt>
8502 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile">gnutls_certificate_set_openpgp_key_file</a> (gnutls_certificate_credentials_t      <var>res</var>, const char * <var>certfile</var>, const char * <var>keyfile</var>, gnutls_openpgp_crt_fmt_t <var>format</var>)</code></dt>
8503 </dl>
8504
8505 <p>Note however, that since functions like <a href="#gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile2">gnutls_certificate_set_x509_key_file2</a>
8506 may accept URLs that specify objects stored in token, another important
8507 function is <a href="#gnutls_005fcertificate_005fset_005fpin_005ffunction">gnutls_certificate_set_pin_function</a>. That
8508 allows setting a callback function to retrieve a PIN if the input keys are
8509 protected by PIN by the token.
8510 </p>
8511
8512
8513
8514
8515 <dl>
8516 <dt><a name="index-gnutls_005fcertificate_005fset_005fpin_005ffunction"></a>Function: <em>void</em> <strong>gnutls_certificate_set_pin_function</strong> <em>(gnutls_certificate_credentials_t       <var>cred</var>, gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</em></dt>
8517 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
8518 </p>
8519 <p><var>fn</var>: A PIN callback
8520 </p>
8521 <p><var>userdata</var>: Data to be passed in the callback
8522 </p>
8523 <p>This function will set a callback function to be used when
8524 required to access a protected object. This function overrides any other
8525 global PIN functions.
8526 </p>
8527 <p>Note that this function must be called right after initialization
8528 to have effect.
8529 </p>
8530 <p><strong>Since:</strong> 3.1.0
8531 </p></dd></dl>
8532
8533 <p>If the imported keys and certificates need to be accessed before any TLS session
8534 is established, it is convenient to use <a href="#gnutls_005fcertificate_005fset_005fkey">gnutls_certificate_set_key</a>
8535 in combination with <a href="#gnutls_005fpcert_005fimport_005fx509_005fraw">gnutls_pcert_import_x509_raw</a> and <a href="#gnutls_005fprivkey_005fimport_005fx509_005fraw">gnutls_privkey_import_x509_raw</a>.
8536 </p>
8537
8538
8539
8540 <dl>
8541 <dt><a name="index-gnutls_005fcertificate_005fset_005fkey"></a>Function: <em>int</em> <strong>gnutls_certificate_set_key</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, const char ** <var>names</var>, int <var>names_size</var>, gnutls_pcert_st * <var>pcert_list</var>, int <var>pcert_list_size</var>, gnutls_privkey_t <var>key</var>)</em></dt>
8542 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
8543 </p>
8544 <p><var>names</var>: is an array of DNS name of the certificate (NULL if none)
8545 </p>
8546 <p><var>names_size</var>: holds the size of the names list
8547 </p>
8548 <p><var>pcert_list</var>: contains a certificate list (path) for the specified private key
8549 </p>
8550 <p><var>pcert_list_size</var>: holds the size of the certificate list
8551 </p>
8552 <p><var>key</var>: is a <code>gnutls_privkey_t</code>  key
8553 </p>
8554 <p>This function sets a certificate/private key pair in the
8555 gnutls_certificate_credentials_t structure.  This function may be
8556 called more than once, in case multiple keys/certificates exist for
8557 the server.  For clients that wants to send more than its own end
8558 entity certificate (e.g., also an intermediate CA cert) then put
8559 the certificate chain in  <code>pcert_list</code> .
8560 </p>
8561 <p>Note that the  <code>pcert_list</code> and  <code>key</code> will become part of the credentials
8562 structure and must not be deallocated. They will be automatically deallocated
8563 when the  <code>res</code> structure is deinitialized.
8564 </p>
8565 <p>If that function fails to load the  <code>res</code> structure is at an undefined state, it must
8566 not be reused to load other keys or certificates.
8567 </p>
8568 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success, or a negative error code.
8569 </p>
8570 <p><strong>Since:</strong> 3.0
8571 </p></dd></dl>
8572
8573 <p>If multiple certificates are used with the functions above each
8574 client&rsquo;s request will be served with the certificate that matches the
8575 requested name (see <a href="#Server-name-indication">Server name indication</a>).
8576 </p>
8577 <p>As an alternative to loading from files or buffers, a callback may be used for the
8578 server or the client to specify the certificate and the key at the handshake time.
8579 In that case a certificate should be selected according the peer&rsquo;s signature
8580 algorithm preferences. To get those preferences use
8581 <a href="#gnutls_005fsign_005falgorithm_005fget_005frequested">gnutls_sign_algorithm_get_requested</a>. Both functions are shown below.
8582 </p>
8583 <dl compact="compact">
8584 <dt><code><var>void</var> <a href="#gnutls_005fcertificate_005fset_005fretrieve_005ffunction">gnutls_certificate_set_retrieve_function</a> (gnutls_certificate_credentials_t <var>cred</var>, gnutls_certificate_retrieve_function * <var>func</var>)</code></dt>
8585 <dt><code><var>void</var> <a href="#gnutls_005fcertificate_005fset_005fretrieve_005ffunction2">gnutls_certificate_set_retrieve_function2</a> (gnutls_certificate_credentials_t <var>cred</var>, gnutls_certificate_retrieve_function2 * <var>func</var>)</code></dt>
8586 <dt><code><var>int</var> <a href="#gnutls_005fsign_005falgorithm_005fget_005frequested">gnutls_sign_algorithm_get_requested</a> (gnutls_session_t <var>session</var>, size_t <var>indx</var>, gnutls_sign_algorithm_t * <var>algo</var>)</code></dt>
8587 </dl>
8588 <p>c
8589 The functions above do not handle the requested server name automatically.
8590 A server would need to check the name requested by the client
8591 using <a href="#gnutls_005fserver_005fname_005fget">gnutls_server_name_get</a>, and serve the appropriate
8592 certificate. Note that some of these functions require the <code>gnutls_pcert_st</code> structure to be
8593 filled in. Helper functions to fill in the structure are listed below.
8594 </p>
8595 <pre class="verbatim">typedef struct gnutls_pcert_st
8596 {
8597   gnutls_pubkey_t pubkey;
8598   gnutls_datum_t cert;
8599   gnutls_certificate_type_t type;
8600 } gnutls_pcert_st;
8601 </pre>
8602 <dl compact="compact">
8603 <dt><code><var>int</var> <a href="#gnutls_005fpcert_005fimport_005fx509">gnutls_pcert_import_x509</a> (gnutls_pcert_st * <var>pcert</var>, gnutls_x509_crt_t <var>crt</var>, unsigned int <var>flags</var>)</code></dt>
8604 <dt><code><var>int</var> <a href="#gnutls_005fpcert_005fimport_005fopenpgp">gnutls_pcert_import_openpgp</a> (gnutls_pcert_st * <var>pcert</var>, gnutls_openpgp_crt_t <var>crt</var>, unsigned int <var>flags</var>)</code></dt>
8605 <dt><code><var>int</var> <a href="#gnutls_005fpcert_005fimport_005fx509_005fraw">gnutls_pcert_import_x509_raw</a> (gnutls_pcert_st * <var>pcert</var>, const gnutls_datum_t * <var>cert</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned int <var>flags</var>)</code></dt>
8606 <dt><code><var>int</var> <a href="#gnutls_005fpcert_005fimport_005fopenpgp_005fraw">gnutls_pcert_import_openpgp_raw</a> (gnutls_pcert_st * <var>pcert</var>, const gnutls_datum_t * <var>cert</var>, gnutls_openpgp_crt_fmt_t <var>format</var>, gnutls_openpgp_keyid_t <var>keyid</var>, unsigned int <var>flags</var>)</code></dt>
8607 <dt><code><var>void</var> <a href="#gnutls_005fpcert_005fdeinit">gnutls_pcert_deinit</a> (gnutls_pcert_st * <var>pcert</var>)</code></dt>
8608 </dl>
8609
8610 <p>In a handshake, the negotiated cipher suite depends on the
8611 certificate&rsquo;s parameters, so some key exchange methods might not be
8612 available with all certificates. <acronym>GnuTLS</acronym> will disable
8613 ciphersuites that are not compatible with the key, or the enabled
8614 authentication methods.  For example keys marked as sign-only, will
8615 not be able to access the plain RSA ciphersuites, that require
8616 decryption. It is not recommended to use RSA keys for both
8617 signing and encryption. If possible use a different key for the
8618 <code>DHE-RSA</code> which uses signing and <code>RSA</code> that requires decryption.
8619 All the key exchange methods shown in <a href="#tab_003akey_002dexchange">Table 4.1</a> are
8620 available in certificate authentication.
8621 </p>
8622
8623 <a name="Client-certificate-authentication"></a>
8624 <h4 class="subsubheading">Client certificate authentication</h4>
8625
8626 <p>If a certificate is to be requested from the client during the handshake, the server
8627 will send a certificate request message. This behavior is controlled <a href="#gnutls_005fcertificate_005fserver_005fset_005frequest">gnutls_certificate_server_set_request</a>.
8628 The request contains a list of the acceptable by the server certificate signers. This list
8629 is constructed using the trusted certificate authorities of the server.
8630 In cases where the server supports a large number of certificate authorities
8631 it makes sense not to advertise all of the names to save bandwidth. That can
8632 be controlled using the function <a href="#gnutls_005fcertificate_005fsend_005fx509_005frdn_005fsequence">gnutls_certificate_send_x509_rdn_sequence</a>.
8633 This however will have the side-effect of not restricting the client to certificates
8634 signed by server&rsquo;s acceptable signers.
8635 </p>
8636
8637
8638
8639
8640 <dl>
8641 <dt><a name="index-gnutls_005fcertificate_005fserver_005fset_005frequest"></a>Function: <em>void</em> <strong>gnutls_certificate_server_set_request</strong> <em>(gnutls_session_t <var>session</var>, gnutls_certificate_request_t <var>req</var>)</em></dt>
8642 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
8643 </p>
8644 <p><var>req</var>: is one of GNUTLS_CERT_REQUEST, GNUTLS_CERT_REQUIRE
8645 </p>
8646 <p>This function specifies if we (in case of a server) are going to
8647 send a certificate request message to the client. If  <code>req</code> is
8648 GNUTLS_CERT_REQUIRE then the server will return an error if the
8649 peer does not provide a certificate. If you do not call this
8650 function then the client will not be asked to send a certificate.
8651 </p></dd></dl>
8652
8653
8654
8655
8656
8657 <dl>
8658 <dt><a name="index-gnutls_005fcertificate_005fsend_005fx509_005frdn_005fsequence"></a>Function: <em>void</em> <strong>gnutls_certificate_send_x509_rdn_sequence</strong> <em>(gnutls_session_t <var>session</var>, int <var>status</var>)</em></dt>
8659 <dd><p><var>session</var>: is a pointer to a <code>gnutls_session_t</code>  structure.
8660 </p>
8661 <p><var>status</var>: is 0 or 1
8662 </p>
8663 <p>If status is non zero, this function will order gnutls not to send
8664 the rdnSequence in the certificate request message. That is the
8665 server will not advertise its trusted CAs to the peer. If status
8666 is zero then the default behaviour will take effect, which is to
8667 advertise the server&rsquo;s trusted CAs.
8668 </p>
8669 <p>This function has no effect in clients, and in authentication
8670 methods other than certificate with X.509 certificates.
8671 </p></dd></dl>
8672
8673
8674 <a name="Client-or-server-certificate-verification"></a>
8675 <h4 class="subsubheading">Client or server certificate verification</h4>
8676
8677 <p>Certificate verification is possible by loading the trusted
8678 authorities into the credentials structure by using
8679 the following functions, applicable to X.509 and OpenPGP certificates.
8680 </p>
8681 <dl compact="compact">
8682 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fx509_005fsystem_005ftrust">gnutls_certificate_set_x509_system_trust</a> (gnutls_certificate_credentials_t       <var>cred</var>)</code></dt>
8683 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fx509_005ftrust_005ffile">gnutls_certificate_set_x509_trust_file</a> (gnutls_certificate_credentials_t            <var>cred</var>, const char * <var>cafile</var>, gnutls_x509_crt_fmt_t <var>type</var>)</code></dt>
8684 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005ffile">gnutls_certificate_set_openpgp_keyring_file</a> (gnutls_certificate_credentials_t <var>c</var>, const char * <var>file</var>, gnutls_openpgp_crt_fmt_t <var>format</var>)</code></dt>
8685 </dl>
8686
8687 <p>The peer&rsquo;s certificate is not automatically verified and one
8688 must call <a href="#gnutls_005fcertificate_005fverify_005fpeers3">gnutls_certificate_verify_peers3</a>
8689 after a successful handshake to verify the certificate&rsquo;s signature and the owner
8690 of the certificate. The verification status returned can be printed using
8691 <a href="#gnutls_005fcertificate_005fverification_005fstatus_005fprint">gnutls_certificate_verification_status_print</a>.
8692 </p>
8693 <p>Alternatively the verification can occur during the handshake
8694 by using <a href="#gnutls_005fcertificate_005fset_005fverify_005ffunction">gnutls_certificate_set_verify_function</a>.
8695 </p>
8696 <p>The functions above provide a brief verification output. If a
8697 detailed output is required one should call <a href="#gnutls_005fcertificate_005fget_005fpeers">gnutls_certificate_get_peers</a>
8698 to obtain the raw certificate of the peer and verify it using the
8699 functions discussed in <a href="#X_002e509-certificates">X.509 certificates</a>.
8700 </p>
8701
8702
8703
8704
8705 <dl>
8706 <dt><a name="index-gnutls_005fcertificate_005fverify_005fpeers3"></a>Function: <em>int</em> <strong>gnutls_certificate_verify_peers3</strong> <em>(gnutls_session_t <var>session</var>, const char * <var>hostname</var>, unsigned int * <var>status</var>)</em></dt>
8707 <dd><p><var>session</var>: is a gnutls session
8708 </p>
8709 <p><var>hostname</var>: is the expected name of the peer; may be <code>NULL</code>
8710 </p>
8711 <p><var>status</var>: is the output of the verification
8712 </p>
8713 <p>This function will verify the peer&rsquo;s certificate and store the
8714 status in the  <code>status</code> variable as a bitwise or&rsquo;d gnutls_certificate_status_t
8715 values or zero if the certificate is trusted. Note that value in  <code>status</code> is set only when the return value of this function is success (i.e, failure
8716 to trust a certificate does not imply a negative return value).
8717 The default verification flags used by this function can be overridden
8718 using <code>gnutls_certificate_set_verify_flags()</code> . See the documentation
8719 of <code>gnutls_certificate_verify_peers2()</code>  for details in the verification process.
8720 </p>
8721 <p>If the  <code>hostname</code> provided is non-NULL then this function will compare
8722 the hostname in the certificate against the given. The comparison will
8723 be accurate for ascii names; non-ascii names are compared byte-by-byte.
8724 If names do not match the <code>GNUTLS_CERT_UNEXPECTED_OWNER</code>  status flag will be set.
8725 </p>
8726 <p>In order to verify the purpose of the end-certificate (by checking the extended
8727 key usage), use <code>gnutls_certificate_verify_peers()</code> .
8728 </p>
8729 <p><strong>Returns:</strong> a negative error code on error and <code>GNUTLS_E_SUCCESS</code>  (0)
8730 when the peer&rsquo;s certificate was successfully parsed, irrespective of whether
8731 it was verified.
8732 </p>
8733 <p><strong>Since:</strong> 3.1.4
8734 </p></dd></dl>
8735
8736
8737
8738
8739
8740 <dl>
8741 <dt><a name="index-gnutls_005fcertificate_005fset_005fverify_005ffunction"></a>Function: <em>void</em> <strong>gnutls_certificate_set_verify_function</strong> <em>(gnutls_certificate_credentials_t <var>cred</var>, gnutls_certificate_verify_function * <var>func</var>)</em></dt>
8742 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
8743 </p>
8744 <p><var>func</var>: is the callback function
8745 </p>
8746 <p>This function sets a callback to be called when peer&rsquo;s certificate
8747 has been received in order to verify it on receipt rather than
8748 doing after the handshake is completed.
8749 </p>
8750 <p>The callback&rsquo;s function prototype is:
8751 int (*callback)(gnutls_session_t);
8752 </p>
8753 <p>If the callback function is provided then gnutls will call it, in the
8754 handshake, just after the certificate message has been received.
8755 To verify or obtain the certificate the <code>gnutls_certificate_verify_peers2()</code> ,
8756 <code>gnutls_certificate_type_get()</code> , <code>gnutls_certificate_get_peers()</code>  functions
8757 can be used.
8758 </p>
8759 <p>The callback function should return 0 for the handshake to continue
8760 or non-zero to terminate.
8761 </p>
8762 <p><strong>Since:</strong> 2.10.0
8763 </p></dd></dl>
8764
8765
8766 <hr>
8767 <a name="SRP-credentials"></a>
8768 <div class="header">
8769 <p>
8770 Next: <a href="#PSK-credentials" accesskey="n" rel="next">PSK credentials</a>, Previous: <a href="#Certificate-credentials" accesskey="p" rel="prev">Certificate credentials</a>, Up: <a href="#Associating-the-credentials" accesskey="u" rel="up">Associating the credentials</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8771 </div>
8772 <a name="SRP"></a>
8773 <h4 class="subsection">6.4.2 SRP</h4>
8774
8775 <p>The initialization functions in SRP credentials differ between
8776 client and server.
8777 Clients supporting <acronym>SRP</acronym> should set the username and password
8778 prior to connection, to the credentials structure.
8779 Alternatively <a href="#gnutls_005fsrp_005fset_005fclient_005fcredentials_005ffunction">gnutls_srp_set_client_credentials_function</a>
8780 may be used instead, to specify a callback function that should return the
8781 SRP username and password.
8782 The callback is called once during the <acronym>TLS</acronym> handshake.
8783 </p>
8784 <dl compact="compact">
8785 <dt><code><var>int</var> <a href="#gnutls_005fsrp_005fallocate_005fserver_005fcredentials">gnutls_srp_allocate_server_credentials</a> (gnutls_srp_server_credentials_t *            <var>sc</var>)</code></dt>
8786 <dt><code><var>int</var> <a href="#gnutls_005fsrp_005fallocate_005fclient_005fcredentials">gnutls_srp_allocate_client_credentials</a> (gnutls_srp_client_credentials_t *            <var>sc</var>)</code></dt>
8787 <dt><code><var>void</var> <a href="#gnutls_005fsrp_005ffree_005fserver_005fcredentials">gnutls_srp_free_server_credentials</a> (gnutls_srp_server_credentials_t <var>sc</var>)</code></dt>
8788 <dt><code><var>void</var> <a href="#gnutls_005fsrp_005ffree_005fclient_005fcredentials">gnutls_srp_free_client_credentials</a> (gnutls_srp_client_credentials_t <var>sc</var>)</code></dt>
8789 <dt><code><var>int</var> <a href="#gnutls_005fsrp_005fset_005fclient_005fcredentials">gnutls_srp_set_client_credentials</a> (gnutls_srp_client_credentials_t <var>res</var>, const char * <var>username</var>, const char * <var>password</var>)</code></dt>
8790 </dl>
8791
8792
8793
8794
8795
8796 <dl>
8797 <dt><a name="index-gnutls_005fsrp_005fset_005fclient_005fcredentials_005ffunction"></a>Function: <em>void</em> <strong>gnutls_srp_set_client_credentials_function</strong> <em>(gnutls_srp_client_credentials_t         <var>cred</var>, gnutls_srp_client_credentials_function         * <var>func</var>)</em></dt>
8798 <dd><p><var>cred</var>: is a <code>gnutls_srp_server_credentials_t</code>  structure.
8799 </p>
8800 <p><var>func</var>: is the callback function
8801 </p>
8802 <p>This function can be used to set a callback to retrieve the
8803 username and password for client SRP authentication.  The
8804 callback&rsquo;s function form is:
8805 </p>
8806 <p>int (*callback)(gnutls_session_t, char** username, char**password);
8807 </p>
8808 <p>The  <code>username</code> and  <code>password</code> must be allocated using
8809 <code>gnutls_malloc()</code> .   <code>username</code> and  <code>password</code> should be ASCII strings
8810 or UTF-8 strings prepared using the &quot;SASLprep&quot; profile of
8811 &quot;stringprep&quot;.
8812 </p>
8813 <p>The callback function will be called once per handshake before the
8814 initial hello message is sent.
8815 </p>
8816 <p>The callback should not return a negative error code the second
8817 time called, since the handshake procedure will be aborted.
8818 </p>
8819 <p>The callback function should return 0 on success.
8820 -1 indicates an error.
8821 </p></dd></dl>
8822
8823 <p>In server side the default behavior of <acronym>GnuTLS</acronym> is to read
8824 the usernames and <acronym>SRP</acronym> verifiers from password files. These
8825 password file format is compatible the with the <em>Stanford srp libraries</em>
8826 format.  If a different password file format is to be used, then
8827 <a href="#gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffunction">gnutls_srp_set_server_credentials_function</a> should be called,
8828 to set an appropriate callback.
8829 </p>
8830
8831
8832
8833
8834 <dl>
8835 <dt><a name="index-gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffile"></a>Function: <em>int</em> <strong>gnutls_srp_set_server_credentials_file</strong> <em>(gnutls_srp_server_credentials_t <var>res</var>, const char * <var>password_file</var>, const char * <var>password_conf_file</var>)</em></dt>
8836 <dd><p><var>res</var>: is a <code>gnutls_srp_server_credentials_t</code>  structure.
8837 </p>
8838 <p><var>password_file</var>: is the SRP password file (tpasswd)
8839 </p>
8840 <p><var>password_conf_file</var>: is the SRP password conf file (tpasswd.conf)
8841 </p>
8842 <p>This function sets the password files, in a
8843 <code>gnutls_srp_server_credentials_t</code>  structure.  Those password files
8844 hold usernames and verifiers and will be used for SRP
8845 authentication.
8846 </p>
8847 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or an
8848 error code.
8849 </p></dd></dl>
8850
8851
8852
8853
8854
8855 <dl>
8856 <dt><a name="index-gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffunction"></a>Function: <em>void</em> <strong>gnutls_srp_set_server_credentials_function</strong> <em>(gnutls_srp_server_credentials_t         <var>cred</var>, gnutls_srp_server_credentials_function         * <var>func</var>)</em></dt>
8857 <dd><p><var>cred</var>: is a <code>gnutls_srp_server_credentials_t</code>  structure.
8858 </p>
8859 <p><var>func</var>: is the callback function
8860 </p>
8861 <p>This function can be used to set a callback to retrieve the user&rsquo;s
8862 SRP credentials.  The callback&rsquo;s function form is:
8863 </p>
8864 <p>int (*callback)(gnutls_session_t, const char* username,
8865 gnutls_datum_t *salt, gnutls_datum_t *verifier, gnutls_datum_t *generator,
8866 gnutls_datum_t *prime);
8867 </p>
8868 <p><code>username</code> contains the actual username.
8869 The  <code>salt</code> ,  <code>verifier</code> ,  <code>generator</code> and  <code>prime</code> must be filled
8870 in using the <code>gnutls_malloc()</code> . For convenience  <code>prime</code> and  <code>generator</code> may also be one of the static parameters defined in gnutls.h.
8871 </p>
8872 <p>Initially, the data field is NULL in every <code>gnutls_datum_t</code>
8873 structure that the callback has to fill in. When the
8874 callback is done GnuTLS deallocates all of those buffers
8875 which are non-NULL, regardless of the return value.
8876 </p>
8877 <p>In order to prevent attackers from guessing valid usernames,
8878 if a user does not exist, g and n values should be filled in
8879 using a random user&rsquo;s parameters. In that case the callback must
8880 return the special value (1).
8881 See <code>gnutls_srp_set_server_fake_salt_seed</code>  too.
8882 If this is not required for your application, return a negative
8883 number from the callback to abort the handshake.
8884 </p>
8885 <p>The callback function will only be called once per handshake.
8886 The callback function should return 0 on success, while
8887 -1 indicates an error.
8888 </p></dd></dl>
8889
8890
8891 <hr>
8892 <a name="PSK-credentials"></a>
8893 <div class="header">
8894 <p>
8895 Next: <a href="#Anonymous-credentials" accesskey="n" rel="next">Anonymous credentials</a>, Previous: <a href="#SRP-credentials" accesskey="p" rel="prev">SRP credentials</a>, Up: <a href="#Associating-the-credentials" accesskey="u" rel="up">Associating the credentials</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8896 </div>
8897 <a name="PSK"></a>
8898 <h4 class="subsection">6.4.3 PSK</h4>
8899 <p>The initialization functions in PSK credentials differ between
8900 client and server.
8901 </p>
8902 <dl compact="compact">
8903 <dt><code><var>int</var> <a href="#gnutls_005fpsk_005fallocate_005fserver_005fcredentials">gnutls_psk_allocate_server_credentials</a> (gnutls_psk_server_credentials_t *            <var>sc</var>)</code></dt>
8904 <dt><code><var>int</var> <a href="#gnutls_005fpsk_005fallocate_005fclient_005fcredentials">gnutls_psk_allocate_client_credentials</a> (gnutls_psk_client_credentials_t *            <var>sc</var>)</code></dt>
8905 <dt><code><var>void</var> <a href="#gnutls_005fpsk_005ffree_005fserver_005fcredentials">gnutls_psk_free_server_credentials</a> (gnutls_psk_server_credentials_t <var>sc</var>)</code></dt>
8906 <dt><code><var>void</var> <a href="#gnutls_005fpsk_005ffree_005fclient_005fcredentials">gnutls_psk_free_client_credentials</a> (gnutls_psk_client_credentials_t <var>sc</var>)</code></dt>
8907 </dl>
8908
8909 <p>Clients supporting <acronym>PSK</acronym> should supply the username and key
8910 before a TLS session is established.  Alternatively
8911 <a href="#gnutls_005fpsk_005fset_005fclient_005fcredentials_005ffunction">gnutls_psk_set_client_credentials_function</a> can be used to
8912 specify a callback function. This has the
8913 advantage that the callback will be called only if <acronym>PSK</acronym> has
8914 been negotiated.
8915 </p>
8916 <dl compact="compact">
8917 <dt><code><var>int</var> <a href="#gnutls_005fpsk_005fset_005fclient_005fcredentials">gnutls_psk_set_client_credentials</a> (gnutls_psk_client_credentials_t <var>res</var>, const char * <var>username</var>, const gnutls_datum_t * <var>key</var>, gnutls_psk_key_flags <var>flags</var>)</code></dt>
8918 </dl>
8919
8920
8921
8922
8923
8924 <dl>
8925 <dt><a name="index-gnutls_005fpsk_005fset_005fclient_005fcredentials_005ffunction"></a>Function: <em>void</em> <strong>gnutls_psk_set_client_credentials_function</strong> <em>(gnutls_psk_client_credentials_t         <var>cred</var>, gnutls_psk_client_credentials_function         * <var>func</var>)</em></dt>
8926 <dd><p><var>cred</var>: is a <code>gnutls_psk_server_credentials_t</code>  structure.
8927 </p>
8928 <p><var>func</var>: is the callback function
8929 </p>
8930 <p>This function can be used to set a callback to retrieve the username and
8931 password for client PSK authentication.
8932 The callback&rsquo;s function form is:
8933 int (*callback)(gnutls_session_t, char** username,
8934 gnutls_datum_t* key);
8935 </p>
8936 <p>The  <code>username</code> and  <code>key</code> -&gt;data must be allocated using <code>gnutls_malloc()</code> .
8937  <code>username</code> should be ASCII strings or UTF-8 strings prepared using
8938 the &quot;SASLprep&quot; profile of &quot;stringprep&quot;.
8939 </p>
8940 <p>The callback function will be called once per handshake.
8941 </p>
8942 <p>The callback function should return 0 on success.
8943 -1 indicates an error.
8944 </p></dd></dl>
8945
8946 <p>In server side the default behavior of <acronym>GnuTLS</acronym> is to read
8947 the usernames and <acronym>PSK</acronym> keys from a password file. The
8948 password file should contain usernames and keys in hexadecimal
8949 format. The name of the password file can be stored to the credentials
8950 structure by calling <a href="#gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffile">gnutls_psk_set_server_credentials_file</a>.  If
8951 a different password file format is to be used, then
8952 a callback should be set instead by <a href="#gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffunction">gnutls_psk_set_server_credentials_function</a>.
8953 </p>
8954 <p>The server can help the client chose a suitable username and password,
8955 by sending a hint. Note that there is no common profile for the PSK hint and applications
8956 are discouraged to use it.
8957 A server, may specify the hint by calling
8958 <a href="#gnutls_005fpsk_005fset_005fserver_005fcredentials_005fhint">gnutls_psk_set_server_credentials_hint</a>.  The client can retrieve
8959 the hint, for example in the callback function, using
8960 <a href="#gnutls_005fpsk_005fclient_005fget_005fhint">gnutls_psk_client_get_hint</a>.
8961 </p>
8962
8963
8964
8965
8966 <dl>
8967 <dt><a name="index-gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffile"></a>Function: <em>int</em> <strong>gnutls_psk_set_server_credentials_file</strong> <em>(gnutls_psk_server_credentials_t            <var>res</var>, const char * <var>password_file</var>)</em></dt>
8968 <dd><p><var>res</var>: is a <code>gnutls_psk_server_credentials_t</code>  structure.
8969 </p>
8970 <p><var>password_file</var>: is the PSK password file (passwd.psk)
8971 </p>
8972 <p>This function sets the password file, in a
8973 <code>gnutls_psk_server_credentials_t</code>  structure.  This password file
8974 holds usernames and keys and will be used for PSK authentication.
8975 </p>
8976 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
8977 an error code is returned.
8978 </p></dd></dl>
8979
8980 <dl compact="compact">
8981 <dt><code><var>void</var> <a href="#gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffunction">gnutls_psk_set_server_credentials_function</a> (gnutls_psk_server_credentials_t         <var>cred</var>, gnutls_psk_server_credentials_function         * <var>func</var>)</code></dt>
8982 <dt><code><var>int</var> <a href="#gnutls_005fpsk_005fset_005fserver_005fcredentials_005fhint">gnutls_psk_set_server_credentials_hint</a> (gnutls_psk_server_credentials_t <var>res</var>, const char * <var>hint</var>)</code></dt>
8983 <dt><code><var>const char *</var> <a href="#gnutls_005fpsk_005fclient_005fget_005fhint">gnutls_psk_client_get_hint</a> (gnutls_session_t <var>session</var>)</code></dt>
8984 </dl>
8985
8986 <hr>
8987 <a name="Anonymous-credentials"></a>
8988 <div class="header">
8989 <p>
8990 Previous: <a href="#PSK-credentials" accesskey="p" rel="prev">PSK credentials</a>, Up: <a href="#Associating-the-credentials" accesskey="u" rel="up">Associating the credentials</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
8991 </div>
8992 <a name="Anonymous"></a>
8993 <h4 class="subsection">6.4.4 Anonymous</h4>
8994 <p>The key exchange methods for anonymous authentication
8995 might require Diffie-Hellman parameters to be generated by the server and
8996 associated with an anonymous credentials structure. Check
8997 <a href="#Parameter-generation">Parameter generation</a> for more information.
8998 The initialization functions for the credentials are shown below.
8999 </p>
9000 <dl compact="compact">
9001 <dt><code><var>int</var> <a href="#gnutls_005fanon_005fallocate_005fserver_005fcredentials">gnutls_anon_allocate_server_credentials</a> (gnutls_anon_server_credentials_t *      <var>sc</var>)</code></dt>
9002 <dt><code><var>int</var> <a href="#gnutls_005fanon_005fallocate_005fclient_005fcredentials">gnutls_anon_allocate_client_credentials</a> (gnutls_anon_client_credentials_t *      <var>sc</var>)</code></dt>
9003 <dt><code><var>void</var> <a href="#gnutls_005fanon_005ffree_005fserver_005fcredentials">gnutls_anon_free_server_credentials</a> (gnutls_anon_server_credentials_t <var>sc</var>)</code></dt>
9004 <dt><code><var>void</var> <a href="#gnutls_005fanon_005ffree_005fclient_005fcredentials">gnutls_anon_free_client_credentials</a> (gnutls_anon_client_credentials_t <var>sc</var>)</code></dt>
9005 </dl>
9006
9007
9008
9009 <hr>
9010 <a name="Setting-up-the-transport-layer"></a>
9011 <div class="header">
9012 <p>
9013 Next: <a href="#TLS-handshake" accesskey="n" rel="next">TLS handshake</a>, Previous: <a href="#Associating-the-credentials" accesskey="p" rel="prev">Associating the credentials</a>, Up: <a href="#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
9014 </div>
9015 <a name="Setting-up-the-transport-layer-1"></a>
9016 <h3 class="section">6.5 Setting up the transport layer</h3>
9017
9018 <p>The next step is to setup the underlying transport layer details. The
9019 Berkeley sockets are implicitly used by GnuTLS, thus a
9020 call to <a href="#gnutls_005ftransport_005fset_005fint">gnutls_transport_set_int</a> would be sufficient to
9021 specify the socket descriptor.
9022 </p>
9023 <dl compact="compact">
9024 <dt><code><var>void</var> <a href="#gnutls_005ftransport_005fset_005fint">gnutls_transport_set_int</a> (gnutls_session_t <var>session</var>, int <var>i</var>)</code></dt>
9025 <dt><code><var>void</var> <a href="#gnutls_005ftransport_005fset_005fint2">gnutls_transport_set_int2</a> (gnutls_session_t <var>session</var>, int <var>recv_int</var>, int <var>send_int</var>)</code></dt>
9026 </dl>
9027
9028 <p>If however another transport layer than TCP is selected, then
9029 a pointer should be used instead to express the parameter to be
9030 passed to custom functions. In that case the following functions should
9031 be used instead.
9032 </p>
9033 <dl compact="compact">
9034 <dt><code><var>void</var> <a href="#gnutls_005ftransport_005fset_005fptr">gnutls_transport_set_ptr</a> (gnutls_session_t <var>session</var>, gnutls_transport_ptr_t <var>ptr</var>)</code></dt>
9035 <dt><code><var>void</var> <a href="#gnutls_005ftransport_005fset_005fptr2">gnutls_transport_set_ptr2</a> (gnutls_session_t <var>session</var>, gnutls_transport_ptr_t <var>recv_ptr</var>, gnutls_transport_ptr_t <var>send_ptr</var>)</code></dt>
9036 </dl>
9037
9038 <p>Moreover all of the following push and pull callbacks should be set.
9039 </p>
9040
9041
9042
9043
9044 <dl>
9045 <dt><a name="index-gnutls_005ftransport_005fset_005fpush_005ffunction"></a>Function: <em>void</em> <strong>gnutls_transport_set_push_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_push_func <var>push_func</var>)</em></dt>
9046 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9047 </p>
9048 <p><var>push_func</var>: a callback function similar to <code>write()</code>
9049 </p>
9050 <p>This is the function where you set a push function for gnutls to
9051 use in order to send data.  If you are going to use berkeley style
9052 sockets, you do not need to use this function since the default
9053 send(2) will probably be ok.  Otherwise you should specify this
9054 function for gnutls to be able to send data.
9055 The callback should return a positive number indicating the
9056 bytes sent, and -1 on error.
9057 </p>
9058 <p><code>push_func</code> is of the form,
9059 ssize_t (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t);
9060 </p></dd></dl>
9061
9062
9063
9064
9065 <dl>
9066 <dt><a name="index-gnutls_005ftransport_005fset_005fvec_005fpush_005ffunction"></a>Function: <em>void</em> <strong>gnutls_transport_set_vec_push_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_vec_push_func <var>vec_func</var>)</em></dt>
9067 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9068 </p>
9069 <p><var>vec_func</var>: a callback function similar to <code>writev()</code>
9070 </p>
9071 <p>Using this function you can override the default writev(2)
9072 function for gnutls to send data. Setting this callback
9073 instead of <code>gnutls_transport_set_push_function()</code>  is recommended
9074 since it introduces less overhead in the TLS handshake process.
9075 </p>
9076 <p><code>vec_func</code> is of the form,
9077 ssize_t (*gnutls_vec_push_func) (gnutls_transport_ptr_t, const giovec_t * iov, int iovcnt);
9078 </p>
9079 <p><strong>Since:</strong> 2.12.0
9080 </p></dd></dl>
9081
9082
9083
9084
9085 <dl>
9086 <dt><a name="index-gnutls_005ftransport_005fset_005fpull_005ffunction"></a>Function: <em>void</em> <strong>gnutls_transport_set_pull_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_pull_func <var>pull_func</var>)</em></dt>
9087 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9088 </p>
9089 <p><var>pull_func</var>: a callback function similar to <code>read()</code>
9090 </p>
9091 <p>This is the function where you set a function for gnutls to receive
9092 data.  Normally, if you use berkeley style sockets, do not need to
9093 use this function since the default recv(2) will probably be ok.
9094 The callback should return 0 on connection termination, a positive
9095 number indicating the number of bytes received, and -1 on error.
9096 </p>
9097 <p><code>gnutls_pull_func</code> is of the form,
9098 ssize_t (*gnutls_pull_func)(gnutls_transport_ptr_t, void*, size_t);
9099 </p></dd></dl>
9100
9101
9102
9103
9104 <dl>
9105 <dt><a name="index-gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction"></a>Function: <em>void</em> <strong>gnutls_transport_set_pull_timeout_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_pull_timeout_func <var>func</var>)</em></dt>
9106 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9107 </p>
9108 <p><var>func</var>: a callback function
9109 </p>
9110 <p>This is the function where you set a function for gnutls to know
9111 whether data are ready to be received. It should wait for data a
9112 given time frame in milliseconds. The callback should return 0 on
9113 timeout, a positive number if data can be received, and -1 on error.
9114 You&rsquo;ll need to override this function if <code>select()</code>  is not suitable
9115 for the provided transport calls.
9116 </p>
9117 <p>As with <code>select()</code> , if the timeout value is zero the callback should return
9118 zero if no data are immediately available.
9119 </p>
9120 <p><code>gnutls_pull_timeout_func</code> is of the form,
9121 int (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int ms);
9122 </p>
9123 <p><strong>Since:</strong> 3.0
9124 </p></dd></dl>
9125
9126
9127 <p>The functions above accept a callback function which
9128 should return the number of bytes written, or -1 on
9129 error and should set <code>errno</code> appropriately.
9130 In some environments, setting <code>errno</code> is unreliable. For example
9131 Windows have several errno variables in different CRTs, or in other
9132 systems it may be a non thread-local variable.  If this is a concern to
9133 you, call <a href="#gnutls_005ftransport_005fset_005ferrno">gnutls_transport_set_errno</a> with the intended errno
9134 value instead of setting <code>errno</code> directly.
9135 </p>
9136
9137
9138
9139
9140 <dl>
9141 <dt><a name="index-gnutls_005ftransport_005fset_005ferrno"></a>Function: <em>void</em> <strong>gnutls_transport_set_errno</strong> <em>(gnutls_session_t <var>session</var>, int <var>err</var>)</em></dt>
9142 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9143 </p>
9144 <p><var>err</var>: error value to store in session-specific errno variable.
9145 </p>
9146 <p>Store  <code>err</code> in the session-specific errno variable.  Useful values
9147 for  <code>err</code> are EINTR, EAGAIN and EMSGSIZE, other values are treated will be
9148 treated as real errors in the push/pull function.
9149 </p>
9150 <p>This function is useful in replacement push and pull functions set by
9151 <code>gnutls_transport_set_push_function()</code>  and
9152 <code>gnutls_transport_set_pull_function()</code>  under Windows, where the
9153 replacements may not have access to the same  <code>errno</code> variable that is used by GnuTLS (e.g., the application is linked to
9154 msvcr71.dll and gnutls is linked to msvcrt.dll).
9155 </p></dd></dl>
9156
9157 <p><acronym>GnuTLS</acronym> currently only interprets the EINTR, EAGAIN and EMSGSIZE errno
9158 values and returns the corresponding <acronym>GnuTLS</acronym> error codes:
9159 </p><ul>
9160 <li> <code>GNUTLS_E_INTERRUPTED</code>
9161 </li><li> <code>GNUTLS_E_AGAIN</code>
9162 </li><li> <code>GNUTLS_E_LARGE_PACKET</code>
9163 </li></ul>
9164 <p>The EINTR and EAGAIN values are returned by interrupted system calls,
9165 or when non blocking IO is used.  All <acronym>GnuTLS</acronym> functions can be
9166 resumed (called again), if any of the above error codes is returned. The
9167 EMSGSIZE value is returned when attempting to send a large datagram.
9168 </p>
9169 <p>In the case of DTLS it is also desirable to override the generic
9170 transport functions with functions that emulate the operation
9171 of <code>recvfrom</code> and <code>sendto</code>. In addition
9172 <acronym>DTLS</acronym> requires timers during the receive of a handshake
9173 message, set using the <a href="#gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction">gnutls_transport_set_pull_timeout_function</a>
9174 function. To check the retransmission timers the function
9175 <a href="#gnutls_005fdtls_005fget_005ftimeout">gnutls_dtls_get_timeout</a> is provided, which returns the time
9176 remaining until the next retransmission, or better the time until
9177 <a href="#gnutls_005fhandshake">gnutls_handshake</a> should be called again.
9178 </p>
9179
9180
9181
9182
9183 <dl>
9184 <dt><a name="index-gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction-1"></a>Function: <em>void</em> <strong>gnutls_transport_set_pull_timeout_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_pull_timeout_func <var>func</var>)</em></dt>
9185 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9186 </p>
9187 <p><var>func</var>: a callback function
9188 </p>
9189 <p>This is the function where you set a function for gnutls to know
9190 whether data are ready to be received. It should wait for data a
9191 given time frame in milliseconds. The callback should return 0 on
9192 timeout, a positive number if data can be received, and -1 on error.
9193 You&rsquo;ll need to override this function if <code>select()</code>  is not suitable
9194 for the provided transport calls.
9195 </p>
9196 <p>As with <code>select()</code> , if the timeout value is zero the callback should return
9197 zero if no data are immediately available.
9198 </p>
9199 <p><code>gnutls_pull_timeout_func</code> is of the form,
9200 int (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int ms);
9201 </p>
9202 <p><strong>Since:</strong> 3.0
9203 </p></dd></dl>
9204
9205
9206
9207
9208 <dl>
9209 <dt><a name="index-gnutls_005fdtls_005fget_005ftimeout"></a>Function: <em>unsigned int</em> <strong>gnutls_dtls_get_timeout</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
9210 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9211 </p>
9212 <p>This function will return the milliseconds remaining
9213 for a retransmission of the previously sent handshake
9214 message. This function is useful when DTLS is used in
9215 non-blocking mode, to estimate when to call <code>gnutls_handshake()</code>
9216 if no packets have been received.
9217 </p>
9218 <p><strong>Returns:</strong> the remaining time in milliseconds.
9219 </p>
9220 <p><strong>Since:</strong> 3.0
9221 </p></dd></dl>
9222
9223 <table class="menu" border="0" cellspacing="0">
9224 <tr><td align="left" valign="top">&bull; <a href="#Asynchronous-operation" accesskey="1">Asynchronous operation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
9225 </td></tr>
9226 <tr><td align="left" valign="top">&bull; <a href="#DTLS-sessions" accesskey="2">DTLS sessions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
9227 </td></tr>
9228 </table>
9229
9230 <hr>
9231 <a name="Asynchronous-operation"></a>
9232 <div class="header">
9233 <p>
9234 Next: <a href="#DTLS-sessions" accesskey="n" rel="next">DTLS sessions</a>, Up: <a href="#Setting-up-the-transport-layer" accesskey="u" rel="up">Setting up the transport layer</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
9235 </div>
9236 <a name="Asynchronous-operation-1"></a>
9237 <h4 class="subsection">6.5.1 Asynchronous operation</h4>
9238 <p><acronym>GnuTLS</acronym> can be used with asynchronous socket or event-driven programming.
9239 The approach is similar to using Berkeley sockets under such an environment.
9240 The blocking, due to network interaction, calls such as
9241 <a href="#gnutls_005fhandshake">gnutls_handshake</a>, <a href="#gnutls_005frecord_005frecv">gnutls_record_recv</a>,
9242 can be set to non-blocking by setting the underlying sockets to non-blocking.
9243 If other push and pull functions are setup, then they should behave the same
9244 way as <code>recv</code> and <code>send</code> when used in a non-blocking
9245 way, i.e., set errno to <code>EAGAIN</code>. Since, during a TLS protocol session
9246 <acronym>GnuTLS</acronym> does not block except for network interaction, the non blocking
9247 <code>EAGAIN</code> errno will be propagated and <acronym>GnuTLS</acronym> functions
9248 will return the <code>GNUTLS_E_AGAIN</code> error code. Such calls can be resumed the
9249 same way as a system call would.
9250 The only exception is <a href="#gnutls_005frecord_005fsend">gnutls_record_send</a>,
9251 which if interrupted subsequent calls need not to include the data to be
9252 sent (can be called with NULL argument).
9253 </p>
9254 <p>The <code>select</code> system call can also be used in combination with the
9255 <acronym>GnuTLS</acronym> functions. <code>select</code> allows monitoring of sockets
9256 and notifies on them being ready for reading or writing data. Note however
9257 that this system call cannot notify on data present in <acronym>GnuTLS</acronym>
9258 read buffers, it is only applicable to the kernel sockets API. Thus if
9259 you are using it for reading from a <acronym>GnuTLS</acronym> session, make sure
9260 that any cached data are read completely. That can be achieved by checking there
9261 are no data waiting to be read (using <a href="#gnutls_005frecord_005fcheck_005fpending">gnutls_record_check_pending</a>),
9262 either before the <code>select</code> system call, or after a call to
9263 <a href="#gnutls_005frecord_005frecv">gnutls_record_recv</a>. <acronym>GnuTLS</acronym> does not keep a write buffer,
9264 thus when writing no additional actions are required.
9265 </p>
9266 <p>Although in the TLS protocol implementation each call to receive or send
9267 function implies to restoring the same function that was interrupted, in
9268 the DTLS protocol this requirement isn&rsquo;t true.
9269 There are cases where a retransmission is required, which are indicated by
9270 a received message and thus <a href="#gnutls_005frecord_005fget_005fdirection">gnutls_record_get_direction</a> must be called
9271 to decide which direction to check prior to restoring a function call.
9272 </p>
9273
9274
9275
9276 <dl>
9277 <dt><a name="index-gnutls_005frecord_005fget_005fdirection"></a>Function: <em>int</em> <strong>gnutls_record_get_direction</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
9278 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9279 </p>
9280 <p>This function provides information about the internals of the
9281 record protocol and is only useful if a prior gnutls function call
9282 (e.g.  <code>gnutls_handshake()</code> ) was interrupted for some reason, that
9283 is, if a function returned <code>GNUTLS_E_INTERRUPTED</code>  or
9284 <code>GNUTLS_E_AGAIN</code> .  In such a case, you might want to call <code>select()</code>
9285 or <code>poll()</code>  before calling the interrupted gnutls function again.  To
9286 tell you whether a file descriptor should be selected for either
9287 reading or writing, <code>gnutls_record_get_direction()</code>  returns 0 if the
9288 interrupted function was trying to read data, and 1 if it was
9289 trying to write data.
9290 </p>
9291 <p>This function&rsquo;s output is unreliable if you are using the
9292  <code>session</code> in different threads, for sending and receiving.
9293 </p>
9294 <p><strong>Returns:</strong> 0 if trying to read data, 1 if trying to write data.
9295 </p></dd></dl>
9296
9297 <p>Moreover, to prevent blocking from DTLS&rsquo; retransmission timers to block a
9298 handshake, the <a href="#gnutls_005finit">gnutls_init</a> function should be called with the
9299 <code>GNUTLS_NONBLOCK</code> flag set (see <a href="#Session-initialization">Session initialization</a>). In that
9300 case, in order to be able to use the DTLS handshake timers, the function
9301 <a href="#gnutls_005fdtls_005fget_005ftimeout">gnutls_dtls_get_timeout</a> should be used to estimate when to call
9302 <a href="#gnutls_005fhandshake">gnutls_handshake</a> if no packets have been received.
9303 </p>
9304
9305 <hr>
9306 <a name="DTLS-sessions"></a>
9307 <div class="header">
9308 <p>
9309 Previous: <a href="#Asynchronous-operation" accesskey="p" rel="prev">Asynchronous operation</a>, Up: <a href="#Setting-up-the-transport-layer" accesskey="u" rel="up">Setting up the transport layer</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
9310 </div>
9311 <a name="DTLS-sessions-1"></a>
9312 <h4 class="subsection">6.5.2 DTLS sessions</h4>
9313
9314 <p>Because datagram TLS can operate over connections where the client
9315 cannot be reliably verified, functionality in the form of cookies, is available to prevent
9316 denial of service attacks to servers. <acronym>GnuTLS</acronym> requires a server
9317 to generate a secret key that is used to sign a cookie<a name="DOCF13" href="#FOOT13"><sup>13</sup></a>.
9318 That cookie is sent to the client using <a href="#gnutls_005fdtls_005fcookie_005fsend">gnutls_dtls_cookie_send</a>, and
9319 the client must reply using the correct cookie. The server side
9320 should verify the initial message sent by client using <a href="#gnutls_005fdtls_005fcookie_005fverify">gnutls_dtls_cookie_verify</a>.
9321 If successful the session should be initialized and associated with
9322 the cookie using <a href="#gnutls_005fdtls_005fprestate_005fset">gnutls_dtls_prestate_set</a>, before proceeding to
9323 the handshake.
9324 </p>
9325 <dl compact="compact">
9326 <dt><code><var>int</var> <a href="#gnutls_005fkey_005fgenerate">gnutls_key_generate</a> (gnutls_datum_t * <var>key</var>, unsigned int <var>key_size</var>)</code></dt>
9327 <dt><code><var>int</var> <a href="#gnutls_005fdtls_005fcookie_005fsend">gnutls_dtls_cookie_send</a> (gnutls_datum_t * <var>key</var>, void * <var>client_data</var>, size_t <var>client_data_size</var>, gnutls_dtls_prestate_st * <var>prestate</var>, gnutls_transport_ptr_t <var>ptr</var>, gnutls_push_func <var>push_func</var>)</code></dt>
9328 <dt><code><var>int</var> <a href="#gnutls_005fdtls_005fcookie_005fverify">gnutls_dtls_cookie_verify</a> (gnutls_datum_t * <var>key</var>, void * <var>client_data</var>, size_t <var>client_data_size</var>, void * <var>_msg</var>, size_t <var>msg_size</var>, gnutls_dtls_prestate_st * <var>prestate</var>)</code></dt>
9329 <dt><code><var>void</var> <a href="#gnutls_005fdtls_005fprestate_005fset">gnutls_dtls_prestate_set</a> (gnutls_session_t <var>session</var>, gnutls_dtls_prestate_st * <var>prestate</var>)</code></dt>
9330 </dl>
9331
9332 <p>Note that the above apply to server side only and they are not mandatory to be
9333 used. Not using them, however, allows denial of service attacks.
9334 The client side cookie handling is part of <a href="#gnutls_005fhandshake">gnutls_handshake</a>.
9335 </p>
9336 <p>Datagrams are typically restricted by a maximum transfer unit (MTU). For that
9337 both client and server side should set the correct maximum transfer unit for
9338 the layer underneath <acronym>GnuTLS</acronym>. This will allow proper fragmentation
9339 of DTLS messages and prevent messages from being silently discarded by the
9340 transport layer. The &ldquo;correct&rdquo; maximum transfer unit can be obtained through
9341 a path MTU discovery mechanism [<em>RFC4821</em>].
9342 </p>
9343 <dl compact="compact">
9344 <dt><code><var>void</var> <a href="#gnutls_005fdtls_005fset_005fmtu">gnutls_dtls_set_mtu</a> (gnutls_session_t <var>session</var>, unsigned int <var>mtu</var>)</code></dt>
9345 <dt><code><var>unsigned int</var> <a href="#gnutls_005fdtls_005fget_005fmtu">gnutls_dtls_get_mtu</a> (gnutls_session_t <var>session</var>)</code></dt>
9346 <dt><code><var>unsigned int</var> <a href="#gnutls_005fdtls_005fget_005fdata_005fmtu">gnutls_dtls_get_data_mtu</a> (gnutls_session_t <var>session</var>)</code></dt>
9347 </dl>
9348
9349
9350 <hr>
9351 <a name="TLS-handshake"></a>
9352 <div class="header">
9353 <p>
9354 Next: <a href="#Data-transfer-and-termination" accesskey="n" rel="next">Data transfer and termination</a>, Previous: <a href="#Setting-up-the-transport-layer" accesskey="p" rel="prev">Setting up the transport layer</a>, Up: <a href="#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
9355 </div>
9356 <a name="TLS-handshake-1"></a>
9357 <h3 class="section">6.6 TLS handshake</h3>
9358 <p>Once a session has been initialized and a network
9359 connection has been set up, TLS and DTLS protocols
9360 perform a handshake. The handshake is the actual key
9361 exchange.
9362 </p>
9363
9364
9365
9366
9367 <dl>
9368 <dt><a name="index-gnutls_005fhandshake"></a>Function: <em>int</em> <strong>gnutls_handshake</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
9369 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9370 </p>
9371 <p>This function does the handshake of the TLS/SSL protocol, and
9372 initializes the TLS connection.
9373 </p>
9374 <p>This function will fail if any problem is encountered, and will
9375 return a negative error code. In case of a client, if the client
9376 has asked to resume a session, but the server couldn&rsquo;t, then a
9377 full handshake will be performed.
9378 </p>
9379 <p>The non-fatal errors expected by this function are:
9380 <code>GNUTLS_E_INTERRUPTED</code> , <code>GNUTLS_E_AGAIN</code> ,
9381 <code>GNUTLS_E_WARNING_ALERT_RECEIVED</code> , and <code>GNUTLS_E_GOT_APPLICATION_DATA</code> ,
9382 the latter only in a case of rehandshake.
9383 </p>
9384 <p>The former two interrupt the handshake procedure due to the lower
9385 layer being interrupted, and the latter because of an alert that
9386 may be sent by a server (it is always a good idea to check any
9387 received alerts). On these errors call this function again, until it
9388 returns 0; cf.  <code>gnutls_record_get_direction()</code>  and
9389 <code>gnutls_error_is_fatal()</code> . In DTLS sessions the non-fatal error
9390 <code>GNUTLS_E_LARGE_PACKET</code>  is also possible, and indicates that
9391 the MTU should be adjusted.
9392 </p>
9393 <p>If this function is called by a server after a rehandshake request
9394 then <code>GNUTLS_E_GOT_APPLICATION_DATA</code>  or
9395 <code>GNUTLS_E_WARNING_ALERT_RECEIVED</code>  may be returned.  Note that these
9396 are non fatal errors, only in the specific case of a rehandshake.
9397 Their meaning is that the client rejected the rehandshake request or
9398 in the case of <code>GNUTLS_E_GOT_APPLICATION_DATA</code>  it could also mean that
9399 some data were pending.
9400 </p>
9401 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
9402 </p></dd></dl>
9403
9404
9405
9406
9407
9408 <dl>
9409 <dt><a name="index-gnutls_005fhandshake_005fset_005ftimeout"></a>Function: <em>void</em> <strong>gnutls_handshake_set_timeout</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>ms</var>)</em></dt>
9410 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9411 </p>
9412 <p><var>ms</var>: is a timeout value in milliseconds
9413 </p>
9414 <p>This function sets the timeout for the handshake process
9415 to the provided value. Use an  <code>ms</code> value of zero to disable
9416 timeout, or <code>GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT</code>  for a reasonable
9417 default value.
9418 </p>
9419 <p><strong>Since:</strong> 3.1.0
9420 </p></dd></dl>
9421
9422 <p>The handshake process doesn&rsquo;t ensure the verification
9423 of the peer&rsquo;s identity. When certificates are in use,
9424 this can be done, either after the handshake is complete, or during
9425 the handshake if <a href="#gnutls_005fcertificate_005fset_005fverify_005ffunction">gnutls_certificate_set_verify_function</a>
9426 has been used. In both cases the <a href="#gnutls_005fcertificate_005fverify_005fpeers2">gnutls_certificate_verify_peers2</a> function can be
9427 used to verify the peer&rsquo;s certificate (see <a href="#Certificate-authentication">Certificate authentication</a>
9428 for more information).
9429 </p>
9430 <dl compact="compact">
9431 <dt><code><var>int</var> <a href="#gnutls_005fcertificate_005fverify_005fpeers2">gnutls_certificate_verify_peers2</a> (gnutls_session_t <var>session</var>, unsigned int * <var>status</var>)</code></dt>
9432 </dl>
9433
9434 <hr>
9435 <a name="Data-transfer-and-termination"></a>
9436 <div class="header">
9437 <p>
9438 Next: <a href="#Buffered-data-transfer" accesskey="n" rel="next">Buffered data transfer</a>, Previous: <a href="#TLS-handshake" accesskey="p" rel="prev">TLS handshake</a>, Up: <a href="#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
9439 </div>
9440 <a name="Data-transfer-and-termination-1"></a>
9441 <h3 class="section">6.7 Data transfer and termination</h3>
9442 <p>Once the handshake is complete and peer&rsquo;s identity
9443 has been verified data can be exchanged. The available
9444 functions resemble the POSIX <code>recv</code> and <code>send</code>
9445 functions. It is suggested to use <a href="#gnutls_005ferror_005fis_005ffatal">gnutls_error_is_fatal</a>
9446 to check whether the error codes returned by these functions are
9447 fatal for the protocol or can be ignored.
9448 </p>
9449
9450
9451
9452
9453 <dl>
9454 <dt><a name="index-gnutls_005frecord_005fsend"></a>Function: <em>ssize_t</em> <strong>gnutls_record_send</strong> <em>(gnutls_session_t <var>session</var>, const void * <var>data</var>, size_t <var>data_size</var>)</em></dt>
9455 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9456 </p>
9457 <p><var>data</var>: contains the data to send
9458 </p>
9459 <p><var>data_size</var>: is the length of the data
9460 </p>
9461 <p>This function has the similar semantics with <code>send()</code> .  The only
9462 difference is that it accepts a GnuTLS session, and uses different
9463 error codes.
9464 Note that if the send buffer is full, <code>send()</code>  will block this
9465 function.  See the <code>send()</code>  documentation for more information.
9466 </p>
9467 <p>You can replace the default push function which is <code>send()</code> , by using
9468 <code>gnutls_transport_set_push_function()</code> .
9469 </p>
9470 <p>If the EINTR is returned by the internal push function
9471 then <code>GNUTLS_E_INTERRUPTED</code>  will be returned. If
9472 <code>GNUTLS_E_INTERRUPTED</code>  or <code>GNUTLS_E_AGAIN</code>  is returned, you must
9473 call this function again, with the exact same parameters; alternatively
9474 you could provide a <code>NULL</code>  pointer for data, and 0 for
9475 size. cf. <code>gnutls_record_get_direction()</code> .
9476 </p>
9477 <p>Note that in DTLS this function will return the <code>GNUTLS_E_LARGE_PACKET</code>
9478 error code if the send data exceed the data MTU value - as returned
9479 by <code>gnutls_dtls_get_data_mtu()</code> . The errno value EMSGSIZE
9480 also maps to <code>GNUTLS_E_LARGE_PACKET</code> .
9481 Note that since 3.2.13 this function can be called under cork in DTLS
9482 mode, and will refuse to send data over the MTU size by returning
9483 <code>GNUTLS_E_LARGE_PACKET</code> .
9484 </p>
9485 <p><strong>Returns:</strong> The number of bytes sent, or a negative error code.  The
9486 number of bytes sent might be less than  <code>data_size</code> .  The maximum
9487 number of bytes this function can send in a single call depends
9488 on the negotiated maximum record size.
9489 </p></dd></dl>
9490
9491
9492
9493
9494
9495 <dl>
9496 <dt><a name="index-gnutls_005frecord_005frecv"></a>Function: <em>ssize_t</em> <strong>gnutls_record_recv</strong> <em>(gnutls_session_t <var>session</var>, void * <var>data</var>, size_t <var>data_size</var>)</em></dt>
9497 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9498 </p>
9499 <p><var>data</var>: the buffer that the data will be read into
9500 </p>
9501 <p><var>data_size</var>: the number of requested bytes
9502 </p>
9503 <p>This function has the similar semantics with <code>recv()</code> .  The only
9504 difference is that it accepts a GnuTLS session, and uses different
9505 error codes.
9506 In the special case that a server requests a renegotiation, the
9507 client may receive an error code of <code>GNUTLS_E_REHANDSHAKE</code> .  This
9508 message may be simply ignored, replied with an alert
9509 <code>GNUTLS_A_NO_RENEGOTIATION</code> , or replied with a new handshake,
9510 depending on the client&rsquo;s will.
9511 If <code>EINTR</code>  is returned by the internal push function (the default
9512 is <code>recv()</code> ) then <code>GNUTLS_E_INTERRUPTED</code>  will be returned.  If
9513 <code>GNUTLS_E_INTERRUPTED</code>  or <code>GNUTLS_E_AGAIN</code>  is returned, you must
9514 call this function again to get the data.  See also
9515 <code>gnutls_record_get_direction()</code> .
9516 A server may also receive <code>GNUTLS_E_REHANDSHAKE</code>  when a client has
9517 initiated a handshake. In that case the server can only initiate a
9518 handshake or terminate the connection.
9519 </p>
9520 <p><strong>Returns:</strong> The number of bytes received and zero on EOF (for stream
9521 connections).  A negative error code is returned in case of an error.
9522 The number of bytes received might be less than the requested  <code>data_size</code> .
9523 </p></dd></dl>
9524
9525
9526
9527
9528
9529 <dl>
9530 <dt><a name="index-gnutls_005ferror_005fis_005ffatal"></a>Function: <em>int</em> <strong>gnutls_error_is_fatal</strong> <em>(int <var>error</var>)</em></dt>
9531 <dd><p><var>error</var>: is a GnuTLS error code, a negative error code
9532 </p>
9533 <p>If a GnuTLS function returns a negative error code you may feed that
9534 value to this function to see if the error condition is fatal to
9535 a TLS session (i.e., must be terminated).
9536 </p>
9537 <p>Note that you may also want to check the error code manually, since some
9538 non-fatal errors to the protocol (such as a warning alert or
9539 a rehandshake request) may be fatal for your program.
9540 </p>
9541 <p>This function is only useful if you are dealing with errors from
9542 functions that relate to a TLS session (e.g., record layer or handshake
9543 layer handling functions).
9544 </p>
9545 <p><strong>Returns:</strong> Non-zero value on fatal errors or zero on non-fatal.
9546 </p></dd></dl>
9547
9548 <p>Although, in the TLS protocol the receive function can be called
9549 at any time, when DTLS is used the GnuTLS receive functions must be
9550 called once a message is available for reading, even if no data are
9551 expected. This is because in DTLS various (internal) actions
9552 may be required due to retransmission timers. Moreover,
9553 an extended receive function is shown below, which allows the extraction
9554 of the message&rsquo;s sequence number. Due to the unreliable nature of the
9555 protocol, this field allows distinguishing out-of-order messages.
9556 </p>
9557
9558
9559
9560
9561 <dl>
9562 <dt><a name="index-gnutls_005frecord_005frecv_005fseq"></a>Function: <em>ssize_t</em> <strong>gnutls_record_recv_seq</strong> <em>(gnutls_session_t <var>session</var>, void * <var>data</var>, size_t <var>data_size</var>, unsigned char * <var>seq</var>)</em></dt>
9563 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9564 </p>
9565 <p><var>data</var>: the buffer that the data will be read into
9566 </p>
9567 <p><var>data_size</var>: the number of requested bytes
9568 </p>
9569 <p><var>seq</var>: is the packet&rsquo;s 64-bit sequence number. Should have space for 8 bytes.
9570 </p>
9571 <p>This function is the same as <code>gnutls_record_recv()</code> , except that
9572 it returns in addition to data, the sequence number of the data.
9573 This is useful in DTLS where record packets might be received
9574 out-of-order. The returned 8-byte sequence number is an
9575 integer in big-endian format and should be
9576 treated as a unique message identification.
9577 </p>
9578 <p><strong>Returns:</strong> The number of bytes received and zero on EOF.  A negative
9579 error code is returned in case of an error.  The number of bytes
9580 received might be less than  <code>data_size</code> .
9581 </p>
9582 <p><strong>Since:</strong> 3.0
9583 </p></dd></dl>
9584
9585 <p>The <a href="#gnutls_005frecord_005fcheck_005fpending">gnutls_record_check_pending</a> helper function is available to
9586 allow checking whether data are available to be read in a <acronym>GnuTLS</acronym> session
9587 buffers. Note that this function complements but does not replace <code>select</code>,
9588 i.e., <a href="#gnutls_005frecord_005fcheck_005fpending">gnutls_record_check_pending</a> reports no data to be read, <code>select</code>
9589 should be called to check for data in the network buffers.
9590 </p>
9591
9592
9593
9594
9595 <dl>
9596 <dt><a name="index-gnutls_005frecord_005fcheck_005fpending"></a>Function: <em>size_t</em> <strong>gnutls_record_check_pending</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
9597 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9598 </p>
9599 <p>This function checks if there are unread data
9600 in the gnutls buffers. If the return value is
9601 non-zero the next call to <code>gnutls_record_recv()</code>
9602 is guaranteed not to block.
9603 </p>
9604 <p><strong>Returns:</strong> Returns the size of the data or zero.
9605 </p></dd></dl>
9606 <dl compact="compact">
9607 <dt><code><var>int</var> <a href="#gnutls_005frecord_005fget_005fdirection">gnutls_record_get_direction</a> (gnutls_session_t <var>session</var>)</code></dt>
9608 </dl>
9609
9610 <p>Once a TLS or DTLS session is no longer needed, it is
9611 recommended to use <a href="#gnutls_005fbye">gnutls_bye</a> to terminate the
9612 session. That way the peer is notified securely about the
9613 intention of termination, which allows distinguishing it
9614 from a malicious connection termination.
9615 A session can be deinitialized with the <a href="#gnutls_005fdeinit">gnutls_deinit</a> function.
9616 </p>
9617
9618
9619
9620
9621 <dl>
9622 <dt><a name="index-gnutls_005fbye"></a>Function: <em>int</em> <strong>gnutls_bye</strong> <em>(gnutls_session_t <var>session</var>, gnutls_close_request_t <var>how</var>)</em></dt>
9623 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9624 </p>
9625 <p><var>how</var>: is an integer
9626 </p>
9627 <p>Terminates the current TLS/SSL connection. The connection should
9628 have been initiated using <code>gnutls_handshake()</code> .   <code>how</code> should be one
9629 of <code>GNUTLS_SHUT_RDWR</code> , <code>GNUTLS_SHUT_WR</code> .
9630 </p>
9631 <p>In case of <code>GNUTLS_SHUT_RDWR</code>  the TLS session gets
9632 terminated and further receives and sends will be disallowed.  If
9633 the return value is zero you may continue using the underlying
9634 transport layer. <code>GNUTLS_SHUT_RDWR</code>  sends an alert containing a close
9635 request and waits for the peer to reply with the same message.
9636 </p>
9637 <p>In case of <code>GNUTLS_SHUT_WR</code>  the TLS session gets terminated
9638 and further sends will be disallowed. In order to reuse the
9639 connection you should wait for an EOF from the peer.
9640 <code>GNUTLS_SHUT_WR</code>  sends an alert containing a close request.
9641 </p>
9642 <p>Note that not all implementations will properly terminate a TLS
9643 connection.  Some of them, usually for performance reasons, will
9644 terminate only the underlying transport layer, and thus not
9645 distinguishing between a malicious party prematurely terminating
9646 the connection and normal termination.
9647 </p>
9648 <p>This function may also return <code>GNUTLS_E_AGAIN</code>  or
9649 <code>GNUTLS_E_INTERRUPTED</code> ; cf.  <code>gnutls_record_get_direction()</code> .
9650 </p>
9651 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code, see
9652 function documentation for entire semantics.
9653 </p></dd></dl>
9654
9655
9656
9657
9658 <dl>
9659 <dt><a name="index-gnutls_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_deinit</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
9660 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9661 </p>
9662 <p>This function clears all buffers associated with the  <code>session</code> .
9663 This function will also remove session data from the session
9664 database if the session was terminated abnormally.
9665 </p></dd></dl>
9666
9667 <hr>
9668 <a name="Buffered-data-transfer"></a>
9669 <div class="header">
9670 <p>
9671 Next: <a href="#Handling-alerts" accesskey="n" rel="next">Handling alerts</a>, Previous: <a href="#Data-transfer-and-termination" accesskey="p" rel="prev">Data transfer and termination</a>, Up: <a href="#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
9672 </div>
9673 <a name="Buffered-data-transfer-1"></a>
9674 <h3 class="section">6.8 Buffered data transfer</h3>
9675
9676 <p>Although <a href="#gnutls_005frecord_005fsend">gnutls_record_send</a> is sufficient to transmit data
9677 to the peer, when many small chunks of data are to be transmitted
9678 it is inefficient and wastes bandwidth due to the TLS record
9679 overhead. In that case it is preferrable to combine the small chunks
9680 before transmission. The following functions provide that functionality.
9681 </p>
9682
9683
9684
9685
9686 <dl>
9687 <dt><a name="index-gnutls_005frecord_005fcork"></a>Function: <em>void</em> <strong>gnutls_record_cork</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
9688 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9689 </p>
9690 <p>If called, <code>gnutls_record_send()</code>  will no longer send any records.
9691 Any sent records will be cached until <code>gnutls_record_uncork()</code>  is called.
9692 </p>
9693 <p>This function is safe to use with DTLS after GnuTLS 3.3.0.
9694 </p>
9695 <p><strong>Since:</strong> 3.1.9
9696 </p></dd></dl>
9697
9698
9699
9700
9701
9702 <dl>
9703 <dt><a name="index-gnutls_005frecord_005funcork"></a>Function: <em>int</em> <strong>gnutls_record_uncork</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>flags</var>)</em></dt>
9704 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9705 </p>
9706 <p><var>flags</var>: Could be zero or <code>GNUTLS_RECORD_WAIT</code>
9707 </p>
9708 <p>This resets the effect of <code>gnutls_record_cork()</code> , and flushes any pending
9709 data. If the <code>GNUTLS_RECORD_WAIT</code>  flag is specified then this
9710 function will block until the data is sent or a fatal error
9711 occurs (i.e., the function will retry on <code>GNUTLS_E_AGAIN</code>  and
9712 <code>GNUTLS_E_INTERRUPTED</code> ).
9713 </p>
9714 <p>If the flag <code>GNUTLS_RECORD_WAIT</code>  is not specified and the function
9715 is interrupted then the <code>GNUTLS_E_AGAIN</code>  or <code>GNUTLS_E_INTERRUPTED</code>
9716 errors will be returned. To obtain the data left in the corked
9717 buffer use <code>gnutls_record_check_corked()</code> .
9718 </p>
9719 <p><strong>Returns:</strong> On success the number of transmitted data is returned, or
9720 otherwise a negative error code.
9721 </p>
9722 <p><strong>Since:</strong> 3.1.9
9723 </p></dd></dl>
9724
9725
9726 <hr>
9727 <a name="Handling-alerts"></a>
9728 <div class="header">
9729 <p>
9730 Next: <a href="#Priority-Strings" accesskey="n" rel="next">Priority Strings</a>, Previous: <a href="#Buffered-data-transfer" accesskey="p" rel="prev">Buffered data transfer</a>, Up: <a href="#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
9731 </div>
9732 <a name="Handling-alerts-1"></a>
9733 <h3 class="section">6.9 Handling alerts</h3>
9734 <p>During a TLS connection alert messages may be exchanged by the
9735 two peers. Those messages may be fatal, meaning the connection
9736 must be terminated afterwards, or warning when something needs
9737 to be reported to the peer, but without interrupting the session.
9738 The error codes <code>GNUTLS_E_WARNING_ALERT_RECEIVED</code>
9739 or <code>GNUTLS_E_FATAL_ALERT_RECEIVED</code> signal those alerts
9740 when received, and may be returned by all GnuTLS functions that receive
9741 data from the peer, being <a href="#gnutls_005fhandshake">gnutls_handshake</a> and <a href="#gnutls_005frecord_005frecv">gnutls_record_recv</a>.
9742 </p>
9743 <p>If those error codes are received the alert and its level should be logged
9744 or reported to the peer using the functions below.
9745 </p>
9746
9747
9748
9749 <dl>
9750 <dt><a name="index-gnutls_005falert_005fget"></a>Function: <em>gnutls_alert_description_t</em> <strong>gnutls_alert_get</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
9751 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9752 </p>
9753 <p>This function will return the last alert number received.  This
9754 function should be called when <code>GNUTLS_E_WARNING_ALERT_RECEIVED</code>  or
9755 <code>GNUTLS_E_FATAL_ALERT_RECEIVED</code>  errors are returned by a gnutls
9756 function.  The peer may send alerts if he encounters an error.
9757 If no alert has been received the returned value is undefined.
9758 </p>
9759 <p><strong>Returns:</strong> the last alert received, a
9760 <code>gnutls_alert_description_t</code>  value.
9761 </p></dd></dl>
9762
9763
9764
9765
9766 <dl>
9767 <dt><a name="index-gnutls_005falert_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_alert_get_name</strong> <em>(gnutls_alert_description_t <var>alert</var>)</em></dt>
9768 <dd><p><var>alert</var>: is an alert number.
9769 </p>
9770 <p>This function will return a string that describes the given alert
9771 number, or <code>NULL</code> .  See <code>gnutls_alert_get()</code> .
9772 </p>
9773 <p><strong>Returns:</strong> string corresponding to <code>gnutls_alert_description_t</code>  value.
9774 </p></dd></dl>
9775
9776 <p>The peer may also be warned or notified of a fatal issue
9777 by using one of the functions below. All the available alerts
9778 are listed in <a href="#The-Alert-Protocol">The Alert Protocol</a>.
9779 </p>
9780
9781
9782
9783
9784 <dl>
9785 <dt><a name="index-gnutls_005falert_005fsend"></a>Function: <em>int</em> <strong>gnutls_alert_send</strong> <em>(gnutls_session_t <var>session</var>, gnutls_alert_level_t <var>level</var>, gnutls_alert_description_t <var>desc</var>)</em></dt>
9786 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
9787 </p>
9788 <p><var>level</var>: is the level of the alert
9789 </p>
9790 <p><var>desc</var>: is the alert description
9791 </p>
9792 <p>This function will send an alert to the peer in order to inform
9793 him of something important (eg. his Certificate could not be verified).
9794 If the alert level is Fatal then the peer is expected to close the
9795 connection, otherwise he may ignore the alert and continue.
9796 </p>
9797 <p>The error code of the underlying record send function will be
9798 returned, so you may also receive <code>GNUTLS_E_INTERRUPTED</code>  or
9799 <code>GNUTLS_E_AGAIN</code>  as well.
9800 </p>
9801 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
9802 an error code is returned.
9803 </p></dd></dl>
9804
9805
9806
9807
9808 <dl>
9809 <dt><a name="index-gnutls_005ferror_005fto_005falert"></a>Function: <em>int</em> <strong>gnutls_error_to_alert</strong> <em>(int <var>err</var>, int * <var>level</var>)</em></dt>
9810 <dd><p><var>err</var>: is a negative integer
9811 </p>
9812 <p><var>level</var>: the alert level will be stored there
9813 </p>
9814 <p>Get an alert depending on the error code returned by a gnutls
9815 function.  All alerts sent by this function should be considered
9816 fatal.  The only exception is when  <code>err</code> is <code>GNUTLS_E_REHANDSHAKE</code> ,
9817 where a warning alert should be sent to the peer indicating that no
9818 renegotiation will be performed.
9819 </p>
9820 <p>If there is no mapping to a valid alert the alert to indicate
9821 internal error is returned.
9822 </p>
9823 <p><strong>Returns:</strong> the alert code to use for a particular error code.
9824 </p></dd></dl>
9825
9826
9827 <hr>
9828 <a name="Priority-Strings"></a>
9829 <div class="header">
9830 <p>
9831 Next: <a href="#Selecting-cryptographic-key-sizes" accesskey="n" rel="next">Selecting cryptographic key sizes</a>, Previous: <a href="#Handling-alerts" accesskey="p" rel="prev">Handling alerts</a>, Up: <a href="#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
9832 </div>
9833 <a name="Priority-strings"></a>
9834 <h3 class="section">6.10 Priority strings</h3>
9835 <a name="index-Priority-strings"></a>
9836
9837 <p>The GnuTLS priority strings specify the TLS session&rsquo;s handshake
9838 algorithms and options in a compact, easy-to-use format.  That string
9839 may contain a single initial keyword such as in
9840 <a href="#tab_003aprio_002dkeywords">Table 6.3</a> and may be followed by additional algorithm or
9841 special keywords. Note that their description is intentionally avoiding
9842 specific algorithm details, as the priority strings are not constant between
9843 gnutls versions (they are periodically updated to account for cryptographic
9844 advances while providing compatibility with old clients and servers).
9845 </p>
9846 <dl compact="compact">
9847 <dt><code><var>int</var> <a href="#gnutls_005fpriority_005fset_005fdirect">gnutls_priority_set_direct</a> (gnutls_session_t <var>session</var>, const char * <var>priorities</var>, const char ** <var>err_pos</var>)</code></dt>
9848 <dt><code><var>int</var> <a href="#gnutls_005fpriority_005fset">gnutls_priority_set</a> (gnutls_session_t <var>session</var>, gnutls_priority_t <var>priority</var>)</code></dt>
9849 </dl>
9850
9851 <div class="float"><a name="tab_003aprio_002dkeywords"></a>
9852 <table>
9853 <thead><tr><th width="20%">Keyword</th><th width="70%">Description</th></tr></thead>
9854 <tr><td width="20%">@KEYWORD</td><td width="70%">Means that a compile-time specified system configuration file<a name="DOCF14" href="#FOOT14"><sup>14</sup></a>
9855 will be used to expand the provided keyword. That is used to impose system-specific policies.
9856 It may be followed by additional options that will be appended to the
9857 system string (e.g., &quot;@SYSTEM:+SRP&quot;). The system file should have the
9858 format &rsquo;KEYWORD=VALUE&rsquo;, e.g., &rsquo;SYSTEM=NORMAL:-ARCFOUR-128&rsquo;.</td></tr>
9859 <tr><td width="20%">PERFORMANCE</td><td width="70%">All the known to be secure ciphersuites are enabled,
9860 limited to 128 bit ciphers and sorted by terms of speed
9861 performance. The message authenticity security level is of 64 bits or more,
9862 and the certificate verification profile is set to GNUTLS_PROFILE_LOW (80-bits).</td></tr>
9863 <tr><td width="20%">NORMAL</td><td width="70%">Means all the known to be secure ciphersuites. The ciphers are sorted by security
9864 margin, although the 256-bit ciphers are included as a fallback only.
9865 The message authenticity security level is of 64 bits or more,
9866 and the certificate verification profile is set to GNUTLS_PROFILE_LOW (80-bits).
9867
9868 <p>This priority string implicitly enables ECDHE and DHE. The ECDHE ciphersuites
9869 are placed first in the priority order, but due to compatibility
9870 issues with the DHE ciphersuites they are placed last in the priority order,
9871 after the plain RSA ciphersuites.
9872 </p></td></tr>
9873 <tr><td width="20%">LEGACY</td><td width="70%">This sets the NORMAL settings that were used for GnuTLS 3.2.x or earlier. There is
9874 no verification profile set, and the allowed DH primes are considered
9875 weak today (but are often used by misconfigured servers).</td></tr>
9876 <tr><td width="20%">PFS</td><td width="70%">Means all the known to be secure ciphersuites that support perfect forward
9877 secrecy (ECDHE and DHE). The ciphers are sorted by security
9878 margin, although the 256-bit ciphers are included as a fallback only.
9879 The message authenticity security level is of 80 bits or more,
9880 and the certificate verification profile is set to GNUTLS_PROFILE_LOW (80-bits).
9881 This option is available since 3.2.4 or later.</td></tr>
9882 <tr><td width="20%">SECURE128</td><td width="70%">Means all known to be secure ciphersuites that offer a
9883 security level 128-bit or more.
9884 The message authenticity security level is of 80 bits or more,
9885 and the certificate verification profile is set to GNUTLS_PROFILE_LOW (80-bits).</td></tr>
9886 <tr><td width="20%">SECURE192</td><td width="70%">Means all the known to be secure ciphersuites that offer a
9887 security level 192-bit or more.
9888 The message authenticity security level is of 128 bits or more,
9889 and the certificate verification profile is set to GNUTLS_PROFILE_HIGH (128-bits).</td></tr>
9890 <tr><td width="20%">SECURE256</td><td width="70%">Currently alias for SECURE192. This option, will enable ciphers which use a
9891 256-bit key but, due to limitations of the TLS protocol, the overall security
9892 level will be 192-bits (the security level depends on more factors than cipher key size).</td></tr>
9893 <tr><td width="20%">SUITEB128</td><td width="70%">Means all the NSA Suite B cryptography (RFC5430) ciphersuites
9894 with an 128 bit security level, as well as the enabling of the corresponding
9895 verification profile.</td></tr>
9896 <tr><td width="20%">SUITEB192</td><td width="70%">Means all the NSA Suite B cryptography (RFC5430) ciphersuites
9897 with an 192 bit security level, as well as the enabling of the corresponding
9898 verification profile.</td></tr>
9899 <tr><td width="20%">EXPORT</td><td width="70%">This priority string should be treated as deprecated.
9900 GnuTLS no longer negotiates 40-bit ciphers.</td></tr>
9901 <tr><td width="20%">NONE</td><td width="70%">Means nothing is enabled.  This disables even protocols and
9902 compression methods. It should be followed by the
9903 algorithms to be enabled.</td></tr>
9904 </table>
9905
9906 <div class="float-caption"><p><strong>Table 6.3: </strong>Supported initial keywords.</p></div></div>
9907 <p>Unless the initial keyword is &quot;NONE&quot; the defaults (in preference
9908 order) are for TLS protocols TLS 1.2, TLS1.1, TLS1.0, SSL3.0; for
9909 compression NULL; for certificate types X.509.
9910 In key exchange algorithms when in NORMAL or SECURE levels the
9911 perfect forward secrecy algorithms take precedence of the other
9912 protocols.  In all cases all the supported key exchange algorithms
9913 are enabled.
9914 </p>
9915 <p>Note that the SECURE levels distinguish between overall security level and
9916 message authenticity security level. That is because the message
9917 authenticity security level requires the adversary to break
9918 the algorithms at real-time during the protocol run, whilst
9919 the overall security level refers to off-line adversaries
9920 (e.g. adversaries breaking the ciphertext years after it was captured).
9921 </p>
9922 <p>The NONE keyword, if used, must followed by keywords specifying
9923 the algorithms and protocols to be enabled. The other initial keywords
9924 do not require, but may be followed by such keywords. All level keywords
9925 can be combined, and for example a level of &quot;SECURE256:+SECURE128&quot; is
9926 allowed.
9927 </p>
9928 <p>The order with which every algorithm or protocol
9929 is specified is significant. Algorithms specified before others
9930 will take precedence. The supported algorithms and protocols
9931 are shown in <a href="#tab_003aprio_002dalgorithms">Table 6.4</a>.
9932 To avoid collisions in order to specify a compression algorithm in
9933 the priority string you have to prefix it with &quot;COMP-&quot;, protocol versions
9934 with &quot;VERS-&quot;, signature algorithms with &quot;SIGN-&quot; and certificate types with &quot;CTYPE-&quot;.
9935 All other algorithms don&rsquo;t need a prefix. Each specified keyword can
9936 be prefixed with any of the following characters.
9937 </p>
9938 <dl compact="compact">
9939 <dt>&rsquo;!&rsquo; or &rsquo;-&rsquo;</dt>
9940 <dd><p>appended with an algorithm will remove this algorithm.
9941 </p></dd>
9942 <dt>&quot;+&quot;</dt>
9943 <dd><p>appended with an algorithm will add this algorithm.
9944 </p></dd>
9945 </dl>
9946
9947 <div class="float"><a name="tab_003aprio_002dalgorithms"></a>
9948 <table>
9949 <thead><tr><th width="20%">Type</th><th width="70%">Keywords</th></tr></thead>
9950 <tr><td width="20%">Ciphers</td><td width="70%">AES-128-CBC, AES-256-CBC, AES-128-GCM, CAMELLIA-128-CBC,
9951 CAMELLIA-256-CBC, ARCFOUR-128, 3DES-CBC ARCFOUR-40. Catch all
9952 name is CIPHER-ALL which will add all the algorithms from NORMAL
9953 priority.</td></tr>
9954 <tr><td width="20%">Key exchange</td><td width="70%">RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS,
9955 PSK, DHE-PSK, ECDHE-RSA, ANON-ECDH, ANON-DH. The
9956 Catch all name is KX-ALL which will add all the algorithms from NORMAL
9957 priority.
9958
9959 <p>Add <code>!DHE-RSA:!DHE-DSS</code> to the priority string to disable DHE.
9960 </p></td></tr>
9961 <tr><td width="20%">MAC</td><td width="70%">MD5, SHA1, SHA256, SHA384, AEAD (used with
9962 GCM ciphers only). All algorithms from NORMAL priority can be accessed with MAC-ALL.</td></tr>
9963 <tr><td width="20%">Compression algorithms</td><td width="70%">COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.</td></tr>
9964 <tr><td width="20%">TLS versions</td><td width="70%">VERS-SSL3.0, VERS-TLS1.0, VERS-TLS1.1,
9965 VERS-TLS1.2, VERS-DTLS1.2, VERS-DTLS1.0.
9966 Catch all is VERS-TLS-ALL and VERS-DTLS-ALL.</td></tr>
9967 <tr><td width="20%">Signature algorithms</td><td width="70%">SIGN-RSA-SHA1, SIGN-RSA-SHA224,
9968 SIGN-RSA-SHA256, SIGN-RSA-SHA384, SIGN-RSA-SHA512, SIGN-DSA-SHA1,
9969 SIGN-DSA-SHA224, SIGN-DSA-SHA256, SIGN-RSA-MD5. Catch all
9970 is SIGN-ALL. This is only valid for TLS 1.2 and later.</td></tr>
9971 <tr><td width="20%">Elliptic curves</td><td width="70%">CURVE-SECP192R1, CURVE-SECP224R1, CURVE-SECP256R1, CURVE-SECP384R1, CURVE-SECP521R1. Catch all is CURVE-ALL.</td></tr>
9972 </table>
9973
9974 <div class="float-caption"><p><strong>Table 6.4: </strong>The supported algorithm keywords in priority strings.</p></div></div>
9975 <p>Note that the DHE key exchange methods are generally
9976 slower<a name="DOCF15" href="#FOOT15"><sup>15</sup></a> than their elliptic curves counterpart
9977 (ECDHE). Moreover the plain Diffie-Hellman key exchange
9978 requires parameters to be generated and associated with a credentials
9979 structure by the server (see <a href="#Parameter-generation">Parameter generation</a>).
9980 </p>
9981 <p>The available special keywords are shown in <a href="#tab_003aprio_002dspecial1">Table 6.5</a>
9982 and <a href="#tab_003aprio_002dspecial2">Table 6.6</a>.
9983 </p>
9984 <div class="float"><a name="tab_003aprio_002dspecial1"></a>
9985 <table>
9986 <thead><tr><th width="45%">Keyword</th><th width="45%">Description</th></tr></thead>
9987 <tr><td width="45%">%COMPAT</td><td width="45%">will enable compatibility mode. It might mean that violations
9988 of the protocols are allowed as long as maximum compatibility with
9989 problematic clients and servers is achieved. More specifically this
9990 string would disable TLS record random padding, tolerate packets
9991 over the maximum allowed TLS record, and add a padding to TLS Client
9992 Hello packet to prevent it being in the 256-512 range which is known
9993 to be causing issues with a commonly used firewall.</td></tr>
9994 <tr><td width="45%">%DUMBFW</td><td width="45%">will add a private extension with bogus data that make the client
9995 hello exceed 512 bytes. This avoids a black hole behavior in some
9996 firewalls. This is a non-standard TLS extension, use with care.</td></tr>
9997 <tr><td width="45%">%NO_EXTENSIONS</td><td width="45%">will prevent the sending of any TLS extensions in client side. Note
9998 that TLS 1.2 requires extensions to be used, as well as safe
9999 renegotiation thus this option must be used with care.</td></tr>
10000 <tr><td width="45%">%SERVER_PRECEDENCE</td><td width="45%">The ciphersuite will be selected according to server priorities
10001 and not the client&rsquo;s.</td></tr>
10002 <tr><td width="45%">%SSL3_RECORD_VERSION</td><td width="45%">will use SSL3.0 record version in client hello.
10003 This is the default.</td></tr>
10004 <tr><td width="45%">%LATEST_RECORD_VERSION</td><td width="45%">will use the latest TLS version record version in client hello.</td></tr>
10005 </table>
10006
10007 <div class="float-caption"><p><strong>Table 6.5: </strong>Special priority string keywords.</p></div></div>
10008 <div class="float"><a name="tab_003aprio_002dspecial2"></a>
10009 <table>
10010 <thead><tr><th width="45%">Keyword</th><th width="45%">Description</th></tr></thead>
10011 <tr><td width="45%">%STATELESS_COMPRESSION</td><td width="45%">will disable keeping state across records when compressing. This may
10012 help to mitigate attacks when compression is used but an attacker
10013 is in control of input data. This has to be used only when the
10014 data that are possibly controlled by an attacker are placed in
10015 separate records.</td></tr>
10016 <tr><td width="45%">%DISABLE_WILDCARDS</td><td width="45%">will disable matching wildcards when comparing hostnames
10017 in certificates.</td></tr>
10018 <tr><td width="45%">%DISABLE_SAFE_RENEGOTIATION</td><td width="45%">will completely disable safe renegotiation
10019 completely.  Do not use unless you know what you are doing.</td></tr>
10020 <tr><td width="45%">%UNSAFE_RENEGOTIATION</td><td width="45%">will allow handshakes and re-handshakes
10021 without the safe renegotiation extension.  Note that for clients
10022 this mode is insecure (you may be under attack), and for servers it
10023 will allow insecure clients to connect (which could be fooled by an
10024 attacker).  Do not use unless you know what you are doing and want
10025 maximum compatibility.</td></tr>
10026 <tr><td width="45%">%PARTIAL_RENEGOTIATION</td><td width="45%">will allow initial handshakes to proceed,
10027 but not re-handshakes.  This leaves the client vulnerable to attack,
10028 and servers will be compatible with non-upgraded clients for
10029 initial handshakes.  This is currently the default for clients and
10030 servers, for compatibility reasons.</td></tr>
10031 <tr><td width="45%">%SAFE_RENEGOTIATION</td><td width="45%">will enforce safe renegotiation.  Clients and
10032 servers will refuse to talk to an insecure peer.  Currently this
10033 causes interoperability problems, but is required for full protection.</td></tr>
10034 <tr><td width="45%">%VERIFY_ALLOW_SIGN_RSA_MD5</td><td width="45%">will allow RSA-MD5 signatures in certificate chains.</td></tr>
10035 <tr><td width="45%">%VERIFY_DISABLE_CRL_CHECKS</td><td width="45%">will disable CRL or OCSP checks in the verification of the certificate chain.</td></tr>
10036 <tr><td width="45%">%VERIFY_ALLOW_X509_V1_CA_CRT</td><td width="45%">will allow V1 CAs in chains.</td></tr>
10037 <tr><td width="45%">%PROFILE_(LOW|LEGACY|MEDIUM|HIGH|ULTRA)</td><td width="45%">require a certificate verification profile the corresponds to the specified
10038 security level, see <a href="#tab_003akey_002dsizes">Table 6.7</a> for the mappings to values.</td></tr>
10039 <tr><td width="45%">%PROFILE_(SUITEB128|SUITEB192)</td><td width="45%">require a certificate verification profile the corresponds to SUITEB. Note
10040 that an initial keyword that enables SUITEB automatically sets the profile.</td></tr>
10041 </table>
10042
10043 <div class="float-caption"><p><strong>Table 6.6: </strong>More priority string keywords.</p></div></div>
10044 <p>Finally the ciphersuites enabled by any priority string can be
10045 listed using the <code>gnutls-cli</code> application (see <a href="#gnutls_002dcli-Invocation">gnutls-cli Invocation</a>),
10046 or by using the priority functions as in <a href="#Listing-the-ciphersuites-in-a-priority-string">Listing the ciphersuites in a priority string</a>.
10047 </p>
10048 <p>Example priority strings are:
10049 </p><div class="example">
10050 <pre class="example">The system imposed security level:
10051     &quot;SYSTEM&quot;
10052
10053 The default priority without the HMAC-MD5:
10054     &quot;NORMAL:-MD5&quot;
10055
10056 Specifying RSA with AES-128-CBC:
10057     &quot;NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL&quot;
10058
10059 Specifying the defaults except ARCFOUR-128:
10060     &quot;NORMAL:-ARCFOUR-128&quot;
10061
10062 Enabling the 128-bit secure ciphers, while disabling SSL 3.0 and enabling compression:
10063     &quot;SECURE128:-VERS-SSL3.0:+COMP-DEFLATE&quot;
10064
10065 Enabling the 128-bit and 192-bit secure ciphers, while disabling all TLS versions
10066 except TLS 1.2:
10067     &quot;SECURE128:+SECURE192:-VERS-TLS-ALL:+VERS-TLS1.2&quot;
10068 </pre></div>
10069
10070 <hr>
10071 <a name="Selecting-cryptographic-key-sizes"></a>
10072 <div class="header">
10073 <p>
10074 Next: <a href="#Advanced-topics" accesskey="n" rel="next">Advanced topics</a>, Previous: <a href="#Priority-Strings" accesskey="p" rel="prev">Priority Strings</a>, Up: <a href="#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
10075 </div>
10076 <a name="Selecting-cryptographic-key-sizes-1"></a>
10077 <h3 class="section">6.11 Selecting cryptographic key sizes</h3>
10078 <a name="index-key-sizes"></a>
10079
10080 <p>Because many algorithms are involved in TLS, it is not easy to set
10081 a consistent security level.  For this reason in <a href="#tab_003akey_002dsizes">Table 6.7</a> we
10082 present some correspondence between key sizes of symmetric algorithms
10083 and public key algorithms based on [<em>ECRYPT</em>].
10084 Those can be used to generate certificates with
10085 appropriate key sizes as well as select parameters for Diffie-Hellman and SRP
10086 authentication.
10087 </p>
10088 <div class="float"><a name="tab_003akey_002dsizes"></a>
10089 <table>
10090 <thead><tr><th width="10%">Security bits</th><th width="12%">RSA, DH and SRP parameter size</th><th width="10%">ECC key size</th><th width="20%">Security parameter</th><th width="32%">Description</th></tr></thead>
10091 <tr><td width="10%">&lt;64</td><td width="12%">&lt;768</td><td width="10%">&lt;128</td><td width="20%"><code>INSECURE</code></td><td width="32%">Considered to be insecure</td></tr>
10092 <tr><td width="10%">64</td><td width="12%">768</td><td width="10%">128</td><td width="20%"><code>VERY WEAK</code></td><td width="32%">Short term protection against individuals</td></tr>
10093 <tr><td width="10%">72</td><td width="12%">1008</td><td width="10%">160</td><td width="20%"><code>WEAK</code></td><td width="32%">Short term protection against small organizations</td></tr>
10094 <tr><td width="10%">80</td><td width="12%">1024</td><td width="10%">160</td><td width="20%"><code>LOW</code></td><td width="32%">Very short term protection against agencies (corresponds to ENISA legacy level)</td></tr>
10095 <tr><td width="10%">96</td><td width="12%">1776</td><td width="10%">192</td><td width="20%"><code>LEGACY</code></td><td width="32%">Legacy standard level</td></tr>
10096 <tr><td width="10%">112</td><td width="12%">2048</td><td width="10%">224</td><td width="20%"><code>MEDIUM</code></td><td width="32%">Medium-term protection</td></tr>
10097 <tr><td width="10%">128</td><td width="12%">3072</td><td width="10%">256</td><td width="20%"><code>HIGH</code></td><td width="32%">Long term protection</td></tr>
10098 <tr><td width="10%">256</td><td width="12%">15424</td><td width="10%">512</td><td width="20%"><code>ULTRA</code></td><td width="32%">Foreseeable future</td></tr>
10099 </table>
10100
10101 <div class="float-caption"><p><strong>Table 6.7: </strong>Key sizes and security parameters.</p></div></div>
10102 <p>The first column  provides a security parameter in a number of bits. This
10103 gives an indication of the number of combinations to be tried by an adversary
10104 to brute force a key. For example to test all possible keys in a 112 bit security parameter
10105 <em>2^{112}</em> combinations have to be tried. For today&rsquo;s technology this is infeasible.
10106 The next two columns correlate the security
10107 parameter with actual bit sizes of parameters for DH, RSA, SRP and ECC algorithms.
10108 A mapping to <code>gnutls_sec_param_t</code> value is given for each security parameter, on
10109 the next column, and finally a brief description of the level.
10110 </p>
10111
10112 <p>Note, however, that the values suggested here are nothing more than an
10113 educated guess that is valid today. There are no guarantees that an
10114 algorithm will remain unbreakable or that these values will remain
10115 constant in time. There could be scientific breakthroughs that cannot
10116 be predicted or total failure of the current public key systems by
10117 quantum computers. On the other hand though the cryptosystems used in
10118 TLS are selected in a conservative way and such catastrophic
10119 breakthroughs or failures are believed to be unlikely.
10120 The NIST publication SP 800-57 [<em>NISTSP80057</em>] contains a similar
10121 table.
10122 </p>
10123 <p>When using <acronym>GnuTLS</acronym> and a decision on bit sizes for a public
10124 key algorithm is required, use of the following functions is
10125 recommended:
10126 </p>
10127
10128
10129
10130
10131 <dl>
10132 <dt><a name="index-gnutls_005fsec_005fparam_005fto_005fpk_005fbits"></a>Function: <em>unsigned int</em> <strong>gnutls_sec_param_to_pk_bits</strong> <em>(gnutls_pk_algorithm_t <var>algo</var>, gnutls_sec_param_t <var>param</var>)</em></dt>
10133 <dd><p><var>algo</var>: is a public key algorithm
10134 </p>
10135 <p><var>param</var>: is a security parameter
10136 </p>
10137 <p>When generating private and public key pairs a difficult question
10138 is which size of &quot;bits&quot; the modulus will be in RSA and the group size
10139 in DSA. The easy answer is 1024, which is also wrong. This function
10140 will convert a human understandable security parameter to an
10141 appropriate size for the specific algorithm.
10142 </p>
10143 <p><strong>Returns:</strong> The number of bits, or (0).
10144 </p>
10145 <p><strong>Since:</strong> 2.12.0
10146 </p></dd></dl>
10147
10148
10149
10150
10151
10152 <dl>
10153 <dt><a name="index-gnutls_005fpk_005fbits_005fto_005fsec_005fparam"></a>Function: <em>gnutls_sec_param_t</em> <strong>gnutls_pk_bits_to_sec_param</strong> <em>(gnutls_pk_algorithm_t <var>algo</var>, unsigned int <var>bits</var>)</em></dt>
10154 <dd><p><var>algo</var>: is a public key algorithm
10155 </p>
10156 <p><var>bits</var>: is the number of bits
10157 </p>
10158 <p>This is the inverse of <code>gnutls_sec_param_to_pk_bits()</code> . Given an algorithm
10159 and the number of bits, it will return the security parameter. This is
10160 a rough indication.
10161 </p>
10162 <p><strong>Returns:</strong> The security parameter.
10163 </p>
10164 <p><strong>Since:</strong> 2.12.0
10165 </p></dd></dl>
10166
10167 <p>Those functions will convert a human understandable security parameter
10168 of <code>gnutls_sec_param_t</code> type, to a number of bits suitable for a public
10169 key algorithm.
10170 </p>
10171 <dl compact="compact">
10172 <dt><code><var>const char *</var> <a href="#gnutls_005fsec_005fparam_005fget_005fname">gnutls_sec_param_get_name</a> (gnutls_sec_param_t <var>param</var>)</code></dt>
10173 </dl>
10174
10175 <p>The following functions will set the minimum acceptable group size for Diffie-Hellman
10176 and SRP authentication.
10177 </p><dl compact="compact">
10178 <dt><code><var>void</var> <a href="#gnutls_005fdh_005fset_005fprime_005fbits">gnutls_dh_set_prime_bits</a> (gnutls_session_t <var>session</var>, unsigned int <var>bits</var>)</code></dt>
10179 <dt><code><var>void</var> <a href="#gnutls_005fsrp_005fset_005fprime_005fbits">gnutls_srp_set_prime_bits</a> (gnutls_session_t <var>session</var>, unsigned int <var>bits</var>)</code></dt>
10180 </dl>
10181
10182
10183 <hr>
10184 <a name="Advanced-topics"></a>
10185 <div class="header">
10186 <p>
10187 Previous: <a href="#Selecting-cryptographic-key-sizes" accesskey="p" rel="prev">Selecting cryptographic key sizes</a>, Up: <a href="#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
10188 </div>
10189 <a name="Advanced-topics-1"></a>
10190 <h3 class="section">6.12 Advanced topics</h3>
10191
10192 <table class="menu" border="0" cellspacing="0">
10193 <tr><td align="left" valign="top">&bull; <a href="#Session-resumption" accesskey="1">Session resumption</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10194 </td></tr>
10195 <tr><td align="left" valign="top">&bull; <a href="#Certificate-verification" accesskey="2">Certificate verification</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10196 </td></tr>
10197 <tr><td align="left" valign="top">&bull; <a href="#Parameter-generation" accesskey="3">Parameter generation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10198 </td></tr>
10199 <tr><td align="left" valign="top">&bull; <a href="#Deriving-keys-for-other-applications_002fprotocols" accesskey="4">Deriving keys for other applications/protocols</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10200 </td></tr>
10201 <tr><td align="left" valign="top">&bull; <a href="#Channel-Bindings" accesskey="5">Channel Bindings</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10202 </td></tr>
10203 <tr><td align="left" valign="top">&bull; <a href="#Interoperability" accesskey="6">Interoperability</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10204 </td></tr>
10205 <tr><td align="left" valign="top">&bull; <a href="#Compatibility-with-the-OpenSSL-library" accesskey="7">Compatibility with the OpenSSL library</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10206 </td></tr>
10207 </table>
10208
10209 <hr>
10210 <a name="Session-resumption"></a>
10211 <div class="header">
10212 <p>
10213 Next: <a href="#Certificate-verification" accesskey="n" rel="next">Certificate verification</a>, Up: <a href="#Advanced-topics" accesskey="u" rel="up">Advanced topics</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
10214 </div>
10215 <a name="Session-resumption-1"></a>
10216 <h4 class="subsection">6.12.1 Session resumption</h4>
10217 <a name="index-resuming-sessions-1"></a>
10218 <a name="index-session-resumption-1"></a>
10219
10220 <a name="Client-side"></a>
10221 <h4 class="subsubheading">Client side</h4>
10222
10223 <p>To reduce time and roundtrips spent in a handshake the client can
10224 request session resumption from a server that previously shared
10225 a session with the client. For that the client has to retrieve and store
10226 the session parameters. Before establishing a new session to the same
10227 server the parameters must be re-associated with the GnuTLS session
10228 using <a href="#gnutls_005fsession_005fset_005fdata">gnutls_session_set_data</a>.
10229 </p>
10230 <dl compact="compact">
10231 <dt><code><var>int</var> <a href="#gnutls_005fsession_005fget_005fdata2">gnutls_session_get_data2</a> (gnutls_session_t <var>session</var>, gnutls_datum_t * <var>data</var>)</code></dt>
10232 <dt><code><var>int</var> <a href="#gnutls_005fsession_005fget_005fid2">gnutls_session_get_id2</a> (gnutls_session_t <var>session</var>, gnutls_datum_t * <var>session_id</var>)</code></dt>
10233 <dt><code><var>int</var> <a href="#gnutls_005fsession_005fset_005fdata">gnutls_session_set_data</a> (gnutls_session_t <var>session</var>, const void * <var>session_data</var>, size_t <var>session_data_size</var>)</code></dt>
10234 </dl>
10235
10236 <p>Keep in mind that sessions will be expired after some time, depending
10237 on the server, and a server may choose not to resume a session
10238 even when requested to.  The expiration is to prevent temporal session keys
10239 from becoming long-term keys. Also note that as a client you must enable,
10240 using the priority functions, at least the algorithms used in the last session.
10241 </p>
10242
10243
10244
10245
10246 <dl>
10247 <dt><a name="index-gnutls_005fsession_005fis_005fresumed"></a>Function: <em>int</em> <strong>gnutls_session_is_resumed</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
10248 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
10249 </p>
10250 <p>Check whether session is resumed or not.
10251 </p>
10252 <p><strong>Returns:</strong> non zero if this session is resumed, or a zero if this is
10253 a new session.
10254 </p></dd></dl>
10255
10256 <a name="Server-side"></a>
10257 <h4 class="subsubheading">Server side</h4>
10258
10259 <p>In order to support resumption a server can store
10260 the session security parameters in a local database or by using session
10261 tickets (see <a href="#Session-tickets">Session tickets</a>) to delegate storage to the client. Because
10262 session tickets might not be supported by all clients, servers
10263 could combine the two methods.
10264 </p>
10265 <p>A storing server needs to specify callback functions to store, retrieve and delete session data. These can be
10266 registered with the functions below. The stored sessions in the database can be checked using <a href="#gnutls_005fdb_005fcheck_005fentry">gnutls_db_check_entry</a>
10267 for expiration.
10268 </p>
10269 <dl compact="compact">
10270 <dt><code><var>void</var> <a href="#gnutls_005fdb_005fset_005fretrieve_005ffunction">gnutls_db_set_retrieve_function</a> (gnutls_session_t <var>session</var>, gnutls_db_retr_func <var>retr_func</var>)</code></dt>
10271 <dt><code><var>void</var> <a href="#gnutls_005fdb_005fset_005fstore_005ffunction">gnutls_db_set_store_function</a> (gnutls_session_t <var>session</var>, gnutls_db_store_func <var>store_func</var>)</code></dt>
10272 <dt><code><var>void</var> <a href="#gnutls_005fdb_005fset_005fptr">gnutls_db_set_ptr</a> (gnutls_session_t <var>session</var>, void * <var>ptr</var>)</code></dt>
10273 <dt><code><var>void</var> <a href="#gnutls_005fdb_005fset_005fremove_005ffunction">gnutls_db_set_remove_function</a> (gnutls_session_t <var>session</var>, gnutls_db_remove_func <var>rem_func</var>)</code></dt>
10274 </dl>
10275 <dl compact="compact">
10276 <dt><code><var>int</var> <a href="#gnutls_005fdb_005fcheck_005fentry">gnutls_db_check_entry</a> (gnutls_session_t <var>session</var>, gnutls_datum_t <var>session_entry</var>)</code></dt>
10277 </dl>
10278
10279 <p>A server utilizing tickets should generate ticket encryption
10280 and authentication keys using <a href="#gnutls_005fsession_005fticket_005fkey_005fgenerate">gnutls_session_ticket_key_generate</a>.
10281 Those keys should be associated with the GnuTLS session using
10282 <a href="#gnutls_005fsession_005fticket_005fenable_005fserver">gnutls_session_ticket_enable_server</a>, and should be rotated regularly
10283 (e.g., every few hours), to prevent them from becoming long-term keys which
10284 if revealed could be used to decrypt all previous sessions.
10285 </p>
10286
10287
10288
10289
10290 <dl>
10291 <dt><a name="index-gnutls_005fsession_005fticket_005fenable_005fserver"></a>Function: <em>int</em> <strong>gnutls_session_ticket_enable_server</strong> <em>(gnutls_session_t <var>session</var>, const gnutls_datum_t * <var>key</var>)</em></dt>
10292 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
10293 </p>
10294 <p><var>key</var>: key to encrypt session parameters.
10295 </p>
10296 <p>Request that the server should attempt session resumption using
10297 SessionTicket.   <code>key</code> must be initialized with
10298 <code>gnutls_session_ticket_key_generate()</code> .
10299 </p>
10300 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or an
10301 error code.
10302 </p>
10303 <p><strong>Since:</strong> 2.10.0
10304 </p></dd></dl>
10305
10306
10307
10308
10309 <dl>
10310 <dt><a name="index-gnutls_005fsession_005fticket_005fkey_005fgenerate"></a>Function: <em>int</em> <strong>gnutls_session_ticket_key_generate</strong> <em>(gnutls_datum_t * <var>key</var>)</em></dt>
10311 <dd><p><var>key</var>: is a pointer to a <code>gnutls_datum_t</code>  which will contain a newly
10312 created key.
10313 </p>
10314 <p>Generate a random key to encrypt security parameters within
10315 SessionTicket.
10316 </p>
10317 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or an
10318 error code.
10319 </p>
10320 <p><strong>Since:</strong> 2.10.0
10321 </p></dd></dl>
10322
10323
10324
10325
10326 <dl>
10327 <dt><a name="index-gnutls_005fsession_005fresumption_005frequested"></a>Function: <em>int</em> <strong>gnutls_session_resumption_requested</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
10328 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
10329 </p>
10330 <p>Check whether the client has asked for session resumption.
10331 This function is valid only on server side.
10332 </p>
10333 <p><strong>Returns:</strong> non zero if session resumption was asked, or a zero if not.
10334 </p></dd></dl>
10335
10336 <p>A server enabling both session tickets and a storage for session data
10337 would use session tickets when clients support it and the storage otherwise.
10338 </p>
10339 <hr>
10340 <a name="Certificate-verification"></a>
10341 <div class="header">
10342 <p>
10343 Next: <a href="#Parameter-generation" accesskey="n" rel="next">Parameter generation</a>, Previous: <a href="#Session-resumption" accesskey="p" rel="prev">Session resumption</a>, Up: <a href="#Advanced-topics" accesskey="u" rel="up">Advanced topics</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
10344 </div>
10345 <a name="Certificate-verification-1"></a>
10346 <h4 class="subsection">6.12.2 Certificate verification</h4>
10347 <a name="index-DANE-1"></a>
10348 <a name="index-DNSSEC-1"></a>
10349 <a name="index-SSH_002dstyle-authentication-1"></a>
10350 <a name="index-Trust-on-first-use-1"></a>
10351 <a name="index-Key-pinning-1"></a>
10352 <a name="index-gnutls_005fcertificate_005fverify_005fflags-1"></a>
10353
10354 <p>In this section the functionality for additional certificate verification methods is listed.
10355 These methods are intended to be used in addition to normal PKI verification, in order to reduce
10356 the risk of a compromised CA being undetected.
10357 </p>
10358 <a name="Trust-on-first-use"></a>
10359 <h4 class="subsubsection">6.12.2.1 Trust on first use</h4>
10360
10361 <p>The GnuTLS library includes functionlity to use an SSH-like trust on first use authentication.
10362 The available functions to store and verify public keys are listed below.
10363 </p>
10364
10365
10366
10367
10368 <dl>
10369 <dt><a name="index-gnutls_005fverify_005fstored_005fpubkey"></a>Function: <em>int</em> <strong>gnutls_verify_stored_pubkey</strong> <em>(const char * <var>db_name</var>, gnutls_tdb_t <var>tdb</var>, const char * <var>host</var>, const char * <var>service</var>, gnutls_certificate_type_t <var>cert_type</var>, const gnutls_datum_t * <var>cert</var>, unsigned int <var>flags</var>)</em></dt>
10370 <dd><p><var>db_name</var>: A file specifying the stored keys (use NULL for the default)
10371 </p>
10372 <p><var>tdb</var>: A storage structure or NULL to use the default
10373 </p>
10374 <p><var>host</var>: The peer&rsquo;s name
10375 </p>
10376 <p><var>service</var>: non-NULL if this key is specific to a service (e.g. http)
10377 </p>
10378 <p><var>cert_type</var>: The type of the certificate
10379 </p>
10380 <p><var>cert</var>: The raw (der) data of the certificate
10381 </p>
10382 <p><var>flags</var>: should be 0.
10383 </p>
10384 <p>This function will try to verify the provided (raw or DER-encoded) certificate
10385 using a list of stored public keys.  The  <code>service</code> field if non-NULL should
10386 be a port number.
10387 </p>
10388 <p>The  <code>retrieve</code> variable if non-null specifies a custom backend for
10389 the retrieval of entries. If it is NULL then the
10390 default file backend will be used. In POSIX-like systems the
10391 file backend uses the $HOME/.gnutls/known_hosts file.
10392 </p>
10393 <p>Note that if the custom storage backend is provided the
10394 retrieval function should return <code>GNUTLS_E_CERTIFICATE_KEY_MISMATCH</code>
10395 if the host/service pair is found but key doesn&rsquo;t match,
10396 <code>GNUTLS_E_NO_CERTIFICATE_FOUND</code>  if no such host/service with
10397 the given key is found, and 0 if it was found. The storage
10398 function should return 0 on success.
10399 </p>
10400 <p><strong>Returns:</strong> If no associated public key is found
10401 then <code>GNUTLS_E_NO_CERTIFICATE_FOUND</code>  will be returned. If a key
10402 is found but does not match <code>GNUTLS_E_CERTIFICATE_KEY_MISMATCH</code>
10403 is returned. On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
10404 or a negative error value on other errors.
10405 </p>
10406 <p><strong>Since:</strong> 3.0.13
10407 </p></dd></dl>
10408
10409
10410
10411
10412 <dl>
10413 <dt><a name="index-gnutls_005fstore_005fpubkey"></a>Function: <em>int</em> <strong>gnutls_store_pubkey</strong> <em>(const char * <var>db_name</var>, gnutls_tdb_t <var>tdb</var>, const char * <var>host</var>, const char * <var>service</var>, gnutls_certificate_type_t <var>cert_type</var>, const gnutls_datum_t * <var>cert</var>, time_t <var>expiration</var>, unsigned int <var>flags</var>)</em></dt>
10414 <dd><p><var>db_name</var>: A file specifying the stored keys (use NULL for the default)
10415 </p>
10416 <p><var>tdb</var>: A storage structure or NULL to use the default
10417 </p>
10418 <p><var>host</var>: The peer&rsquo;s name
10419 </p>
10420 <p><var>service</var>: non-NULL if this key is specific to a service (e.g. http)
10421 </p>
10422 <p><var>cert_type</var>: The type of the certificate
10423 </p>
10424 <p><var>cert</var>: The data of the certificate
10425 </p>
10426 <p><var>expiration</var>: The expiration time (use 0 to disable expiration)
10427 </p>
10428 <p><var>flags</var>: should be 0.
10429 </p>
10430 <p>This function will store the provided (raw or DER-encoded) certificate to
10431 the list of stored public keys. The key will be considered valid until
10432 the provided expiration time.
10433 </p>
10434 <p>The  <code>store</code> variable if non-null specifies a custom backend for
10435 the storage of entries. If it is NULL then the
10436 default file backend will be used.
10437 </p>
10438 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
10439 negative error value.
10440 </p>
10441 <p><strong>Since:</strong> 3.0.13
10442 </p></dd></dl>
10443
10444 <p>In addition to the above the <a href="#gnutls_005fstore_005fcommitment">gnutls_store_commitment</a> can be
10445 used to implement a key-pinning architecture as in [<em>KEYPIN</em>].
10446 This provides a way for web server to commit on a public key that is
10447 not yet active.
10448 </p>
10449
10450
10451
10452
10453 <dl>
10454 <dt><a name="index-gnutls_005fstore_005fcommitment"></a>Function: <em>int</em> <strong>gnutls_store_commitment</strong> <em>(const char * <var>db_name</var>, gnutls_tdb_t <var>tdb</var>, const char * <var>host</var>, const char * <var>service</var>, gnutls_digest_algorithm_t <var>hash_algo</var>, const gnutls_datum_t * <var>hash</var>, time_t <var>expiration</var>, unsigned int <var>flags</var>)</em></dt>
10455 <dd><p><var>db_name</var>: A file specifying the stored keys (use NULL for the default)
10456 </p>
10457 <p><var>tdb</var>: A storage structure or NULL to use the default
10458 </p>
10459 <p><var>host</var>: The peer&rsquo;s name
10460 </p>
10461 <p><var>service</var>: non-NULL if this key is specific to a service (e.g. http)
10462 </p>
10463 <p><var>hash_algo</var>: The hash algorithm type
10464 </p>
10465 <p><var>hash</var>: The raw hash
10466 </p>
10467 <p><var>expiration</var>: The expiration time (use 0 to disable expiration)
10468 </p>
10469 <p><var>flags</var>: should be 0.
10470 </p>
10471 <p>This function will store the provided hash commitment to
10472 the list of stored public keys. The key with the given
10473 hash will be considered valid until the provided expiration time.
10474 </p>
10475 <p>The  <code>store</code> variable if non-null specifies a custom backend for
10476 the storage of entries. If it is NULL then the
10477 default file backend will be used.
10478 </p>
10479 <p>Note that this function is not thread safe with the default backend.
10480 </p>
10481 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
10482 negative error value.
10483 </p>
10484 <p><strong>Since:</strong> 3.0
10485 </p></dd></dl>
10486
10487 <p>The storage and verification functions may be used with the default
10488 text file based back-end, or another back-end may be specified. That
10489 should contain storage and retrieval functions and specified as below.
10490 </p>
10491 <dl compact="compact">
10492 <dt><code><var>int</var> <a href="#gnutls_005ftdb_005finit">gnutls_tdb_init</a> (gnutls_tdb_t * <var>tdb</var>)</code></dt>
10493 <dt><code><var>void</var> <a href="#gnutls_005ftdb_005fdeinit">gnutls_tdb_deinit</a> (gnutls_tdb_t <var>tdb</var>)</code></dt>
10494 <dt><code><var>void</var> <a href="#gnutls_005ftdb_005fset_005fverify_005ffunc">gnutls_tdb_set_verify_func</a> (gnutls_tdb_t <var>tdb</var>, gnutls_tdb_verify_func <var>verify</var>)</code></dt>
10495 <dt><code><var>void</var> <a href="#gnutls_005ftdb_005fset_005fstore_005ffunc">gnutls_tdb_set_store_func</a> (gnutls_tdb_t <var>tdb</var>, gnutls_tdb_store_func <var>store</var>)</code></dt>
10496 <dt><code><var>void</var> <a href="#gnutls_005ftdb_005fset_005fstore_005fcommitment_005ffunc">gnutls_tdb_set_store_commitment_func</a> (gnutls_tdb_t <var>tdb</var>, gnutls_tdb_store_commitment_func        <var>cstore</var>)</code></dt>
10497 </dl>
10498
10499 <a name="DANE-verification"></a>
10500 <h4 class="subsubsection">6.12.2.2 DANE verification</h4>
10501 <p>Since the DANE library is not included in GnuTLS it requires programs
10502 to be linked against it. This can be achieved with the following commands.
10503 </p>
10504 <div class="example">
10505 <pre class="example">gcc -o foo foo.c `pkg-config gnutls-dane --cflags --libs`
10506 </pre></div>
10507
10508 <p>When a program uses the GNU autoconf system, then the following
10509 line or similar can be used to detect the presence of the library.
10510 </p>
10511 <div class="example">
10512 <pre class="example">PKG_CHECK_MODULES([LIBDANE], [gnutls-dane &gt;= 3.0.0])
10513
10514 AC_SUBST([LIBDANE_CFLAGS])
10515 AC_SUBST([LIBDANE_LIBS])
10516 </pre></div>
10517
10518 <p>The high level functionality provided by the DANE library is shown below.
10519 </p>
10520
10521
10522
10523
10524 <dl>
10525 <dt><a name="index-dane_005fverify_005fcrt"></a>Function: <em>int</em> <strong>dane_verify_crt</strong> <em>(dane_state_t <var>s</var>, const gnutls_datum_t * <var>chain</var>, unsigned <var>chain_size</var>, gnutls_certificate_type_t <var>chain_type</var>, const char * <var>hostname</var>, const char * <var>proto</var>, unsigned int <var>port</var>, unsigned int <var>sflags</var>, unsigned int <var>vflags</var>, unsigned int * <var>verify</var>)</em></dt>
10526 <dd><p><var>s</var>: A DANE state structure (may be NULL)
10527 </p>
10528 <p><var>chain</var>: A certificate chain
10529 </p>
10530 <p><var>chain_size</var>: The size of the chain
10531 </p>
10532 <p><var>chain_type</var>: The type of the certificate chain
10533 </p>
10534 <p><var>hostname</var>: The hostname associated with the chain
10535 </p>
10536 <p><var>proto</var>: The protocol of the service connecting (e.g. tcp)
10537 </p>
10538 <p><var>port</var>: The port of the service connecting (e.g. 443)
10539 </p>
10540 <p><var>sflags</var>: Flags for the the initialization of  <code>s</code> (if NULL)
10541 </p>
10542 <p><var>vflags</var>: Verification flags; an OR&rsquo;ed list of <code>dane_verify_flags_t</code> .
10543 </p>
10544 <p><var>verify</var>: An OR&rsquo;ed list of <code>dane_verify_status_t</code> .
10545 </p>
10546 <p>This function will verify the given certificate chain against the
10547 CA constrains and/or the certificate available via DANE.
10548 If no information via DANE can be obtained the flag <code>DANE_VERIFY_NO_DANE_INFO</code>
10549 is set. If a DNSSEC signature is not available for the DANE
10550 record then the verify flag <code>DANE_VERIFY_NO_DNSSEC_DATA</code>  is set.
10551 </p>
10552 <p>Due to the many possible options of DANE, there is no single threat
10553 model countered. When notifying the user about DANE verification results
10554 it may be better to mention: DANE verification did not reject the certificate,
10555 rather than mentioning a successful DANE verication.
10556 </p>
10557 <p>Note that this function is designed to be run in addition to
10558 PKIX - certificate chain - verification. To be run independently
10559 the <code>DANE_VFLAG_ONLY_CHECK_EE_USAGE</code>  flag should be specified;
10560 then the function will check whether the key of the peer matches the
10561 key advertized in the DANE entry.
10562 </p>
10563 <p><strong>Returns:</strong> a negative error code on error and <code>DANE_E_SUCCESS</code>  (0)
10564 when the DANE entries were successfully parsed, irrespective of
10565 whether they were verified (see  <code>verify</code> for that information). If
10566 no usable entries were encountered <code>DANE_E_REQUESTED_DATA_NOT_AVAILABLE</code>
10567 will be returned.
10568 </p></dd></dl>
10569
10570 <dl compact="compact">
10571 <dt><code><var>int</var> <a href="#dane_005fverify_005fsession_005fcrt">dane_verify_session_crt</a> (dane_state_t <var>s</var>, gnutls_session_t <var>session</var>, const char * <var>hostname</var>, const char * <var>proto</var>, unsigned int <var>port</var>, unsigned int <var>sflags</var>, unsigned int <var>vflags</var>, unsigned int * <var>verify</var>)</code></dt>
10572 <dt><code><var>const char *</var> <a href="#dane_005fstrerror">dane_strerror</a> (int <var>error</var>)</code></dt>
10573 </dl>
10574
10575 <p>Note that the <code>dane_state_t</code> structure that is accepted by both
10576 verification functions is optional. It is required when many queries
10577 are performed to facilitate caching.
10578 The following flags are returned by the verify functions to
10579 indicate the status of the verification.
10580 </p>
10581 <div class="float"><a name="dane_005fverify_005fstatus_005ft"></a>
10582
10583
10584 <dl compact="compact">
10585 <dt><code>DANE_VERIFY_CA_CONSTRAINTS_VIOLATED</code></dt>
10586 <dd><p>The CA constraints were violated.
10587 </p></dd>
10588 <dt><code>DANE_VERIFY_CERT_DIFFERS</code></dt>
10589 <dd><p>The certificate obtained via DNS differs.
10590 </p></dd>
10591 <dt><code>DANE_VERIFY_UNKNOWN_DANE_INFO</code></dt>
10592 <dd><p>No known DANE data was found in the DNS record.
10593 </p></dd>
10594 </dl>
10595
10596 <div class="float-caption"><p><strong>Figure 6.2: </strong>The DANE verification status flags.</p></div></div>
10597 <p>In order to generate a DANE TLSA entry to use in a DNS server
10598 you may use danetool (see <a href="#danetool-Invocation">danetool Invocation</a>).
10599 </p>
10600
10601
10602 <hr>
10603 <a name="Parameter-generation"></a>
10604 <div class="header">
10605 <p>
10606 Next: <a href="#Deriving-keys-for-other-applications_002fprotocols" accesskey="n" rel="next">Deriving keys for other applications/protocols</a>, Previous: <a href="#Certificate-verification" accesskey="p" rel="prev">Certificate verification</a>, Up: <a href="#Advanced-topics" accesskey="u" rel="up">Advanced topics</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
10607 </div>
10608 <a name="Parameter-generation-1"></a>
10609 <h4 class="subsection">6.12.3 Parameter generation</h4>
10610 <a name="index-parameter-generation"></a>
10611 <a name="index-generating-parameters"></a>
10612
10613 <p>Several TLS ciphersuites require additional parameters that
10614 need to be generated or provided by the application. The
10615 Diffie-Hellman based ciphersuites (ANON-DH or DHE), require
10616 the group parameters to be provided. Those can either be
10617 be generated on the fly using <a href="#gnutls_005fdh_005fparams_005fgenerate2">gnutls_dh_params_generate2</a>
10618 or imported from pregenerated data using <a href="#gnutls_005fdh_005fparams_005fimport_005fpkcs3">gnutls_dh_params_import_pkcs3</a>.
10619 The parameters can be used in a <acronym>TLS</acronym> session by calling
10620 <a href="#gnutls_005fcertificate_005fset_005fdh_005fparams">gnutls_certificate_set_dh_params</a> or
10621 <a href="#gnutls_005fanon_005fset_005fserver_005fdh_005fparams">gnutls_anon_set_server_dh_params</a> for anonymous sessions.
10622 </p>
10623 <dl compact="compact">
10624 <dt><code><var>int</var> <a href="#gnutls_005fdh_005fparams_005fgenerate2">gnutls_dh_params_generate2</a> (gnutls_dh_params_t <var>dparams</var>, unsigned int <var>bits</var>)</code></dt>
10625 <dt><code><var>int</var> <a href="#gnutls_005fdh_005fparams_005fimport_005fpkcs3">gnutls_dh_params_import_pkcs3</a> (gnutls_dh_params_t <var>params</var>, const gnutls_datum_t * <var>pkcs3_params</var>, gnutls_x509_crt_fmt_t <var>format</var>)</code></dt>
10626 <dt><code><var>void</var> <a href="#gnutls_005fcertificate_005fset_005fdh_005fparams">gnutls_certificate_set_dh_params</a> (gnutls_certificate_credentials_t <var>res</var>, gnutls_dh_params_t <var>dh_params</var>)</code></dt>
10627 <dt><code><var>void</var> <a href="#gnutls_005fanon_005fset_005fserver_005fdh_005fparams">gnutls_anon_set_server_dh_params</a> (gnutls_anon_server_credentials_t <var>res</var>, gnutls_dh_params_t <var>dh_params</var>)</code></dt>
10628 </dl>
10629
10630 <p>Due to the time-consuming calculations required for the generation
10631 of Diffie-Hellman parameters we suggest against performing generation
10632 of them within an application. The <code>certtool</code> tool can be used to
10633 generate or export known safe values that can be stored in code
10634 or in a configuration file to provide the ability to replace. We also
10635 recommend the usage of <a href="#gnutls_005fsec_005fparam_005fto_005fpk_005fbits">gnutls_sec_param_to_pk_bits</a>
10636 (see <a href="#Selecting-cryptographic-key-sizes">Selecting cryptographic key sizes</a>) to determine
10637 the bit size of the generated parameters.
10638 </p>
10639 <p>Note that the information stored in the generated PKCS #3 structure
10640 changed with GnuTLS 3.0.9. Since that version the <code>privateValueLength</code>
10641 member of the structure is set, allowing the server utilizing the
10642 parameters to use keys of the size of the security parameter. This
10643 provides better performance in key exchange.
10644 </p>
10645 <p>To allow renewal of the parameters within an application without
10646 accessing the credentials, which are a shared structure,
10647 an alternative interface is available using a callback function.
10648 </p>
10649
10650
10651
10652
10653 <dl>
10654 <dt><a name="index-gnutls_005fcertificate_005fset_005fparams_005ffunction"></a>Function: <em>void</em> <strong>gnutls_certificate_set_params_function</strong> <em>(gnutls_certificate_credentials_t            <var>res</var>, gnutls_params_function * <var>func</var>)</em></dt>
10655 <dd><p><var>res</var>: is a gnutls_certificate_credentials_t structure
10656 </p>
10657 <p><var>func</var>: is the function to be called
10658 </p>
10659 <p>This function will set a callback in order for the server to get
10660 the Diffie-Hellman or RSA parameters for certificate
10661 authentication.  The callback should return <code>GNUTLS_E_SUCCESS</code>  (0) on success.
10662 </p></dd></dl>
10663
10664
10665 <hr>
10666 <a name="Deriving-keys-for-other-applications_002fprotocols"></a>
10667 <div class="header">
10668 <p>
10669 Next: <a href="#Channel-Bindings" accesskey="n" rel="next">Channel Bindings</a>, Previous: <a href="#Parameter-generation" accesskey="p" rel="prev">Parameter generation</a>, Up: <a href="#Advanced-topics" accesskey="u" rel="up">Advanced topics</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
10670 </div>
10671 <a name="Deriving-keys-for-other-applications_002fprotocols-1"></a>
10672 <h4 class="subsection">6.12.4 Deriving keys for other applications/protocols</h4>
10673 <a name="index-keying-material-exporters"></a>
10674 <a name="index-exporting-keying-material"></a>
10675 <a name="index-deriving-keys"></a>
10676 <a name="index-key-extraction"></a>
10677
10678 <p>In several cases, after a TLS connection is established, it is desirable
10679 to derive keys to be used in another application or protocol (e.g., in an
10680 other TLS session using pre-shared keys). The following describe GnuTLS&rsquo;
10681 implementation of RFC5705 to extract keys based on a session&rsquo;s master secret.
10682 </p>
10683 <p>The API to use is <a href="#gnutls_005fprf">gnutls_prf</a>.  The
10684 function needs to be provided with a label,
10685 and additional context data to mix in the <code>extra</code> parameter.
10686 Moreover, the API allows to switch the mix of the
10687 client and server random nonces, using the <code>server_random_first</code> parameter.
10688 In typical uses you don&rsquo;t need it, so a zero value should be provided in <code>server_random_first</code>.
10689 </p>
10690 <p>For example, after establishing a TLS session using
10691 <a href="#gnutls_005fhandshake">gnutls_handshake</a>, you can obtain 32-bytes to be used as key, using this call:
10692 </p>
10693 <div class="example">
10694 <pre class="example">#define MYLABEL &quot;EXPORTER-My-protocol-name&quot;
10695 #define MYCONTEXT &quot;my-protocol's-1st-session&quot;
10696
10697 char out[32];
10698 rc = gnutls_prf (session, sizeof(MYLABEL)-1, MYLABEL, 0,
10699                  sizeof(MYCONTEXT)-1, MYCONTEXT, 32, out);
10700 </pre></div>
10701
10702 <p>The output key depends on TLS&rsquo; master secret, and is the same on both client
10703 and server.
10704 </p>
10705 <p>If you don&rsquo;t want to use the RFC5705 interface and not mix in the client and server random
10706 nonces, there is a low-level TLS PRF interface called <a href="#gnutls_005fprf_005fraw">gnutls_prf_raw</a>.
10707 </p>
10708 <hr>
10709 <a name="Channel-Bindings"></a>
10710 <div class="header">
10711 <p>
10712 Next: <a href="#Interoperability" accesskey="n" rel="next">Interoperability</a>, Previous: <a href="#Deriving-keys-for-other-applications_002fprotocols" accesskey="p" rel="prev">Deriving keys for other applications/protocols</a>, Up: <a href="#Advanced-topics" accesskey="u" rel="up">Advanced topics</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
10713 </div>
10714 <a name="Channel-bindings"></a>
10715 <h4 class="subsection">6.12.5 Channel bindings</h4>
10716 <a name="index-channel-bindings"></a>
10717
10718 <p>In user authentication protocols (e.g., EAP or SASL mechanisms) it is
10719 useful to have a unique string that identifies the secure channel that
10720 is used, to bind together the user authentication with the secure
10721 channel.  This can protect against man-in-the-middle attacks in some
10722 situations.  That unique string is called a &ldquo;channel binding&rdquo;.  For
10723 background and discussion see [<em>RFC5056</em>].
10724 </p>
10725 <p>In <acronym>GnuTLS</acronym> you can extract a channel binding using the
10726 <a href="#gnutls_005fsession_005fchannel_005fbinding">gnutls_session_channel_binding</a> function.  Currently only the
10727 type <code>GNUTLS_CB_TLS_UNIQUE</code> is supported, which corresponds to
10728 the <code>tls-unique</code> channel binding for TLS defined in
10729 [<em>RFC5929</em>].
10730 </p>
10731 <p>The following example describes how to print the channel binding data.
10732 Note that it must be run after a successful TLS handshake.
10733 </p>
10734 <div class="example">
10735 <pre class="example">{
10736   gnutls_datum_t cb;
10737   int rc;
10738
10739   rc = gnutls_session_channel_binding (session,
10740                                        GNUTLS_CB_TLS_UNIQUE,
10741                                        &amp;cb);
10742   if (rc)
10743     fprintf (stderr, &quot;Channel binding error: %s\n&quot;,
10744              gnutls_strerror (rc));
10745   else
10746     {
10747       size_t i;
10748       printf (&quot;- Channel binding 'tls-unique': &quot;);
10749       for (i = 0; i &lt; cb.size; i++)
10750         printf (&quot;%02x&quot;, cb.data[i]);
10751       printf (&quot;\n&quot;);
10752     }
10753 }
10754 </pre></div>
10755
10756 <hr>
10757 <a name="Interoperability"></a>
10758 <div class="header">
10759 <p>
10760 Next: <a href="#Compatibility-with-the-OpenSSL-library" accesskey="n" rel="next">Compatibility with the OpenSSL library</a>, Previous: <a href="#Channel-Bindings" accesskey="p" rel="prev">Channel Bindings</a>, Up: <a href="#Advanced-topics" accesskey="u" rel="up">Advanced topics</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
10761 </div>
10762 <a name="Interoperability-1"></a>
10763 <h4 class="subsection">6.12.6 Interoperability</h4>
10764
10765 <p>The <acronym>TLS</acronym> protocols support many ciphersuites, extensions and version
10766 numbers. As a result, few implementations are
10767 not able to properly interoperate once faced with extensions or version protocols
10768 they do not support and understand. The <acronym>TLS</acronym> protocol allows for a
10769 graceful downgrade to the commonly supported options, but practice shows
10770 it is not always implemented correctly.
10771 </p>
10772 <p>Because there is no way to achieve maximum interoperability with broken peers
10773 without sacrificing security, <acronym>GnuTLS</acronym> ignores such peers by default.
10774 This might not be acceptable in cases where maximum compatibility
10775 is required. Thus we allow enabling compatibility with broken peers using
10776 priority strings (see <a href="#Priority-Strings">Priority Strings</a>). A conservative priority
10777 string that would disable certain <acronym>TLS</acronym> protocol
10778 options that are known to cause compatibility problems, is shown below.
10779 </p><pre class="verbatim">NORMAL:%COMPAT
10780 </pre>
10781 <p>For broken peers that do not tolerate TLS version numbers over TLS 1.0
10782 another priority string is:
10783 </p><pre class="verbatim">NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:%COMPAT
10784 </pre><p>This priority string will in addition to above, only enable SSL 3.0 and
10785 TLS 1.0 as protocols.
10786 </p>
10787
10788 <hr>
10789 <a name="Compatibility-with-the-OpenSSL-library"></a>
10790 <div class="header">
10791 <p>
10792 Previous: <a href="#Interoperability" accesskey="p" rel="prev">Interoperability</a>, Up: <a href="#Advanced-topics" accesskey="u" rel="up">Advanced topics</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
10793 </div>
10794 <a name="Compatibility-with-the-OpenSSL-library-1"></a>
10795 <h4 class="subsection">6.12.7 Compatibility with the OpenSSL library</h4>
10796 <a name="index-OpenSSL"></a>
10797
10798 <p>To ease <acronym>GnuTLS</acronym>&rsquo; integration with existing applications, a
10799 compatibility layer with the OpenSSL library is included
10800 in the <code>gnutls-openssl</code> library. This compatibility layer is not
10801 complete and it is not intended to completely re-implement the OpenSSL
10802 API with <acronym>GnuTLS</acronym>.  It only provides limited source-level
10803 compatibility.
10804 </p>
10805 <p>The prototypes for the compatibility functions are in the
10806 <samp>gnutls/openssl.h</samp> header file. The limitations
10807 imposed by the compatibility layer include:
10808 </p>
10809 <ul>
10810 <li> Error handling is not thread safe.
10811
10812 </li></ul>
10813
10814
10815 <hr>
10816 <a name="GnuTLS-application-examples"></a>
10817 <div class="header">
10818 <p>
10819 Next: <a href="#Using-GnuTLS-as-a-cryptographic-library" accesskey="n" rel="next">Using GnuTLS as a cryptographic library</a>, Previous: <a href="#How-to-use-GnuTLS-in-applications" accesskey="p" rel="prev">How to use GnuTLS in applications</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
10820 </div>
10821 <a name="GnuTLS-application-examples-1"></a>
10822 <h2 class="chapter">7 GnuTLS application examples</h2>
10823 <a name="examples"></a><a name="index-example-programs"></a>
10824 <a name="index-examples"></a>
10825
10826 <p>In this chapter several examples of real-world use cases are listed.
10827 The examples are simplified to promote readability and contain little or
10828 no error checking.
10829 </p>
10830 <table class="menu" border="0" cellspacing="0">
10831 <tr><td align="left" valign="top">&bull; <a href="#Client-examples" accesskey="1">Client examples</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10832 </td></tr>
10833 <tr><td align="left" valign="top">&bull; <a href="#Server-examples" accesskey="2">Server examples</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10834 </td></tr>
10835 <tr><td align="left" valign="top">&bull; <a href="#OCSP-example" accesskey="3">OCSP example</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10836 </td></tr>
10837 <tr><td align="left" valign="top">&bull; <a href="#Miscellaneous-examples" accesskey="4">Miscellaneous examples</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10838 </td></tr>
10839 </table>
10840
10841 <hr>
10842 <a name="Client-examples"></a>
10843 <div class="header">
10844 <p>
10845 Next: <a href="#Server-examples" accesskey="n" rel="next">Server examples</a>, Up: <a href="#GnuTLS-application-examples" accesskey="u" rel="up">GnuTLS application examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
10846 </div>
10847 <a name="Client-examples-1"></a>
10848 <h3 class="section">7.1 Client examples</h3>
10849
10850 <p>This section contains examples of <acronym>TLS</acronym> and <acronym>SSL</acronym>
10851 clients, using <acronym>GnuTLS</acronym>. Note that some of the examples require functions
10852 implemented by another example.
10853 </p>
10854 <table class="menu" border="0" cellspacing="0">
10855 <tr><td align="left" valign="top">&bull; <a href="#Simple-client-example-with-X_002e509-certificate-support" accesskey="1">Simple client example with X.509 certificate support</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10856 </td></tr>
10857 <tr><td align="left" valign="top">&bull; <a href="#Simple-client-example-with-SSH_002dstyle-certificate-verification" accesskey="2">Simple client example with SSH-style certificate verification</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10858 </td></tr>
10859 <tr><td align="left" valign="top">&bull; <a href="#Simple-client-example-with-anonymous-authentication" accesskey="3">Simple client example with anonymous authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10860 </td></tr>
10861 <tr><td align="left" valign="top">&bull; <a href="#Simple-Datagram-TLS-client-example" accesskey="4">Simple Datagram TLS client example</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10862 </td></tr>
10863 <tr><td align="left" valign="top">&bull; <a href="#Obtaining-session-information" accesskey="5">Obtaining session information</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10864 </td></tr>
10865 <tr><td align="left" valign="top">&bull; <a href="#Using-a-callback-to-select-the-certificate-to-use" accesskey="6">Using a callback to select the certificate to use</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10866 </td></tr>
10867 <tr><td align="left" valign="top">&bull; <a href="#Verifying-a-certificate" accesskey="7">Verifying a certificate</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10868 </td></tr>
10869 <tr><td align="left" valign="top">&bull; <a href="#Client-using-a-smart-card-with-TLS" accesskey="8">Client using a smart card with TLS</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10870 </td></tr>
10871 <tr><td align="left" valign="top">&bull; <a href="#Client-with-Resume-capability-example" accesskey="9">Client with Resume capability example</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10872 </td></tr>
10873 <tr><td align="left" valign="top">&bull; <a href="#Simple-client-example-with-SRP-authentication">Simple client example with SRP authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10874 </td></tr>
10875 <tr><td align="left" valign="top">&bull; <a href="#Simple-client-example-in-C_002b_002b">Simple client example in C++</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10876 </td></tr>
10877 <tr><td align="left" valign="top">&bull; <a href="#Helper-functions-for-TCP-connections">Helper functions for TCP connections</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10878 </td></tr>
10879 <tr><td align="left" valign="top">&bull; <a href="#Helper-functions-for-UDP-connections">Helper functions for UDP connections</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
10880 </td></tr>
10881 </table>
10882
10883 <hr>
10884 <a name="Simple-client-example-with-X_002e509-certificate-support"></a>
10885 <div class="header">
10886 <p>
10887 Next: <a href="#Simple-client-example-with-SSH_002dstyle-certificate-verification" accesskey="n" rel="next">Simple client example with SSH-style certificate verification</a>, Up: <a href="#Client-examples" accesskey="u" rel="up">Client examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
10888 </div>
10889 <a name="Simple-client-example-with-X_002e509-certificate-support-1"></a>
10890 <h4 class="subsection">7.1.1 Simple client example with <acronym>X.509</acronym> certificate support</h4>
10891 <a name="ex_002dverify"></a>
10892 <p>Let&rsquo;s assume now that we want to create a TCP client which
10893 communicates with servers that use <acronym>X.509</acronym> or
10894 <acronym>OpenPGP</acronym> certificate authentication. The following client is
10895 a very simple <acronym>TLS</acronym> client, which uses the high level verification
10896 functions for certificates, but does not support session
10897 resumption.
10898 </p>
10899 <pre class="verbatim">/* This example code is placed in the public domain. */
10900
10901 #ifdef HAVE_CONFIG_H
10902 #include &lt;config.h&gt;
10903 #endif
10904
10905 #include &lt;stdio.h&gt;
10906 #include &lt;stdlib.h&gt;
10907 #include &lt;string.h&gt;
10908 #include &lt;gnutls/gnutls.h&gt;
10909 #include &lt;gnutls/x509.h&gt;
10910 #include &quot;examples.h&quot;
10911
10912 /* A very basic TLS client, with X.509 authentication and server certificate
10913  * verification. Note that error checking for missing files etc. is omitted
10914  * for simplicity.
10915  */
10916
10917 #define MAX_BUF 1024
10918 #define CAFILE &quot;/etc/ssl/certs/ca-certificates.crt&quot;
10919 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
10920
10921 extern int tcp_connect(void);
10922 extern void tcp_close(int sd);
10923 static int _verify_certificate_callback(gnutls_session_t session);
10924
10925 int main(void)
10926 {
10927         int ret, sd, ii;
10928         gnutls_session_t session;
10929         char buffer[MAX_BUF + 1];
10930         const char *err;
10931         gnutls_certificate_credentials_t xcred;
10932
10933         if (gnutls_check_version(&quot;3.1.4&quot;) == NULL) {
10934                 fprintf(stderr, &quot;GnuTLS 3.1.4 or later is required for this example\n&quot;);
10935                 exit(1);
10936         }
10937
10938         /* for backwards compatibility with gnutls &lt; 3.3.0 */
10939         gnutls_global_init();
10940
10941         /* X509 stuff */
10942         gnutls_certificate_allocate_credentials(&amp;xcred);
10943
10944         /* sets the trusted cas file
10945          */
10946         gnutls_certificate_set_x509_trust_file(xcred, CAFILE,
10947                                                GNUTLS_X509_FMT_PEM);
10948         gnutls_certificate_set_verify_function(xcred,
10949                                                _verify_certificate_callback);
10950
10951         /* If client holds a certificate it can be set using the following:
10952          *
10953          gnutls_certificate_set_x509_key_file (xcred,
10954          &quot;cert.pem&quot;, &quot;key.pem&quot;,
10955          GNUTLS_X509_FMT_PEM);
10956          */
10957
10958         /* Initialize TLS session
10959          */
10960         gnutls_init(&amp;session, GNUTLS_CLIENT);
10961
10962         gnutls_session_set_ptr(session, (void *) &quot;my_host_name&quot;);
10963
10964         gnutls_server_name_set(session, GNUTLS_NAME_DNS, &quot;my_host_name&quot;,
10965                                strlen(&quot;my_host_name&quot;));
10966
10967         /* use default priorities */
10968         gnutls_set_default_priority(session);
10969 #if 0
10970         /* if more fine-graned control is required */
10971         ret = gnutls_priority_set_direct(session,
10972                                          &quot;NORMAL&quot;, &amp;err);
10973         if (ret &lt; 0) {
10974                 if (ret == GNUTLS_E_INVALID_REQUEST) {
10975                         fprintf(stderr, &quot;Syntax error at: %s\n&quot;, err);
10976                 }
10977                 exit(1);
10978         }
10979 #endif
10980
10981         /* put the x509 credentials to the current session
10982          */
10983         gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, xcred);
10984
10985         /* connect to the peer
10986          */
10987         sd = tcp_connect();
10988
10989         gnutls_transport_set_int(session, sd);
10990         gnutls_handshake_set_timeout(session,
10991                                      GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
10992
10993         /* Perform the TLS handshake
10994          */
10995         do {
10996                 ret = gnutls_handshake(session);
10997         }
10998         while (ret &lt; 0 &amp;&amp; gnutls_error_is_fatal(ret) == 0);
10999
11000         if (ret &lt; 0) {
11001                 fprintf(stderr, &quot;*** Handshake failed\n&quot;);
11002                 gnutls_perror(ret);
11003                 goto end;
11004         } else {
11005                 char *desc;
11006
11007                 desc = gnutls_session_get_desc(session);
11008                 printf(&quot;- Session info: %s\n&quot;, desc);
11009                 gnutls_free(desc);
11010         }
11011
11012         gnutls_record_send(session, MSG, strlen(MSG));
11013
11014         ret = gnutls_record_recv(session, buffer, MAX_BUF);
11015         if (ret == 0) {
11016                 printf(&quot;- Peer has closed the TLS connection\n&quot;);
11017                 goto end;
11018         } else if (ret &lt; 0 &amp;&amp; gnutls_error_is_fatal(ret) == 0) {
11019                 fprintf(stderr, &quot;*** Warning: %s\n&quot;, gnutls_strerror(ret));
11020         } else if (ret &lt; 0) {
11021                 fprintf(stderr, &quot;*** Error: %s\n&quot;, gnutls_strerror(ret));
11022                 goto end;
11023         }
11024
11025         if (ret &gt; 0) {
11026                 printf(&quot;- Received %d bytes: &quot;, ret);
11027                 for (ii = 0; ii &lt; ret; ii++) {
11028                         fputc(buffer[ii], stdout);
11029                 }
11030                 fputs(&quot;\n&quot;, stdout);
11031         }
11032
11033         gnutls_bye(session, GNUTLS_SHUT_RDWR);
11034
11035       end:
11036
11037         tcp_close(sd);
11038
11039         gnutls_deinit(session);
11040
11041         gnutls_certificate_free_credentials(xcred);
11042
11043         gnutls_global_deinit();
11044
11045         return 0;
11046 }
11047
11048 /* This function will verify the peer's certificate, and check
11049  * if the hostname matches, as well as the activation, expiration dates.
11050  */
11051 static int _verify_certificate_callback(gnutls_session_t session)
11052 {
11053         unsigned int status;
11054         int ret, type;
11055         const char *hostname;
11056         gnutls_datum_t out;
11057
11058         /* read hostname */
11059         hostname = gnutls_session_get_ptr(session);
11060
11061         /* This verification function uses the trusted CAs in the credentials
11062          * structure. So you must have installed one or more CA certificates.
11063          */
11064
11065          /* The following demonstrate two different verification functions,
11066           * the more flexible gnutls_certificate_verify_peers(), as well
11067           * as the old gnutls_certificate_verify_peers3(). */
11068 #if 1
11069         {
11070         gnutls_typed_vdata_st data[2];
11071
11072         memset(data, 0, sizeof(data));
11073
11074         data[0].type = GNUTLS_DT_DNS_HOSTNAME;
11075         data[0].data = (void*)hostname;
11076
11077         data[1].type = GNUTLS_DT_KEY_PURPOSE_OID;
11078         data[1].data = (void*)GNUTLS_KP_TLS_WWW_SERVER;
11079
11080         ret = gnutls_certificate_verify_peers(session, data, 2,
11081                                               &amp;status);
11082         }
11083 #else
11084         ret = gnutls_certificate_verify_peers3(session, hostname,
11085                                                &amp;status);
11086 #endif
11087         if (ret &lt; 0) {
11088                 printf(&quot;Error\n&quot;);
11089                 return GNUTLS_E_CERTIFICATE_ERROR;
11090         }
11091
11092         type = gnutls_certificate_type_get(session);
11093
11094         ret =
11095             gnutls_certificate_verification_status_print(status, type,
11096                                                          &amp;out, 0);
11097         if (ret &lt; 0) {
11098                 printf(&quot;Error\n&quot;);
11099                 return GNUTLS_E_CERTIFICATE_ERROR;
11100         }
11101
11102         printf(&quot;%s&quot;, out.data);
11103
11104         gnutls_free(out.data);
11105
11106         if (status != 0)        /* Certificate is not trusted */
11107                 return GNUTLS_E_CERTIFICATE_ERROR;
11108
11109         /* notify gnutls to continue handshake normally */
11110         return 0;
11111 }
11112 </pre>
11113 <hr>
11114 <a name="Simple-client-example-with-SSH_002dstyle-certificate-verification"></a>
11115 <div class="header">
11116 <p>
11117 Next: <a href="#Simple-client-example-with-anonymous-authentication" accesskey="n" rel="next">Simple client example with anonymous authentication</a>, Previous: <a href="#Simple-client-example-with-X_002e509-certificate-support" accesskey="p" rel="prev">Simple client example with X.509 certificate support</a>, Up: <a href="#Client-examples" accesskey="u" rel="up">Client examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
11118 </div>
11119 <a name="Simple-client-example-with-SSH_002dstyle-certificate-verification-1"></a>
11120 <h4 class="subsection">7.1.2 Simple client example with SSH-style certificate verification</h4>
11121
11122 <p>This is an alternative verification function that will use the
11123 X.509 certificate authorities for verification, but also assume an
11124 trust on first use (SSH-like) authentication system. That is the user is
11125 prompted on unknown public keys and known public keys are considered
11126 trusted.
11127 </p>
11128 <pre class="verbatim">/* This example code is placed in the public domain. */
11129
11130 #ifdef HAVE_CONFIG_H
11131 #include &lt;config.h&gt;
11132 #endif
11133
11134 #include &lt;stdio.h&gt;
11135 #include &lt;stdlib.h&gt;
11136 #include &lt;string.h&gt;
11137 #include &lt;gnutls/gnutls.h&gt;
11138 #include &lt;gnutls/x509.h&gt;
11139 #include &quot;examples.h&quot;
11140
11141 /* This function will verify the peer's certificate, check
11142  * if the hostname matches. In addition it will perform an
11143  * SSH-style authentication, where ultimately trusted keys
11144  * are only the keys that have been seen before.
11145  */
11146 int _ssh_verify_certificate_callback(gnutls_session_t session)
11147 {
11148         unsigned int status;
11149         const gnutls_datum_t *cert_list;
11150         unsigned int cert_list_size;
11151         int ret, type;
11152         gnutls_datum_t out;
11153         const char *hostname;
11154
11155         /* read hostname */
11156         hostname = gnutls_session_get_ptr(session);
11157
11158         /* This verification function uses the trusted CAs in the credentials
11159          * structure. So you must have installed one or more CA certificates.
11160          */
11161         ret = gnutls_certificate_verify_peers3(session, hostname, &amp;status);
11162         if (ret &lt; 0) {
11163                 printf(&quot;Error\n&quot;);
11164                 return GNUTLS_E_CERTIFICATE_ERROR;
11165         }
11166
11167         type = gnutls_certificate_type_get(session);
11168
11169         ret =
11170             gnutls_certificate_verification_status_print(status, type,
11171                                                          &amp;out, 0);
11172         if (ret &lt; 0) {
11173                 printf(&quot;Error\n&quot;);
11174                 return GNUTLS_E_CERTIFICATE_ERROR;
11175         }
11176
11177         printf(&quot;%s&quot;, out.data);
11178
11179         gnutls_free(out.data);
11180
11181         if (status != 0)        /* Certificate is not trusted */
11182                 return GNUTLS_E_CERTIFICATE_ERROR;
11183
11184         /* Do SSH verification */
11185         cert_list = gnutls_certificate_get_peers(session, &amp;cert_list_size);
11186         if (cert_list == NULL) {
11187                 printf(&quot;No certificate was found!\n&quot;);
11188                 return GNUTLS_E_CERTIFICATE_ERROR;
11189         }
11190
11191         /* service may be obtained alternatively using getservbyport() */
11192         ret = gnutls_verify_stored_pubkey(NULL, NULL, hostname, &quot;https&quot;,
11193                                           type, &amp;cert_list[0], 0);
11194         if (ret == GNUTLS_E_NO_CERTIFICATE_FOUND) {
11195                 printf(&quot;Host %s is not known.&quot;, hostname);
11196                 if (status == 0)
11197                         printf(&quot;Its certificate is valid for %s.\n&quot;,
11198                                hostname);
11199
11200                 /* the certificate must be printed and user must be asked on
11201                  * whether it is trustworthy. --see gnutls_x509_crt_print() */
11202
11203                 /* if not trusted */
11204                 return GNUTLS_E_CERTIFICATE_ERROR;
11205         } else if (ret == GNUTLS_E_CERTIFICATE_KEY_MISMATCH) {
11206                 printf
11207                     (&quot;Warning: host %s is known but has another key associated.&quot;,
11208                      hostname);
11209                 printf
11210                     (&quot;It might be that the server has multiple keys, or you are under attack\n&quot;);
11211                 if (status == 0)
11212                         printf(&quot;Its certificate is valid for %s.\n&quot;,
11213                                hostname);
11214
11215                 /* the certificate must be printed and user must be asked on
11216                  * whether it is trustworthy. --see gnutls_x509_crt_print() */
11217
11218                 /* if not trusted */
11219                 return GNUTLS_E_CERTIFICATE_ERROR;
11220         } else if (ret &lt; 0) {
11221                 printf(&quot;gnutls_verify_stored_pubkey: %s\n&quot;,
11222                        gnutls_strerror(ret));
11223                 return ret;
11224         }
11225
11226         /* user trusts the key -&gt; store it */
11227         if (ret != 0) {
11228                 ret = gnutls_store_pubkey(NULL, NULL, hostname, &quot;https&quot;,
11229                                           type, &amp;cert_list[0], 0, 0);
11230                 if (ret &lt; 0)
11231                         printf(&quot;gnutls_store_pubkey: %s\n&quot;,
11232                                gnutls_strerror(ret));
11233         }
11234
11235         /* notify gnutls to continue handshake normally */
11236         return 0;
11237 }
11238 </pre>
11239 <hr>
11240 <a name="Simple-client-example-with-anonymous-authentication"></a>
11241 <div class="header">
11242 <p>
11243 Next: <a href="#Simple-Datagram-TLS-client-example" accesskey="n" rel="next">Simple Datagram TLS client example</a>, Previous: <a href="#Simple-client-example-with-SSH_002dstyle-certificate-verification" accesskey="p" rel="prev">Simple client example with SSH-style certificate verification</a>, Up: <a href="#Client-examples" accesskey="u" rel="up">Client examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
11244 </div>
11245 <a name="Simple-client-example-with-anonymous-authentication-1"></a>
11246 <h4 class="subsection">7.1.3 Simple client example with anonymous authentication</h4>
11247
11248 <p>The simplest client using TLS is the one that doesn&rsquo;t do any
11249 authentication.  This means no external certificates or passwords are
11250 needed to set up the connection.  As could be expected, the connection
11251 is vulnerable to man-in-the-middle (active or redirection) attacks.
11252 However, the data are integrity protected and encrypted from
11253 passive eavesdroppers.
11254 </p>
11255 <p>Note that due to the vulnerable nature of this method very few public
11256 servers support it.
11257 </p>
11258 <pre class="verbatim">/* This example code is placed in the public domain. */
11259
11260 #ifdef HAVE_CONFIG_H
11261 #include &lt;config.h&gt;
11262 #endif
11263
11264 #include &lt;stdio.h&gt;
11265 #include &lt;stdlib.h&gt;
11266 #include &lt;string.h&gt;
11267 #include &lt;sys/types.h&gt;
11268 #include &lt;sys/socket.h&gt;
11269 #include &lt;arpa/inet.h&gt;
11270 #include &lt;unistd.h&gt;
11271 #include &lt;gnutls/gnutls.h&gt;
11272
11273 /* A very basic TLS client, with anonymous authentication.
11274  */
11275
11276 #define MAX_BUF 1024
11277 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
11278
11279 extern int tcp_connect(void);
11280 extern void tcp_close(int sd);
11281
11282 int main(void)
11283 {
11284         int ret, sd, ii;
11285         gnutls_session_t session;
11286         char buffer[MAX_BUF + 1];
11287         gnutls_anon_client_credentials_t anoncred;
11288         /* Need to enable anonymous KX specifically. */
11289
11290         gnutls_global_init();
11291
11292         gnutls_anon_allocate_client_credentials(&amp;anoncred);
11293
11294         /* Initialize TLS session
11295          */
11296         gnutls_init(&amp;session, GNUTLS_CLIENT);
11297
11298         /* Use default priorities */
11299         gnutls_priority_set_direct(session,
11300                                    &quot;PERFORMANCE:+ANON-ECDH:+ANON-DH&quot;,
11301                                    NULL);
11302
11303         /* put the anonymous credentials to the current session
11304          */
11305         gnutls_credentials_set(session, GNUTLS_CRD_ANON, anoncred);
11306
11307         /* connect to the peer
11308          */
11309         sd = tcp_connect();
11310
11311         gnutls_transport_set_int(session, sd);
11312         gnutls_handshake_set_timeout(session,
11313                                      GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
11314
11315         /* Perform the TLS handshake
11316          */
11317         do {
11318                 ret = gnutls_handshake(session);
11319         }
11320         while (ret &lt; 0 &amp;&amp; gnutls_error_is_fatal(ret) == 0);
11321
11322         if (ret &lt; 0) {
11323                 fprintf(stderr, &quot;*** Handshake failed\n&quot;);
11324                 gnutls_perror(ret);
11325                 goto end;
11326         } else {
11327                 char *desc;
11328
11329                 desc = gnutls_session_get_desc(session);
11330                 printf(&quot;- Session info: %s\n&quot;, desc);
11331                 gnutls_free(desc);
11332         }
11333
11334         gnutls_record_send(session, MSG, strlen(MSG));
11335
11336         ret = gnutls_record_recv(session, buffer, MAX_BUF);
11337         if (ret == 0) {
11338                 printf(&quot;- Peer has closed the TLS connection\n&quot;);
11339                 goto end;
11340         } else if (ret &lt; 0 &amp;&amp; gnutls_error_is_fatal(ret) == 0) {
11341                 fprintf(stderr, &quot;*** Warning: %s\n&quot;, gnutls_strerror(ret));
11342         } else if (ret &lt; 0) {
11343                 fprintf(stderr, &quot;*** Error: %s\n&quot;, gnutls_strerror(ret));
11344                 goto end;
11345         }
11346
11347         if (ret &gt; 0) {
11348                 printf(&quot;- Received %d bytes: &quot;, ret);
11349                 for (ii = 0; ii &lt; ret; ii++) {
11350                         fputc(buffer[ii], stdout);
11351                 }
11352                 fputs(&quot;\n&quot;, stdout);
11353         }
11354
11355         gnutls_bye(session, GNUTLS_SHUT_RDWR);
11356
11357       end:
11358
11359         tcp_close(sd);
11360
11361         gnutls_deinit(session);
11362
11363         gnutls_anon_free_client_credentials(anoncred);
11364
11365         gnutls_global_deinit();
11366
11367         return 0;
11368 }
11369 </pre>
11370
11371 <hr>
11372 <a name="Simple-Datagram-TLS-client-example"></a>
11373 <div class="header">
11374 <p>
11375 Next: <a href="#Obtaining-session-information" accesskey="n" rel="next">Obtaining session information</a>, Previous: <a href="#Simple-client-example-with-anonymous-authentication" accesskey="p" rel="prev">Simple client example with anonymous authentication</a>, Up: <a href="#Client-examples" accesskey="u" rel="up">Client examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
11376 </div>
11377 <a name="Simple-datagram-TLS-client-example"></a>
11378 <h4 class="subsection">7.1.4 Simple datagram <acronym>TLS</acronym> client example</h4>
11379
11380 <p>This is a client that uses <acronym>UDP</acronym> to connect to a
11381 server. This is the <acronym>DTLS</acronym> equivalent to the TLS example
11382 with X.509 certificates.
11383 </p>
11384 <pre class="verbatim">/* This example code is placed in the public domain. */
11385
11386 #ifdef HAVE_CONFIG_H
11387 #include &lt;config.h&gt;
11388 #endif
11389
11390 #include &lt;stdio.h&gt;
11391 #include &lt;stdlib.h&gt;
11392 #include &lt;string.h&gt;
11393 #include &lt;sys/types.h&gt;
11394 #include &lt;sys/socket.h&gt;
11395 #include &lt;arpa/inet.h&gt;
11396 #include &lt;unistd.h&gt;
11397 #include &lt;gnutls/gnutls.h&gt;
11398 #include &lt;gnutls/dtls.h&gt;
11399
11400 /* A very basic Datagram TLS client, over UDP with X.509 authentication.
11401  */
11402
11403 #define MAX_BUF 1024
11404 #define CAFILE &quot;/etc/ssl/certs/ca-certificates.crt&quot;
11405 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
11406
11407 extern int udp_connect(void);
11408 extern void udp_close(int sd);
11409 extern int verify_certificate_callback(gnutls_session_t session);
11410
11411 int main(void)
11412 {
11413         int ret, sd, ii;
11414         gnutls_session_t session;
11415         char buffer[MAX_BUF + 1];
11416         const char *err;
11417         gnutls_certificate_credentials_t xcred;
11418
11419         if (gnutls_check_version(&quot;3.1.4&quot;) == NULL) {
11420                 fprintf(stderr, &quot;GnuTLS 3.1.4 or later is required for this example\n&quot;);
11421                 exit(1);
11422         }
11423
11424         /* for backwards compatibility with gnutls &lt; 3.3.0 */
11425         gnutls_global_init();
11426
11427         /* X509 stuff */
11428         gnutls_certificate_allocate_credentials(&amp;xcred);
11429
11430         /* sets the trusted cas file */
11431         gnutls_certificate_set_x509_trust_file(xcred, CAFILE,
11432                                                GNUTLS_X509_FMT_PEM);
11433         gnutls_certificate_set_verify_function(xcred,
11434                                                verify_certificate_callback);
11435
11436         /* Initialize TLS session */
11437         gnutls_init(&amp;session, GNUTLS_CLIENT | GNUTLS_DATAGRAM);
11438
11439         /* Use default priorities */
11440         ret = gnutls_priority_set_direct(session,
11441                                          &quot;NORMAL&quot;, &amp;err);
11442         if (ret &lt; 0) {
11443                 if (ret == GNUTLS_E_INVALID_REQUEST) {
11444                         fprintf(stderr, &quot;Syntax error at: %s\n&quot;, err);
11445                 }
11446                 exit(1);
11447         }
11448
11449         /* put the x509 credentials to the current session */
11450         gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, xcred);
11451         gnutls_server_name_set(session, GNUTLS_NAME_DNS, &quot;my_host_name&quot;,
11452                                strlen(&quot;my_host_name&quot;));
11453
11454         /* connect to the peer */
11455         sd = udp_connect();
11456
11457         gnutls_transport_set_int(session, sd);
11458
11459         /* set the connection MTU */
11460         gnutls_dtls_set_mtu(session, 1000);
11461         /* gnutls_dtls_set_timeouts(session, 1000, 60000); */
11462
11463         /* Perform the TLS handshake */
11464         do {
11465                 ret = gnutls_handshake(session);
11466         }
11467         while (ret == GNUTLS_E_INTERRUPTED || ret == GNUTLS_E_AGAIN);
11468         /* Note that DTLS may also receive GNUTLS_E_LARGE_PACKET */
11469
11470         if (ret &lt; 0) {
11471                 fprintf(stderr, &quot;*** Handshake failed\n&quot;);
11472                 gnutls_perror(ret);
11473                 goto end;
11474         } else {
11475                 char *desc;
11476
11477                 desc = gnutls_session_get_desc(session);
11478                 printf(&quot;- Session info: %s\n&quot;, desc);
11479                 gnutls_free(desc);
11480         }
11481
11482         gnutls_record_send(session, MSG, strlen(MSG));
11483
11484         ret = gnutls_record_recv(session, buffer, MAX_BUF);
11485         if (ret == 0) {
11486                 printf(&quot;- Peer has closed the TLS connection\n&quot;);
11487                 goto end;
11488         } else if (ret &lt; 0 &amp;&amp; gnutls_error_is_fatal(ret) == 0) {
11489                 fprintf(stderr, &quot;*** Warning: %s\n&quot;, gnutls_strerror(ret));
11490         } else if (ret &lt; 0) {
11491                 fprintf(stderr, &quot;*** Error: %s\n&quot;, gnutls_strerror(ret));
11492                 goto end;
11493         }
11494
11495         if (ret &gt; 0) {
11496                 printf(&quot;- Received %d bytes: &quot;, ret);
11497                 for (ii = 0; ii &lt; ret; ii++) {
11498                         fputc(buffer[ii], stdout);
11499                 }
11500                 fputs(&quot;\n&quot;, stdout);
11501         }
11502
11503         /* It is suggested not to use GNUTLS_SHUT_RDWR in DTLS
11504          * connections because the peer's closure message might
11505          * be lost */
11506         gnutls_bye(session, GNUTLS_SHUT_WR);
11507
11508       end:
11509
11510         udp_close(sd);
11511
11512         gnutls_deinit(session);
11513
11514         gnutls_certificate_free_credentials(xcred);
11515
11516         gnutls_global_deinit();
11517
11518         return 0;
11519 }
11520 </pre>
11521 <hr>
11522 <a name="Obtaining-session-information"></a>
11523 <div class="header">
11524 <p>
11525 Next: <a href="#Using-a-callback-to-select-the-certificate-to-use" accesskey="n" rel="next">Using a callback to select the certificate to use</a>, Previous: <a href="#Simple-Datagram-TLS-client-example" accesskey="p" rel="prev">Simple Datagram TLS client example</a>, Up: <a href="#Client-examples" accesskey="u" rel="up">Client examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
11526 </div>
11527 <a name="Obtaining-session-information-1"></a>
11528 <h4 class="subsection">7.1.5 Obtaining session information</h4>
11529
11530 <p>Most of the times it is desirable to know the security properties of
11531 the current established session.  This includes the underlying ciphers
11532 and the protocols involved.  That is the purpose of the following
11533 function.  Note that this function will print meaningful values only
11534 if called after a successful <a href="#gnutls_005fhandshake">gnutls_handshake</a>.
11535 </p>
11536 <pre class="verbatim">/* This example code is placed in the public domain. */
11537
11538 #ifdef HAVE_CONFIG_H
11539 #include &lt;config.h&gt;
11540 #endif
11541
11542 #include &lt;stdio.h&gt;
11543 #include &lt;stdlib.h&gt;
11544 #include &lt;gnutls/gnutls.h&gt;
11545 #include &lt;gnutls/x509.h&gt;
11546
11547 #include &quot;examples.h&quot;
11548
11549 /* This function will print some details of the
11550  * given session.
11551  */
11552 int print_info(gnutls_session_t session)
11553 {
11554         const char *tmp;
11555         gnutls_credentials_type_t cred;
11556         gnutls_kx_algorithm_t kx;
11557         int dhe, ecdh;
11558
11559         dhe = ecdh = 0;
11560
11561         /* print the key exchange's algorithm name
11562          */
11563         kx = gnutls_kx_get(session);
11564         tmp = gnutls_kx_get_name(kx);
11565         printf(&quot;- Key Exchange: %s\n&quot;, tmp);
11566
11567         /* Check the authentication type used and switch
11568          * to the appropriate.
11569          */
11570         cred = gnutls_auth_get_type(session);
11571         switch (cred) {
11572         case GNUTLS_CRD_IA:
11573                 printf(&quot;- TLS/IA session\n&quot;);
11574                 break;
11575
11576
11577 #ifdef ENABLE_SRP
11578         case GNUTLS_CRD_SRP:
11579                 printf(&quot;- SRP session with username %s\n&quot;,
11580                        gnutls_srp_server_get_username(session));
11581                 break;
11582 #endif
11583
11584         case GNUTLS_CRD_PSK:
11585                 /* This returns NULL in server side.
11586                  */
11587                 if (gnutls_psk_client_get_hint(session) != NULL)
11588                         printf(&quot;- PSK authentication. PSK hint '%s'\n&quot;,
11589                                gnutls_psk_client_get_hint(session));
11590                 /* This returns NULL in client side.
11591                  */
11592                 if (gnutls_psk_server_get_username(session) != NULL)
11593                         printf(&quot;- PSK authentication. Connected as '%s'\n&quot;,
11594                                gnutls_psk_server_get_username(session));
11595
11596                 if (kx == GNUTLS_KX_ECDHE_PSK)
11597                         ecdh = 1;
11598                 else if (kx == GNUTLS_KX_DHE_PSK)
11599                         dhe = 1;
11600                 break;
11601
11602         case GNUTLS_CRD_ANON:  /* anonymous authentication */
11603
11604                 printf(&quot;- Anonymous authentication.\n&quot;);
11605                 if (kx == GNUTLS_KX_ANON_ECDH)
11606                         ecdh = 1;
11607                 else if (kx == GNUTLS_KX_ANON_DH)
11608                         dhe = 1;
11609                 break;
11610
11611         case GNUTLS_CRD_CERTIFICATE:   /* certificate authentication */
11612
11613                 /* Check if we have been using ephemeral Diffie-Hellman.
11614                  */
11615                 if (kx == GNUTLS_KX_DHE_RSA || kx == GNUTLS_KX_DHE_DSS)
11616                         dhe = 1;
11617                 else if (kx == GNUTLS_KX_ECDHE_RSA
11618                          || kx == GNUTLS_KX_ECDHE_ECDSA)
11619                         ecdh = 1;
11620
11621                 /* if the certificate list is available, then
11622                  * print some information about it.
11623                  */
11624                 print_x509_certificate_info(session);
11625
11626         }                       /* switch */
11627
11628         if (ecdh != 0)
11629                 printf(&quot;- Ephemeral ECDH using curve %s\n&quot;,
11630                        gnutls_ecc_curve_get_name(gnutls_ecc_curve_get
11631                                                  (session)));
11632         else if (dhe != 0)
11633                 printf(&quot;- Ephemeral DH using prime of %d bits\n&quot;,
11634                        gnutls_dh_get_prime_bits(session));
11635
11636         /* print the protocol's name (ie TLS 1.0)
11637          */
11638         tmp =
11639             gnutls_protocol_get_name(gnutls_protocol_get_version(session));
11640         printf(&quot;- Protocol: %s\n&quot;, tmp);
11641
11642         /* print the certificate type of the peer.
11643          * ie X.509
11644          */
11645         tmp =
11646             gnutls_certificate_type_get_name(gnutls_certificate_type_get
11647                                              (session));
11648
11649         printf(&quot;- Certificate Type: %s\n&quot;, tmp);
11650
11651         /* print the compression algorithm (if any)
11652          */
11653         tmp = gnutls_compression_get_name(gnutls_compression_get(session));
11654         printf(&quot;- Compression: %s\n&quot;, tmp);
11655
11656         /* print the name of the cipher used.
11657          * ie 3DES.
11658          */
11659         tmp = gnutls_cipher_get_name(gnutls_cipher_get(session));
11660         printf(&quot;- Cipher: %s\n&quot;, tmp);
11661
11662         /* Print the MAC algorithms name.
11663          * ie SHA1
11664          */
11665         tmp = gnutls_mac_get_name(gnutls_mac_get(session));
11666         printf(&quot;- MAC: %s\n&quot;, tmp);
11667
11668         return 0;
11669 }
11670 </pre>
11671 <hr>
11672 <a name="Using-a-callback-to-select-the-certificate-to-use"></a>
11673 <div class="header">
11674 <p>
11675 Next: <a href="#Verifying-a-certificate" accesskey="n" rel="next">Verifying a certificate</a>, Previous: <a href="#Obtaining-session-information" accesskey="p" rel="prev">Obtaining session information</a>, Up: <a href="#Client-examples" accesskey="u" rel="up">Client examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
11676 </div>
11677 <a name="Using-a-callback-to-select-the-certificate-to-use-1"></a>
11678 <h4 class="subsection">7.1.6 Using a callback to select the certificate to use</h4>
11679
11680 <p>There are cases where a client holds several certificate and key
11681 pairs, and may not want to load all of them in the credentials
11682 structure.  The following example demonstrates the use of the
11683 certificate selection callback.
11684 </p>
11685 <pre class="verbatim">/* This example code is placed in the public domain. */
11686
11687 #ifdef HAVE_CONFIG_H
11688 #include &lt;config.h&gt;
11689 #endif
11690
11691 #include &lt;stdio.h&gt;
11692 #include &lt;stdlib.h&gt;
11693 #include &lt;string.h&gt;
11694 #include &lt;sys/types.h&gt;
11695 #include &lt;sys/socket.h&gt;
11696 #include &lt;arpa/inet.h&gt;
11697 #include &lt;unistd.h&gt;
11698 #include &lt;gnutls/gnutls.h&gt;
11699 #include &lt;gnutls/x509.h&gt;
11700 #include &lt;gnutls/abstract.h&gt;
11701 #include &lt;sys/types.h&gt;
11702 #include &lt;sys/stat.h&gt;
11703 #include &lt;fcntl.h&gt;
11704
11705 /* A TLS client that loads the certificate and key.
11706  */
11707
11708 #define MAX_BUF 1024
11709 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
11710
11711 #define CERT_FILE &quot;cert.pem&quot;
11712 #define KEY_FILE &quot;key.pem&quot;
11713 #define CAFILE &quot;/etc/ssl/certs/ca-certificates.crt&quot;
11714
11715 extern int tcp_connect(void);
11716 extern void tcp_close(int sd);
11717
11718 static int
11719 cert_callback(gnutls_session_t session,
11720               const gnutls_datum_t * req_ca_rdn, int nreqs,
11721               const gnutls_pk_algorithm_t * sign_algos,
11722               int sign_algos_length, gnutls_pcert_st ** pcert,
11723               unsigned int *pcert_length, gnutls_privkey_t * pkey);
11724
11725 gnutls_pcert_st pcrt;
11726 gnutls_privkey_t key;
11727
11728 /* Load the certificate and the private key.
11729  */
11730 static void load_keys(void)
11731 {
11732         int ret;
11733         gnutls_datum_t data;
11734
11735         ret = gnutls_load_file(CERT_FILE, &amp;data);
11736         if (ret &lt; 0) {
11737                 fprintf(stderr, &quot;*** Error loading certificate file.\n&quot;);
11738                 exit(1);
11739         }
11740
11741         ret =
11742             gnutls_pcert_import_x509_raw(&amp;pcrt, &amp;data, GNUTLS_X509_FMT_PEM,
11743                                          0);
11744         if (ret &lt; 0) {
11745                 fprintf(stderr, &quot;*** Error loading certificate file: %s\n&quot;,
11746                         gnutls_strerror(ret));
11747                 exit(1);
11748         }
11749
11750         gnutls_free(data.data);
11751
11752         ret = gnutls_load_file(KEY_FILE, &amp;data);
11753         if (ret &lt; 0) {
11754                 fprintf(stderr, &quot;*** Error loading key file.\n&quot;);
11755                 exit(1);
11756         }
11757
11758         gnutls_privkey_init(&amp;key);
11759
11760         ret =
11761             gnutls_privkey_import_x509_raw(key, &amp;data, GNUTLS_X509_FMT_PEM,
11762                                            NULL, 0);
11763         if (ret &lt; 0) {
11764                 fprintf(stderr, &quot;*** Error loading key file: %s\n&quot;,
11765                         gnutls_strerror(ret));
11766                 exit(1);
11767         }
11768
11769         gnutls_free(data.data);
11770 }
11771
11772 int main(void)
11773 {
11774         int ret, sd, ii;
11775         gnutls_session_t session;
11776         gnutls_priority_t priorities_cache;
11777         char buffer[MAX_BUF + 1];
11778         gnutls_certificate_credentials_t xcred;
11779
11780         if (gnutls_check_version(&quot;3.1.4&quot;) == NULL) {
11781                 fprintf(stderr, &quot;GnuTLS 3.1.4 or later is required for this example\n&quot;);
11782                 exit(1);
11783         }
11784
11785         /* for backwards compatibility with gnutls &lt; 3.3.0 */
11786         gnutls_global_init();
11787
11788         load_keys();
11789
11790         /* X509 stuff */
11791         gnutls_certificate_allocate_credentials(&amp;xcred);
11792
11793         /* priorities */
11794         gnutls_priority_init(&amp;priorities_cache,
11795                              &quot;NORMAL&quot;, NULL);
11796
11797         /* sets the trusted cas file
11798          */
11799         gnutls_certificate_set_x509_trust_file(xcred, CAFILE,
11800                                                GNUTLS_X509_FMT_PEM);
11801
11802         gnutls_certificate_set_retrieve_function2(xcred, cert_callback);
11803
11804         /* Initialize TLS session
11805          */
11806         gnutls_init(&amp;session, GNUTLS_CLIENT);
11807
11808         /* Use default priorities */
11809         gnutls_priority_set(session, priorities_cache);
11810
11811         /* put the x509 credentials to the current session
11812          */
11813         gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, xcred);
11814
11815         /* connect to the peer
11816          */
11817         sd = tcp_connect();
11818
11819         gnutls_transport_set_int(session, sd);
11820
11821         /* Perform the TLS handshake
11822          */
11823         ret = gnutls_handshake(session);
11824
11825         if (ret &lt; 0) {
11826                 fprintf(stderr, &quot;*** Handshake failed\n&quot;);
11827                 gnutls_perror(ret);
11828                 goto end;
11829         } else {
11830                 char *desc;
11831
11832                 desc = gnutls_session_get_desc(session);
11833                 printf(&quot;- Session info: %s\n&quot;, desc);
11834                 gnutls_free(desc);
11835         }
11836
11837         gnutls_record_send(session, MSG, strlen(MSG));
11838
11839         ret = gnutls_record_recv(session, buffer, MAX_BUF);
11840         if (ret == 0) {
11841                 printf(&quot;- Peer has closed the TLS connection\n&quot;);
11842                 goto end;
11843         } else if (ret &lt; 0) {
11844                 fprintf(stderr, &quot;*** Error: %s\n&quot;, gnutls_strerror(ret));
11845                 goto end;
11846         }
11847
11848         printf(&quot;- Received %d bytes: &quot;, ret);
11849         for (ii = 0; ii &lt; ret; ii++) {
11850                 fputc(buffer[ii], stdout);
11851         }
11852         fputs(&quot;\n&quot;, stdout);
11853
11854         gnutls_bye(session, GNUTLS_SHUT_RDWR);
11855
11856       end:
11857
11858         tcp_close(sd);
11859
11860         gnutls_deinit(session);
11861
11862         gnutls_certificate_free_credentials(xcred);
11863         gnutls_priority_deinit(priorities_cache);
11864
11865         gnutls_global_deinit();
11866
11867         return 0;
11868 }
11869
11870
11871
11872 /* This callback should be associated with a session by calling
11873  * gnutls_certificate_client_set_retrieve_function( session, cert_callback),
11874  * before a handshake.
11875  */
11876
11877 static int
11878 cert_callback(gnutls_session_t session,
11879               const gnutls_datum_t * req_ca_rdn, int nreqs,
11880               const gnutls_pk_algorithm_t * sign_algos,
11881               int sign_algos_length, gnutls_pcert_st ** pcert,
11882               unsigned int *pcert_length, gnutls_privkey_t * pkey)
11883 {
11884         char issuer_dn[256];
11885         int i, ret;
11886         size_t len;
11887         gnutls_certificate_type_t type;
11888
11889         /* Print the server's trusted CAs
11890          */
11891         if (nreqs &gt; 0)
11892                 printf(&quot;- Server's trusted authorities:\n&quot;);
11893         else
11894                 printf
11895                     (&quot;- Server did not send us any trusted authorities names.\n&quot;);
11896
11897         /* print the names (if any) */
11898         for (i = 0; i &lt; nreqs; i++) {
11899                 len = sizeof(issuer_dn);
11900                 ret = gnutls_x509_rdn_get(&amp;req_ca_rdn[i], issuer_dn, &amp;len);
11901                 if (ret &gt;= 0) {
11902                         printf(&quot;   [%d]: &quot;, i);
11903                         printf(&quot;%s\n&quot;, issuer_dn);
11904                 }
11905         }
11906
11907         /* Select a certificate and return it.
11908          * The certificate must be of any of the &quot;sign algorithms&quot;
11909          * supported by the server.
11910          */
11911         type = gnutls_certificate_type_get(session);
11912         if (type == GNUTLS_CRT_X509) {
11913                 *pcert_length = 1;
11914                 *pcert = &amp;pcrt;
11915                 *pkey = key;
11916         } else {
11917                 return -1;
11918         }
11919
11920         return 0;
11921
11922 }
11923 </pre>
11924 <hr>
11925 <a name="Verifying-a-certificate"></a>
11926 <div class="header">
11927 <p>
11928 Next: <a href="#Client-using-a-smart-card-with-TLS" accesskey="n" rel="next">Client using a smart card with TLS</a>, Previous: <a href="#Using-a-callback-to-select-the-certificate-to-use" accesskey="p" rel="prev">Using a callback to select the certificate to use</a>, Up: <a href="#Client-examples" accesskey="u" rel="up">Client examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
11929 </div>
11930 <a name="Verifying-a-certificate-1"></a>
11931 <h4 class="subsection">7.1.7 Verifying a certificate</h4>
11932 <a name="ex_002dverify2"></a>
11933 <p>An example is listed below which uses the high level verification
11934 functions to verify a given certificate list.
11935 </p>
11936 <pre class="verbatim">/* This example code is placed in the public domain. */
11937
11938 #ifdef HAVE_CONFIG_H
11939 #include &lt;config.h&gt;
11940 #endif
11941
11942 #include &lt;stdio.h&gt;
11943 #include &lt;stdlib.h&gt;
11944 #include &lt;string.h&gt;
11945 #include &lt;gnutls/gnutls.h&gt;
11946 #include &lt;gnutls/x509.h&gt;
11947
11948 #include &quot;examples.h&quot;
11949
11950 /* All the available CRLs
11951  */
11952 gnutls_x509_crl_t *crl_list;
11953 int crl_list_size;
11954
11955 /* All the available trusted CAs
11956  */
11957 gnutls_x509_crt_t *ca_list;
11958 int ca_list_size;
11959
11960 static int print_details_func(gnutls_x509_crt_t cert,
11961                               gnutls_x509_crt_t issuer,
11962                               gnutls_x509_crl_t crl,
11963                               unsigned int verification_output);
11964
11965 /* This function will try to verify the peer's certificate chain, and
11966  * also check if the hostname matches.
11967  */
11968 void
11969 verify_certificate_chain(const char *hostname,
11970                          const gnutls_datum_t * cert_chain,
11971                          int cert_chain_length)
11972 {
11973         int i;
11974         gnutls_x509_trust_list_t tlist;
11975         gnutls_x509_crt_t *cert;
11976
11977         unsigned int output;
11978
11979         /* Initialize the trusted certificate list. This should be done
11980          * once on initialization. gnutls_x509_crt_list_import2() and
11981          * gnutls_x509_crl_list_import2() can be used to load them.
11982          */
11983         gnutls_x509_trust_list_init(&amp;tlist, 0);
11984
11985         gnutls_x509_trust_list_add_cas(tlist, ca_list, ca_list_size, 0);
11986         gnutls_x509_trust_list_add_crls(tlist, crl_list, crl_list_size,
11987                                         GNUTLS_TL_VERIFY_CRL, 0);
11988
11989         cert = malloc(sizeof(*cert) * cert_chain_length);
11990
11991         /* Import all the certificates in the chain to
11992          * native certificate format.
11993          */
11994         for (i = 0; i &lt; cert_chain_length; i++) {
11995                 gnutls_x509_crt_init(&amp;cert[i]);
11996                 gnutls_x509_crt_import(cert[i], &amp;cert_chain[i],
11997                                        GNUTLS_X509_FMT_DER);
11998         }
11999
12000         gnutls_x509_trust_list_verify_named_crt(tlist, cert[0], hostname,
12001                                                 strlen(hostname),
12002                                                 GNUTLS_VERIFY_DISABLE_CRL_CHECKS,
12003                                                 &amp;output,
12004                                                 print_details_func);
12005
12006         /* if this certificate is not explicitly trusted verify against CAs
12007          */
12008         if (output != 0) {
12009                 gnutls_x509_trust_list_verify_crt(tlist, cert,
12010                                                   cert_chain_length, 0,
12011                                                   &amp;output,
12012                                                   print_details_func);
12013         }
12014
12015         if (output &amp; GNUTLS_CERT_INVALID) {
12016                 fprintf(stderr, &quot;Not trusted&quot;);
12017
12018                 if (output &amp; GNUTLS_CERT_SIGNER_NOT_FOUND)
12019                         fprintf(stderr, &quot;: no issuer was found&quot;);
12020                 if (output &amp; GNUTLS_CERT_SIGNER_NOT_CA)
12021                         fprintf(stderr, &quot;: issuer is not a CA&quot;);
12022                 if (output &amp; GNUTLS_CERT_NOT_ACTIVATED)
12023                         fprintf(stderr, &quot;: not yet activated\n&quot;);
12024                 if (output &amp; GNUTLS_CERT_EXPIRED)
12025                         fprintf(stderr, &quot;: expired\n&quot;);
12026
12027                 fprintf(stderr, &quot;\n&quot;);
12028         } else
12029                 fprintf(stderr, &quot;Trusted\n&quot;);
12030
12031         /* Check if the name in the first certificate matches our destination!
12032          */
12033         if (!gnutls_x509_crt_check_hostname(cert[0], hostname)) {
12034                 printf
12035                     (&quot;The certificate's owner does not match hostname '%s'\n&quot;,
12036                      hostname);
12037         }
12038
12039         gnutls_x509_trust_list_deinit(tlist, 1);
12040
12041         return;
12042 }
12043
12044 static int
12045 print_details_func(gnutls_x509_crt_t cert,
12046                    gnutls_x509_crt_t issuer, gnutls_x509_crl_t crl,
12047                    unsigned int verification_output)
12048 {
12049         char name[512];
12050         char issuer_name[512];
12051         size_t name_size;
12052         size_t issuer_name_size;
12053
12054         issuer_name_size = sizeof(issuer_name);
12055         gnutls_x509_crt_get_issuer_dn(cert, issuer_name,
12056                                       &amp;issuer_name_size);
12057
12058         name_size = sizeof(name);
12059         gnutls_x509_crt_get_dn(cert, name, &amp;name_size);
12060
12061         fprintf(stdout, &quot;\tSubject: %s\n&quot;, name);
12062         fprintf(stdout, &quot;\tIssuer: %s\n&quot;, issuer_name);
12063
12064         if (issuer != NULL) {
12065                 issuer_name_size = sizeof(issuer_name);
12066                 gnutls_x509_crt_get_dn(issuer, issuer_name,
12067                                        &amp;issuer_name_size);
12068
12069                 fprintf(stdout, &quot;\tVerified against: %s\n&quot;, issuer_name);
12070         }
12071
12072         if (crl != NULL) {
12073                 issuer_name_size = sizeof(issuer_name);
12074                 gnutls_x509_crl_get_issuer_dn(crl, issuer_name,
12075                                               &amp;issuer_name_size);
12076
12077                 fprintf(stdout, &quot;\tVerified against CRL of: %s\n&quot;,
12078                         issuer_name);
12079         }
12080
12081         fprintf(stdout, &quot;\tVerification output: %x\n\n&quot;,
12082                 verification_output);
12083
12084         return 0;
12085 }
12086 </pre>
12087 <hr>
12088 <a name="Client-using-a-smart-card-with-TLS"></a>
12089 <div class="header">
12090 <p>
12091 Next: <a href="#Client-with-Resume-capability-example" accesskey="n" rel="next">Client with Resume capability example</a>, Previous: <a href="#Verifying-a-certificate" accesskey="p" rel="prev">Verifying a certificate</a>, Up: <a href="#Client-examples" accesskey="u" rel="up">Client examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
12092 </div>
12093 <a name="Using-a-smart-card-with-TLS"></a>
12094 <h4 class="subsection">7.1.8 Using a smart card with TLS</h4>
12095 <a name="ex_002dpkcs11_002dclient"></a><a name="index-Smart-card-example"></a>
12096
12097 <p>This example will demonstrate how to load keys and certificates
12098 from a smart-card or any other <acronym>PKCS</acronym> #11 token, and
12099 use it in a TLS connection.
12100 </p>
12101 <pre class="verbatim">/* This example code is placed in the public domain. */
12102
12103 #ifdef HAVE_CONFIG_H
12104 #include &lt;config.h&gt;
12105 #endif
12106
12107 #include &lt;stdio.h&gt;
12108 #include &lt;stdlib.h&gt;
12109 #include &lt;string.h&gt;
12110 #include &lt;sys/types.h&gt;
12111 #include &lt;sys/socket.h&gt;
12112 #include &lt;arpa/inet.h&gt;
12113 #include &lt;unistd.h&gt;
12114 #include &lt;gnutls/gnutls.h&gt;
12115 #include &lt;gnutls/x509.h&gt;
12116 #include &lt;gnutls/pkcs11.h&gt;
12117 #include &lt;sys/types.h&gt;
12118 #include &lt;sys/stat.h&gt;
12119 #include &lt;fcntl.h&gt;
12120 #include &lt;getpass.h&gt;            /* for getpass() */
12121
12122 /* A TLS client that loads the certificate and key.
12123  */
12124
12125 #define MAX_BUF 1024
12126 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
12127 #define MIN(x,y) (((x)&lt;(y))?(x):(y))
12128
12129 #define CAFILE &quot;/etc/ssl/certs/ca-certificates.crt&quot;
12130
12131 /* The URLs of the objects can be obtained
12132  * using p11tool --list-all --login
12133  */
12134 #define KEY_URL &quot;pkcs11:manufacturer=SomeManufacturer;object=Private%20Key&quot; \
12135   &quot;;objecttype=private;id=%db%5b%3e%b5%72%33&quot;
12136 #define CERT_URL &quot;pkcs11:manufacturer=SomeManufacturer;object=Certificate;&quot; \
12137   &quot;objecttype=cert;id=db%5b%3e%b5%72%33&quot;
12138
12139 extern int tcp_connect(void);
12140 extern void tcp_close(int sd);
12141
12142 static int
12143 pin_callback(void *user, int attempt, const char *token_url,
12144              const char *token_label, unsigned int flags, char *pin,
12145              size_t pin_max)
12146 {
12147         const char *password;
12148         int len;
12149
12150         printf(&quot;PIN required for token '%s' with URL '%s'\n&quot;, token_label,
12151                token_url);
12152         if (flags &amp; GNUTLS_PIN_FINAL_TRY)
12153                 printf(&quot;*** This is the final try before locking!\n&quot;);
12154         if (flags &amp; GNUTLS_PIN_COUNT_LOW)
12155                 printf(&quot;*** Only few tries left before locking!\n&quot;);
12156         if (flags &amp; GNUTLS_PIN_WRONG)
12157                 printf(&quot;*** Wrong PIN\n&quot;);
12158
12159         password = getpass(&quot;Enter pin: &quot;);
12160         if (password == NULL || password[0] == 0) {
12161                 fprintf(stderr, &quot;No password given\n&quot;);
12162                 exit(1);
12163         }
12164
12165         len = MIN(pin_max - 1, strlen(password));
12166         memcpy(pin, password, len);
12167         pin[len] = 0;
12168
12169         return 0;
12170 }
12171
12172 int main(void)
12173 {
12174         int ret, sd, ii;
12175         gnutls_session_t session;
12176         gnutls_priority_t priorities_cache;
12177         char buffer[MAX_BUF + 1];
12178         gnutls_certificate_credentials_t xcred;
12179         /* Allow connections to servers that have OpenPGP keys as well.
12180          */
12181
12182         if (gnutls_check_version(&quot;3.1.4&quot;) == NULL) {
12183                 fprintf(stderr, &quot;GnuTLS 3.1.4 or later is required for this example\n&quot;);
12184                 exit(1);
12185         }
12186
12187         /* for backwards compatibility with gnutls &lt; 3.3.0 */
12188         gnutls_global_init();
12189
12190         /* The PKCS11 private key operations may require PIN.
12191          * Register a callback. */
12192         gnutls_pkcs11_set_pin_function(pin_callback, NULL);
12193
12194         /* X509 stuff */
12195         gnutls_certificate_allocate_credentials(&amp;xcred);
12196
12197         /* priorities */
12198         gnutls_priority_init(&amp;priorities_cache,
12199                              &quot;NORMAL&quot;, NULL);
12200
12201         /* sets the trusted cas file
12202          */
12203         gnutls_certificate_set_x509_trust_file(xcred, CAFILE,
12204                                                GNUTLS_X509_FMT_PEM);
12205
12206         gnutls_certificate_set_x509_key_file(xcred, CERT_URL, KEY_URL,
12207                                              GNUTLS_X509_FMT_DER);
12208
12209         /* Initialize TLS session
12210          */
12211         gnutls_init(&amp;session, GNUTLS_CLIENT);
12212
12213         /* Use default priorities */
12214         gnutls_priority_set(session, priorities_cache);
12215
12216         /* put the x509 credentials to the current session
12217          */
12218         gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, xcred);
12219
12220         /* connect to the peer
12221          */
12222         sd = tcp_connect();
12223
12224         gnutls_transport_set_int(session, sd);
12225
12226         /* Perform the TLS handshake
12227          */
12228         ret = gnutls_handshake(session);
12229
12230         if (ret &lt; 0) {
12231                 fprintf(stderr, &quot;*** Handshake failed\n&quot;);
12232                 gnutls_perror(ret);
12233                 goto end;
12234         } else {
12235                 char *desc;
12236
12237                 desc = gnutls_session_get_desc(session);
12238                 printf(&quot;- Session info: %s\n&quot;, desc);
12239                 gnutls_free(desc);
12240         }
12241
12242         gnutls_record_send(session, MSG, strlen(MSG));
12243
12244         ret = gnutls_record_recv(session, buffer, MAX_BUF);
12245         if (ret == 0) {
12246                 printf(&quot;- Peer has closed the TLS connection\n&quot;);
12247                 goto end;
12248         } else if (ret &lt; 0) {
12249                 fprintf(stderr, &quot;*** Error: %s\n&quot;, gnutls_strerror(ret));
12250                 goto end;
12251         }
12252
12253         printf(&quot;- Received %d bytes: &quot;, ret);
12254         for (ii = 0; ii &lt; ret; ii++) {
12255                 fputc(buffer[ii], stdout);
12256         }
12257         fputs(&quot;\n&quot;, stdout);
12258
12259         gnutls_bye(session, GNUTLS_SHUT_RDWR);
12260
12261       end:
12262
12263         tcp_close(sd);
12264
12265         gnutls_deinit(session);
12266
12267         gnutls_certificate_free_credentials(xcred);
12268         gnutls_priority_deinit(priorities_cache);
12269
12270         gnutls_global_deinit();
12271
12272         return 0;
12273 }
12274 </pre>
12275
12276 <hr>
12277 <a name="Client-with-Resume-capability-example"></a>
12278 <div class="header">
12279 <p>
12280 Next: <a href="#Simple-client-example-with-SRP-authentication" accesskey="n" rel="next">Simple client example with SRP authentication</a>, Previous: <a href="#Client-using-a-smart-card-with-TLS" accesskey="p" rel="prev">Client using a smart card with TLS</a>, Up: <a href="#Client-examples" accesskey="u" rel="up">Client examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
12281 </div>
12282 <a name="Client-with-resume-capability-example"></a>
12283 <h4 class="subsection">7.1.9 Client with resume capability example</h4>
12284 <a name="ex_002dresume_002dclient"></a>
12285 <p>This is a modification of the simple client example. Here we
12286 demonstrate the use of session resumption. The client tries to connect
12287 once using <acronym>TLS</acronym>, close the connection and then try to
12288 establish a new connection using the previously negotiated data.
12289 </p>
12290 <pre class="verbatim">/* This example code is placed in the public domain. */
12291
12292 #ifdef HAVE_CONFIG_H
12293 #include &lt;config.h&gt;
12294 #endif
12295
12296 #include &lt;string.h&gt;
12297 #include &lt;stdio.h&gt;
12298 #include &lt;stdlib.h&gt;
12299 #include &lt;gnutls/gnutls.h&gt;
12300
12301 /* Those functions are defined in other examples.
12302  */
12303 extern void check_alert(gnutls_session_t session, int ret);
12304 extern int tcp_connect(void);
12305 extern void tcp_close(int sd);
12306
12307 #define MAX_BUF 1024
12308 #define CAFILE &quot;/etc/ssl/certs/ca-certificates.crt&quot;
12309 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
12310
12311 int main(void)
12312 {
12313         int ret;
12314         int sd, ii;
12315         gnutls_session_t session;
12316         char buffer[MAX_BUF + 1];
12317         gnutls_certificate_credentials_t xcred;
12318
12319         /* variables used in session resuming
12320          */
12321         int t;
12322         char *session_data = NULL;
12323         size_t session_data_size = 0;
12324
12325         gnutls_global_init();
12326
12327         /* X509 stuff */
12328         gnutls_certificate_allocate_credentials(&amp;xcred);
12329
12330         gnutls_certificate_set_x509_trust_file(xcred, CAFILE,
12331                                                GNUTLS_X509_FMT_PEM);
12332
12333         for (t = 0; t &lt; 2; t++) {       /* connect 2 times to the server */
12334
12335                 sd = tcp_connect();
12336
12337                 gnutls_init(&amp;session, GNUTLS_CLIENT);
12338
12339                 gnutls_priority_set_direct(session,
12340                                            &quot;PERFORMANCE:!ARCFOUR-128&quot;,
12341                                            NULL);
12342
12343                 gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE,
12344                                        xcred);
12345
12346                 if (t &gt; 0) {
12347                         /* if this is not the first time we connect */
12348                         gnutls_session_set_data(session, session_data,
12349                                                 session_data_size);
12350                         free(session_data);
12351                 }
12352
12353                 gnutls_transport_set_int(session, sd);
12354                 gnutls_handshake_set_timeout(session,
12355                                              GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
12356
12357                 /* Perform the TLS handshake
12358                  */
12359                 do {
12360                         ret = gnutls_handshake(session);
12361                 }
12362                 while (ret &lt; 0 &amp;&amp; gnutls_error_is_fatal(ret) == 0);
12363
12364                 if (ret &lt; 0) {
12365                         fprintf(stderr, &quot;*** Handshake failed\n&quot;);
12366                         gnutls_perror(ret);
12367                         goto end;
12368                 } else {
12369                         printf(&quot;- Handshake was completed\n&quot;);
12370                 }
12371
12372                 if (t == 0) {   /* the first time we connect */
12373                         /* get the session data size */
12374                         gnutls_session_get_data(session, NULL,
12375                                                 &amp;session_data_size);
12376                         session_data = malloc(session_data_size);
12377
12378                         /* put session data to the session variable */
12379                         gnutls_session_get_data(session, session_data,
12380                                                 &amp;session_data_size);
12381
12382                 } else {        /* the second time we connect */
12383
12384                         /* check if we actually resumed the previous session */
12385                         if (gnutls_session_is_resumed(session) != 0) {
12386                                 printf(&quot;- Previous session was resumed\n&quot;);
12387                         } else {
12388                                 fprintf(stderr,
12389                                         &quot;*** Previous session was NOT resumed\n&quot;);
12390                         }
12391                 }
12392
12393                 /* This function was defined in a previous example
12394                  */
12395                 /* print_info(session); */
12396
12397                 gnutls_record_send(session, MSG, strlen(MSG));
12398
12399                 ret = gnutls_record_recv(session, buffer, MAX_BUF);
12400                 if (ret == 0) {
12401                         printf(&quot;- Peer has closed the TLS connection\n&quot;);
12402                         goto end;
12403                 } else if (ret &lt; 0 &amp;&amp; gnutls_error_is_fatal(ret) == 0) {
12404                         fprintf(stderr, &quot;*** Warning: %s\n&quot;,
12405                                 gnutls_strerror(ret));
12406                 } else if (ret &lt; 0) {
12407                         fprintf(stderr, &quot;*** Error: %s\n&quot;,
12408                                 gnutls_strerror(ret));
12409                         goto end;
12410                 }
12411
12412                 if (ret &gt; 0) {
12413                         printf(&quot;- Received %d bytes: &quot;, ret);
12414                         for (ii = 0; ii &lt; ret; ii++) {
12415                                 fputc(buffer[ii], stdout);
12416                         }
12417                         fputs(&quot;\n&quot;, stdout);
12418                 }
12419
12420                 gnutls_bye(session, GNUTLS_SHUT_RDWR);
12421
12422               end:
12423
12424                 tcp_close(sd);
12425
12426                 gnutls_deinit(session);
12427
12428         }                       /* for() */
12429
12430         gnutls_certificate_free_credentials(xcred);
12431
12432         gnutls_global_deinit();
12433
12434         return 0;
12435 }
12436 </pre>
12437
12438 <hr>
12439 <a name="Simple-client-example-with-SRP-authentication"></a>
12440 <div class="header">
12441 <p>
12442 Next: <a href="#Simple-client-example-in-C_002b_002b" accesskey="n" rel="next">Simple client example in C++</a>, Previous: <a href="#Client-with-Resume-capability-example" accesskey="p" rel="prev">Client with Resume capability example</a>, Up: <a href="#Client-examples" accesskey="u" rel="up">Client examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
12443 </div>
12444 <a name="Simple-client-example-with-SRP-authentication-1"></a>
12445 <h4 class="subsection">7.1.10 Simple client example with <acronym>SRP</acronym> authentication</h4>
12446
12447 <p>The following client is a very simple <acronym>SRP</acronym> <acronym>TLS</acronym>
12448 client which connects to a server and authenticates using a
12449 <em>username</em> and a <em>password</em>. The server may authenticate
12450 itself using a certificate, and in that case it has to be verified.
12451 </p>
12452 <pre class="verbatim">/* This example code is placed in the public domain. */
12453
12454 #ifdef HAVE_CONFIG_H
12455 #include &lt;config.h&gt;
12456 #endif
12457
12458 #include &lt;stdio.h&gt;
12459 #include &lt;stdlib.h&gt;
12460 #include &lt;string.h&gt;
12461 #include &lt;gnutls/gnutls.h&gt;
12462
12463 /* Those functions are defined in other examples.
12464  */
12465 extern void check_alert(gnutls_session_t session, int ret);
12466 extern int tcp_connect(void);
12467 extern void tcp_close(int sd);
12468
12469 #define MAX_BUF 1024
12470 #define USERNAME &quot;user&quot;
12471 #define PASSWORD &quot;pass&quot;
12472 #define CAFILE &quot;/etc/ssl/certs/ca-certificates.crt&quot;
12473 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
12474
12475 int main(void)
12476 {
12477         int ret;
12478         int sd, ii;
12479         gnutls_session_t session;
12480         char buffer[MAX_BUF + 1];
12481         gnutls_srp_client_credentials_t srp_cred;
12482         gnutls_certificate_credentials_t cert_cred;
12483
12484         if (gnutls_check_version(&quot;3.1.4&quot;) == NULL) {
12485                 fprintf(stderr, &quot;GnuTLS 3.1.4 or later is required for this example\n&quot;);
12486                 exit(1);
12487         }
12488
12489         /* for backwards compatibility with gnutls &lt; 3.3.0 */
12490         gnutls_global_init();
12491
12492         gnutls_srp_allocate_client_credentials(&amp;srp_cred);
12493         gnutls_certificate_allocate_credentials(&amp;cert_cred);
12494
12495         gnutls_certificate_set_x509_trust_file(cert_cred, CAFILE,
12496                                                GNUTLS_X509_FMT_PEM);
12497         gnutls_srp_set_client_credentials(srp_cred, USERNAME, PASSWORD);
12498
12499         /* connects to server
12500          */
12501         sd = tcp_connect();
12502
12503         /* Initialize TLS session
12504          */
12505         gnutls_init(&amp;session, GNUTLS_CLIENT);
12506
12507
12508         /* Set the priorities.
12509          */
12510         gnutls_priority_set_direct(session,
12511                                    &quot;NORMAL:+SRP:+SRP-RSA:+SRP-DSS&quot;,
12512                                    NULL);
12513
12514         /* put the SRP credentials to the current session
12515          */
12516         gnutls_credentials_set(session, GNUTLS_CRD_SRP, srp_cred);
12517         gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, cert_cred);
12518
12519         gnutls_transport_set_int(session, sd);
12520         gnutls_handshake_set_timeout(session,
12521                                      GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT);
12522
12523         /* Perform the TLS handshake
12524          */
12525         do {
12526                 ret = gnutls_handshake(session);
12527         }
12528         while (ret &lt; 0 &amp;&amp; gnutls_error_is_fatal(ret) == 0);
12529
12530         if (ret &lt; 0) {
12531                 fprintf(stderr, &quot;*** Handshake failed\n&quot;);
12532                 gnutls_perror(ret);
12533                 goto end;
12534         } else {
12535                 char *desc;
12536
12537                 desc = gnutls_session_get_desc(session);
12538                 printf(&quot;- Session info: %s\n&quot;, desc);
12539                 gnutls_free(desc);
12540         }
12541
12542         gnutls_record_send(session, MSG, strlen(MSG));
12543
12544         ret = gnutls_record_recv(session, buffer, MAX_BUF);
12545         if (gnutls_error_is_fatal(ret) != 0 || ret == 0) {
12546                 if (ret == 0) {
12547                         printf
12548                             (&quot;- Peer has closed the GnuTLS connection\n&quot;);
12549                         goto end;
12550                 } else {
12551                         fprintf(stderr, &quot;*** Error: %s\n&quot;,
12552                                 gnutls_strerror(ret));
12553                         goto end;
12554                 }
12555         } else
12556                 check_alert(session, ret);
12557
12558         if (ret &gt; 0) {
12559                 printf(&quot;- Received %d bytes: &quot;, ret);
12560                 for (ii = 0; ii &lt; ret; ii++) {
12561                         fputc(buffer[ii], stdout);
12562                 }
12563                 fputs(&quot;\n&quot;, stdout);
12564         }
12565         gnutls_bye(session, GNUTLS_SHUT_RDWR);
12566
12567       end:
12568
12569         tcp_close(sd);
12570
12571         gnutls_deinit(session);
12572
12573         gnutls_srp_free_client_credentials(srp_cred);
12574         gnutls_certificate_free_credentials(cert_cred);
12575
12576         gnutls_global_deinit();
12577
12578         return 0;
12579 }
12580 </pre>
12581 <hr>
12582 <a name="Simple-client-example-in-C_002b_002b"></a>
12583 <div class="header">
12584 <p>
12585 Next: <a href="#Helper-functions-for-TCP-connections" accesskey="n" rel="next">Helper functions for TCP connections</a>, Previous: <a href="#Simple-client-example-with-SRP-authentication" accesskey="p" rel="prev">Simple client example with SRP authentication</a>, Up: <a href="#Client-examples" accesskey="u" rel="up">Client examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
12586 </div>
12587 <a name="Simple-client-example-using-the-C_002b_002b-API"></a>
12588 <h4 class="subsection">7.1.11 Simple client example using the C++ API</h4>
12589
12590 <p>The following client is a simple example of a client client utilizing
12591 the GnuTLS C++ API.
12592 </p>
12593 <pre class="verbatim">#include &lt;config.h&gt;
12594 #include &lt;iostream&gt;
12595 #include &lt;stdexcept&gt;
12596 #include &lt;gnutls/gnutls.h&gt;
12597 #include &lt;gnutls/gnutlsxx.h&gt;
12598 #include &lt;cstring&gt; /* for strlen */
12599
12600 /* A very basic TLS client, with anonymous authentication.
12601  * written by Eduardo Villanueva Che.
12602  */
12603
12604 #define MAX_BUF 1024
12605 #define SA struct sockaddr
12606
12607 #define CAFILE &quot;ca.pem&quot;
12608 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
12609
12610 extern &quot;C&quot;
12611 {
12612     int tcp_connect(void);
12613     void tcp_close(int sd);
12614 }
12615
12616
12617 int main(void)
12618 {
12619     int sd = -1;
12620     gnutls_global_init();
12621
12622     try
12623     {
12624
12625         /* Allow connections to servers that have OpenPGP keys as well.
12626          */
12627         gnutls::client_session session;
12628
12629         /* X509 stuff */
12630         gnutls::certificate_credentials credentials;
12631
12632
12633         /* sets the trusted cas file
12634          */
12635         credentials.set_x509_trust_file(CAFILE, GNUTLS_X509_FMT_PEM);
12636         /* put the x509 credentials to the current session
12637          */
12638         session.set_credentials(credentials);
12639
12640         /* Use default priorities */
12641         session.set_priority (&quot;NORMAL&quot;, NULL);
12642
12643         /* connect to the peer
12644          */
12645         sd = tcp_connect();
12646         session.set_transport_ptr((gnutls_transport_ptr_t) (ptrdiff_t)sd);
12647
12648         /* Perform the TLS handshake
12649          */
12650         int ret = session.handshake();
12651         if (ret &lt; 0)
12652         {
12653             throw std::runtime_error(&quot;Handshake failed&quot;);
12654         }
12655         else
12656         {
12657             std::cout &lt;&lt; &quot;- Handshake was completed&quot; &lt;&lt; std::endl;
12658         }
12659
12660         session.send(MSG, strlen(MSG));
12661         char buffer[MAX_BUF + 1];
12662         ret = session.recv(buffer, MAX_BUF);
12663         if (ret == 0)
12664         {
12665             throw std::runtime_error(&quot;Peer has closed the TLS connection&quot;);
12666         }
12667         else if (ret &lt; 0)
12668         {
12669             throw std::runtime_error(gnutls_strerror(ret));
12670         }
12671
12672         std::cout &lt;&lt; &quot;- Received &quot; &lt;&lt; ret &lt;&lt; &quot; bytes:&quot; &lt;&lt; std::endl;
12673         std::cout.write(buffer, ret);
12674         std::cout &lt;&lt; std::endl;
12675
12676         session.bye(GNUTLS_SHUT_RDWR);
12677     }
12678     catch (std::exception &amp;ex)
12679     {
12680         std::cerr &lt;&lt; &quot;Exception caught: &quot; &lt;&lt; ex.what() &lt;&lt; std::endl;
12681     }
12682
12683     if (sd != -1)
12684         tcp_close(sd);
12685
12686     gnutls_global_deinit();
12687
12688     return 0;
12689 }
12690 </pre>
12691 <hr>
12692 <a name="Helper-functions-for-TCP-connections"></a>
12693 <div class="header">
12694 <p>
12695 Next: <a href="#Helper-functions-for-UDP-connections" accesskey="n" rel="next">Helper functions for UDP connections</a>, Previous: <a href="#Simple-client-example-in-C_002b_002b" accesskey="p" rel="prev">Simple client example in C++</a>, Up: <a href="#Client-examples" accesskey="u" rel="up">Client examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
12696 </div>
12697 <a name="Helper-functions-for-TCP-connections-1"></a>
12698 <h4 class="subsection">7.1.12 Helper functions for TCP connections</h4>
12699
12700 <p>Those helper function abstract away TCP connection handling from the
12701 other examples.  It is required to build some examples.
12702 </p>
12703 <pre class="verbatim">/* This example code is placed in the public domain. */
12704
12705 #ifdef HAVE_CONFIG_H
12706 #include &lt;config.h&gt;
12707 #endif
12708
12709 #include &lt;stdio.h&gt;
12710 #include &lt;stdlib.h&gt;
12711 #include &lt;string.h&gt;
12712 #include &lt;sys/types.h&gt;
12713 #include &lt;sys/socket.h&gt;
12714 #include &lt;arpa/inet.h&gt;
12715 #include &lt;netinet/in.h&gt;
12716 #include &lt;unistd.h&gt;
12717
12718 /* tcp.c */
12719 int tcp_connect(void);
12720 void tcp_close(int sd);
12721
12722 /* Connects to the peer and returns a socket
12723  * descriptor.
12724  */
12725 extern int tcp_connect(void)
12726 {
12727         const char *PORT = &quot;5556&quot;;
12728         const char *SERVER = &quot;127.0.0.1&quot;;
12729         int err, sd;
12730         struct sockaddr_in sa;
12731
12732         /* connects to server
12733          */
12734         sd = socket(AF_INET, SOCK_STREAM, 0);
12735
12736         memset(&amp;sa, '\0', sizeof(sa));
12737         sa.sin_family = AF_INET;
12738         sa.sin_port = htons(atoi(PORT));
12739         inet_pton(AF_INET, SERVER, &amp;sa.sin_addr);
12740
12741         err = connect(sd, (struct sockaddr *) &amp;sa, sizeof(sa));
12742         if (err &lt; 0) {
12743                 fprintf(stderr, &quot;Connect error\n&quot;);
12744                 exit(1);
12745         }
12746
12747         return sd;
12748 }
12749
12750 /* closes the given socket descriptor.
12751  */
12752 extern void tcp_close(int sd)
12753 {
12754         shutdown(sd, SHUT_RDWR);        /* no more receptions */
12755         close(sd);
12756 }
12757 </pre>
12758 <hr>
12759 <a name="Helper-functions-for-UDP-connections"></a>
12760 <div class="header">
12761 <p>
12762 Previous: <a href="#Helper-functions-for-TCP-connections" accesskey="p" rel="prev">Helper functions for TCP connections</a>, Up: <a href="#Client-examples" accesskey="u" rel="up">Client examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
12763 </div>
12764 <a name="Helper-functions-for-UDP-connections-1"></a>
12765 <h4 class="subsection">7.1.13 Helper functions for UDP connections</h4>
12766
12767 <p>The UDP helper functions abstract away UDP connection handling from the
12768 other examples.  It is required to build the examples using UDP.
12769 </p>
12770 <pre class="verbatim">/* This example code is placed in the public domain. */
12771
12772 #ifdef HAVE_CONFIG_H
12773 #include &lt;config.h&gt;
12774 #endif
12775
12776 #include &lt;stdio.h&gt;
12777 #include &lt;stdlib.h&gt;
12778 #include &lt;string.h&gt;
12779 #include &lt;sys/types.h&gt;
12780 #include &lt;sys/socket.h&gt;
12781 #include &lt;arpa/inet.h&gt;
12782 #include &lt;netinet/in.h&gt;
12783 #include &lt;unistd.h&gt;
12784
12785 /* udp.c */
12786 int udp_connect(void);
12787 void udp_close(int sd);
12788
12789 /* Connects to the peer and returns a socket
12790  * descriptor.
12791  */
12792 extern int udp_connect(void)
12793 {
12794         const char *PORT = &quot;5557&quot;;
12795         const char *SERVER = &quot;127.0.0.1&quot;;
12796         int err, sd, optval;
12797         struct sockaddr_in sa;
12798
12799         /* connects to server
12800          */
12801         sd = socket(AF_INET, SOCK_DGRAM, 0);
12802
12803         memset(&amp;sa, '\0', sizeof(sa));
12804         sa.sin_family = AF_INET;
12805         sa.sin_port = htons(atoi(PORT));
12806         inet_pton(AF_INET, SERVER, &amp;sa.sin_addr);
12807
12808 #if defined(IP_DONTFRAG)
12809         optval = 1;
12810         setsockopt(sd, IPPROTO_IP, IP_DONTFRAG,
12811                    (const void *) &amp;optval, sizeof(optval));
12812 #elif defined(IP_MTU_DISCOVER)
12813         optval = IP_PMTUDISC_DO;
12814         setsockopt(sd, IPPROTO_IP, IP_MTU_DISCOVER,
12815                    (const void *) &amp;optval, sizeof(optval));
12816 #endif
12817
12818         err = connect(sd, (struct sockaddr *) &amp;sa, sizeof(sa));
12819         if (err &lt; 0) {
12820                 fprintf(stderr, &quot;Connect error\n&quot;);
12821                 exit(1);
12822         }
12823
12824         return sd;
12825 }
12826
12827 /* closes the given socket descriptor.
12828  */
12829 extern void udp_close(int sd)
12830 {
12831         close(sd);
12832 }
12833 </pre>
12834 <hr>
12835 <a name="Server-examples"></a>
12836 <div class="header">
12837 <p>
12838 Next: <a href="#OCSP-example" accesskey="n" rel="next">OCSP example</a>, Previous: <a href="#Client-examples" accesskey="p" rel="prev">Client examples</a>, Up: <a href="#GnuTLS-application-examples" accesskey="u" rel="up">GnuTLS application examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
12839 </div>
12840 <a name="Server-examples-1"></a>
12841 <h3 class="section">7.2 Server examples</h3>
12842
12843 <p>This section contains examples of <acronym>TLS</acronym> and <acronym>SSL</acronym>
12844 servers, using <acronym>GnuTLS</acronym>.
12845 </p>
12846 <table class="menu" border="0" cellspacing="0">
12847 <tr><td align="left" valign="top">&bull; <a href="#Echo-server-with-X_002e509-authentication" accesskey="1">Echo server with X.509 authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
12848 </td></tr>
12849 <tr><td align="left" valign="top">&bull; <a href="#Echo-server-with-OpenPGP-authentication" accesskey="2">Echo server with OpenPGP authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
12850 </td></tr>
12851 <tr><td align="left" valign="top">&bull; <a href="#Echo-server-with-SRP-authentication" accesskey="3">Echo server with SRP authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
12852 </td></tr>
12853 <tr><td align="left" valign="top">&bull; <a href="#Echo-server-with-anonymous-authentication" accesskey="4">Echo server with anonymous authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
12854 </td></tr>
12855 <tr><td align="left" valign="top">&bull; <a href="#DTLS-echo-server-with-X_002e509-authentication" accesskey="5">DTLS echo server with X.509 authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
12856 </td></tr>
12857 </table>
12858
12859 <hr>
12860 <a name="Echo-server-with-X_002e509-authentication"></a>
12861 <div class="header">
12862 <p>
12863 Next: <a href="#Echo-server-with-OpenPGP-authentication" accesskey="n" rel="next">Echo server with OpenPGP authentication</a>, Up: <a href="#Server-examples" accesskey="u" rel="up">Server examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
12864 </div>
12865 <a name="Echo-server-with-X_002e509-authentication-1"></a>
12866 <h4 class="subsection">7.2.1 Echo server with <acronym>X.509</acronym> authentication</h4>
12867
12868 <p>This example is a very simple echo server which supports
12869 <acronym>X.509</acronym> authentication.
12870 </p>
12871 <pre class="verbatim">/* This example code is placed in the public domain. */
12872
12873 #ifdef HAVE_CONFIG_H
12874 #include &lt;config.h&gt;
12875 #endif
12876
12877 #include &lt;stdio.h&gt;
12878 #include &lt;stdlib.h&gt;
12879 #include &lt;errno.h&gt;
12880 #include &lt;sys/types.h&gt;
12881 #include &lt;sys/socket.h&gt;
12882 #include &lt;arpa/inet.h&gt;
12883 #include &lt;netinet/in.h&gt;
12884 #include &lt;string.h&gt;
12885 #include &lt;unistd.h&gt;
12886 #include &lt;gnutls/gnutls.h&gt;
12887
12888 #define KEYFILE &quot;key.pem&quot;
12889 #define CERTFILE &quot;cert.pem&quot;
12890 #define CAFILE &quot;/etc/ssl/certs/ca-certificates.crt&quot;
12891 #define CRLFILE &quot;crl.pem&quot;
12892
12893 /* The OCSP status file contains up to date information about revocation
12894  * of the server's certificate. That can be periodically be updated
12895  * using:
12896  * $ ocsptool --ask --load-cert your_cert.pem --load-issuer your_issuer.pem
12897  *            --load-signer your_issuer.pem --outfile ocsp-status.der
12898  */
12899 #define OCSP_STATUS_FILE &quot;ocsp-status.der&quot;
12900
12901 /* This is a sample TLS 1.0 echo server, using X.509 authentication and
12902  * OCSP stapling support.
12903  */
12904
12905 #define MAX_BUF 1024
12906 #define PORT 5556               /* listen to 5556 port */
12907
12908 /* These are global */
12909 static gnutls_dh_params_t dh_params;
12910
12911 static int generate_dh_params(void)
12912 {
12913         unsigned int bits = gnutls_sec_param_to_pk_bits(GNUTLS_PK_DH,
12914                                                         GNUTLS_SEC_PARAM_LEGACY);
12915
12916         /* Generate Diffie-Hellman parameters - for use with DHE
12917          * kx algorithms. When short bit length is used, it might
12918          * be wise to regenerate parameters often.
12919          */
12920         gnutls_dh_params_init(&amp;dh_params);
12921         gnutls_dh_params_generate2(dh_params, bits);
12922
12923         return 0;
12924 }
12925
12926 int main(void)
12927 {
12928         int listen_sd;
12929         int sd, ret;
12930         gnutls_certificate_credentials_t x509_cred;
12931         gnutls_priority_t priority_cache;
12932         struct sockaddr_in sa_serv;
12933         struct sockaddr_in sa_cli;
12934         socklen_t client_len;
12935         char topbuf[512];
12936         gnutls_session_t session;
12937         char buffer[MAX_BUF + 1];
12938         int optval = 1;
12939
12940         /* for backwards compatibility with gnutls &lt; 3.3.0 */
12941         gnutls_global_init();
12942
12943         gnutls_certificate_allocate_credentials(&amp;x509_cred);
12944         /* gnutls_certificate_set_x509_system_trust(xcred); */
12945         gnutls_certificate_set_x509_trust_file(x509_cred, CAFILE,
12946                                                GNUTLS_X509_FMT_PEM);
12947
12948         gnutls_certificate_set_x509_crl_file(x509_cred, CRLFILE,
12949                                              GNUTLS_X509_FMT_PEM);
12950
12951         ret =
12952             gnutls_certificate_set_x509_key_file(x509_cred, CERTFILE,
12953                                                  KEYFILE,
12954                                                  GNUTLS_X509_FMT_PEM);
12955         if (ret &lt; 0) {
12956                 printf(&quot;No certificate or key were found\n&quot;);
12957                 exit(1);
12958         }
12959
12960         /* loads an OCSP status request if available */
12961         gnutls_certificate_set_ocsp_status_request_file(x509_cred,
12962                                                         OCSP_STATUS_FILE,
12963                                                         0);
12964
12965         generate_dh_params();
12966
12967         gnutls_priority_init(&amp;priority_cache,
12968                              &quot;PERFORMANCE:%SERVER_PRECEDENCE&quot;, NULL);
12969
12970
12971         gnutls_certificate_set_dh_params(x509_cred, dh_params);
12972
12973         /* Socket operations
12974          */
12975         listen_sd = socket(AF_INET, SOCK_STREAM, 0);
12976
12977         memset(&amp;sa_serv, '\0', sizeof(sa_serv));
12978         sa_serv.sin_family = AF_INET;
12979         sa_serv.sin_addr.s_addr = INADDR_ANY;
12980         sa_serv.sin_port = htons(PORT); /* Server Port number */
12981
12982         setsockopt(listen_sd, SOL_SOCKET, SO_REUSEADDR, (void *) &amp;optval,
12983                    sizeof(int));
12984
12985         bind(listen_sd, (struct sockaddr *) &amp;sa_serv, sizeof(sa_serv));
12986
12987         listen(listen_sd, 1024);
12988
12989         printf(&quot;Server ready. Listening to port '%d'.\n\n&quot;, PORT);
12990
12991         client_len = sizeof(sa_cli);
12992         for (;;) {
12993                 gnutls_init(&amp;session, GNUTLS_SERVER);
12994                 gnutls_priority_set(session, priority_cache);
12995                 gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE,
12996                                        x509_cred);
12997
12998                 /* We don't request any certificate from the client.
12999                  * If we did we would need to verify it. One way of
13000                  * doing that is shown in the &quot;Verifying a certificate&quot;
13001                  * example.
13002                  */
13003                 gnutls_certificate_server_set_request(session,
13004                                                       GNUTLS_CERT_IGNORE);
13005
13006                 sd = accept(listen_sd, (struct sockaddr *) &amp;sa_cli,
13007                             &amp;client_len);
13008
13009                 printf(&quot;- connection from %s, port %d\n&quot;,
13010                        inet_ntop(AF_INET, &amp;sa_cli.sin_addr, topbuf,
13011                                  sizeof(topbuf)), ntohs(sa_cli.sin_port));
13012
13013                 gnutls_transport_set_int(session, sd);
13014
13015                 do {
13016                         ret = gnutls_handshake(session);
13017                 }
13018                 while (ret &lt; 0 &amp;&amp; gnutls_error_is_fatal(ret) == 0);
13019
13020                 if (ret &lt; 0) {
13021                         close(sd);
13022                         gnutls_deinit(session);
13023                         fprintf(stderr,
13024                                 &quot;*** Handshake has failed (%s)\n\n&quot;,
13025                                 gnutls_strerror(ret));
13026                         continue;
13027                 }
13028                 printf(&quot;- Handshake was completed\n&quot;);
13029
13030                 /* see the Getting peer's information example */
13031                 /* print_info(session); */
13032
13033                 for (;;) {
13034                         ret = gnutls_record_recv(session, buffer, MAX_BUF);
13035
13036                         if (ret == 0) {
13037                                 printf
13038                                     (&quot;\n- Peer has closed the GnuTLS connection\n&quot;);
13039                                 break;
13040                         } else if (ret &lt; 0
13041                                    &amp;&amp; gnutls_error_is_fatal(ret) == 0) {
13042                                 fprintf(stderr, &quot;*** Warning: %s\n&quot;,
13043                                         gnutls_strerror(ret));
13044                         } else if (ret &lt; 0) {
13045                                 fprintf(stderr, &quot;\n*** Received corrupted &quot;
13046                                         &quot;data(%d). Closing the connection.\n\n&quot;,
13047                                         ret);
13048                                 break;
13049                         } else if (ret &gt; 0) {
13050                                 /* echo data back to the client
13051                                  */
13052                                 gnutls_record_send(session, buffer, ret);
13053                         }
13054                 }
13055                 printf(&quot;\n&quot;);
13056                 /* do not wait for the peer to close the connection.
13057                  */
13058                 gnutls_bye(session, GNUTLS_SHUT_WR);
13059
13060                 close(sd);
13061                 gnutls_deinit(session);
13062
13063         }
13064         close(listen_sd);
13065
13066         gnutls_certificate_free_credentials(x509_cred);
13067         gnutls_priority_deinit(priority_cache);
13068
13069         gnutls_global_deinit();
13070
13071         return 0;
13072
13073 }
13074 </pre>
13075 <hr>
13076 <a name="Echo-server-with-OpenPGP-authentication"></a>
13077 <div class="header">
13078 <p>
13079 Next: <a href="#Echo-server-with-SRP-authentication" accesskey="n" rel="next">Echo server with SRP authentication</a>, Previous: <a href="#Echo-server-with-X_002e509-authentication" accesskey="p" rel="prev">Echo server with X.509 authentication</a>, Up: <a href="#Server-examples" accesskey="u" rel="up">Server examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
13080 </div>
13081 <a name="Echo-server-with-OpenPGP-authentication-1"></a>
13082 <h4 class="subsection">7.2.2 Echo server with <acronym>OpenPGP</acronym> authentication</h4>
13083 <a name="index-OpenPGP-server"></a>
13084
13085 <p>The following example is an echo server which supports
13086 <acronym>OpenPGP</acronym> key authentication. You can easily combine
13087 this functionality &mdash;that is have a server that supports both
13088 <acronym>X.509</acronym> and <acronym>OpenPGP</acronym> certificates&mdash; but we separated
13089 them to keep these examples as simple as possible.
13090 </p>
13091 <pre class="verbatim">/* This example code is placed in the public domain. */
13092
13093 #ifdef HAVE_CONFIG_H
13094 #include &lt;config.h&gt;
13095 #endif
13096
13097 #include &lt;stdio.h&gt;
13098 #include &lt;stdlib.h&gt;
13099 #include &lt;errno.h&gt;
13100 #include &lt;sys/types.h&gt;
13101 #include &lt;sys/socket.h&gt;
13102 #include &lt;arpa/inet.h&gt;
13103 #include &lt;netinet/in.h&gt;
13104 #include &lt;string.h&gt;
13105 #include &lt;unistd.h&gt;
13106 #include &lt;gnutls/gnutls.h&gt;
13107 #include &lt;gnutls/openpgp.h&gt;
13108
13109 #define KEYFILE &quot;secret.asc&quot;
13110 #define CERTFILE &quot;public.asc&quot;
13111 #define RINGFILE &quot;ring.gpg&quot;
13112
13113 /* This is a sample TLS 1.0-OpenPGP echo server.
13114  */
13115
13116
13117 #define SOCKET_ERR(err,s) if(err==-1) {perror(s);return(1);}
13118 #define MAX_BUF 1024
13119 #define PORT 5556               /* listen to 5556 port */
13120
13121 /* These are global */
13122 gnutls_dh_params_t dh_params;
13123
13124 static int generate_dh_params(void)
13125 {
13126         unsigned int bits = gnutls_sec_param_to_pk_bits(GNUTLS_PK_DH,
13127                                                         GNUTLS_SEC_PARAM_LEGACY);
13128
13129         /* Generate Diffie-Hellman parameters - for use with DHE
13130          * kx algorithms. These should be discarded and regenerated
13131          * once a day, once a week or once a month. Depending on the
13132          * security requirements.
13133          */
13134         gnutls_dh_params_init(&amp;dh_params);
13135         gnutls_dh_params_generate2(dh_params, bits);
13136
13137         return 0;
13138 }
13139
13140 int main(void)
13141 {
13142         int err, listen_sd;
13143         int sd, ret;
13144         struct sockaddr_in sa_serv;
13145         struct sockaddr_in sa_cli;
13146         socklen_t client_len;
13147         char topbuf[512];
13148         gnutls_session_t session;
13149         gnutls_certificate_credentials_t cred;
13150         char buffer[MAX_BUF + 1];
13151         int optval = 1;
13152         char name[256];
13153
13154         strcpy(name, &quot;Echo Server&quot;);
13155
13156         if (gnutls_check_version(&quot;3.1.4&quot;) == NULL) {
13157                 fprintf(stderr, &quot;GnuTLS 3.1.4 or later is required for this example\n&quot;);
13158                 exit(1);
13159         }
13160
13161         /* for backwards compatibility with gnutls &lt; 3.3.0 */
13162         gnutls_global_init();
13163
13164         gnutls_certificate_allocate_credentials(&amp;cred);
13165         gnutls_certificate_set_openpgp_keyring_file(cred, RINGFILE,
13166                                                     GNUTLS_OPENPGP_FMT_BASE64);
13167
13168         gnutls_certificate_set_openpgp_key_file(cred, CERTFILE, KEYFILE,
13169                                                 GNUTLS_OPENPGP_FMT_BASE64);
13170
13171         generate_dh_params();
13172
13173         gnutls_certificate_set_dh_params(cred, dh_params);
13174
13175         /* Socket operations
13176          */
13177         listen_sd = socket(AF_INET, SOCK_STREAM, 0);
13178         SOCKET_ERR(listen_sd, &quot;socket&quot;);
13179
13180         memset(&amp;sa_serv, '\0', sizeof(sa_serv));
13181         sa_serv.sin_family = AF_INET;
13182         sa_serv.sin_addr.s_addr = INADDR_ANY;
13183         sa_serv.sin_port = htons(PORT); /* Server Port number */
13184
13185         setsockopt(listen_sd, SOL_SOCKET, SO_REUSEADDR, (void *) &amp;optval,
13186                    sizeof(int));
13187
13188         err =
13189             bind(listen_sd, (struct sockaddr *) &amp;sa_serv, sizeof(sa_serv));
13190         SOCKET_ERR(err, &quot;bind&quot;);
13191         err = listen(listen_sd, 1024);
13192         SOCKET_ERR(err, &quot;listen&quot;);
13193
13194         printf(&quot;%s ready. Listening to port '%d'.\n\n&quot;, name, PORT);
13195
13196         client_len = sizeof(sa_cli);
13197         for (;;) {
13198                 gnutls_init(&amp;session, GNUTLS_SERVER);
13199                 gnutls_priority_set_direct(session,
13200                                            &quot;NORMAL:+CTYPE-OPENPGP&quot;, NULL);
13201
13202                 /* request client certificate if any.
13203                  */
13204                 gnutls_certificate_server_set_request(session,
13205                                                       GNUTLS_CERT_REQUEST);
13206
13207                 sd = accept(listen_sd, (struct sockaddr *) &amp;sa_cli,
13208                             &amp;client_len);
13209
13210                 printf(&quot;- connection from %s, port %d\n&quot;,
13211                        inet_ntop(AF_INET, &amp;sa_cli.sin_addr, topbuf,
13212                                  sizeof(topbuf)), ntohs(sa_cli.sin_port));
13213
13214                 gnutls_transport_set_int(session, sd);
13215                 ret = gnutls_handshake(session);
13216                 if (ret &lt; 0) {
13217                         close(sd);
13218                         gnutls_deinit(session);
13219                         fprintf(stderr,
13220                                 &quot;*** Handshake has failed (%s)\n\n&quot;,
13221                                 gnutls_strerror(ret));
13222                         continue;
13223                 }
13224                 printf(&quot;- Handshake was completed\n&quot;);
13225
13226                 /* see the Getting peer's information example */
13227                 /* print_info(session); */
13228
13229                 for (;;) {
13230                         ret = gnutls_record_recv(session, buffer, MAX_BUF);
13231
13232                         if (ret == 0) {
13233                                 printf
13234                                     (&quot;\n- Peer has closed the GnuTLS connection\n&quot;);
13235                                 break;
13236                         } else if (ret &lt; 0
13237                                    &amp;&amp; gnutls_error_is_fatal(ret) == 0) {
13238                                 fprintf(stderr, &quot;*** Warning: %s\n&quot;,
13239                                         gnutls_strerror(ret));
13240                         } else if (ret &lt; 0) {
13241                                 fprintf(stderr, &quot;\n*** Received corrupted &quot;
13242                                         &quot;data(%d). Closing the connection.\n\n&quot;,
13243                                         ret);
13244                                 break;
13245                         } else if (ret &gt; 0) {
13246                                 /* echo data back to the client
13247                                  */
13248                                 gnutls_record_send(session, buffer, ret);
13249                         }
13250                 }
13251                 printf(&quot;\n&quot;);
13252                 /* do not wait for the peer to close the connection.
13253                  */
13254                 gnutls_bye(session, GNUTLS_SHUT_WR);
13255
13256                 close(sd);
13257                 gnutls_deinit(session);
13258
13259         }
13260         close(listen_sd);
13261
13262         gnutls_certificate_free_credentials(cred);
13263
13264         gnutls_global_deinit();
13265
13266         return 0;
13267
13268 }
13269 </pre>
13270 <hr>
13271 <a name="Echo-server-with-SRP-authentication"></a>
13272 <div class="header">
13273 <p>
13274 Next: <a href="#Echo-server-with-anonymous-authentication" accesskey="n" rel="next">Echo server with anonymous authentication</a>, Previous: <a href="#Echo-server-with-OpenPGP-authentication" accesskey="p" rel="prev">Echo server with OpenPGP authentication</a>, Up: <a href="#Server-examples" accesskey="u" rel="up">Server examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
13275 </div>
13276 <a name="Echo-server-with-SRP-authentication-1"></a>
13277 <h4 class="subsection">7.2.3 Echo server with <acronym>SRP</acronym> authentication</h4>
13278
13279 <p>This is a server which supports <acronym>SRP</acronym> authentication. It is
13280 also possible to combine this functionality with a certificate
13281 server. Here it is separate for simplicity.
13282 </p>
13283 <pre class="verbatim">/* This example code is placed in the public domain. */
13284
13285 #ifdef HAVE_CONFIG_H
13286 #include &lt;config.h&gt;
13287 #endif
13288
13289 #include &lt;stdio.h&gt;
13290 #include &lt;stdlib.h&gt;
13291 #include &lt;errno.h&gt;
13292 #include &lt;sys/types.h&gt;
13293 #include &lt;sys/socket.h&gt;
13294 #include &lt;arpa/inet.h&gt;
13295 #include &lt;netinet/in.h&gt;
13296 #include &lt;string.h&gt;
13297 #include &lt;unistd.h&gt;
13298 #include &lt;gnutls/gnutls.h&gt;
13299
13300 #define SRP_PASSWD &quot;tpasswd&quot;
13301 #define SRP_PASSWD_CONF &quot;tpasswd.conf&quot;
13302
13303 #define KEYFILE &quot;key.pem&quot;
13304 #define CERTFILE &quot;cert.pem&quot;
13305 #define CAFILE &quot;/etc/ssl/certs/ca-certificates.crt&quot;
13306
13307 /* This is a sample TLS-SRP echo server.
13308  */
13309
13310 #define SOCKET_ERR(err,s) if(err==-1) {perror(s);return(1);}
13311 #define MAX_BUF 1024
13312 #define PORT 5556               /* listen to 5556 port */
13313
13314 int main(void)
13315 {
13316         int err, listen_sd;
13317         int sd, ret;
13318         struct sockaddr_in sa_serv;
13319         struct sockaddr_in sa_cli;
13320         socklen_t client_len;
13321         char topbuf[512];
13322         gnutls_session_t session;
13323         gnutls_srp_server_credentials_t srp_cred;
13324         gnutls_certificate_credentials_t cert_cred;
13325         char buffer[MAX_BUF + 1];
13326         int optval = 1;
13327         char name[256];
13328
13329         strcpy(name, &quot;Echo Server&quot;);
13330
13331         if (gnutls_check_version(&quot;3.1.4&quot;) == NULL) {
13332                 fprintf(stderr, &quot;GnuTLS 3.1.4 or later is required for this example\n&quot;);
13333                 exit(1);
13334         }
13335
13336         /* for backwards compatibility with gnutls &lt; 3.3.0 */
13337         gnutls_global_init();
13338
13339         /* SRP_PASSWD a password file (created with the included srptool utility)
13340          */
13341         gnutls_srp_allocate_server_credentials(&amp;srp_cred);
13342         gnutls_srp_set_server_credentials_file(srp_cred, SRP_PASSWD,
13343                                                SRP_PASSWD_CONF);
13344
13345         gnutls_certificate_allocate_credentials(&amp;cert_cred);
13346         gnutls_certificate_set_x509_trust_file(cert_cred, CAFILE,
13347                                                GNUTLS_X509_FMT_PEM);
13348         gnutls_certificate_set_x509_key_file(cert_cred, CERTFILE, KEYFILE,
13349                                              GNUTLS_X509_FMT_PEM);
13350
13351         /* TCP socket operations
13352          */
13353         listen_sd = socket(AF_INET, SOCK_STREAM, 0);
13354         SOCKET_ERR(listen_sd, &quot;socket&quot;);
13355
13356         memset(&amp;sa_serv, '\0', sizeof(sa_serv));
13357         sa_serv.sin_family = AF_INET;
13358         sa_serv.sin_addr.s_addr = INADDR_ANY;
13359         sa_serv.sin_port = htons(PORT); /* Server Port number */
13360
13361         setsockopt(listen_sd, SOL_SOCKET, SO_REUSEADDR, (void *) &amp;optval,
13362                    sizeof(int));
13363
13364         err =
13365             bind(listen_sd, (struct sockaddr *) &amp;sa_serv, sizeof(sa_serv));
13366         SOCKET_ERR(err, &quot;bind&quot;);
13367         err = listen(listen_sd, 1024);
13368         SOCKET_ERR(err, &quot;listen&quot;);
13369
13370         printf(&quot;%s ready. Listening to port '%d'.\n\n&quot;, name, PORT);
13371
13372         client_len = sizeof(sa_cli);
13373         for (;;) {
13374                 gnutls_init(&amp;session, GNUTLS_SERVER);
13375                 gnutls_priority_set_direct(session,
13376                                            &quot;NORMAL&quot;
13377                                            &quot;:-KX-ALL:+SRP:+SRP-DSS:+SRP-RSA&quot;,
13378                                            NULL);
13379                 gnutls_credentials_set(session, GNUTLS_CRD_SRP, srp_cred);
13380                 /* for the certificate authenticated ciphersuites.
13381                  */
13382                 gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE,
13383                                        cert_cred);
13384
13385                 /* We don't request any certificate from the client.
13386                  * If we did we would need to verify it. One way of
13387                  * doing that is shown in the &quot;Verifying a certificate&quot;
13388                  * example.
13389                  */
13390                 gnutls_certificate_server_set_request(session,
13391                                                       GNUTLS_CERT_IGNORE);
13392
13393                 sd = accept(listen_sd, (struct sockaddr *) &amp;sa_cli,
13394                             &amp;client_len);
13395
13396                 printf(&quot;- connection from %s, port %d\n&quot;,
13397                        inet_ntop(AF_INET, &amp;sa_cli.sin_addr, topbuf,
13398                                  sizeof(topbuf)), ntohs(sa_cli.sin_port));
13399
13400                 gnutls_transport_set_int(session, sd);
13401
13402                 do {
13403                         ret = gnutls_handshake(session);
13404                 }
13405                 while (ret &lt; 0 &amp;&amp; gnutls_error_is_fatal(ret) == 0);
13406
13407                 if (ret &lt; 0) {
13408                         close(sd);
13409                         gnutls_deinit(session);
13410                         fprintf(stderr,
13411                                 &quot;*** Handshake has failed (%s)\n\n&quot;,
13412                                 gnutls_strerror(ret));
13413                         continue;
13414                 }
13415                 printf(&quot;- Handshake was completed\n&quot;);
13416                 printf(&quot;- User %s was connected\n&quot;,
13417                        gnutls_srp_server_get_username(session));
13418
13419                 /* print_info(session); */
13420
13421                 for (;;) {
13422                         ret = gnutls_record_recv(session, buffer, MAX_BUF);
13423
13424                         if (ret == 0) {
13425                                 printf
13426                                     (&quot;\n- Peer has closed the GnuTLS connection\n&quot;);
13427                                 break;
13428                         } else if (ret &lt; 0
13429                                    &amp;&amp; gnutls_error_is_fatal(ret) == 0) {
13430                                 fprintf(stderr, &quot;*** Warning: %s\n&quot;,
13431                                         gnutls_strerror(ret));
13432                         } else if (ret &lt; 0) {
13433                                 fprintf(stderr, &quot;\n*** Received corrupted &quot;
13434                                         &quot;data(%d). Closing the connection.\n\n&quot;,
13435                                         ret);
13436                                 break;
13437                         } else if (ret &gt; 0) {
13438                                 /* echo data back to the client
13439                                  */
13440                                 gnutls_record_send(session, buffer, ret);
13441                         }
13442                 }
13443                 printf(&quot;\n&quot;);
13444                 /* do not wait for the peer to close the connection. */
13445                 gnutls_bye(session, GNUTLS_SHUT_WR);
13446
13447                 close(sd);
13448                 gnutls_deinit(session);
13449
13450         }
13451         close(listen_sd);
13452
13453         gnutls_srp_free_server_credentials(srp_cred);
13454         gnutls_certificate_free_credentials(cert_cred);
13455
13456         gnutls_global_deinit();
13457
13458         return 0;
13459
13460 }
13461 </pre>
13462 <hr>
13463 <a name="Echo-server-with-anonymous-authentication"></a>
13464 <div class="header">
13465 <p>
13466 Next: <a href="#DTLS-echo-server-with-X_002e509-authentication" accesskey="n" rel="next">DTLS echo server with X.509 authentication</a>, Previous: <a href="#Echo-server-with-SRP-authentication" accesskey="p" rel="prev">Echo server with SRP authentication</a>, Up: <a href="#Server-examples" accesskey="u" rel="up">Server examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
13467 </div>
13468 <a name="Echo-server-with-anonymous-authentication-1"></a>
13469 <h4 class="subsection">7.2.4 Echo server with anonymous authentication</h4>
13470
13471 <p>This example server supports anonymous authentication, and could be
13472 used to serve the example client for anonymous authentication.
13473 </p>
13474 <pre class="verbatim">/* This example code is placed in the public domain. */
13475
13476 #ifdef HAVE_CONFIG_H
13477 #include &lt;config.h&gt;
13478 #endif
13479
13480 #include &lt;stdio.h&gt;
13481 #include &lt;stdlib.h&gt;
13482 #include &lt;errno.h&gt;
13483 #include &lt;sys/types.h&gt;
13484 #include &lt;sys/socket.h&gt;
13485 #include &lt;arpa/inet.h&gt;
13486 #include &lt;netinet/in.h&gt;
13487 #include &lt;string.h&gt;
13488 #include &lt;unistd.h&gt;
13489 #include &lt;gnutls/gnutls.h&gt;
13490
13491 /* This is a sample TLS 1.0 echo server, for anonymous authentication only.
13492  */
13493
13494
13495 #define SOCKET_ERR(err,s) if(err==-1) {perror(s);return(1);}
13496 #define MAX_BUF 1024
13497 #define PORT 5556               /* listen to 5556 port */
13498
13499 /* These are global */
13500 static gnutls_dh_params_t dh_params;
13501
13502 static int generate_dh_params(void)
13503 {
13504         unsigned int bits = gnutls_sec_param_to_pk_bits(GNUTLS_PK_DH,
13505                                                         GNUTLS_SEC_PARAM_LEGACY);
13506         /* Generate Diffie-Hellman parameters - for use with DHE
13507          * kx algorithms. These should be discarded and regenerated
13508          * once a day, once a week or once a month. Depending on the
13509          * security requirements.
13510          */
13511         gnutls_dh_params_init(&amp;dh_params);
13512         gnutls_dh_params_generate2(dh_params, bits);
13513
13514         return 0;
13515 }
13516
13517 int main(void)
13518 {
13519         int err, listen_sd;
13520         int sd, ret;
13521         struct sockaddr_in sa_serv;
13522         struct sockaddr_in sa_cli;
13523         socklen_t client_len;
13524         char topbuf[512];
13525         gnutls_session_t session;
13526         gnutls_anon_server_credentials_t anoncred;
13527         char buffer[MAX_BUF + 1];
13528         int optval = 1;
13529
13530         if (gnutls_check_version(&quot;3.1.4&quot;) == NULL) {
13531                 fprintf(stderr, &quot;GnuTLS 3.1.4 or later is required for this example\n&quot;);
13532                 exit(1);
13533         }
13534
13535         /* for backwards compatibility with gnutls &lt; 3.3.0 */
13536         gnutls_global_init();
13537
13538         gnutls_anon_allocate_server_credentials(&amp;anoncred);
13539
13540         generate_dh_params();
13541
13542         gnutls_anon_set_server_dh_params(anoncred, dh_params);
13543
13544         /* Socket operations
13545          */
13546         listen_sd = socket(AF_INET, SOCK_STREAM, 0);
13547         SOCKET_ERR(listen_sd, &quot;socket&quot;);
13548
13549         memset(&amp;sa_serv, '\0', sizeof(sa_serv));
13550         sa_serv.sin_family = AF_INET;
13551         sa_serv.sin_addr.s_addr = INADDR_ANY;
13552         sa_serv.sin_port = htons(PORT); /* Server Port number */
13553
13554         setsockopt(listen_sd, SOL_SOCKET, SO_REUSEADDR, (void *) &amp;optval,
13555                    sizeof(int));
13556
13557         err =
13558             bind(listen_sd, (struct sockaddr *) &amp;sa_serv, sizeof(sa_serv));
13559         SOCKET_ERR(err, &quot;bind&quot;);
13560         err = listen(listen_sd, 1024);
13561         SOCKET_ERR(err, &quot;listen&quot;);
13562
13563         printf(&quot;Server ready. Listening to port '%d'.\n\n&quot;, PORT);
13564
13565         client_len = sizeof(sa_cli);
13566         for (;;) {
13567                 gnutls_init(&amp;session, GNUTLS_SERVER);
13568                 gnutls_priority_set_direct(session,
13569                                            &quot;NORMAL::+ANON-ECDH:+ANON-DH&quot;,
13570                                            NULL);
13571                 gnutls_credentials_set(session, GNUTLS_CRD_ANON, anoncred);
13572
13573                 sd = accept(listen_sd, (struct sockaddr *) &amp;sa_cli,
13574                             &amp;client_len);
13575
13576                 printf(&quot;- connection from %s, port %d\n&quot;,
13577                        inet_ntop(AF_INET, &amp;sa_cli.sin_addr, topbuf,
13578                                  sizeof(topbuf)), ntohs(sa_cli.sin_port));
13579
13580                 gnutls_transport_set_int(session, sd);
13581
13582                 do {
13583                         ret = gnutls_handshake(session);
13584                 }
13585                 while (ret &lt; 0 &amp;&amp; gnutls_error_is_fatal(ret) == 0);
13586
13587                 if (ret &lt; 0) {
13588                         close(sd);
13589                         gnutls_deinit(session);
13590                         fprintf(stderr,
13591                                 &quot;*** Handshake has failed (%s)\n\n&quot;,
13592                                 gnutls_strerror(ret));
13593                         continue;
13594                 }
13595                 printf(&quot;- Handshake was completed\n&quot;);
13596
13597                 /* see the Getting peer's information example */
13598                 /* print_info(session); */
13599
13600                 for (;;) {
13601                         ret = gnutls_record_recv(session, buffer, MAX_BUF);
13602
13603                         if (ret == 0) {
13604                                 printf
13605                                     (&quot;\n- Peer has closed the GnuTLS connection\n&quot;);
13606                                 break;
13607                         } else if (ret &lt; 0
13608                                    &amp;&amp; gnutls_error_is_fatal(ret) == 0) {
13609                                 fprintf(stderr, &quot;*** Warning: %s\n&quot;,
13610                                         gnutls_strerror(ret));
13611                         } else if (ret &lt; 0) {
13612                                 fprintf(stderr, &quot;\n*** Received corrupted &quot;
13613                                         &quot;data(%d). Closing the connection.\n\n&quot;,
13614                                         ret);
13615                                 break;
13616                         } else if (ret &gt; 0) {
13617                                 /* echo data back to the client
13618                                  */
13619                                 gnutls_record_send(session, buffer, ret);
13620                         }
13621                 }
13622                 printf(&quot;\n&quot;);
13623                 /* do not wait for the peer to close the connection.
13624                  */
13625                 gnutls_bye(session, GNUTLS_SHUT_WR);
13626
13627                 close(sd);
13628                 gnutls_deinit(session);
13629
13630         }
13631         close(listen_sd);
13632
13633         gnutls_anon_free_server_credentials(anoncred);
13634
13635         gnutls_global_deinit();
13636
13637         return 0;
13638
13639 }
13640 </pre>
13641 <hr>
13642 <a name="DTLS-echo-server-with-X_002e509-authentication"></a>
13643 <div class="header">
13644 <p>
13645 Previous: <a href="#Echo-server-with-anonymous-authentication" accesskey="p" rel="prev">Echo server with anonymous authentication</a>, Up: <a href="#Server-examples" accesskey="u" rel="up">Server examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
13646 </div>
13647 <a name="DTLS-echo-server-with-X_002e509-authentication-1"></a>
13648 <h4 class="subsection">7.2.5 DTLS echo server with <acronym>X.509</acronym> authentication</h4>
13649
13650 <p>This example is a very simple echo server using Datagram TLS and
13651 <acronym>X.509</acronym> authentication.
13652 </p>
13653 <pre class="verbatim">/* This example code is placed in the public domain. */
13654
13655 #ifdef HAVE_CONFIG_H
13656 #include &lt;config.h&gt;
13657 #endif
13658
13659 #include &lt;stdio.h&gt;
13660 #include &lt;stdlib.h&gt;
13661 #include &lt;errno.h&gt;
13662 #include &lt;sys/types.h&gt;
13663 #include &lt;sys/socket.h&gt;
13664 #include &lt;arpa/inet.h&gt;
13665 #include &lt;netinet/in.h&gt;
13666 #include &lt;sys/select.h&gt;
13667 #include &lt;netdb.h&gt;
13668 #include &lt;string.h&gt;
13669 #include &lt;unistd.h&gt;
13670 #include &lt;gnutls/gnutls.h&gt;
13671 #include &lt;gnutls/dtls.h&gt;
13672
13673 #define KEYFILE &quot;key.pem&quot;
13674 #define CERTFILE &quot;cert.pem&quot;
13675 #define CAFILE &quot;/etc/ssl/certs/ca-certificates.crt&quot;
13676 #define CRLFILE &quot;crl.pem&quot;
13677
13678 /* This is a sample DTLS echo server, using X.509 authentication.
13679  * Note that error checking is minimal to simplify the example.
13680  */
13681
13682 #define MAX_BUFFER 1024
13683 #define PORT 5557
13684
13685 typedef struct {
13686         gnutls_session_t session;
13687         int fd;
13688         struct sockaddr *cli_addr;
13689         socklen_t cli_addr_size;
13690 } priv_data_st;
13691
13692 static int pull_timeout_func(gnutls_transport_ptr_t ptr, unsigned int ms);
13693 static ssize_t push_func(gnutls_transport_ptr_t p, const void *data,
13694                          size_t size);
13695 static ssize_t pull_func(gnutls_transport_ptr_t p, void *data,
13696                          size_t size);
13697 static const char *human_addr(const struct sockaddr *sa, socklen_t salen,
13698                               char *buf, size_t buflen);
13699 static int wait_for_connection(int fd);
13700 static int generate_dh_params(void);
13701
13702 /* Use global credentials and parameters to simplify
13703  * the example. */
13704 static gnutls_certificate_credentials_t x509_cred;
13705 static gnutls_priority_t priority_cache;
13706 static gnutls_dh_params_t dh_params;
13707
13708 int main(void)
13709 {
13710         int listen_sd;
13711         int sock, ret;
13712         struct sockaddr_in sa_serv;
13713         struct sockaddr_in cli_addr;
13714         socklen_t cli_addr_size;
13715         gnutls_session_t session;
13716         char buffer[MAX_BUFFER];
13717         priv_data_st priv;
13718         gnutls_datum_t cookie_key;
13719         gnutls_dtls_prestate_st prestate;
13720         int mtu = 1400;
13721         unsigned char sequence[8];
13722
13723         /* this must be called once in the program
13724          */
13725         gnutls_global_init();
13726
13727         gnutls_certificate_allocate_credentials(&amp;x509_cred);
13728         gnutls_certificate_set_x509_trust_file(x509_cred, CAFILE,
13729                                                GNUTLS_X509_FMT_PEM);
13730
13731         gnutls_certificate_set_x509_crl_file(x509_cred, CRLFILE,
13732                                              GNUTLS_X509_FMT_PEM);
13733
13734         ret =
13735             gnutls_certificate_set_x509_key_file(x509_cred, CERTFILE,
13736                                                  KEYFILE,
13737                                                  GNUTLS_X509_FMT_PEM);
13738         if (ret &lt; 0) {
13739                 printf(&quot;No certificate or key were found\n&quot;);
13740                 exit(1);
13741         }
13742
13743         generate_dh_params();
13744
13745         gnutls_certificate_set_dh_params(x509_cred, dh_params);
13746
13747         gnutls_priority_init(&amp;priority_cache,
13748                              &quot;PERFORMANCE:-VERS-TLS-ALL:+VERS-DTLS1.0:%SERVER_PRECEDENCE&quot;,
13749                              NULL);
13750
13751         gnutls_key_generate(&amp;cookie_key, GNUTLS_COOKIE_KEY_SIZE);
13752
13753         /* Socket operations
13754          */
13755         listen_sd = socket(AF_INET, SOCK_DGRAM, 0);
13756
13757         memset(&amp;sa_serv, '\0', sizeof(sa_serv));
13758         sa_serv.sin_family = AF_INET;
13759         sa_serv.sin_addr.s_addr = INADDR_ANY;
13760         sa_serv.sin_port = htons(PORT);
13761
13762         {                       /* DTLS requires the IP don't fragment (DF) bit to be set */
13763 #if defined(IP_DONTFRAG)
13764                 int optval = 1;
13765                 setsockopt(listen_sd, IPPROTO_IP, IP_DONTFRAG,
13766                            (const void *) &amp;optval, sizeof(optval));
13767 #elif defined(IP_MTU_DISCOVER)
13768                 int optval = IP_PMTUDISC_DO;
13769                 setsockopt(listen_sd, IPPROTO_IP, IP_MTU_DISCOVER,
13770                            (const void *) &amp;optval, sizeof(optval));
13771 #endif
13772         }
13773
13774         bind(listen_sd, (struct sockaddr *) &amp;sa_serv, sizeof(sa_serv));
13775
13776         printf(&quot;UDP server ready. Listening to port '%d'.\n\n&quot;, PORT);
13777
13778         for (;;) {
13779                 printf(&quot;Waiting for connection...\n&quot;);
13780                 sock = wait_for_connection(listen_sd);
13781                 if (sock &lt; 0)
13782                         continue;
13783
13784                 cli_addr_size = sizeof(cli_addr);
13785                 ret = recvfrom(sock, buffer, sizeof(buffer), MSG_PEEK,
13786                                (struct sockaddr *) &amp;cli_addr,
13787                                &amp;cli_addr_size);
13788                 if (ret &gt; 0) {
13789                         memset(&amp;prestate, 0, sizeof(prestate));
13790                         ret =
13791                             gnutls_dtls_cookie_verify(&amp;cookie_key,
13792                                                       &amp;cli_addr,
13793                                                       sizeof(cli_addr),
13794                                                       buffer, ret,
13795                                                       &amp;prestate);
13796                         if (ret &lt; 0) {  /* cookie not valid */
13797                                 priv_data_st s;
13798
13799                                 memset(&amp;s, 0, sizeof(s));
13800                                 s.fd = sock;
13801                                 s.cli_addr = (void *) &amp;cli_addr;
13802                                 s.cli_addr_size = sizeof(cli_addr);
13803
13804                                 printf
13805                                     (&quot;Sending hello verify request to %s\n&quot;,
13806                                      human_addr((struct sockaddr *)
13807                                                 &amp;cli_addr,
13808                                                 sizeof(cli_addr), buffer,
13809                                                 sizeof(buffer)));
13810
13811                                 gnutls_dtls_cookie_send(&amp;cookie_key,
13812                                                         &amp;cli_addr,
13813                                                         sizeof(cli_addr),
13814                                                         &amp;prestate,
13815                                                         (gnutls_transport_ptr_t)
13816                                                         &amp; s, push_func);
13817
13818                                 /* discard peeked data */
13819                                 recvfrom(sock, buffer, sizeof(buffer), 0,
13820                                          (struct sockaddr *) &amp;cli_addr,
13821                                          &amp;cli_addr_size);
13822                                 usleep(100);
13823                                 continue;
13824                         }
13825                         printf(&quot;Accepted connection from %s\n&quot;,
13826                                human_addr((struct sockaddr *)
13827                                           &amp;cli_addr, sizeof(cli_addr),
13828                                           buffer, sizeof(buffer)));
13829                 } else
13830                         continue;
13831
13832                 gnutls_init(&amp;session, GNUTLS_SERVER | GNUTLS_DATAGRAM);
13833                 gnutls_priority_set(session, priority_cache);
13834                 gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE,
13835                                        x509_cred);
13836
13837                 gnutls_dtls_prestate_set(session, &amp;prestate);
13838                 gnutls_dtls_set_mtu(session, mtu);
13839
13840                 priv.session = session;
13841                 priv.fd = sock;
13842                 priv.cli_addr = (struct sockaddr *) &amp;cli_addr;
13843                 priv.cli_addr_size = sizeof(cli_addr);
13844
13845                 gnutls_transport_set_ptr(session, &amp;priv);
13846                 gnutls_transport_set_push_function(session, push_func);
13847                 gnutls_transport_set_pull_function(session, pull_func);
13848                 gnutls_transport_set_pull_timeout_function(session,
13849                                                            pull_timeout_func);
13850
13851                 do {
13852                         ret = gnutls_handshake(session);
13853                 }
13854                 while (ret == GNUTLS_E_INTERRUPTED
13855                        || ret == GNUTLS_E_AGAIN);
13856                 /* Note that DTLS may also receive GNUTLS_E_LARGE_PACKET.
13857                  * In that case the MTU should be adjusted.
13858                  */
13859
13860                 if (ret &lt; 0) {
13861                         fprintf(stderr, &quot;Error in handshake(): %s\n&quot;,
13862                                 gnutls_strerror(ret));
13863                         gnutls_deinit(session);
13864                         continue;
13865                 }
13866
13867                 printf(&quot;- Handshake was completed\n&quot;);
13868
13869                 for (;;) {
13870                         do {
13871                                 ret =
13872                                     gnutls_record_recv_seq(session, buffer,
13873                                                            MAX_BUFFER,
13874                                                            sequence);
13875                         }
13876                         while (ret == GNUTLS_E_AGAIN
13877                                || ret == GNUTLS_E_INTERRUPTED);
13878
13879                         if (ret &lt; 0 &amp;&amp; gnutls_error_is_fatal(ret) == 0) {
13880                                 fprintf(stderr, &quot;*** Warning: %s\n&quot;,
13881                                         gnutls_strerror(ret));
13882                                 continue;
13883                         } else if (ret &lt; 0) {
13884                                 fprintf(stderr, &quot;Error in recv(): %s\n&quot;,
13885                                         gnutls_strerror(ret));
13886                                 break;
13887                         }
13888
13889                         if (ret == 0) {
13890                                 printf(&quot;EOF\n\n&quot;);
13891                                 break;
13892                         }
13893
13894                         buffer[ret] = 0;
13895                         printf
13896                             (&quot;received[%.2x%.2x%.2x%.2x%.2x%.2x%.2x%.2x]: %s\n&quot;,
13897                              sequence[0], sequence[1], sequence[2],
13898                              sequence[3], sequence[4], sequence[5],
13899                              sequence[6], sequence[7], buffer);
13900
13901                         /* reply back */
13902                         ret = gnutls_record_send(session, buffer, ret);
13903                         if (ret &lt; 0) {
13904                                 fprintf(stderr, &quot;Error in send(): %s\n&quot;,
13905                                         gnutls_strerror(ret));
13906                                 break;
13907                         }
13908                 }
13909
13910                 gnutls_bye(session, GNUTLS_SHUT_WR);
13911                 gnutls_deinit(session);
13912
13913         }
13914         close(listen_sd);
13915
13916         gnutls_certificate_free_credentials(x509_cred);
13917         gnutls_priority_deinit(priority_cache);
13918
13919         gnutls_global_deinit();
13920
13921         return 0;
13922
13923 }
13924
13925 static int wait_for_connection(int fd)
13926 {
13927         fd_set rd, wr;
13928         int n;
13929
13930         FD_ZERO(&amp;rd);
13931         FD_ZERO(&amp;wr);
13932
13933         FD_SET(fd, &amp;rd);
13934
13935         /* waiting part */
13936         n = select(fd + 1, &amp;rd, &amp;wr, NULL, NULL);
13937         if (n == -1 &amp;&amp; errno == EINTR)
13938                 return -1;
13939         if (n &lt; 0) {
13940                 perror(&quot;select()&quot;);
13941                 exit(1);
13942         }
13943
13944         return fd;
13945 }
13946
13947 /* Wait for data to be received within a timeout period in milliseconds
13948  */
13949 static int pull_timeout_func(gnutls_transport_ptr_t ptr, unsigned int ms)
13950 {
13951         fd_set rfds;
13952         struct timeval tv;
13953         priv_data_st *priv = ptr;
13954         struct sockaddr_in cli_addr;
13955         socklen_t cli_addr_size;
13956         int ret;
13957         char c;
13958
13959         FD_ZERO(&amp;rfds);
13960         FD_SET(priv-&gt;fd, &amp;rfds);
13961
13962         tv.tv_sec = 0;
13963         tv.tv_usec = ms * 1000;
13964
13965         while (tv.tv_usec &gt;= 1000000) {
13966                 tv.tv_usec -= 1000000;
13967                 tv.tv_sec++;
13968         }
13969
13970         ret = select(priv-&gt;fd + 1, &amp;rfds, NULL, NULL, &amp;tv);
13971
13972         if (ret &lt;= 0)
13973                 return ret;
13974
13975         /* only report ok if the next message is from the peer we expect
13976          * from
13977          */
13978         cli_addr_size = sizeof(cli_addr);
13979         ret =
13980             recvfrom(priv-&gt;fd, &amp;c, 1, MSG_PEEK,
13981                      (struct sockaddr *) &amp;cli_addr, &amp;cli_addr_size);
13982         if (ret &gt; 0) {
13983                 if (cli_addr_size == priv-&gt;cli_addr_size
13984                     &amp;&amp; memcmp(&amp;cli_addr, priv-&gt;cli_addr,
13985                               sizeof(cli_addr)) == 0)
13986                         return 1;
13987         }
13988
13989         return 0;
13990 }
13991
13992 static ssize_t
13993 push_func(gnutls_transport_ptr_t p, const void *data, size_t size)
13994 {
13995         priv_data_st *priv = p;
13996
13997         return sendto(priv-&gt;fd, data, size, 0, priv-&gt;cli_addr,
13998                       priv-&gt;cli_addr_size);
13999 }
14000
14001 static ssize_t pull_func(gnutls_transport_ptr_t p, void *data, size_t size)
14002 {
14003         priv_data_st *priv = p;
14004         struct sockaddr_in cli_addr;
14005         socklen_t cli_addr_size;
14006         char buffer[64];
14007         int ret;
14008
14009         cli_addr_size = sizeof(cli_addr);
14010         ret =
14011             recvfrom(priv-&gt;fd, data, size, 0,
14012                      (struct sockaddr *) &amp;cli_addr, &amp;cli_addr_size);
14013         if (ret == -1)
14014                 return ret;
14015
14016         if (cli_addr_size == priv-&gt;cli_addr_size
14017             &amp;&amp; memcmp(&amp;cli_addr, priv-&gt;cli_addr, sizeof(cli_addr)) == 0)
14018                 return ret;
14019
14020         printf(&quot;Denied connection from %s\n&quot;,
14021                human_addr((struct sockaddr *)
14022                           &amp;cli_addr, sizeof(cli_addr), buffer,
14023                           sizeof(buffer)));
14024
14025         gnutls_transport_set_errno(priv-&gt;session, EAGAIN);
14026         return -1;
14027 }
14028
14029 static const char *human_addr(const struct sockaddr *sa, socklen_t salen,
14030                               char *buf, size_t buflen)
14031 {
14032         const char *save_buf = buf;
14033         size_t l;
14034
14035         if (!buf || !buflen)
14036                 return NULL;
14037
14038         *buf = '\0';
14039
14040         switch (sa-&gt;sa_family) {
14041 #if HAVE_IPV6
14042         case AF_INET6:
14043                 snprintf(buf, buflen, &quot;IPv6 &quot;);
14044                 break;
14045 #endif
14046
14047         case AF_INET:
14048                 snprintf(buf, buflen, &quot;IPv4 &quot;);
14049                 break;
14050         }
14051
14052         l = strlen(buf);
14053         buf += l;
14054         buflen -= l;
14055
14056         if (getnameinfo(sa, salen, buf, buflen, NULL, 0, NI_NUMERICHOST) !=
14057             0)
14058                 return NULL;
14059
14060         l = strlen(buf);
14061         buf += l;
14062         buflen -= l;
14063
14064         strncat(buf, &quot; port &quot;, buflen);
14065
14066         l = strlen(buf);
14067         buf += l;
14068         buflen -= l;
14069
14070         if (getnameinfo(sa, salen, NULL, 0, buf, buflen, NI_NUMERICSERV) !=
14071             0)
14072                 return NULL;
14073
14074         return save_buf;
14075 }
14076
14077 static int generate_dh_params(void)
14078 {
14079         int bits = gnutls_sec_param_to_pk_bits(GNUTLS_PK_DH,
14080                                                GNUTLS_SEC_PARAM_LEGACY);
14081
14082         /* Generate Diffie-Hellman parameters - for use with DHE
14083          * kx algorithms. When short bit length is used, it might
14084          * be wise to regenerate parameters often.
14085          */
14086         gnutls_dh_params_init(&amp;dh_params);
14087         gnutls_dh_params_generate2(dh_params, bits);
14088
14089         return 0;
14090 }
14091 </pre>
14092
14093 <hr>
14094 <a name="OCSP-example"></a>
14095 <div class="header">
14096 <p>
14097 Next: <a href="#Miscellaneous-examples" accesskey="n" rel="next">Miscellaneous examples</a>, Previous: <a href="#Server-examples" accesskey="p" rel="prev">Server examples</a>, Up: <a href="#GnuTLS-application-examples" accesskey="u" rel="up">GnuTLS application examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
14098 </div>
14099 <a name="OCSP-example-1"></a>
14100 <h3 class="section">7.3 OCSP example</h3>
14101
14102 <a name="Generate-OCSP-request"></a><a name="Generate-OCSP-request-1"></a>
14103 <h4 class="subheading">Generate <acronym>OCSP</acronym> request</h4>
14104
14105 <p>A small tool to generate OCSP requests.
14106 </p>
14107 <pre class="verbatim">/* This example code is placed in the public domain. */
14108
14109 #ifdef HAVE_CONFIG_H
14110 #include &lt;config.h&gt;
14111 #endif
14112
14113 #include &lt;stdio.h&gt;
14114 #include &lt;stdlib.h&gt;
14115 #include &lt;string.h&gt;
14116 #include &lt;gnutls/gnutls.h&gt;
14117 #include &lt;gnutls/crypto.h&gt;
14118 #include &lt;gnutls/ocsp.h&gt;
14119 #ifndef NO_LIBCURL
14120 #include &lt;curl/curl.h&gt;
14121 #endif
14122 #include &quot;read-file.h&quot;
14123
14124 size_t get_data(void *buffer, size_t size, size_t nmemb, void *userp);
14125 static gnutls_x509_crt_t load_cert(const char *cert_file);
14126 static void _response_info(const gnutls_datum_t * data);
14127 static void
14128 _generate_request(gnutls_datum_t * rdata, gnutls_x509_crt_t cert,
14129                   gnutls_x509_crt_t issuer, gnutls_datum_t *nonce);
14130 static int
14131 _verify_response(gnutls_datum_t * data, gnutls_x509_crt_t cert,
14132                  gnutls_x509_crt_t signer, gnutls_datum_t *nonce);
14133
14134 /* This program queries an OCSP server.
14135    It expects three files. argv[1] containing the certificate to
14136    be checked, argv[2] holding the issuer for this certificate,
14137    and argv[3] holding a trusted certificate to verify OCSP's response.
14138    argv[4] is optional and should hold the server host name.
14139
14140    For simplicity the libcurl library is used.
14141  */
14142
14143 int main(int argc, char *argv[])
14144 {
14145         gnutls_datum_t ud, tmp;
14146         int ret;
14147         gnutls_datum_t req;
14148         gnutls_x509_crt_t cert, issuer, signer;
14149 #ifndef NO_LIBCURL
14150         CURL *handle;
14151         struct curl_slist *headers = NULL;
14152 #endif
14153         int v, seq;
14154         const char *cert_file = argv[1];
14155         const char *issuer_file = argv[2];
14156         const char *signer_file = argv[3];
14157         char *hostname = NULL;
14158         unsigned char noncebuf[23];
14159         gnutls_datum_t nonce = { noncebuf, sizeof(noncebuf) };
14160
14161         gnutls_global_init();
14162
14163         if (argc &gt; 4)
14164                 hostname = argv[4];
14165
14166         ret = gnutls_rnd(GNUTLS_RND_NONCE, nonce.data, nonce.size);
14167         if (ret &lt; 0)
14168                 exit(1);
14169
14170         cert = load_cert(cert_file);
14171         issuer = load_cert(issuer_file);
14172         signer = load_cert(signer_file);
14173
14174         if (hostname == NULL) {
14175
14176                 for (seq = 0;; seq++) {
14177                         ret =
14178                             gnutls_x509_crt_get_authority_info_access(cert,
14179                                                                       seq,
14180                                                                       GNUTLS_IA_OCSP_URI,
14181                                                                       &amp;tmp,
14182                                                                       NULL);
14183                         if (ret == GNUTLS_E_UNKNOWN_ALGORITHM)
14184                                 continue;
14185                         if (ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE) {
14186                                 fprintf(stderr,
14187                                         &quot;No URI was found in the certificate.\n&quot;);
14188                                 exit(1);
14189                         }
14190                         if (ret &lt; 0) {
14191                                 fprintf(stderr, &quot;error: %s\n&quot;,
14192                                         gnutls_strerror(ret));
14193                                 exit(1);
14194                         }
14195
14196                         printf(&quot;CA issuers URI: %.*s\n&quot;, tmp.size,
14197                                tmp.data);
14198
14199                         hostname = malloc(tmp.size + 1);
14200                         memcpy(hostname, tmp.data, tmp.size);
14201                         hostname[tmp.size] = 0;
14202
14203                         gnutls_free(tmp.data);
14204                         break;
14205                 }
14206
14207         }
14208
14209         /* Note that the OCSP servers hostname might be available
14210          * using gnutls_x509_crt_get_authority_info_access() in the issuer's
14211          * certificate */
14212
14213         memset(&amp;ud, 0, sizeof(ud));
14214         fprintf(stderr, &quot;Connecting to %s\n&quot;, hostname);
14215
14216         _generate_request(&amp;req, cert, issuer, &amp;nonce);
14217
14218 #ifndef NO_LIBCURL
14219         curl_global_init(CURL_GLOBAL_ALL);
14220
14221         handle = curl_easy_init();
14222         if (handle == NULL)
14223                 exit(1);
14224
14225         headers =
14226             curl_slist_append(headers,
14227                               &quot;Content-Type: application/ocsp-request&quot;);
14228
14229         curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers);
14230         curl_easy_setopt(handle, CURLOPT_POSTFIELDS, (void *) req.data);
14231         curl_easy_setopt(handle, CURLOPT_POSTFIELDSIZE, req.size);
14232         curl_easy_setopt(handle, CURLOPT_URL, hostname);
14233         curl_easy_setopt(handle, CURLOPT_WRITEFUNCTION, get_data);
14234         curl_easy_setopt(handle, CURLOPT_WRITEDATA, &amp;ud);
14235
14236         ret = curl_easy_perform(handle);
14237         if (ret != 0) {
14238                 fprintf(stderr, &quot;curl[%d] error %d\n&quot;, __LINE__, ret);
14239                 exit(1);
14240         }
14241
14242         curl_easy_cleanup(handle);
14243 #endif
14244
14245         _response_info(&amp;ud);
14246
14247         v = _verify_response(&amp;ud, cert, signer, &amp;nonce);
14248
14249         gnutls_x509_crt_deinit(cert);
14250         gnutls_x509_crt_deinit(issuer);
14251         gnutls_x509_crt_deinit(signer);
14252         gnutls_global_deinit();
14253
14254         return v;
14255 }
14256
14257 static void _response_info(const gnutls_datum_t * data)
14258 {
14259         gnutls_ocsp_resp_t resp;
14260         int ret;
14261         gnutls_datum buf;
14262
14263         ret = gnutls_ocsp_resp_init(&amp;resp);
14264         if (ret &lt; 0)
14265                 exit(1);
14266
14267         ret = gnutls_ocsp_resp_import(resp, data);
14268         if (ret &lt; 0)
14269                 exit(1);
14270
14271         ret = gnutls_ocsp_resp_print(resp, GNUTLS_OCSP_PRINT_FULL, &amp;buf);
14272         if (ret != 0)
14273                 exit(1);
14274
14275         printf(&quot;%.*s&quot;, buf.size, buf.data);
14276         gnutls_free(buf.data);
14277
14278         gnutls_ocsp_resp_deinit(resp);
14279 }
14280
14281 static gnutls_x509_crt_t load_cert(const char *cert_file)
14282 {
14283         gnutls_x509_crt_t crt;
14284         int ret;
14285         gnutls_datum_t data;
14286         size_t size;
14287
14288         ret = gnutls_x509_crt_init(&amp;crt);
14289         if (ret &lt; 0)
14290                 exit(1);
14291
14292         data.data = (void *) read_binary_file(cert_file, &amp;size);
14293         data.size = size;
14294
14295         if (!data.data) {
14296                 fprintf(stderr, &quot;Cannot open file: %s\n&quot;, cert_file);
14297                 exit(1);
14298         }
14299
14300         ret = gnutls_x509_crt_import(crt, &amp;data, GNUTLS_X509_FMT_PEM);
14301         free(data.data);
14302         if (ret &lt; 0) {
14303                 fprintf(stderr, &quot;Cannot import certificate in %s: %s\n&quot;,
14304                         cert_file, gnutls_strerror(ret));
14305                 exit(1);
14306         }
14307
14308         return crt;
14309 }
14310
14311 static void
14312 _generate_request(gnutls_datum_t * rdata, gnutls_x509_crt_t cert,
14313                   gnutls_x509_crt_t issuer, gnutls_datum_t *nonce)
14314 {
14315         gnutls_ocsp_req_t req;
14316         int ret;
14317
14318         ret = gnutls_ocsp_req_init(&amp;req);
14319         if (ret &lt; 0)
14320                 exit(1);
14321
14322         ret = gnutls_ocsp_req_add_cert(req, GNUTLS_DIG_SHA1, issuer, cert);
14323         if (ret &lt; 0)
14324                 exit(1);
14325
14326
14327         ret = gnutls_ocsp_req_set_nonce(req, 0, nonce);
14328         if (ret &lt; 0)
14329                 exit(1);
14330
14331         ret = gnutls_ocsp_req_export(req, rdata);
14332         if (ret != 0)
14333                 exit(1);
14334
14335         gnutls_ocsp_req_deinit(req);
14336
14337         return;
14338 }
14339
14340 static int
14341 _verify_response(gnutls_datum_t * data, gnutls_x509_crt_t cert,
14342                  gnutls_x509_crt_t signer, gnutls_datum_t *nonce)
14343 {
14344         gnutls_ocsp_resp_t resp;
14345         int ret;
14346         unsigned verify;
14347         gnutls_datum_t rnonce;
14348
14349         ret = gnutls_ocsp_resp_init(&amp;resp);
14350         if (ret &lt; 0)
14351                 exit(1);
14352
14353         ret = gnutls_ocsp_resp_import(resp, data);
14354         if (ret &lt; 0)
14355                 exit(1);
14356
14357         ret = gnutls_ocsp_resp_check_crt(resp, 0, cert);
14358         if (ret &lt; 0)
14359                 exit(1);
14360
14361         ret = gnutls_ocsp_resp_get_nonce(resp, NULL, &amp;rnonce);
14362         if (ret &lt; 0)
14363                 exit(1);
14364
14365         if (rnonce.size != nonce-&gt;size || memcmp(nonce-&gt;data, rnonce.data,
14366                 nonce-&gt;size) != 0) {
14367                 exit(1);
14368         }
14369
14370         ret = gnutls_ocsp_resp_verify_direct(resp, signer, &amp;verify, 0);
14371         if (ret &lt; 0)
14372                 exit(1);
14373
14374         printf(&quot;Verifying OCSP Response: &quot;);
14375         if (verify == 0)
14376                 printf(&quot;Verification success!\n&quot;);
14377         else
14378                 printf(&quot;Verification error!\n&quot;);
14379
14380         if (verify &amp; GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND)
14381                 printf(&quot;Signer cert not found\n&quot;);
14382
14383         if (verify &amp; GNUTLS_OCSP_VERIFY_SIGNER_KEYUSAGE_ERROR)
14384                 printf(&quot;Signer cert keyusage error\n&quot;);
14385
14386         if (verify &amp; GNUTLS_OCSP_VERIFY_UNTRUSTED_SIGNER)
14387                 printf(&quot;Signer cert is not trusted\n&quot;);
14388
14389         if (verify &amp; GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM)
14390                 printf(&quot;Insecure algorithm\n&quot;);
14391
14392         if (verify &amp; GNUTLS_OCSP_VERIFY_SIGNATURE_FAILURE)
14393                 printf(&quot;Signature failure\n&quot;);
14394
14395         if (verify &amp; GNUTLS_OCSP_VERIFY_CERT_NOT_ACTIVATED)
14396                 printf(&quot;Signer cert not yet activated\n&quot;);
14397
14398         if (verify &amp; GNUTLS_OCSP_VERIFY_CERT_EXPIRED)
14399                 printf(&quot;Signer cert expired\n&quot;);
14400
14401         gnutls_free(rnonce.data);
14402         gnutls_ocsp_resp_deinit(resp);
14403
14404         return verify;
14405 }
14406
14407 size_t get_data(void *buffer, size_t size, size_t nmemb, void *userp)
14408 {
14409         gnutls_datum_t *ud = userp;
14410
14411         size *= nmemb;
14412
14413         ud-&gt;data = realloc(ud-&gt;data, size + ud-&gt;size);
14414         if (ud-&gt;data == NULL) {
14415                 fprintf(stderr, &quot;Not enough memory for the request\n&quot;);
14416                 exit(1);
14417         }
14418
14419         memcpy(&amp;ud-&gt;data[ud-&gt;size], buffer, size);
14420         ud-&gt;size += size;
14421
14422         return size;
14423 }
14424 </pre>
14425 <hr>
14426 <a name="Miscellaneous-examples"></a>
14427 <div class="header">
14428 <p>
14429 Previous: <a href="#OCSP-example" accesskey="p" rel="prev">OCSP example</a>, Up: <a href="#GnuTLS-application-examples" accesskey="u" rel="up">GnuTLS application examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
14430 </div>
14431 <a name="Miscellaneous-examples-1"></a>
14432 <h3 class="section">7.4 Miscellaneous examples</h3>
14433
14434 <table class="menu" border="0" cellspacing="0">
14435 <tr><td align="left" valign="top">&bull; <a href="#Checking-for-an-alert" accesskey="1">Checking for an alert</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
14436 </td></tr>
14437 <tr><td align="left" valign="top">&bull; <a href="#X_002e509-certificate-parsing-example" accesskey="2">X.509 certificate parsing example</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
14438 </td></tr>
14439 <tr><td align="left" valign="top">&bull; <a href="#Listing-the-ciphersuites-in-a-priority-string" accesskey="3">Listing the ciphersuites in a priority string</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
14440 </td></tr>
14441 <tr><td align="left" valign="top">&bull; <a href="#PKCS12-structure-generation-example" accesskey="4">PKCS12 structure generation example</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
14442 </td></tr>
14443 </table>
14444
14445 <hr>
14446 <a name="Checking-for-an-alert"></a>
14447 <div class="header">
14448 <p>
14449 Next: <a href="#X_002e509-certificate-parsing-example" accesskey="n" rel="next">X.509 certificate parsing example</a>, Up: <a href="#Miscellaneous-examples" accesskey="u" rel="up">Miscellaneous examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
14450 </div>
14451 <a name="Checking-for-an-alert-1"></a>
14452 <h4 class="subsection">7.4.1 Checking for an alert</h4>
14453
14454 <p>This is a function that checks if an alert has been received in the
14455 current session.
14456 </p>
14457 <pre class="verbatim">/* This example code is placed in the public domain. */
14458
14459 #ifdef HAVE_CONFIG_H
14460 #include &lt;config.h&gt;
14461 #endif
14462
14463 #include &lt;stdio.h&gt;
14464 #include &lt;stdlib.h&gt;
14465 #include &lt;gnutls/gnutls.h&gt;
14466
14467 #include &quot;examples.h&quot;
14468
14469 /* This function will check whether the given return code from
14470  * a gnutls function (recv/send), is an alert, and will print
14471  * that alert.
14472  */
14473 void check_alert(gnutls_session_t session, int ret)
14474 {
14475         int last_alert;
14476
14477         if (ret == GNUTLS_E_WARNING_ALERT_RECEIVED
14478             || ret == GNUTLS_E_FATAL_ALERT_RECEIVED) {
14479                 last_alert = gnutls_alert_get(session);
14480
14481                 /* The check for renegotiation is only useful if we are
14482                  * a server, and we had requested a rehandshake.
14483                  */
14484                 if (last_alert == GNUTLS_A_NO_RENEGOTIATION &amp;&amp;
14485                     ret == GNUTLS_E_WARNING_ALERT_RECEIVED)
14486                         printf(&quot;* Received NO_RENEGOTIATION alert. &quot;
14487                                &quot;Client Does not support renegotiation.\n&quot;);
14488                 else
14489                         printf(&quot;* Received alert '%d': %s.\n&quot;, last_alert,
14490                                gnutls_alert_get_name(last_alert));
14491         }
14492 }
14493 </pre>
14494 <hr>
14495 <a name="X_002e509-certificate-parsing-example"></a>
14496 <div class="header">
14497 <p>
14498 Next: <a href="#Listing-the-ciphersuites-in-a-priority-string" accesskey="n" rel="next">Listing the ciphersuites in a priority string</a>, Previous: <a href="#Checking-for-an-alert" accesskey="p" rel="prev">Checking for an alert</a>, Up: <a href="#Miscellaneous-examples" accesskey="u" rel="up">Miscellaneous examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
14499 </div>
14500 <a name="X_002e509-certificate-parsing-example-1"></a>
14501 <h4 class="subsection">7.4.2 <acronym>X.509</acronym> certificate parsing example</h4>
14502 <a name="ex_002dx509_002dinfo"></a>
14503 <p>To demonstrate the <acronym>X.509</acronym> parsing capabilities an example program is
14504 listed below.  That program reads the peer&rsquo;s certificate, and prints
14505 information about it.
14506 </p>
14507 <pre class="verbatim">/* This example code is placed in the public domain. */
14508
14509 #ifdef HAVE_CONFIG_H
14510 #include &lt;config.h&gt;
14511 #endif
14512
14513 #include &lt;stdio.h&gt;
14514 #include &lt;stdlib.h&gt;
14515 #include &lt;gnutls/gnutls.h&gt;
14516 #include &lt;gnutls/x509.h&gt;
14517
14518 #include &quot;examples.h&quot;
14519
14520 static const char *bin2hex(const void *bin, size_t bin_size)
14521 {
14522         static char printable[110];
14523         const unsigned char *_bin = bin;
14524         char *print;
14525         size_t i;
14526
14527         if (bin_size &gt; 50)
14528                 bin_size = 50;
14529
14530         print = printable;
14531         for (i = 0; i &lt; bin_size; i++) {
14532                 sprintf(print, &quot;%.2x &quot;, _bin[i]);
14533                 print += 2;
14534         }
14535
14536         return printable;
14537 }
14538
14539 /* This function will print information about this session's peer
14540  * certificate.
14541  */
14542 void print_x509_certificate_info(gnutls_session_t session)
14543 {
14544         char serial[40];
14545         char dn[256];
14546         size_t size;
14547         unsigned int algo, bits;
14548         time_t expiration_time, activation_time;
14549         const gnutls_datum_t *cert_list;
14550         unsigned int cert_list_size = 0;
14551         gnutls_x509_crt_t cert;
14552         gnutls_datum_t cinfo;
14553
14554         /* This function only works for X.509 certificates.
14555          */
14556         if (gnutls_certificate_type_get(session) != GNUTLS_CRT_X509)
14557                 return;
14558
14559         cert_list = gnutls_certificate_get_peers(session, &amp;cert_list_size);
14560
14561         printf(&quot;Peer provided %d certificates.\n&quot;, cert_list_size);
14562
14563         if (cert_list_size &gt; 0) {
14564                 int ret;
14565
14566                 /* we only print information about the first certificate.
14567                  */
14568                 gnutls_x509_crt_init(&amp;cert);
14569
14570                 gnutls_x509_crt_import(cert, &amp;cert_list[0],
14571                                        GNUTLS_X509_FMT_DER);
14572
14573                 printf(&quot;Certificate info:\n&quot;);
14574
14575                 /* This is the preferred way of printing short information about
14576                    a certificate. */
14577
14578                 ret =
14579                     gnutls_x509_crt_print(cert, GNUTLS_CRT_PRINT_ONELINE,
14580                                           &amp;cinfo);
14581                 if (ret == 0) {
14582                         printf(&quot;\t%s\n&quot;, cinfo.data);
14583                         gnutls_free(cinfo.data);
14584                 }
14585
14586                 /* If you want to extract fields manually for some other reason,
14587                    below are popular example calls. */
14588
14589                 expiration_time =
14590                     gnutls_x509_crt_get_expiration_time(cert);
14591                 activation_time =
14592                     gnutls_x509_crt_get_activation_time(cert);
14593
14594                 printf(&quot;\tCertificate is valid since: %s&quot;,
14595                        ctime(&amp;activation_time));
14596                 printf(&quot;\tCertificate expires: %s&quot;,
14597                        ctime(&amp;expiration_time));
14598
14599                 /* Print the serial number of the certificate.
14600                  */
14601                 size = sizeof(serial);
14602                 gnutls_x509_crt_get_serial(cert, serial, &amp;size);
14603
14604                 printf(&quot;\tCertificate serial number: %s\n&quot;,
14605                        bin2hex(serial, size));
14606
14607                 /* Extract some of the public key algorithm's parameters
14608                  */
14609                 algo = gnutls_x509_crt_get_pk_algorithm(cert, &amp;bits);
14610
14611                 printf(&quot;Certificate public key: %s&quot;,
14612                        gnutls_pk_algorithm_get_name(algo));
14613
14614                 /* Print the version of the X.509
14615                  * certificate.
14616                  */
14617                 printf(&quot;\tCertificate version: #%d\n&quot;,
14618                        gnutls_x509_crt_get_version(cert));
14619
14620                 size = sizeof(dn);
14621                 gnutls_x509_crt_get_dn(cert, dn, &amp;size);
14622                 printf(&quot;\tDN: %s\n&quot;, dn);
14623
14624                 size = sizeof(dn);
14625                 gnutls_x509_crt_get_issuer_dn(cert, dn, &amp;size);
14626                 printf(&quot;\tIssuer's DN: %s\n&quot;, dn);
14627
14628                 gnutls_x509_crt_deinit(cert);
14629
14630         }
14631 }
14632 </pre>
14633 <hr>
14634 <a name="Listing-the-ciphersuites-in-a-priority-string"></a>
14635 <div class="header">
14636 <p>
14637 Next: <a href="#PKCS12-structure-generation-example" accesskey="n" rel="next">PKCS12 structure generation example</a>, Previous: <a href="#X_002e509-certificate-parsing-example" accesskey="p" rel="prev">X.509 certificate parsing example</a>, Up: <a href="#Miscellaneous-examples" accesskey="u" rel="up">Miscellaneous examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
14638 </div>
14639 <a name="Listing-the-ciphersuites-in-a-priority-string-1"></a>
14640 <h4 class="subsection">7.4.3 Listing the ciphersuites in a priority string</h4>
14641
14642 <p>This is a small program to list the enabled ciphersuites by a
14643 priority string.
14644 </p>
14645 <pre class="verbatim">/* This example code is placed in the public domain. */
14646
14647 #include &lt;config.h&gt;
14648 #include &lt;stdio.h&gt;
14649 #include &lt;stdlib.h&gt;
14650 #include &lt;string.h&gt;
14651 #include &lt;gnutls/gnutls.h&gt;
14652
14653 static void print_cipher_suite_list(const char *priorities)
14654 {
14655         size_t i;
14656         int ret;
14657         unsigned int idx;
14658         const char *name;
14659         const char *err;
14660         unsigned char id[2];
14661         gnutls_protocol_t version;
14662         gnutls_priority_t pcache;
14663
14664         if (priorities != NULL) {
14665                 printf(&quot;Cipher suites for %s\n&quot;, priorities);
14666
14667                 ret = gnutls_priority_init(&amp;pcache, priorities, &amp;err);
14668                 if (ret &lt; 0) {
14669                         fprintf(stderr, &quot;Syntax error at: %s\n&quot;, err);
14670                         exit(1);
14671                 }
14672
14673                 for (i = 0;; i++) {
14674                         ret =
14675                             gnutls_priority_get_cipher_suite_index(pcache,
14676                                                                    i,
14677                                                                    &amp;idx);
14678                         if (ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
14679                                 break;
14680                         if (ret == GNUTLS_E_UNKNOWN_CIPHER_SUITE)
14681                                 continue;
14682
14683                         name =
14684                             gnutls_cipher_suite_info(idx, id, NULL, NULL,
14685                                                      NULL, &amp;version);
14686
14687                         if (name != NULL)
14688                                 printf(&quot;%-50s\t0x%02x, 0x%02x\t%s\n&quot;,
14689                                        name, (unsigned char) id[0],
14690                                        (unsigned char) id[1],
14691                                        gnutls_protocol_get_name(version));
14692                 }
14693
14694                 return;
14695         }
14696 }
14697
14698 int main(int argc, char **argv)
14699 {
14700         if (argc &gt; 1)
14701                 print_cipher_suite_list(argv[1]);
14702         return 0;
14703 }
14704 </pre>
14705 <hr>
14706 <a name="PKCS12-structure-generation-example"></a>
14707 <div class="header">
14708 <p>
14709 Previous: <a href="#Listing-the-ciphersuites-in-a-priority-string" accesskey="p" rel="prev">Listing the ciphersuites in a priority string</a>, Up: <a href="#Miscellaneous-examples" accesskey="u" rel="up">Miscellaneous examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
14710 </div>
14711 <a name="PKCS-_002312-structure-generation-example"></a>
14712 <h4 class="subsection">7.4.4 PKCS #12 structure generation example</h4>
14713
14714 <p>This small program demonstrates the usage of the PKCS #12 API, by generating
14715 such a structure.
14716 </p>
14717 <pre class="verbatim">/* This example code is placed in the public domain. */
14718
14719 #ifdef HAVE_CONFIG_H
14720 #include &lt;config.h&gt;
14721 #endif
14722
14723 #include &lt;stdio.h&gt;
14724 #include &lt;stdlib.h&gt;
14725 #include &lt;gnutls/gnutls.h&gt;
14726 #include &lt;gnutls/pkcs12.h&gt;
14727
14728 #include &quot;examples.h&quot;
14729
14730 #define OUTFILE &quot;out.p12&quot;
14731
14732 /* This function will write a pkcs12 structure into a file.
14733  * cert: is a DER encoded certificate
14734  * pkcs8_key: is a PKCS #8 encrypted key (note that this must be
14735  *  encrypted using a PKCS #12 cipher, or some browsers will crash)
14736  * password: is the password used to encrypt the PKCS #12 packet.
14737  */
14738 int
14739 write_pkcs12(const gnutls_datum_t * cert,
14740              const gnutls_datum_t * pkcs8_key, const char *password)
14741 {
14742         gnutls_pkcs12_t pkcs12;
14743         int ret, bag_index;
14744         gnutls_pkcs12_bag_t bag, key_bag;
14745         char pkcs12_struct[10 * 1024];
14746         size_t pkcs12_struct_size;
14747         FILE *fd;
14748
14749         /* A good idea might be to use gnutls_x509_privkey_get_key_id()
14750          * to obtain a unique ID.
14751          */
14752         gnutls_datum_t key_id = { (void *) &quot;\x00\x00\x07&quot;, 3 };
14753
14754         gnutls_global_init();
14755
14756         /* Firstly we create two helper bags, which hold the certificate,
14757          * and the (encrypted) key.
14758          */
14759
14760         gnutls_pkcs12_bag_init(&amp;bag);
14761         gnutls_pkcs12_bag_init(&amp;key_bag);
14762
14763         ret =
14764             gnutls_pkcs12_bag_set_data(bag, GNUTLS_BAG_CERTIFICATE, cert);
14765         if (ret &lt; 0) {
14766                 fprintf(stderr, &quot;ret: %s\n&quot;, gnutls_strerror(ret));
14767                 return 1;
14768         }
14769
14770         /* ret now holds the bag's index.
14771          */
14772         bag_index = ret;
14773
14774         /* Associate a friendly name with the given certificate. Used
14775          * by browsers.
14776          */
14777         gnutls_pkcs12_bag_set_friendly_name(bag, bag_index, &quot;My name&quot;);
14778
14779         /* Associate the certificate with the key using a unique key
14780          * ID.
14781          */
14782         gnutls_pkcs12_bag_set_key_id(bag, bag_index, &amp;key_id);
14783
14784         /* use weak encryption for the certificate.
14785          */
14786         gnutls_pkcs12_bag_encrypt(bag, password,
14787                                   GNUTLS_PKCS_USE_PKCS12_RC2_40);
14788
14789         /* Now the key.
14790          */
14791
14792         ret = gnutls_pkcs12_bag_set_data(key_bag,
14793                                          GNUTLS_BAG_PKCS8_ENCRYPTED_KEY,
14794                                          pkcs8_key);
14795         if (ret &lt; 0) {
14796                 fprintf(stderr, &quot;ret: %s\n&quot;, gnutls_strerror(ret));
14797                 return 1;
14798         }
14799
14800         /* Note that since the PKCS #8 key is already encrypted we don't
14801          * bother encrypting that bag.
14802          */
14803         bag_index = ret;
14804
14805         gnutls_pkcs12_bag_set_friendly_name(key_bag, bag_index, &quot;My name&quot;);
14806
14807         gnutls_pkcs12_bag_set_key_id(key_bag, bag_index, &amp;key_id);
14808
14809
14810         /* The bags were filled. Now create the PKCS #12 structure.
14811          */
14812         gnutls_pkcs12_init(&amp;pkcs12);
14813
14814         /* Insert the two bags in the PKCS #12 structure.
14815          */
14816
14817         gnutls_pkcs12_set_bag(pkcs12, bag);
14818         gnutls_pkcs12_set_bag(pkcs12, key_bag);
14819
14820
14821         /* Generate a message authentication code for the PKCS #12
14822          * structure.
14823          */
14824         gnutls_pkcs12_generate_mac(pkcs12, password);
14825
14826         pkcs12_struct_size = sizeof(pkcs12_struct);
14827         ret =
14828             gnutls_pkcs12_export(pkcs12, GNUTLS_X509_FMT_DER,
14829                                  pkcs12_struct, &amp;pkcs12_struct_size);
14830         if (ret &lt; 0) {
14831                 fprintf(stderr, &quot;ret: %s\n&quot;, gnutls_strerror(ret));
14832                 return 1;
14833         }
14834
14835         fd = fopen(OUTFILE, &quot;w&quot;);
14836         if (fd == NULL) {
14837                 fprintf(stderr, &quot;cannot open file\n&quot;);
14838                 return 1;
14839         }
14840         fwrite(pkcs12_struct, 1, pkcs12_struct_size, fd);
14841         fclose(fd);
14842
14843         gnutls_pkcs12_bag_deinit(bag);
14844         gnutls_pkcs12_bag_deinit(key_bag);
14845         gnutls_pkcs12_deinit(pkcs12);
14846
14847         return 0;
14848 }
14849 </pre>
14850
14851 <hr>
14852 <a name="Using-GnuTLS-as-a-cryptographic-library"></a>
14853 <div class="header">
14854 <p>
14855 Next: <a href="#Other-included-programs" accesskey="n" rel="next">Other included programs</a>, Previous: <a href="#GnuTLS-application-examples" accesskey="p" rel="prev">GnuTLS application examples</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
14856 </div>
14857 <a name="Using-GnuTLS-as-a-cryptographic-library-1"></a>
14858 <h2 class="chapter">8 Using GnuTLS as a cryptographic library</h2>
14859
14860 <p><acronym>GnuTLS</acronym> is not a low-level cryptographic library, i.e.,
14861 it does not provide access to basic cryptographic primitives. However
14862 it abstracts the internal cryptographic back-end (see <a href="#Cryptographic-Backend">Cryptographic Backend</a>),
14863 providing symmetric crypto, hash and HMAC algorithms, as well access
14864 to the random number generation. For a low-level crypto API the usage of nettle
14865 <a name="DOCF16" href="#FOOT16"><sup>16</sup></a> library is recommended.
14866 </p>
14867 <table class="menu" border="0" cellspacing="0">
14868 <tr><td align="left" valign="top">&bull; <a href="#Symmetric-algorithms" accesskey="1">Symmetric algorithms</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
14869 </td></tr>
14870 <tr><td align="left" valign="top">&bull; <a href="#Public-key-algorithms" accesskey="2">Public key algorithms</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
14871 </td></tr>
14872 <tr><td align="left" valign="top">&bull; <a href="#Hash-and-HMAC-functions" accesskey="3">Hash and HMAC functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
14873 </td></tr>
14874 <tr><td align="left" valign="top">&bull; <a href="#Random-number-generation" accesskey="4">Random number generation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
14875 </td></tr>
14876 </table>
14877
14878 <hr>
14879 <a name="Symmetric-algorithms"></a>
14880 <div class="header">
14881 <p>
14882 Next: <a href="#Public-key-algorithms" accesskey="n" rel="next">Public key algorithms</a>, Up: <a href="#Using-GnuTLS-as-a-cryptographic-library" accesskey="u" rel="up">Using GnuTLS as a cryptographic library</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
14883 </div>
14884 <a name="Symmetric-algorithms-1"></a>
14885 <h3 class="section">8.1 Symmetric algorithms</h3>
14886 <a name="index-symmetric-algorithms"></a>
14887 <a name="index-symmetric-cryptography"></a>
14888
14889 <p>The available functions to access symmetric crypto algorithms operations
14890 are shown below. The supported algorithms are the algorithms required by the TLS protocol.
14891 They are listed in <a href="#tab_003aciphers">Table 3.1</a>.
14892 </p>
14893 <dl compact="compact">
14894 <dt><code><var>int</var> <a href="#gnutls_005fcipher_005finit">gnutls_cipher_init</a> (gnutls_cipher_hd_t * <var>handle</var>, gnutls_cipher_algorithm_t <var>cipher</var>, const gnutls_datum_t * <var>key</var>, const gnutls_datum_t * <var>iv</var>)</code></dt>
14895 <dt><code><var>int</var> <a href="#gnutls_005fcipher_005fencrypt2">gnutls_cipher_encrypt2</a> (gnutls_cipher_hd_t <var>handle</var>, const void * <var>text</var>, size_t <var>textlen</var>, void * <var>ciphertext</var>, size_t <var>ciphertextlen</var>)</code></dt>
14896 <dt><code><var>int</var> <a href="#gnutls_005fcipher_005fdecrypt2">gnutls_cipher_decrypt2</a> (gnutls_cipher_hd_t <var>handle</var>, const void * <var>ciphertext</var>, size_t <var>ciphertextlen</var>, void * <var>text</var>, size_t <var>textlen</var>)</code></dt>
14897 <dt><code><var>void</var> <a href="#gnutls_005fcipher_005fset_005fiv">gnutls_cipher_set_iv</a> (gnutls_cipher_hd_t <var>handle</var>, void * <var>iv</var>, size_t <var>ivlen</var>)</code></dt>
14898 <dt><code><var>void</var> <a href="#gnutls_005fcipher_005fdeinit">gnutls_cipher_deinit</a> (gnutls_cipher_hd_t <var>handle</var>)</code></dt>
14899 </dl>
14900
14901 <p>In order to support authenticated encryption with associated data (AEAD) algorithms the following
14902 functions are provided to set the associated data and retrieve the authentication tag.
14903 </p>
14904 <dl compact="compact">
14905 <dt><code><var>int</var> <a href="#gnutls_005fcipher_005fadd_005fauth">gnutls_cipher_add_auth</a> (gnutls_cipher_hd_t <var>handle</var>, const void * <var>text</var>, size_t <var>text_size</var>)</code></dt>
14906 <dt><code><var>int</var> <a href="#gnutls_005fcipher_005ftag">gnutls_cipher_tag</a> (gnutls_cipher_hd_t <var>handle</var>, void * <var>tag</var>, size_t <var>tag_size</var>)</code></dt>
14907 </dl>
14908
14909 <hr>
14910 <a name="Public-key-algorithms"></a>
14911 <div class="header">
14912 <p>
14913 Next: <a href="#Hash-and-HMAC-functions" accesskey="n" rel="next">Hash and HMAC functions</a>, Previous: <a href="#Symmetric-algorithms" accesskey="p" rel="prev">Symmetric algorithms</a>, Up: <a href="#Using-GnuTLS-as-a-cryptographic-library" accesskey="u" rel="up">Using GnuTLS as a cryptographic library</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
14914 </div>
14915 <a name="Public-key-algorithms-1"></a>
14916 <h3 class="section">8.2 Public key algorithms</h3>
14917 <a name="index-public-key-algorithms"></a>
14918
14919 <p>Public key cryptography algorithms such as RSA, DSA and ECDSA, can be
14920 accessed using the abstract key API in <a href="#Abstract-key-types">Abstract key types</a>. This
14921 is a high level API with the advantage of transparently handling keys
14922 in memory and keys present in smart cards.
14923 </p>
14924 <hr>
14925 <a name="Hash-and-HMAC-functions"></a>
14926 <div class="header">
14927 <p>
14928 Next: <a href="#Random-number-generation" accesskey="n" rel="next">Random number generation</a>, Previous: <a href="#Public-key-algorithms" accesskey="p" rel="prev">Public key algorithms</a>, Up: <a href="#Using-GnuTLS-as-a-cryptographic-library" accesskey="u" rel="up">Using GnuTLS as a cryptographic library</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
14929 </div>
14930 <a name="Hash-and-HMAC-functions-1"></a>
14931 <h3 class="section">8.3 Hash and HMAC functions</h3>
14932 <a name="index-hash-functions"></a>
14933 <a name="index-HMAC-functions"></a>
14934
14935 <p>The available operations to access hash functions and hash-MAC (HMAC) algorithms
14936 are shown below. HMAC algorithms provided keyed hash functionality. They supported HMAC algorithms are listed in <a href="#tab_003amacs">Table 3.2</a>.
14937 </p>
14938 <dl compact="compact">
14939 <dt><code><var>int</var> <a href="#gnutls_005fhmac_005finit">gnutls_hmac_init</a> (gnutls_hmac_hd_t * <var>dig</var>, gnutls_mac_algorithm_t <var>algorithm</var>, const void * <var>key</var>, size_t <var>keylen</var>)</code></dt>
14940 <dt><code><var>int</var> <a href="#gnutls_005fhmac">gnutls_hmac</a> (gnutls_hmac_hd_t <var>handle</var>, const void * <var>text</var>, size_t <var>textlen</var>)</code></dt>
14941 <dt><code><var>void</var> <a href="#gnutls_005fhmac_005foutput">gnutls_hmac_output</a> (gnutls_hmac_hd_t <var>handle</var>, void * <var>digest</var>)</code></dt>
14942 <dt><code><var>void</var> <a href="#gnutls_005fhmac_005fdeinit">gnutls_hmac_deinit</a> (gnutls_hmac_hd_t <var>handle</var>, void * <var>digest</var>)</code></dt>
14943 <dt><code><var>int</var> <a href="#gnutls_005fhmac_005fget_005flen">gnutls_hmac_get_len</a> (gnutls_mac_algorithm_t <var>algorithm</var>)</code></dt>
14944 <dt><code><var>int</var> <a href="#gnutls_005fhmac_005ffast">gnutls_hmac_fast</a> (gnutls_mac_algorithm_t <var>algorithm</var>, const void * <var>key</var>, size_t <var>keylen</var>, const void * <var>text</var>, size_t <var>textlen</var>, void * <var>digest</var>)</code></dt>
14945 </dl>
14946
14947 <p>The available functions to access hash functions are shown below. The supported hash functions
14948 are the same as the HMAC algorithms.
14949 </p>
14950 <dl compact="compact">
14951 <dt><code><var>int</var> <a href="#gnutls_005fhash_005finit">gnutls_hash_init</a> (gnutls_hash_hd_t * <var>dig</var>, gnutls_digest_algorithm_t <var>algorithm</var>)</code></dt>
14952 <dt><code><var>int</var> <a href="#gnutls_005fhash">gnutls_hash</a> (gnutls_hash_hd_t <var>handle</var>, const void * <var>text</var>, size_t <var>textlen</var>)</code></dt>
14953 <dt><code><var>void</var> <a href="#gnutls_005fhash_005foutput">gnutls_hash_output</a> (gnutls_hash_hd_t <var>handle</var>, void * <var>digest</var>)</code></dt>
14954 <dt><code><var>void</var> <a href="#gnutls_005fhash_005fdeinit">gnutls_hash_deinit</a> (gnutls_hash_hd_t <var>handle</var>, void * <var>digest</var>)</code></dt>
14955 <dt><code><var>int</var> <a href="#gnutls_005fhash_005fget_005flen">gnutls_hash_get_len</a> (gnutls_digest_algorithm_t <var>algorithm</var>)</code></dt>
14956 <dt><code><var>int</var> <a href="#gnutls_005fhash_005ffast">gnutls_hash_fast</a> (gnutls_digest_algorithm_t <var>algorithm</var>, const void * <var>text</var>, size_t <var>textlen</var>, void * <var>digest</var>)</code></dt>
14957 </dl>
14958 <dl compact="compact">
14959 <dt><code><var>int</var> <a href="#gnutls_005ffingerprint">gnutls_fingerprint</a> (gnutls_digest_algorithm_t <var>algo</var>, const gnutls_datum_t * <var>data</var>, void * <var>result</var>, size_t * <var>result_size</var>)</code></dt>
14960 </dl>
14961
14962 <hr>
14963 <a name="Random-number-generation"></a>
14964 <div class="header">
14965 <p>
14966 Previous: <a href="#Hash-and-HMAC-functions" accesskey="p" rel="prev">Hash and HMAC functions</a>, Up: <a href="#Using-GnuTLS-as-a-cryptographic-library" accesskey="u" rel="up">Using GnuTLS as a cryptographic library</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
14967 </div>
14968 <a name="Random-number-generation-1"></a>
14969 <h3 class="section">8.4 Random number generation</h3>
14970 <a name="index-random-numbers"></a>
14971
14972 <p>Access to the random number generator is provided using the <a href="#gnutls_005frnd">gnutls_rnd</a>
14973 function. It allows obtaining random data of various levels.
14974 </p>
14975 <div class="float"><a name="gnutls_005frnd_005flevel_005ft"></a>
14976
14977
14978 <dl compact="compact">
14979 <dt><code>GNUTLS_RND_NONCE</code></dt>
14980 <dd><p>Non-predictable random number.  Fatal in parts
14981 of session if broken, i.e., vulnerable to statistical analysis.
14982 </p></dd>
14983 <dt><code>GNUTLS_RND_RANDOM</code></dt>
14984 <dd><p>Pseudo-random cryptographic random number.
14985 Fatal in session if broken.
14986 </p></dd>
14987 <dt><code>GNUTLS_RND_KEY</code></dt>
14988 <dd><p>Fatal in many sessions if broken.
14989 </p></dd>
14990 </dl>
14991
14992 <div class="float-caption"><p><strong>Figure 8.1: </strong>The random number levels.</p></div></div>
14993
14994
14995
14996 <dl>
14997 <dt><a name="index-gnutls_005frnd"></a>Function: <em>int</em> <strong>gnutls_rnd</strong> <em>(gnutls_rnd_level_t <var>level</var>, void * <var>data</var>, size_t <var>len</var>)</em></dt>
14998 <dd><p><var>level</var>: a security level
14999 </p>
15000 <p><var>data</var>: place to store random bytes
15001 </p>
15002 <p><var>len</var>: The requested size
15003 </p>
15004 <p>This function will generate random data and store it to output
15005 buffer.
15006 </p>
15007 <p>This function is thread-safe and also fork-safe.
15008 </p>
15009 <p><strong>Returns:</strong> Zero on success, or a negative error code on error.
15010 </p>
15011 <p><strong>Since:</strong> 2.12.0
15012 </p></dd></dl>
15013
15014 <hr>
15015 <a name="Other-included-programs"></a>
15016 <div class="header">
15017 <p>
15018 Next: <a href="#Internal-architecture-of-GnuTLS" accesskey="n" rel="next">Internal architecture of GnuTLS</a>, Previous: <a href="#Using-GnuTLS-as-a-cryptographic-library" accesskey="p" rel="prev">Using GnuTLS as a cryptographic library</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
15019 </div>
15020 <a name="Other-included-programs-1"></a>
15021 <h2 class="chapter">9 Other included programs</h2>
15022
15023 <p>Included with <acronym>GnuTLS</acronym> are also a few command line tools that
15024 let you use the library for common tasks without writing an
15025 application.  The applications are discussed in this chapter.
15026 </p>
15027 <table class="menu" border="0" cellspacing="0">
15028 <tr><td align="left" valign="top">&bull; <a href="#gnutls_002dcli-Invocation" accesskey="1">gnutls-cli Invocation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Invoking gnutls-cli
15029 </td></tr>
15030 <tr><td align="left" valign="top">&bull; <a href="#gnutls_002dserv-Invocation" accesskey="2">gnutls-serv Invocation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Invoking gnutls-serv
15031 </td></tr>
15032 <tr><td align="left" valign="top">&bull; <a href="#gnutls_002dcli_002ddebug-Invocation" accesskey="3">gnutls-cli-debug Invocation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Invoking gnutls-cli-debug
15033 </td></tr>
15034 </table>
15035
15036 <hr>
15037 <a name="gnutls_002dcli-Invocation"></a>
15038 <div class="header">
15039 <p>
15040 Next: <a href="#gnutls_002dserv-Invocation" accesskey="n" rel="next">gnutls-serv Invocation</a>, Up: <a href="#Other-included-programs" accesskey="u" rel="up">Other included programs</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
15041 </div>
15042 <a name="Invoking-gnutls_002dcli"></a>
15043 <h3 class="section">9.1 Invoking gnutls-cli</h3>
15044 <a name="index-gnutls_002dcli"></a>
15045
15046
15047 <p>Simple client program to set up a TLS connection to some other computer.
15048 It sets up a TLS connection and forwards data from the standard input to the secured socket and vice versa.
15049 </p>
15050 <p>This section was generated by <strong>AutoGen</strong>,
15051 using the <code>agtexi-cmd</code> template and the option descriptions for the <code>gnutls-cli</code> program.
15052 This software is released under the GNU General Public License, version 3 or later.
15053 </p>
15054
15055 <a name="gnutls_002dcli-usage"></a><a name="gnutls_002dcli-help_002fusage-_0028_002d_002dhelp_0029"></a>
15056 <h4 class="subheading">gnutls-cli help/usage (<samp>--help</samp>)</h4>
15057 <a name="index-gnutls_002dcli-help"></a>
15058
15059 <p>This is the automatically generated usage text for gnutls-cli.
15060 </p>
15061 <p>The text printed is the same whether selected with the <code>help</code> option
15062 (<samp>--help</samp>) or the <code>more-help</code> option (<samp>--more-help</samp>).  <code>more-help</code> will print
15063 the usage text by passing it through a pager program.
15064 <code>more-help</code> is disabled on platforms without a working
15065 <code>fork(2)</code> function.  The <code>PAGER</code> environment variable is
15066 used to select the program, defaulting to <samp>more</samp>.  Both will exit
15067 with a status code of 0.
15068 </p>
15069 <div class="example">
15070 <pre class="example">gnutls-cli is unavailable - no --help
15071 </pre></div>
15072
15073 <a name="gnutls_002dcli-debug"></a><a name="debug-option-_0028_002dd_0029-7"></a>
15074 <h4 class="subheading">debug option (-d)</h4>
15075
15076 <p>This is the &ldquo;enable debugging&rdquo; option.
15077 This option takes a number argument.
15078 Specifies the debug level.
15079 <a name="gnutls_002dcli-tofu"></a></p><a name="tofu-option"></a>
15080 <h4 class="subheading">tofu option</h4>
15081
15082 <p>This is the &ldquo;enable trust on first use authentication&rdquo; option.
15083 </p>
15084 <p>This option has some usage constraints.  It:
15085 </p><ul>
15086 <li> can be disabled with &ndash;no-tofu.
15087 </li></ul>
15088
15089 <p>This option will, in addition to certificate authentication, perform authentication
15090 based on previously seen public keys, a model similar to SSH authentication. Note that when tofu
15091 is specified (PKI) and DANE authentication will become advisory to assist the public key acceptance
15092 process.
15093 <a name="gnutls_002dcli-strict_002dtofu"></a></p><a name="strict_002dtofu-option"></a>
15094 <h4 class="subheading">strict-tofu option</h4>
15095
15096 <p>This is the &ldquo;fail to connect if a known certificate has changed&rdquo; option.
15097 </p>
15098 <p>This option has some usage constraints.  It:
15099 </p><ul>
15100 <li> can be disabled with &ndash;no-strict-tofu.
15101 </li></ul>
15102
15103 <p>This option will perform authentication as with option &ndash;tofu; however, while &ndash;tofu asks whether to trust a changed public key, this option will fail in case of public key changes.
15104 <a name="gnutls_002dcli-dane"></a></p><a name="dane-option"></a>
15105 <h4 class="subheading">dane option</h4>
15106
15107 <p>This is the &ldquo;enable dane certificate verification (dnssec)&rdquo; option.
15108 </p>
15109 <p>This option has some usage constraints.  It:
15110 </p><ul>
15111 <li> can be disabled with &ndash;no-dane.
15112 </li></ul>
15113
15114 <p>This option will, in addition to certificate authentication using
15115 the trusted CAs, verify the server certificates using on the DANE information
15116 available via DNSSEC.
15117 <a name="gnutls_002dcli-local_002ddns"></a></p><a name="local_002ddns-option-1"></a>
15118 <h4 class="subheading">local-dns option</h4>
15119
15120 <p>This is the &ldquo;use the local dns server for dnssec resolving&rdquo; option.
15121 </p>
15122 <p>This option has some usage constraints.  It:
15123 </p><ul>
15124 <li> can be disabled with &ndash;no-local-dns.
15125 </li></ul>
15126
15127 <p>This option will use the local DNS server for DNSSEC.
15128 This is disabled by default due to many servers not allowing DNSSEC.
15129 <a name="gnutls_002dcli-ca_002dverification"></a></p><a name="ca_002dverification-option"></a>
15130 <h4 class="subheading">ca-verification option</h4>
15131
15132 <p>This is the &ldquo;disable ca certificate verification&rdquo; option.
15133 </p>
15134 <p>This option has some usage constraints.  It:
15135 </p><ul>
15136 <li> can be disabled with &ndash;no-ca-verification.
15137 </li><li> It is enabled by default.
15138 </li></ul>
15139
15140 <p>This option will disable CA certificate verification. It is to be used with the &ndash;dane or &ndash;tofu options.
15141 <a name="gnutls_002dcli-ocsp"></a></p><a name="ocsp-option"></a>
15142 <h4 class="subheading">ocsp option</h4>
15143
15144 <p>This is the &ldquo;enable ocsp certificate verification&rdquo; option.
15145 </p>
15146 <p>This option has some usage constraints.  It:
15147 </p><ul>
15148 <li> can be disabled with &ndash;no-ocsp.
15149 </li></ul>
15150
15151 <p>This option will enable verification of the peer&rsquo;s certificate using ocsp
15152 <a name="gnutls_002dcli-resume"></a></p><a name="resume-option-_0028_002dr_0029"></a>
15153 <h4 class="subheading">resume option (-r)</h4>
15154
15155 <p>This is the &ldquo;establish a session and resume&rdquo; option.
15156 Connect, establish a session, reconnect and resume.
15157 <a name="gnutls_002dcli-rehandshake"></a></p><a name="rehandshake-option-_0028_002de_0029"></a>
15158 <h4 class="subheading">rehandshake option (-e)</h4>
15159
15160 <p>This is the &ldquo;establish a session and rehandshake&rdquo; option.
15161 Connect, establish a session and rehandshake immediately.
15162 <a name="gnutls_002dcli-starttls"></a></p><a name="starttls-option-_0028_002ds_0029"></a>
15163 <h4 class="subheading">starttls option (-s)</h4>
15164
15165 <p>This is the &ldquo;connect, establish a plain session and start tls&rdquo; option.
15166 The TLS session will be initiated when EOF or a SIGALRM is received.
15167 <a name="gnutls_002dcli-app_002dproto"></a></p><a name="app_002dproto-option-1"></a>
15168 <h4 class="subheading">app-proto option</h4>
15169
15170 <p>This is an alias for the <code>starttls-proto</code> option,
15171 see <a href="#gnutls_002dcli-starttls_002dproto">the starttls-proto option documentation</a>.
15172 </p>
15173 <a name="gnutls_002dcli-starttls_002dproto"></a><a name="starttls_002dproto-option"></a>
15174 <h4 class="subheading">starttls-proto option</h4>
15175
15176 <p>This is the &ldquo;the application protocol to be used to obtain the server&rsquo;s certificate (https, ftp, smtp, imap)&rdquo; option.
15177 This option takes a string argument.
15178 </p>
15179 <p>This option has some usage constraints.  It:
15180 </p><ul>
15181 <li> must not appear in combination with any of the following options:
15182 starttls.
15183 </li></ul>
15184
15185 <p>Specify the application layer protocol for STARTTLS. If the protocol is supported, gnutls-cli will proceed to the TLS negotiation.
15186 <a name="gnutls_002dcli-dh_002dbits"></a></p><a name="dh_002dbits-option"></a>
15187 <h4 class="subheading">dh-bits option</h4>
15188
15189 <p>This is the &ldquo;the minimum number of bits allowed for dh&rdquo; option.
15190 This option takes a number argument.
15191 This option sets the minimum number of bits allowed for a Diffie-Hellman key exchange. You may want to lower the default value if the peer sends a weak prime and you get an connection error with unacceptable prime.
15192 <a name="gnutls_002dcli-priority"></a></p><a name="priority-option"></a>
15193 <h4 class="subheading">priority option</h4>
15194
15195 <p>This is the &ldquo;priorities string&rdquo; option.
15196 This option takes a string argument.
15197 TLS algorithms and protocols to enable. You can
15198 use predefined sets of ciphersuites such as PERFORMANCE,
15199 NORMAL, PFS, SECURE128, SECURE256. The default is NORMAL.
15200 </p>
15201 <p>Check  the  GnuTLS  manual  on  section  &ldquo;Priority strings&rdquo; for more
15202 information on the allowed keywords
15203 <a name="gnutls_002dcli-ranges"></a></p><a name="ranges-option"></a>
15204 <h4 class="subheading">ranges option</h4>
15205
15206 <p>This is the &ldquo;use length-hiding padding to prevent traffic analysis&rdquo; option.
15207 When possible (e.g., when using CBC ciphersuites), use length-hiding padding to prevent traffic analysis.
15208 <a name="gnutls_002dcli-list"></a></p><a name="list-option-_0028_002dl_0029"></a>
15209 <h4 class="subheading">list option (-l)</h4>
15210
15211 <p>This is the &ldquo;print a list of the supported algorithms and modes&rdquo; option.
15212 </p>
15213 <p>This option has some usage constraints.  It:
15214 </p><ul>
15215 <li> must not appear in combination with any of the following options:
15216 port.
15217 </li></ul>
15218
15219 <p>Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown.
15220 <a name="gnutls_002dcli-alpn"></a></p><a name="alpn-option"></a>
15221 <h4 class="subheading">alpn option</h4>
15222
15223 <p>This is the &ldquo;application layer protocol&rdquo; option.
15224 This option takes a string argument.
15225 </p>
15226 <p>This option has some usage constraints.  It:
15227 </p><ul>
15228 <li> may appear an unlimited number of times.
15229 </li></ul>
15230
15231 <p>This option will set and enable the Application Layer Protocol Negotiation  (ALPN) in the TLS protocol.
15232 <a name="gnutls_002dcli-disable_002dextensions"></a></p><a name="disable_002dextensions-option"></a>
15233 <h4 class="subheading">disable-extensions option</h4>
15234
15235 <p>This is the &ldquo;disable all the tls extensions&rdquo; option.
15236 This option disables all TLS extensions. Deprecated option. Use the priority string.
15237 <a name="gnutls_002dcli-inline_002dcommands"></a></p><a name="inline_002dcommands-option"></a>
15238 <h4 class="subheading">inline-commands option</h4>
15239
15240 <p>This is the &ldquo;inline commands of the form ^&lt;cmd&gt;^&rdquo; option.
15241 Enable inline commands of the form ^&lt;cmd&gt;^. The inline commands are expected to be in a line by themselves. The available commands are: resume and renegotiate.
15242 <a name="gnutls_002dcli-inline_002dcommands_002dprefix"></a></p><a name="inline_002dcommands_002dprefix-option"></a>
15243 <h4 class="subheading">inline-commands-prefix option</h4>
15244
15245 <p>This is the &ldquo;change the default delimiter for inline commands.&rdquo; option.
15246 This option takes a string argument.
15247 Change the default delimiter (^) used for inline commands. The delimiter is expected to be a single US-ASCII character (octets 0 - 127). This option is only relevant if inline commands are enabled via the inline-commands option
15248 <a name="gnutls_002dcli-provider"></a></p><a name="provider-option-2"></a>
15249 <h4 class="subheading">provider option</h4>
15250
15251 <p>This is the &ldquo;specify the pkcs #11 provider library&rdquo; option.
15252 This option takes a file argument.
15253 This will override the default options in /etc/gnutls/pkcs11.conf
15254 <a name="gnutls_002dcli-exit-status"></a></p><a name="gnutls_002dcli-exit-status-1"></a>
15255 <h4 class="subheading">gnutls-cli exit status</h4>
15256
15257 <p>One of the following exit values will be returned:
15258 </p><dl compact="compact">
15259 <dt>&lsquo;<samp>0 (EXIT_SUCCESS)</samp>&rsquo;</dt>
15260 <dd><p>Successful program execution.
15261 </p></dd>
15262 <dt>&lsquo;<samp>1 (EXIT_FAILURE)</samp>&rsquo;</dt>
15263 <dd><p>The operation failed or the command syntax was not valid.
15264 </p></dd>
15265 </dl>
15266 <a name="gnutls_002dcli-See-Also"></a><a name="gnutls_002dcli-See-Also-1"></a>
15267 <h4 class="subheading">gnutls-cli See Also</h4>
15268 <p>gnutls-cli-debug(1), gnutls-serv(1)
15269 <a name="gnutls_002dcli-Examples"></a></p><a name="gnutls_002dcli-Examples-1"></a>
15270 <h4 class="subheading">gnutls-cli Examples</h4>
15271 <a name="Connecting-using-PSK-authentication"></a>
15272 <h4 class="subheading">Connecting using PSK authentication</h4>
15273 <p>To connect to a server using PSK authentication, you need to enable the choice of PSK by using a cipher priority parameter such as in the example below.
15274 </p><div class="example">
15275 <pre class="example">$ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
15276     --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
15277     --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
15278 Resolving 'localhost'...
15279 Connecting to '127.0.0.1:5556'...
15280 - PSK authentication.
15281 - Version: TLS1.1
15282 - Key Exchange: PSK
15283 - Cipher: AES-128-CBC
15284 - MAC: SHA1
15285 - Compression: NULL
15286 - Handshake was completed
15287
15288 - Simple Client Mode:
15289 </pre></div>
15290 <p>By keeping the &ndash;pskusername parameter and removing the &ndash;pskkey parameter, it will query only for the password during the handshake.
15291 </p>
15292 <a name="Listing-ciphersuites-in-a-priority-string"></a>
15293 <h4 class="subheading">Listing ciphersuites in a priority string</h4>
15294 <p>To list the ciphersuites in a priority string:
15295 </p><div class="example">
15296 <pre class="example">$ ./gnutls-cli --priority SECURE192 -l
15297 Cipher suites for SECURE192
15298 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384         0xc0, 0x24   TLS1.2
15299 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384         0xc0, 0x2e   TLS1.2
15300 TLS_ECDHE_RSA_AES_256_GCM_SHA384           0xc0, 0x30   TLS1.2
15301 TLS_DHE_RSA_AES_256_CBC_SHA256             0x00, 0x6b   TLS1.2
15302 TLS_DHE_DSS_AES_256_CBC_SHA256             0x00, 0x6a   TLS1.2
15303 TLS_RSA_AES_256_CBC_SHA256                 0x00, 0x3d   TLS1.2
15304
15305 Certificate types: CTYPE-X.509
15306 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
15307 Compression: COMP-NULL
15308 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
15309 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
15310 </pre></div>
15311
15312 <a name="Connecting-using-a-PKCS-_002311-token"></a>
15313 <h4 class="subheading">Connecting using a PKCS #11 token</h4>
15314 <p>To connect to a server using a certificate and a private key present in a PKCS #11 token you
15315 need to substitute the PKCS 11 URLs in the x509certfile and x509keyfile parameters.
15316 </p>
15317 <p>Those can be found using &quot;p11tool &ndash;list-tokens&quot; and then listing all the objects in the
15318 needed token, and using the appropriate.
15319 </p><div class="example">
15320 <pre class="example">$ p11tool --list-tokens
15321
15322 Token 0:
15323 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
15324 Label: Test
15325 Manufacturer: EnterSafe
15326 Model: PKCS15
15327 Serial: 1234
15328
15329 $ p11tool --login --list-certs &quot;pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test&quot;
15330
15331 Object 0:
15332 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=cert
15333 Type: X.509 Certificate
15334 Label: client
15335 ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
15336
15337 $ export MYCERT=&quot;pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=cert&quot;
15338 $ export MYKEY=&quot;pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=private&quot;
15339
15340 $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile MYCERT
15341 </pre></div>
15342 <p>Notice that the private key only differs from the certificate in the object-type.
15343 </p><hr>
15344 <a name="gnutls_002dserv-Invocation"></a>
15345 <div class="header">
15346 <p>
15347 Next: <a href="#gnutls_002dcli_002ddebug-Invocation" accesskey="n" rel="next">gnutls-cli-debug Invocation</a>, Previous: <a href="#gnutls_002dcli-Invocation" accesskey="p" rel="prev">gnutls-cli Invocation</a>, Up: <a href="#Other-included-programs" accesskey="u" rel="up">Other included programs</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
15348 </div>
15349 <a name="Invoking-gnutls_002dserv"></a>
15350 <h3 class="section">9.2 Invoking gnutls-serv</h3>
15351 <a name="index-gnutls_002dserv"></a>
15352
15353
15354 <p>Server program that listens to incoming TLS connections.
15355 </p>
15356 <p>This section was generated by <strong>AutoGen</strong>,
15357 using the <code>agtexi-cmd</code> template and the option descriptions for the <code>gnutls-serv</code> program.
15358 This software is released under the GNU General Public License, version 3 or later.
15359 </p>
15360
15361 <a name="gnutls_002dserv-usage"></a><a name="gnutls_002dserv-help_002fusage-_0028_002d_002dhelp_0029"></a>
15362 <h4 class="subheading">gnutls-serv help/usage (<samp>--help</samp>)</h4>
15363 <a name="index-gnutls_002dserv-help"></a>
15364
15365 <p>This is the automatically generated usage text for gnutls-serv.
15366 </p>
15367 <p>The text printed is the same whether selected with the <code>help</code> option
15368 (<samp>--help</samp>) or the <code>more-help</code> option (<samp>--more-help</samp>).  <code>more-help</code> will print
15369 the usage text by passing it through a pager program.
15370 <code>more-help</code> is disabled on platforms without a working
15371 <code>fork(2)</code> function.  The <code>PAGER</code> environment variable is
15372 used to select the program, defaulting to <samp>more</samp>.  Both will exit
15373 with a status code of 0.
15374 </p>
15375 <div class="example">
15376 <pre class="example">gnutls-serv is unavailable - no --help
15377 </pre></div>
15378
15379 <a name="gnutls_002dserv-debug"></a><a name="debug-option-_0028_002dd_0029-8"></a>
15380 <h4 class="subheading">debug option (-d)</h4>
15381
15382 <p>This is the &ldquo;enable debugging&rdquo; option.
15383 This option takes a number argument.
15384 Specifies the debug level.
15385 <a name="gnutls_002dserv-verify_002dclient_002dcert"></a></p><a name="verify_002dclient_002dcert-option"></a>
15386 <h4 class="subheading">verify-client-cert option</h4>
15387
15388 <p>This is the &ldquo;if a client certificate is sent then verify it.&rdquo; option.
15389 Do not require, but if a client certificate is sent then verify it and close the connection if invalid.
15390 <a name="gnutls_002dserv-heartbeat"></a></p><a name="heartbeat-option-_0028_002db_0029"></a>
15391 <h4 class="subheading">heartbeat option (-b)</h4>
15392
15393 <p>This is the &ldquo;activate heartbeat support&rdquo; option.
15394 Regularly ping client via heartbeat extension messages
15395 <a name="gnutls_002dserv-priority"></a></p><a name="priority-option-1"></a>
15396 <h4 class="subheading">priority option</h4>
15397
15398 <p>This is the &ldquo;priorities string&rdquo; option.
15399 This option takes a string argument.
15400 TLS algorithms and protocols to enable. You can
15401 use predefined sets of ciphersuites such as PERFORMANCE,
15402 NORMAL, SECURE128, SECURE256. The default is NORMAL.
15403 </p>
15404 <p>Check  the  GnuTLS  manual  on  section  &ldquo;Priority strings&rdquo; for more
15405 information on allowed keywords
15406 <a name="gnutls_002dserv-ocsp_002dresponse"></a></p><a name="ocsp_002dresponse-option"></a>
15407 <h4 class="subheading">ocsp-response option</h4>
15408
15409 <p>This is the &ldquo;the ocsp response to send to client&rdquo; option.
15410 This option takes a file argument.
15411 If the client requested an OCSP response, return data from this file to the client.
15412 <a name="gnutls_002dserv-list"></a></p><a name="list-option-_0028_002dl_0029-1"></a>
15413 <h4 class="subheading">list option (-l)</h4>
15414
15415 <p>This is the &ldquo;print a list of the supported algorithms and modes&rdquo; option.
15416 Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown.
15417 <a name="gnutls_002dserv-provider"></a></p><a name="provider-option-3"></a>
15418 <h4 class="subheading">provider option</h4>
15419
15420 <p>This is the &ldquo;specify the pkcs #11 provider library&rdquo; option.
15421 This option takes a file argument.
15422 This will override the default options in /etc/gnutls/pkcs11.conf
15423 <a name="gnutls_002dserv-exit-status"></a></p><a name="gnutls_002dserv-exit-status-1"></a>
15424 <h4 class="subheading">gnutls-serv exit status</h4>
15425
15426 <p>One of the following exit values will be returned:
15427 </p><dl compact="compact">
15428 <dt>&lsquo;<samp>0 (EXIT_SUCCESS)</samp>&rsquo;</dt>
15429 <dd><p>Successful program execution.
15430 </p></dd>
15431 <dt>&lsquo;<samp>1 (EXIT_FAILURE)</samp>&rsquo;</dt>
15432 <dd><p>The operation failed or the command syntax was not valid.
15433 </p></dd>
15434 </dl>
15435 <a name="gnutls_002dserv-See-Also"></a><a name="gnutls_002dserv-See-Also-1"></a>
15436 <h4 class="subheading">gnutls-serv See Also</h4>
15437 <p>gnutls-cli-debug(1), gnutls-cli(1)
15438 <a name="gnutls_002dserv-Examples"></a></p><a name="gnutls_002dserv-Examples-1"></a>
15439 <h4 class="subheading">gnutls-serv Examples</h4>
15440 <p>Running your own TLS server based on GnuTLS can be useful when
15441 debugging clients and/or GnuTLS itself.  This section describes how to
15442 use <code>gnutls-serv</code> as a simple HTTPS server.
15443 </p>
15444 <p>The most basic server can be started as:
15445 </p>
15446 <div class="example">
15447 <pre class="example">gnutls-serv --http --priority &quot;NORMAL:+ANON-ECDH:+ANON-DH&quot;
15448 </pre></div>
15449
15450 <p>It will only support anonymous ciphersuites, which many TLS clients
15451 refuse to use.
15452 </p>
15453 <p>The next step is to add support for X.509.  First we generate a CA:
15454 </p>
15455 <div class="example">
15456 <pre class="example">$ certtool --generate-privkey &gt; x509-ca-key.pem
15457 $ echo 'cn = GnuTLS test CA' &gt; ca.tmpl
15458 $ echo 'ca' &gt;&gt; ca.tmpl
15459 $ echo 'cert_signing_key' &gt;&gt; ca.tmpl
15460 $ certtool --generate-self-signed --load-privkey x509-ca-key.pem \
15461   --template ca.tmpl --outfile x509-ca.pem
15462 ...
15463 </pre></div>
15464
15465 <p>Then generate a server certificate.  Remember to change the dns_name
15466 value to the name of your server host, or skip that command to avoid
15467 the field.
15468 </p>
15469 <div class="example">
15470 <pre class="example">$ certtool --generate-privkey &gt; x509-server-key.pem
15471 $ echo 'organization = GnuTLS test server' &gt; server.tmpl
15472 $ echo 'cn = test.gnutls.org' &gt;&gt; server.tmpl
15473 $ echo 'tls_www_server' &gt;&gt; server.tmpl
15474 $ echo 'encryption_key' &gt;&gt; server.tmpl
15475 $ echo 'signing_key' &gt;&gt; server.tmpl
15476 $ echo 'dns_name = test.gnutls.org' &gt;&gt; server.tmpl
15477 $ certtool --generate-certificate --load-privkey x509-server-key.pem \
15478   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
15479   --template server.tmpl --outfile x509-server.pem
15480 ...
15481 </pre></div>
15482
15483 <p>For use in the client, you may want to generate a client certificate
15484 as well.
15485 </p>
15486 <div class="example">
15487 <pre class="example">$ certtool --generate-privkey &gt; x509-client-key.pem
15488 $ echo 'cn = GnuTLS test client' &gt; client.tmpl
15489 $ echo 'tls_www_client' &gt;&gt; client.tmpl
15490 $ echo 'encryption_key' &gt;&gt; client.tmpl
15491 $ echo 'signing_key' &gt;&gt; client.tmpl
15492 $ certtool --generate-certificate --load-privkey x509-client-key.pem \
15493   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
15494   --template client.tmpl --outfile x509-client.pem
15495 ...
15496 </pre></div>
15497
15498 <p>To be able to import the client key/certificate into some
15499 applications, you will need to convert them into a PKCS#12 structure.
15500 This also encrypts the security sensitive key with a password.
15501 </p>
15502 <div class="example">
15503 <pre class="example">$ certtool --to-p12 --load-ca-certificate x509-ca.pem \
15504   --load-privkey x509-client-key.pem --load-certificate x509-client.pem \
15505   --outder --outfile x509-client.p12
15506 </pre></div>
15507
15508 <p>For icing, we&rsquo;ll create a proxy certificate for the client too.
15509 </p>
15510 <div class="example">
15511 <pre class="example">$ certtool --generate-privkey &gt; x509-proxy-key.pem
15512 $ echo 'cn = GnuTLS test client proxy' &gt; proxy.tmpl
15513 $ certtool --generate-proxy --load-privkey x509-proxy-key.pem \
15514   --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \
15515   --load-certificate x509-client.pem --template proxy.tmpl \
15516   --outfile x509-proxy.pem
15517 ...
15518 </pre></div>
15519
15520 <p>Then start the server again:
15521 </p>
15522 <div class="example">
15523 <pre class="example">$ gnutls-serv --http \
15524             --x509cafile x509-ca.pem \
15525             --x509keyfile x509-server-key.pem \
15526             --x509certfile x509-server.pem
15527 </pre></div>
15528
15529 <p>Try connecting to the server using your web browser.  Note that the
15530 server listens to port 5556 by default.
15531 </p>
15532 <p>While you are at it, to allow connections using DSA, you can also
15533 create a DSA key and certificate for the server.  These credentials
15534 will be used in the final example below.
15535 </p>
15536 <div class="example">
15537 <pre class="example">$ certtool --generate-privkey --dsa &gt; x509-server-key-dsa.pem
15538 $ certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \
15539   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
15540   --template server.tmpl --outfile x509-server-dsa.pem
15541 ...
15542 </pre></div>
15543
15544 <p>The next step is to create OpenPGP credentials for the server.
15545 </p>
15546 <div class="example">
15547 <pre class="example">gpg --gen-key
15548 ...enter whatever details you want, use 'test.gnutls.org' as name...
15549 </pre></div>
15550
15551 <p>Make a note of the OpenPGP key identifier of the newly generated key,
15552 here it was <code>5D1D14D8</code>.  You will need to export the key for
15553 GnuTLS to be able to use it.
15554 </p>
15555 <div class="example">
15556 <pre class="example">gpg -a --export 5D1D14D8 &gt; openpgp-server.txt
15557 gpg --export 5D1D14D8 &gt; openpgp-server.bin
15558 gpg --export-secret-keys 5D1D14D8 &gt; openpgp-server-key.bin
15559 gpg -a --export-secret-keys 5D1D14D8 &gt; openpgp-server-key.txt
15560 </pre></div>
15561
15562 <p>Let&rsquo;s start the server with support for OpenPGP credentials:
15563 </p>
15564 <div class="example">
15565 <pre class="example">gnutls-serv --http --priority NORMAL:+CTYPE-OPENPGP \
15566             --pgpkeyfile openpgp-server-key.txt \
15567             --pgpcertfile openpgp-server.txt
15568 </pre></div>
15569
15570 <p>The next step is to add support for SRP authentication. This requires
15571 an SRP password file created with <code>srptool</code>.
15572 To start the server with SRP support:
15573 </p>
15574 <div class="example">
15575 <pre class="example">gnutls-serv --http --priority NORMAL:+SRP-RSA:+SRP \
15576             --srppasswdconf srp-tpasswd.conf \
15577             --srppasswd srp-passwd.txt
15578 </pre></div>
15579
15580 <p>Let&rsquo;s also start a server with support for PSK. This would require
15581 a password file created with <code>psktool</code>.
15582 </p>
15583 <div class="example">
15584 <pre class="example">gnutls-serv --http --priority NORMAL:+ECDHE-PSK:+PSK \
15585             --pskpasswd psk-passwd.txt
15586 </pre></div>
15587
15588 <p>Finally, we start the server with all the earlier parameters and you
15589 get this command:
15590 </p>
15591 <div class="example">
15592 <pre class="example">gnutls-serv --http --priority NORMAL:+PSK:+SRP:+CTYPE-OPENPGP \
15593             --x509cafile x509-ca.pem \
15594             --x509keyfile x509-server-key.pem \
15595             --x509certfile x509-server.pem \
15596             --x509dsakeyfile x509-server-key-dsa.pem \
15597             --x509dsacertfile x509-server-dsa.pem \
15598             --pgpkeyfile openpgp-server-key.txt \
15599             --pgpcertfile openpgp-server.txt \
15600             --srppasswdconf srp-tpasswd.conf \
15601             --srppasswd srp-passwd.txt \
15602             --pskpasswd psk-passwd.txt
15603 </pre></div>
15604 <hr>
15605 <a name="gnutls_002dcli_002ddebug-Invocation"></a>
15606 <div class="header">
15607 <p>
15608 Previous: <a href="#gnutls_002dserv-Invocation" accesskey="p" rel="prev">gnutls-serv Invocation</a>, Up: <a href="#Other-included-programs" accesskey="u" rel="up">Other included programs</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
15609 </div>
15610 <a name="Invoking-gnutls_002dcli_002ddebug"></a>
15611 <h3 class="section">9.3 Invoking gnutls-cli-debug</h3>
15612 <a name="index-gnutls_002dcli_002ddebug"></a>
15613
15614
15615 <p>TLS debug client. It sets up multiple TLS connections to
15616 a server and queries its capabilities. It was created to assist in debugging
15617 GnuTLS, but it might be useful to extract a TLS server&rsquo;s capabilities.
15618 It connects to a TLS server, performs tests and print the server&rsquo;s
15619 capabilities. If called with the &lsquo;-v&rsquo; parameter more checks will be performed.
15620 Can be used to check for servers with special needs or bugs.
15621 </p>
15622 <p>This section was generated by <strong>AutoGen</strong>,
15623 using the <code>agtexi-cmd</code> template and the option descriptions for the <code>gnutls-cli-debug</code> program.
15624 This software is released under the GNU General Public License, version 3 or later.
15625 </p>
15626
15627 <a name="gnutls_002dcli_002ddebug-usage"></a><a name="gnutls_002dcli_002ddebug-help_002fusage-_0028_002d_002dhelp_0029"></a>
15628 <h4 class="subheading">gnutls-cli-debug help/usage (<samp>--help</samp>)</h4>
15629 <a name="index-gnutls_002dcli_002ddebug-help"></a>
15630
15631 <p>This is the automatically generated usage text for gnutls-cli-debug.
15632 </p>
15633 <p>The text printed is the same whether selected with the <code>help</code> option
15634 (<samp>--help</samp>) or the <code>more-help</code> option (<samp>--more-help</samp>).  <code>more-help</code> will print
15635 the usage text by passing it through a pager program.
15636 <code>more-help</code> is disabled on platforms without a working
15637 <code>fork(2)</code> function.  The <code>PAGER</code> environment variable is
15638 used to select the program, defaulting to <samp>more</samp>.  Both will exit
15639 with a status code of 0.
15640 </p>
15641 <div class="example">
15642 <pre class="example">gnutls-cli-debug is unavailable - no --help
15643 </pre></div>
15644
15645 <a name="gnutls_002dcli_002ddebug-debug"></a><a name="debug-option-_0028_002dd_0029-9"></a>
15646 <h4 class="subheading">debug option (-d)</h4>
15647
15648 <p>This is the &ldquo;enable debugging&rdquo; option.
15649 This option takes a number argument.
15650 Specifies the debug level.
15651 <a name="gnutls_002dcli_002ddebug-exit-status"></a></p><a name="gnutls_002dcli_002ddebug-exit-status-1"></a>
15652 <h4 class="subheading">gnutls-cli-debug exit status</h4>
15653
15654 <p>One of the following exit values will be returned:
15655 </p><dl compact="compact">
15656 <dt>&lsquo;<samp>0 (EXIT_SUCCESS)</samp>&rsquo;</dt>
15657 <dd><p>Successful program execution.
15658 </p></dd>
15659 <dt>&lsquo;<samp>1 (EXIT_FAILURE)</samp>&rsquo;</dt>
15660 <dd><p>The operation failed or the command syntax was not valid.
15661 </p></dd>
15662 </dl>
15663 <a name="gnutls_002dcli_002ddebug-See-Also"></a><a name="gnutls_002dcli_002ddebug-See-Also-1"></a>
15664 <h4 class="subheading">gnutls-cli-debug See Also</h4>
15665 <p>gnutls-cli(1), gnutls-serv(1)
15666 <a name="gnutls_002dcli_002ddebug-Examples"></a></p><a name="gnutls_002dcli_002ddebug-Examples-1"></a>
15667 <h4 class="subheading">gnutls-cli-debug Examples</h4>
15668 <div class="example">
15669 <pre class="example">$ ../src/gnutls-cli-debug localhost
15670 Resolving 'localhost'...
15671 Connecting to '127.0.0.1:443'...
15672 Checking for SSL 3.0 support... yes
15673 Checking whether %COMPAT is required... no
15674 Checking for TLS 1.0 support... yes
15675 Checking for TLS 1.1 support... no
15676 Checking fallback from TLS 1.1 to... TLS 1.0
15677 Checking for TLS 1.2 support... no
15678 Checking whether we need to disable TLS 1.0... N/A
15679 Checking for Safe renegotiation support... yes
15680 Checking for Safe renegotiation support (SCSV)... yes
15681 Checking for HTTPS server name... not checked
15682 Checking for version rollback bug in RSA PMS... no
15683 Checking for version rollback bug in Client Hello... no
15684 Checking whether the server ignores the RSA PMS version... no
15685 Checking whether the server can accept Hello Extensions... yes
15686 Checking whether the server can accept small records (512 bytes)... yes
15687 Checking whether the server can accept cipher suites not in SSL 3.0 spec... yes
15688 Checking whether the server can accept a bogus TLS record version in the client hello... yes
15689 Checking for certificate information... N/A
15690 Checking for trusted CAs... N/A
15691 Checking whether the server understands TLS closure alerts... partially
15692 Checking whether the server supports session resumption... yes
15693 Checking for export-grade ciphersuite support... no
15694 Checking RSA-export ciphersuite info... N/A
15695 Checking for anonymous authentication support... no
15696 Checking anonymous Diffie-Hellman group info... N/A
15697 Checking for ephemeral Diffie-Hellman support... no
15698 Checking ephemeral Diffie-Hellman group info... N/A
15699 Checking for ephemeral EC Diffie-Hellman support... yes
15700 Checking ephemeral EC Diffie-Hellman group info...
15701  Curve SECP256R1
15702 Checking for AES-GCM cipher support... no
15703 Checking for AES-CBC cipher support... yes
15704 Checking for CAMELLIA cipher support... no
15705 Checking for 3DES-CBC cipher support... yes
15706 Checking for ARCFOUR 128 cipher support... yes
15707 Checking for ARCFOUR 40 cipher support... no
15708 Checking for MD5 MAC support... yes
15709 Checking for SHA1 MAC support... yes
15710 Checking for SHA256 MAC support... no
15711 Checking for ZLIB compression support... no
15712 Checking for max record size... no
15713 Checking for OpenPGP authentication support... no
15714 </pre></div>
15715
15716 <hr>
15717 <a name="Internal-architecture-of-GnuTLS"></a>
15718 <div class="header">
15719 <p>
15720 Next: <a href="#Upgrading-from-previous-versions" accesskey="n" rel="next">Upgrading from previous versions</a>, Previous: <a href="#Other-included-programs" accesskey="p" rel="prev">Other included programs</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
15721 </div>
15722 <a name="Internal-Architecture-of-GnuTLS"></a>
15723 <h2 class="chapter">10 Internal Architecture of GnuTLS</h2>
15724 <a name="index-internal-architecture"></a>
15725
15726 <p>This chapter is to give a brief description of the
15727 way <acronym>GnuTLS</acronym> works. The focus is to give an idea
15728 to potential developers and those who want to know what
15729 happens inside the black box.
15730 </p>
15731 <table class="menu" border="0" cellspacing="0">
15732 <tr><td align="left" valign="top">&bull; <a href="#The-TLS-Protocol" accesskey="1">The TLS Protocol</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
15733 </td></tr>
15734 <tr><td align="left" valign="top">&bull; <a href="#TLS-Handshake-Protocol" accesskey="2">TLS Handshake Protocol</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
15735 </td></tr>
15736 <tr><td align="left" valign="top">&bull; <a href="#TLS-Authentication-Methods" accesskey="3">TLS Authentication Methods</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
15737 </td></tr>
15738 <tr><td align="left" valign="top">&bull; <a href="#TLS-Extension-Handling" accesskey="4">TLS Extension Handling</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
15739 </td></tr>
15740 <tr><td align="left" valign="top">&bull; <a href="#Cryptographic-Backend" accesskey="5">Cryptographic Backend</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
15741 </td></tr>
15742 </table>
15743
15744 <hr>
15745 <a name="The-TLS-Protocol"></a>
15746 <div class="header">
15747 <p>
15748 Next: <a href="#TLS-Handshake-Protocol" accesskey="n" rel="next">TLS Handshake Protocol</a>, Up: <a href="#Internal-architecture-of-GnuTLS" accesskey="u" rel="up">Internal architecture of GnuTLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
15749 </div>
15750 <a name="The-TLS-Protocol-1"></a>
15751 <h3 class="section">10.1 The TLS Protocol</h3>
15752 <p>The main use case for the TLS protocol is shown in <a href="#fig_002dclient_002dserver">Figure 10.1</a>.
15753 A user of a library implementing the protocol expects no less than this functionality,
15754 i.e., to be able to set parameters such as the accepted security level, perform a
15755 negotiation with the peer and be able to exchange data.
15756 </p>
15757 <div class="float"><a name="fig_002dclient_002dserver"></a>
15758 <img src="gnutls-client-server-use-case.png" alt="gnutls-client-server-use-case">
15759
15760 <div class="float-caption"><p><strong>Figure 10.1: </strong>TLS protocol use case.</p></div></div>
15761 <hr>
15762 <a name="TLS-Handshake-Protocol"></a>
15763 <div class="header">
15764 <p>
15765 Next: <a href="#TLS-Authentication-Methods" accesskey="n" rel="next">TLS Authentication Methods</a>, Previous: <a href="#The-TLS-Protocol" accesskey="p" rel="prev">The TLS Protocol</a>, Up: <a href="#Internal-architecture-of-GnuTLS" accesskey="u" rel="up">Internal architecture of GnuTLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
15766 </div>
15767 <a name="TLS-Handshake-Protocol-1"></a>
15768 <h3 class="section">10.2 TLS Handshake Protocol</h3>
15769 <p>The <acronym>GnuTLS</acronym> handshake protocol is implemented as a state
15770 machine that waits for input or returns immediately when the non-blocking
15771 transport layer functions are used. The main idea is shown in <a href="#fig_002dgnutls_002dhandshake">Figure 10.2</a>.
15772 </p>
15773 <div class="float"><a name="fig_002dgnutls_002dhandshake"></a>
15774 <img src="gnutls-handshake-state.png" alt="gnutls-handshake-state">
15775
15776 <div class="float-caption"><p><strong>Figure 10.2: </strong>GnuTLS handshake state machine.</p></div></div>
15777 <p>Also the way the input is processed varies per ciphersuite. Several
15778 implementations of the internal handlers are available and
15779 <a href="#gnutls_005fhandshake">gnutls_handshake</a> only multiplexes the input to the appropriate
15780 handler. For example a <acronym>PSK</acronym> ciphersuite has a different
15781 implementation of the <code>process_client_key_exchange</code> than a
15782 certificate ciphersuite. We illustrate the idea in <a href="#fig_002dgnutls_002dhandshake_002dsequence">Figure 10.3</a>.
15783 </p>
15784 <div class="float"><a name="fig_002dgnutls_002dhandshake_002dsequence"></a>
15785 <img src="gnutls-handshake-sequence.png" alt="gnutls-handshake-sequence">
15786
15787 <div class="float-caption"><p><strong>Figure 10.3: </strong>GnuTLS handshake process sequence.</p></div></div>
15788 <hr>
15789 <a name="TLS-Authentication-Methods"></a>
15790 <div class="header">
15791 <p>
15792 Next: <a href="#TLS-Extension-Handling" accesskey="n" rel="next">TLS Extension Handling</a>, Previous: <a href="#TLS-Handshake-Protocol" accesskey="p" rel="prev">TLS Handshake Protocol</a>, Up: <a href="#Internal-architecture-of-GnuTLS" accesskey="u" rel="up">Internal architecture of GnuTLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
15793 </div>
15794 <a name="TLS-Authentication-Methods-1"></a>
15795 <h3 class="section">10.3 TLS Authentication Methods</h3>
15796 <p>In <acronym>GnuTLS</acronym> authentication methods can be implemented quite
15797 easily.  Since the required changes to add a new authentication method
15798 affect only the handshake protocol, a simple interface is used. An
15799 authentication method needs to implement the functions shown below.
15800 </p>
15801 <pre class="verbatim">typedef struct
15802 {
15803   const char *name;
15804   int (*gnutls_generate_server_certificate) (gnutls_session_t, gnutls_buffer_st*);
15805   int (*gnutls_generate_client_certificate) (gnutls_session_t, gnutls_buffer_st*);
15806   int (*gnutls_generate_server_kx) (gnutls_session_t, gnutls_buffer_st*);
15807   int (*gnutls_generate_client_kx) (gnutls_session_t, gnutls_buffer_st*);
15808   int (*gnutls_generate_client_cert_vrfy) (gnutls_session_t, gnutls_buffer_st *);
15809   int (*gnutls_generate_server_certificate_request) (gnutls_session_t,
15810                                                      gnutls_buffer_st *);
15811
15812   int (*gnutls_process_server_certificate) (gnutls_session_t, opaque *,
15813                                             size_t);
15814   int (*gnutls_process_client_certificate) (gnutls_session_t, opaque *,
15815                                             size_t);
15816   int (*gnutls_process_server_kx) (gnutls_session_t, opaque *, size_t);
15817   int (*gnutls_process_client_kx) (gnutls_session_t, opaque *, size_t);
15818   int (*gnutls_process_client_cert_vrfy) (gnutls_session_t, opaque *, size_t);
15819   int (*gnutls_process_server_certificate_request) (gnutls_session_t,
15820                                                     opaque *, size_t);
15821 } mod_auth_st;
15822 </pre>
15823 <p>Those functions are responsible for the
15824 interpretation of the handshake protocol messages. It is common for such
15825 functions to read data from one or more <code>credentials_t</code>
15826 structures<a name="DOCF17" href="#FOOT17"><sup>17</sup></a> and write data,
15827 such as certificates, usernames etc. to <code>auth_info_t</code> structures.
15828 </p>
15829
15830 <p>Simple examples of existing authentication methods can be seen in
15831 <code>auth/psk.c</code> for PSK ciphersuites and <code>auth/srp.c</code> for SRP
15832 ciphersuites. After implementing these functions the structure holding
15833 its pointers has to be registered in <code>gnutls_algorithms.c</code> in the
15834 <code>_gnutls_kx_algorithms</code> structure.
15835 </p>
15836 <hr>
15837 <a name="TLS-Extension-Handling"></a>
15838 <div class="header">
15839 <p>
15840 Next: <a href="#Cryptographic-Backend" accesskey="n" rel="next">Cryptographic Backend</a>, Previous: <a href="#TLS-Authentication-Methods" accesskey="p" rel="prev">TLS Authentication Methods</a>, Up: <a href="#Internal-architecture-of-GnuTLS" accesskey="u" rel="up">Internal architecture of GnuTLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
15841 </div>
15842 <a name="TLS-Extension-Handling-1"></a>
15843 <h3 class="section">10.4 TLS Extension Handling</h3>
15844 <p>As with authentication methods, the TLS extensions handlers can be
15845 implemented using the interface shown below.
15846 </p>
15847 <pre class="verbatim">typedef int (*gnutls_ext_recv_func) (gnutls_session_t session,
15848                                      const unsigned char *data, size_t len);
15849 typedef int (*gnutls_ext_send_func) (gnutls_session_t session,
15850                                      gnutls_buffer_st *extdata);
15851 </pre>
15852 <p>Here there are two functions, one for receiving the extension data
15853 and one for sending. These functions have to check internally whether
15854 they operate in client or server side.
15855 </p>
15856 <p>A simple example of an extension handler can be seen in
15857 <code>ext/srp.c</code> in GnuTLS&rsquo; source code. After implementing these functions,
15858 together with the extension number they handle, they have to be registered
15859 using <code>_gnutls_ext_register</code> in
15860 <code>gnutls_extensions.c</code> typically within <code>_gnutls_ext_init</code>.
15861 </p>
15862 <a name="Adding-a-new-TLS-extension"></a>
15863 <h4 class="subheading">Adding a new TLS extension</h4>
15864
15865 <p>Adding support for a new TLS extension is done from time to time, and
15866 the process to do so is not difficult.  Here are the steps you need to
15867 follow if you wish to do this yourself.  For sake of discussion, let&rsquo;s
15868 consider adding support for the hypothetical TLS extension
15869 <code>foobar</code>.
15870 </p>
15871 <a name="Add-configure-option-like-_002d_002denable_002dfoobar-or-_002d_002ddisable_002dfoobar_002e"></a>
15872 <h4 class="subsubheading">Add <code>configure</code> option like <code>--enable-foobar</code> or <code>--disable-foobar</code>.</h4>
15873
15874 <p>This step is useful when the extension code is large and it might be desirable
15875 to disable the extension under some circumstances. Otherwise it can be safely
15876 skipped.
15877 </p>
15878 <p>Whether to chose enable or disable depends on whether you intend to make the extension be
15879 enabled by default.  Look at existing checks (i.e., SRP, authz) for
15880 how to model the code.  For example:
15881 </p>
15882 <div class="example">
15883 <pre class="example">AC_MSG_CHECKING([whether to disable foobar support])
15884 AC_ARG_ENABLE(foobar,
15885         AS_HELP_STRING([--disable-foobar],
15886                 [disable foobar support]),
15887         ac_enable_foobar=no)
15888 if test x$ac_enable_foobar != xno; then
15889  AC_MSG_RESULT(no)
15890  AC_DEFINE(ENABLE_FOOBAR, 1, [enable foobar])
15891 else
15892  ac_full=0
15893  AC_MSG_RESULT(yes)
15894 fi
15895 AM_CONDITIONAL(ENABLE_FOOBAR, test &quot;$ac_enable_foobar&quot; != &quot;no&quot;)
15896 </pre></div>
15897
15898 <p>These lines should go in <code>m4/hooks.m4</code>.
15899 </p>
15900 <a name="Add-IANA-extension-value-to-extensions_005ft-in-gnutls_005fint_002eh_002e"></a>
15901 <h4 class="subsubheading">Add IANA extension value to <code>extensions_t</code> in <code>gnutls_int.h</code>.</h4>
15902
15903 <p>A good name for the value would be GNUTLS_EXTENSION_FOOBAR.  Check
15904 with <a href="http://www.iana.org/assignments/tls-extensiontype-values">http://www.iana.org/assignments/tls-extensiontype-values</a>
15905 for allocated values.  For experiments, you could pick a number but
15906 remember that some consider it a bad idea to deploy such modified
15907 version since it will lead to interoperability problems in the future
15908 when the IANA allocates that number to someone else, or when the
15909 foobar protocol is allocated another number.
15910 </p>
15911 <a name="Add-an-entry-to-_005fgnutls_005fextensions-in-gnutls_005fextensions_002ec_002e"></a>
15912 <h4 class="subsubheading">Add an entry to <code>_gnutls_extensions</code> in <code>gnutls_extensions.c</code>.</h4>
15913
15914 <p>A typical entry would be:
15915 </p>
15916 <div class="example">
15917 <pre class="example">  int ret;
15918
15919 #if ENABLE_FOOBAR
15920   ret = _gnutls_ext_register (&amp;foobar_ext);
15921   if (ret != GNUTLS_E_SUCCESS)
15922     return ret;
15923 #endif
15924 </pre></div>
15925
15926 <p>Most likely you&rsquo;ll need to add an <code>#include &quot;ext/foobar.h&quot;</code>, that
15927 will contain something like
15928 like:
15929 </p><div class="example">
15930 <pre class="example">  extension_entry_st foobar_ext = {
15931     .name = &quot;FOOBAR&quot;,
15932     .type = GNUTLS_EXTENSION_FOOBAR,
15933     .parse_type = GNUTLS_EXT_TLS,
15934     .recv_func = _foobar_recv_params,
15935     .send_func = _foobar_send_params,
15936     .pack_func = _foobar_pack,
15937     .unpack_func = _foobar_unpack,
15938     .deinit_func = NULL
15939   }
15940 </pre></div>
15941
15942 <p>The GNUTLS_EXTENSION_FOOBAR is the integer value you added to
15943 <code>gnutls_int.h</code> earlier.  In this structure you specify the
15944 functions to read the extension from the hello message, the function
15945 to send the reply to, and two more functions to pack and unpack from
15946 stored session data (e.g. when resumming a session). The <code>deinit</code> function
15947 will be called to deinitialize the extension&rsquo;s private parameters, if any.
15948 </p>
15949 <p>Note that the conditional <code>ENABLE_FOOBAR</code> definition should only be
15950 used if step 1 with the <code>configure</code> options has taken place.
15951 </p>
15952 <a name="Add-new-files-that-implement-the-extension_002e"></a>
15953 <h4 class="subsubheading">Add new files that implement the extension.</h4>
15954
15955 <p>The functions you are responsible to add are those mentioned in the
15956 previous step.  They should be added in a file such as <code>ext/foobar.c</code>
15957 and headers should be placed in <code>ext/foobar.h</code>.
15958 As a starter, you could add this:
15959 </p>
15960 <div class="example">
15961 <pre class="example">int
15962 _foobar_recv_params (gnutls_session_t session, const opaque * data,
15963                      size_t data_size)
15964 {
15965   return 0;
15966 }
15967
15968 int
15969 _foobar_send_params (gnutls_session_t session, gnutls_buffer_st* data)
15970 {
15971   return 0;
15972 }
15973
15974 int
15975 _foobar_pack (extension_priv_data_t epriv, gnutls_buffer_st * ps)
15976 {
15977    /* Append the extension's internal state to buffer */
15978    return 0;
15979 }
15980
15981 int
15982 _foobar_unpack (gnutls_buffer_st * ps, extension_priv_data_t * epriv)
15983 {
15984    /* Read the internal state from buffer */
15985    return 0;
15986 }
15987 </pre></div>
15988
15989 <p>The <code>_foobar_recv_params</code> function is responsible for
15990 parsing incoming extension data (both in the client and server).
15991 </p>
15992 <p>The <code>_foobar_send_params</code> function is responsible for
15993 sending extension data (both in the client and server).
15994 </p>
15995 <p>If you receive length fields that don&rsquo;t match, return
15996 <code>GNUTLS_E_UNEXPECTED_PACKET_LENGTH</code>.  If you receive invalid
15997 data, return <code>GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER</code>.  You can use
15998 other error codes from the list in <a href="#Error-codes">Error codes</a>.  Return 0 on success.
15999 </p>
16000 <p>An extension typically stores private information in the <code>session</code>
16001 data for later usage. That can be done using the functions
16002 <code>_gnutls_ext_set_session_data</code> and
16003 <code>_gnutls_ext_get_session_data</code>. You can check simple examples
16004 at <code>ext/max_record.c</code> and <code>ext/server_name.c</code> extensions.
16005 That private information can be saved and restored across session
16006 resumption if the following functions are set:
16007 </p>
16008 <p>The <code>_foobar_pack</code> function is responsible for packing
16009 internal extension data to save them in the session resumption storage.
16010 </p>
16011 <p>The <code>_foobar_unpack</code> function is responsible for
16012 restoring session data from the session resumption storage.
16013 </p>
16014 <p>Recall that both the client and server, send and receive
16015 parameters, and your code most likely will need to do different things
16016 depending on which mode it is in.  It may be useful to make this
16017 distinction explicit in the code.  Thus, for example, a better
16018 template than above would be:
16019 </p>
16020 <div class="example">
16021 <pre class="example">int
16022 _gnutls_foobar_recv_params (gnutls_session_t session,
16023                             const opaque * data,
16024                             size_t data_size)
16025 {
16026   if (session-&gt;security_parameters.entity == GNUTLS_CLIENT)
16027     return foobar_recv_client (session, data, data_size);
16028   else
16029     return foobar_recv_server (session, data, data_size);
16030 }
16031
16032 int
16033 _gnutls_foobar_send_params (gnutls_session_t session,
16034                             gnutls_buffer_st * data)
16035 {
16036   if (session-&gt;security_parameters.entity == GNUTLS_CLIENT)
16037     return foobar_send_client (session, data);
16038   else
16039     return foobar_send_server (session, data);
16040 }
16041 </pre></div>
16042
16043 <p>The functions used would be declared as <code>static</code> functions, of
16044 the appropriate prototype, in the same file.
16045 When adding the files, you&rsquo;ll need to add them to <code>ext/Makefile.am</code>
16046 as well, for example:
16047 </p>
16048 <div class="example">
16049 <pre class="example">if ENABLE_FOOBAR
16050 libgnutls_ext_la_SOURCES += ext/foobar.c ext/foobar.h
16051 endif
16052 </pre></div>
16053
16054 <a name="Add-API-functions-to-enable_002fdisable-the-extension_002e"></a>
16055 <h4 class="subsubheading">Add API functions to enable/disable the extension.</h4>
16056
16057 <p>It might be desirable to allow users of the extension to
16058 request use of the extension, or set extension specific data.
16059 This can be implemented by adding extension specific function calls
16060 that can be added to <code>includes/gnutls/gnutls.h</code>,
16061 as long as the LGPLv2.1+ applies.
16062 The implementation of the function should lie in the <code>ext/foobar.c</code> file.
16063 </p>
16064 <p>To make the API available in the shared library you need to add the
16065 symbol in <code>lib/libgnutls.map</code>, so that the symbol
16066 is exported properly.
16067 </p>
16068 <p>When writing GTK-DOC style documentation for your new APIs, don&rsquo;t
16069 forget to add <code>Since:</code> tags to indicate the GnuTLS version the
16070 API was introduced in.
16071 </p>
16072 <a name="Heartbeat-extension_002e"></a>
16073 <h4 class="subsubheading">Heartbeat extension.</h4>
16074
16075 <p>One such extension is HeartBeat protocol (RFC6520:
16076 <a href="https://tools.ietf.org/html/rfc6520">https://tools.ietf.org/html/rfc6520</a>) implementation. To enable
16077 it use option &ndash;heartbeat with example client and server supplied with
16078 gnutls:
16079 </p>
16080 <div class="example">
16081 <pre class="example">./doc/credentials/gnutls-http-serv --priority &quot;NORMAL:-CIPHER-ALL:+NULL&quot; -d 100 \
16082     --heartbeat --echo
16083 ./src/gnutls-cli --priority &quot;NORMAL:-CIPHER-ALL:+NULL&quot; -d 100 localhost -p 5556 \
16084     --insecure --heartbeat
16085 </pre></div>
16086
16087 <p>After that pasting
16088 </p><div class="example">
16089 <pre class="example">**HEARTBEAT**
16090 </pre></div>
16091 <p>command into gnutls-cli will trigger corresponding command on the server and it will send HeartBeat Request with random length to client.
16092 </p>
16093 <p>Another way is to run capabilities check with:
16094 </p>
16095 <div class="example">
16096 <pre class="example">./doc/credentials/gnutls-http-serv -d 100 --heartbeat
16097 ./src/gnutls-cli-debug localhost -p 5556
16098 </pre></div>
16099
16100 <a name="Adding-a-new-Supplemental-Data-Handshake-Message"></a>
16101 <h4 class="subheading">Adding a new Supplemental Data Handshake Message</h4>
16102
16103 <p>TLS handshake extensions allow to send so called supplemental data
16104 handshake messages [<em>RFC4680</em>]. This short section explains how to
16105 implement a supplemental data handshake message for a given TLS extension.
16106 </p>
16107 <p>First of all, modify your extension <code>foobar</code> in the way, the that
16108 flags
16109 <code>session-&gt;security_parameters.do_send_supplemental</code>
16110 and
16111 <code>session-&gt;security_parameters.do_recv_supplemental</code>
16112 are set:
16113 </p>
16114 <div class="example">
16115 <pre class="example">int
16116 _gnutls_foobar_recv_params (gnutls_session_t session, const opaque * data,
16117                                  size_t _data_size)
16118 {
16119    ...
16120    session-&gt;security_parameters.do_recv_supplemental=1;
16121    ...
16122 }
16123
16124 int
16125 _gnutls_foobar_send_params (gnutls_session_t session, gnutls_buffer_st *extdata)
16126 {
16127    ...
16128    session-&gt;security_parameters.do_send_supplemental=1;
16129    ...
16130 }
16131 </pre></div>
16132
16133 <p>Furthermore add the functions <code>_foobar_supp_recv_params</code>
16134 and <code>_foobar_supp_send_params</code> to <code>_foobar.h</code> and
16135 <code>_foobar.c</code>. The following example code shows how to send a
16136 &ldquo;Hello World&rdquo; string in the supplemental data handshake message:
16137 </p>
16138 <div class="example">
16139 <pre class="example">int
16140 _foobar_supp_recv_params(gnutls_session_t session, const opaque *data, size_t _data_size)
16141 {
16142    uint8_t len = _data_size;
16143    unsigned char *msg;
16144
16145    msg = gnutls_malloc(len);
16146    if (msg == NULL) return GNUTLS_E_MEMORY_ERROR;
16147
16148    memcpy(msg, data, len);
16149    msg[len]='\0';
16150
16151    /* do something with msg */
16152    gnutls_free(msg);
16153
16154    return len;
16155 }
16156
16157 int
16158 _foobar_supp_send_params(gnutls_session_t session, gnutls_buffer_st *buf)
16159 {
16160    unsigned char *msg = &quot;hello world&quot;;
16161    int len = strlen(msg);
16162
16163    _gnutls_buffer_append_data_prefix(buf, 8, msg, len);
16164
16165    return len;
16166 }
16167 </pre></div>
16168
16169 <p>Afterwards, add the new supplemental data handshake message to
16170 <code>lib/gnutls_supplemental.c</code> by adding a new entry to the
16171 <code>_gnutls_supplemental[]</code> structure:
16172 </p>
16173 <div class="example">
16174 <pre class="example">gnutls_supplemental_entry _gnutls_supplemental[] =
16175 {
16176   {&quot;foobar&quot;,
16177    GNUTLS_SUPPLEMENTAL_FOOBAR_DATA,
16178    _foobar_supp_recv_params,
16179    _foobar_supp_send_params},
16180   {0, 0, 0, 0}
16181 };
16182 </pre></div>
16183
16184 <p>You have to include your <code>foobar.h</code> header file as well:
16185 </p>
16186 <div class="example">
16187 <pre class="example">#include &quot;foobar.h&quot;
16188 </pre></div>
16189
16190 <p>Lastly, add the new supplemental data type to
16191 <code>lib/includes/gnutls/gnutls.h</code>:
16192 </p>
16193 <div class="example">
16194 <pre class="example">typedef enum
16195 {
16196     GNUTLS_SUPPLEMENTAL_USER_MAPPING_DATA = 0,
16197     GNUTLS_SUPPLEMENTAL_FOOBAR_DATA = 1
16198 } gnutls_supplemental_data_format_type_t;
16199 </pre></div>
16200
16201
16202 <hr>
16203 <a name="Cryptographic-Backend"></a>
16204 <div class="header">
16205 <p>
16206 Previous: <a href="#TLS-Extension-Handling" accesskey="p" rel="prev">TLS Extension Handling</a>, Up: <a href="#Internal-architecture-of-GnuTLS" accesskey="u" rel="up">Internal architecture of GnuTLS</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
16207 </div>
16208 <a name="Cryptographic-Backend-1"></a>
16209 <h3 class="section">10.5 Cryptographic Backend</h3>
16210 <p>Today most new processors, either for embedded or desktop systems
16211 include either instructions  intended to speed up cryptographic operations,
16212 or a co-processor with cryptographic capabilities. Taking advantage of
16213 those is a challenging task for every cryptographic  application or
16214 library. Unfortunately the cryptographic library that GnuTLS is based
16215 on takes no advantage of these capabilities. For this reason GnuTLS handles
16216 this internally by following a layered approach to accessing
16217 cryptographic operations as in <a href="#fig_002dcrypto_002dlayers">Figure 10.4</a>.
16218 </p>
16219 <div class="float"><a name="fig_002dcrypto_002dlayers"></a>
16220 <img src="gnutls-crypto-layers.png" alt="gnutls-crypto-layers">
16221
16222 <div class="float-caption"><p><strong>Figure 10.4: </strong>GnuTLS cryptographic back-end design.</p></div></div>
16223 <p>The TLS layer uses a cryptographic provider layer, that will in turn either
16224 use the default crypto provider &ndash; a software crypto library, or use an external
16225 crypto provider, if available in the local system. The reason of handling
16226 the external cryptographic provider in GnuTLS and not delegating it to
16227 the cryptographic libraries, is that none of the supported cryptographic
16228 libraries support <code>/dev/crypto</code> or CPU-optimized cryptography in
16229 an efficient way.
16230 </p>
16231 <a name="Cryptographic-library-layer"></a>
16232 <h4 class="subheading">Cryptographic library layer</h4>
16233 <p>The Cryptographic library layer, currently supports only
16234 libnettle. Older versions of GnuTLS used to support libgcrypt,
16235 but it was switched with nettle mainly for performance reasons<a name="DOCF18" href="#FOOT18"><sup>18</sup></a>
16236 and secondary because it is a simpler library to use.
16237 In the future other cryptographic libraries might be supported as well.
16238 </p>
16239 <a name="External-cryptography-provider"></a>
16240 <h4 class="subheading">External cryptography provider</h4>
16241 <p>Systems that include a cryptographic co-processor, typically come with
16242 kernel drivers to utilize the operations from software. For this reason
16243 GnuTLS provides a layer where each individual algorithm used can be replaced
16244 by another implementation, i.e., the one provided by the driver. The
16245 FreeBSD, OpenBSD and Linux kernels<a name="DOCF19" href="#FOOT19"><sup>19</sup></a> include already
16246 a number of hardware assisted implementations, and also provide an interface
16247 to access them, called <code>/dev/crypto</code>.
16248 GnuTLS will take advantage of this interface if compiled with special
16249 options. That is because in most systems where hardware-assisted
16250 cryptographic operations are not available, using this interface might
16251 actually harm performance.
16252 </p>
16253 <p>In systems that include cryptographic instructions with the CPU&rsquo;s
16254 instructions set, using the kernel interface will introduce an
16255 unneeded layer. For this reason GnuTLS includes such optimizations
16256 found in popular processors such as the AES-NI or VIA PADLOCK instruction sets.
16257 This is achieved using a mechanism that detects CPU capabilities and
16258 overrides parts of crypto back-end at runtime.
16259 The next section discusses the registration of a detected algorithm
16260 optimization. For more information please consult the <acronym>GnuTLS</acronym>
16261 source code in <code>lib/accelerated/</code>.
16262 </p>
16263 <a name="Overriding-specific-algorithms"></a>
16264 <h4 class="subsubheading">Overriding specific algorithms</h4>
16265 <p>When an optimized implementation of a single algorithm is available,
16266 say a hardware assisted version of <acronym>AES-CBC</acronym> then the
16267 following (internal) functions, from <code>crypto-backend.h</code>, can
16268 be used to register those algorithms.
16269 </p>
16270 <ul>
16271 <li> <code>gnutls_crypto_single_cipher_register</code>:
16272 To register a cipher algorithm.
16273
16274 </li><li> <code>gnutls_crypto_single_digest_register</code>:
16275 To register a hash (digest) or MAC algorithm.
16276
16277 </li></ul>
16278
16279 <p>Those registration functions will only replace the specified algorithm
16280 and leave the rest of subsystem intact.
16281 </p>
16282 <a name="Overriding-the-cryptographic-library"></a>
16283 <h4 class="subsubheading">Overriding the cryptographic library</h4>
16284 <p>In some systems, that might contain a broad acceleration engine, it
16285 might be desirable to override big parts of the cryptographic back-end,
16286 or even all of them. The following functions are provided for this reason.
16287 </p>
16288 <ul>
16289 <li> <code>gnutls_crypto_cipher_register</code>:
16290 To override the cryptographic algorithms back-end.
16291
16292 </li><li> <code>gnutls_crypto_digest_register</code>:
16293 To override the digest algorithms back-end.
16294
16295 </li><li> <code>gnutls_crypto_rnd_register</code>:
16296 To override the random number generator back-end.
16297
16298 </li><li> <code>gnutls_crypto_bigint_register</code>:
16299 To override the big number number operations back-end.
16300
16301 </li><li> <code>gnutls_crypto_pk_register</code>:
16302 To override the public key encryption back-end. This is tied to the
16303 big number operations so either none or both of them should be overridden.
16304
16305 </li></ul>
16306
16307
16308
16309 <hr>
16310 <a name="Upgrading-from-previous-versions"></a>
16311 <div class="header">
16312 <p>
16313 Next: <a href="#Support" accesskey="n" rel="next">Support</a>, Previous: <a href="#Internal-architecture-of-GnuTLS" accesskey="p" rel="prev">Internal architecture of GnuTLS</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
16314 </div>
16315 <a name="Upgrading-from-previous-versions-1"></a>
16316 <h2 class="appendix">Appendix A Upgrading from previous versions</h2>
16317 <a name="index-upgrading"></a>
16318
16319 <p>The GnuTLS library typically maintains binary and source code compatibility
16320 across versions. The releases that have the major version increased
16321 break binary compatibility but source compatibility is provided.
16322 This section lists exceptional cases where changes to existing code are
16323 required due to library changes.
16324 </p>
16325 <a name="Upgrading-to-2_002e12_002ex-from-previous-versions"></a>
16326 <h3 class="heading">Upgrading to 2.12.x from previous versions</h3>
16327
16328 <p>GnuTLS 2.12.x is binary compatible with previous versions but changes the
16329 semantics of <code>gnutls_transport_set_lowat</code>, which might cause breakage
16330 in applications that relied on its default value be 1. Two fixes
16331 are proposed:
16332 </p><ul>
16333 <li> Quick fix. Explicitly call <code>gnutls_transport_set_lowat (session, 1);</code>
16334 after <a href="#gnutls_005finit">gnutls_init</a>.
16335 </li><li> Long term fix. Because later versions of gnutls abolish the functionality
16336 of using the system call <code>select</code> to check for gnutls pending data, the
16337 function <a href="#gnutls_005frecord_005fcheck_005fpending">gnutls_record_check_pending</a> has to be used to achieve the same
16338 functionality as described in <a href="#Asynchronous-operation">Asynchronous operation</a>.
16339 </li></ul>
16340
16341 <a name="Upgrading-to-3_002e0_002ex-from-2_002e12_002ex"></a>
16342 <h3 class="heading">Upgrading to 3.0.x from 2.12.x</h3>
16343
16344 <p>GnuTLS 3.0.x is source compatible with previous versions except for the functions
16345 listed below.
16346 </p>
16347 <table>
16348 <thead><tr><th width="30%">Old function</th><th width="60%">Replacement</th></tr></thead>
16349 <tr><td width="30%"><code>gnutls_transport_set_lowat</code></td><td width="60%">To replace its functionality the function <a href="#gnutls_005frecord_005fcheck_005fpending">gnutls_record_check_pending</a> has to be used,
16350 as described in <a href="#Asynchronous-operation">Asynchronous operation</a></td></tr>
16351 <tr><td width="30%"><code>gnutls_session_get_server_random</code>,
16352 <code>gnutls_session_get_client_random</code></td><td width="60%">They are replaced by the safer function <a href="#gnutls_005fsession_005fget_005frandom">gnutls_session_get_random</a></td></tr>
16353 <tr><td width="30%"><code>gnutls_session_get_master_secret</code></td><td width="60%">Replaced by the keying material exporters discussed in <a href="#Deriving-keys-for-other-applications_002fprotocols">Deriving keys for other applications/protocols</a></td></tr>
16354 <tr><td width="30%"><code>gnutls_transport_set_global_errno</code></td><td width="60%">Replaced by using the system&rsquo;s errno fascility or <a href="#gnutls_005ftransport_005fset_005ferrno">gnutls_transport_set_errno</a>.</td></tr>
16355 <tr><td width="30%"><code>gnutls_x509_privkey_verify_data</code></td><td width="60%">Replaced by <a href="#gnutls_005fpubkey_005fverify_005fdata">gnutls_pubkey_verify_data</a>.</td></tr>
16356 <tr><td width="30%"><code>gnutls_certificate_verify_peers</code></td><td width="60%">Replaced by <a href="#gnutls_005fcertificate_005fverify_005fpeers2">gnutls_certificate_verify_peers2</a>.</td></tr>
16357 <tr><td width="30%"><code>gnutls_psk_netconf_derive_key</code></td><td width="60%">Removed. The key derivation function was never standardized.</td></tr>
16358 <tr><td width="30%"><code>gnutls_session_set_finished_function</code></td><td width="60%">Removed.</td></tr>
16359 <tr><td width="30%"><code>gnutls_ext_register</code></td><td width="60%">Removed. Extension registration API is now internal to allow easier changes in the API.</td></tr>
16360 <tr><td width="30%"><code>gnutls_certificate_get_x509_crls</code>, <code>gnutls_certificate_get_x509_cas</code></td><td width="60%">Removed to allow updating the internal structures. Replaced by <a href="#gnutls_005fcertificate_005fget_005fissuer">gnutls_certificate_get_issuer</a>.</td></tr>
16361 <tr><td width="30%"><code>gnutls_certificate_get_openpgp_keyring</code></td><td width="60%">Removed.</td></tr>
16362 <tr><td width="30%"><code>gnutls_ia_</code></td><td width="60%">Removed. The inner application extensions were completely removed (they failed to be standardized).</td></tr>
16363 </table>
16364
16365 <a name="Upgrading-to-3_002e1_002ex-from-3_002e0_002ex"></a>
16366 <h3 class="heading">Upgrading to 3.1.x from 3.0.x</h3>
16367
16368 <p>GnuTLS 3.1.x is source and binary compatible with GnuTLS 3.0.x releases. Few
16369 functions have been deprecated and are listed below.
16370 </p>
16371 <table>
16372 <thead><tr><th width="30%">Old function</th><th width="60%">Replacement</th></tr></thead>
16373 <tr><td width="30%"><code>gnutls_pubkey_verify_hash</code></td><td width="60%">The function <a href="#gnutls_005fpubkey_005fverify_005fhash2">gnutls_pubkey_verify_hash2</a> is provided and
16374 is functionally equivalent and safer to use.</td></tr>
16375 <tr><td width="30%"><code>gnutls_pubkey_verify_data</code></td><td width="60%">The function <a href="#gnutls_005fpubkey_005fverify_005fdata2">gnutls_pubkey_verify_data2</a> is provided and
16376 is functionally equivalent and safer to use.</td></tr>
16377 </table>
16378
16379 <a name="Upgrading-to-3_002e2_002ex-from-3_002e1_002ex"></a>
16380 <h3 class="heading">Upgrading to 3.2.x from 3.1.x</h3>
16381
16382 <p>GnuTLS 3.2.x is source and binary compatible with GnuTLS 3.1.x releases. Few
16383 functions have been deprecated and are listed below.
16384 </p>
16385 <table>
16386 <thead><tr><th width="30%">Old function</th><th width="60%">Replacement</th></tr></thead>
16387 <tr><td width="30%"><code>gnutls_privkey_sign_raw_data</code></td><td width="60%">The function <a href="#gnutls_005fprivkey_005fsign_005fhash">gnutls_privkey_sign_hash</a> is equivalent
16388 when the flag <code>GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA</code> is specified.</td></tr>
16389 </table>
16390
16391 <a name="Upgrading-to-3_002e3_002ex-from-3_002e2_002ex"></a>
16392 <h3 class="heading">Upgrading to 3.3.x from 3.2.x</h3>
16393
16394 <p>GnuTLS 3.3.x is source and binary compatible with GnuTLS 3.2.x releases;
16395 however there few changes in semantics which are listed below.
16396 </p>
16397 <table>
16398 <thead><tr><th width="30%">Old function</th><th width="60%">Replacement</th></tr></thead>
16399 <tr><td width="30%"><code>gnutls_global_init</code></td><td width="60%">No longer required. The library is initialized using a constructor.</td></tr>
16400 <tr><td width="30%"><code>gnutls_global_deinit</code></td><td width="60%">No longer required. The library is deinitialized using a destructor.</td></tr>
16401 </table>
16402
16403
16404 <hr>
16405 <a name="Support"></a>
16406 <div class="header">
16407 <p>
16408 Next: <a href="#Error-codes" accesskey="n" rel="next">Error codes</a>, Previous: <a href="#Upgrading-from-previous-versions" accesskey="p" rel="prev">Upgrading from previous versions</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
16409 </div>
16410 <a name="Support-1"></a>
16411 <h2 class="appendix">Appendix B Support</h2>
16412
16413 <table class="menu" border="0" cellspacing="0">
16414 <tr><td align="left" valign="top">&bull; <a href="#Getting-help" accesskey="1">Getting help</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
16415 </td></tr>
16416 <tr><td align="left" valign="top">&bull; <a href="#Commercial-Support" accesskey="2">Commercial Support</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
16417 </td></tr>
16418 <tr><td align="left" valign="top">&bull; <a href="#Bug-Reports" accesskey="3">Bug Reports</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
16419 </td></tr>
16420 <tr><td align="left" valign="top">&bull; <a href="#Contributing" accesskey="4">Contributing</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
16421 </td></tr>
16422 <tr><td align="left" valign="top">&bull; <a href="#Certification" accesskey="5">Certification</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
16423 </td></tr>
16424 </table>
16425
16426 <hr>
16427 <a name="Getting-help"></a>
16428 <div class="header">
16429 <p>
16430 Next: <a href="#Commercial-Support" accesskey="n" rel="next">Commercial Support</a>, Up: <a href="#Support" accesskey="u" rel="up">Support</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
16431 </div>
16432 <a name="Getting-Help"></a>
16433 <h3 class="section">B.1 Getting Help</h3>
16434
16435 <p>A mailing list where users may help each other exists, and you can
16436 reach it by sending e-mail to <a href="mailto:gnutls-help@gnutls.org">gnutls-help@gnutls.org</a>.  Archives
16437 of the mailing list discussions, and an interface to manage
16438 subscriptions, is available through the World Wide Web at
16439 <a href="http://lists.gnutls.org/pipermail/gnutls-help/">http://lists.gnutls.org/pipermail/gnutls-help/</a>.
16440 </p>
16441 <p>A mailing list for developers are also available, see
16442 <a href="http://www.gnutls.org/lists.html">http://www.gnutls.org/lists.html</a>.
16443 Bug reports should be sent to <a href="mailto:bugs@gnutls.org">bugs@gnutls.org</a>, see
16444 <a href="#Bug-Reports">Bug Reports</a>.
16445 </p>
16446 <hr>
16447 <a name="Commercial-Support"></a>
16448 <div class="header">
16449 <p>
16450 Next: <a href="#Bug-Reports" accesskey="n" rel="next">Bug Reports</a>, Previous: <a href="#Getting-help" accesskey="p" rel="prev">Getting help</a>, Up: <a href="#Support" accesskey="u" rel="up">Support</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
16451 </div>
16452 <a name="Commercial-Support-1"></a>
16453 <h3 class="section">B.2 Commercial Support</h3>
16454
16455 <p>Commercial support is available for users of GnuTLS.  The kind of
16456 support that can be purchased may include:
16457 </p>
16458 <ul>
16459 <li> Implement new features.
16460 Such as a new TLS extension.
16461
16462 </li><li> Port GnuTLS to new platforms.
16463 This could include porting to an embedded platforms that may need
16464 memory or size optimization.
16465
16466 </li><li> Integrating TLS as a security environment in your existing project.
16467
16468 </li><li> System design of components related to TLS.
16469
16470 </li></ul>
16471
16472 <p>If you are interested, please write to:
16473 </p>
16474 <pre class="verbatim">Simon Josefsson Datakonsult
16475 Hagagatan 24
16476 113 47 Stockholm
16477 Sweden
16478
16479 E-mail: simon@josefsson.org
16480 </pre>
16481 <p>If your company provides support related to GnuTLS and would like to
16482 be mentioned here, contact the authors.
16483 </p>
16484
16485 <hr>
16486 <a name="Bug-Reports"></a>
16487 <div class="header">
16488 <p>
16489 Next: <a href="#Contributing" accesskey="n" rel="next">Contributing</a>, Previous: <a href="#Commercial-Support" accesskey="p" rel="prev">Commercial Support</a>, Up: <a href="#Support" accesskey="u" rel="up">Support</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
16490 </div>
16491 <a name="Bug-Reports-1"></a>
16492 <h3 class="section">B.3 Bug Reports</h3>
16493 <a name="index-reporting-bugs"></a>
16494
16495 <p>If you think you have found a bug in GnuTLS, please investigate it and
16496 report it.
16497 </p>
16498 <ul>
16499 <li> Please make sure that the bug is really in GnuTLS, and
16500 preferably also check that it hasn&rsquo;t already been fixed in the latest
16501 version.
16502
16503 </li><li> You have to send us a test case that makes it possible for us to
16504 reproduce the bug.
16505
16506 </li><li> You also have to explain what is wrong; if you get a crash, or
16507 if the results printed are not good and in that case, in what way.
16508 Make sure that the bug report includes all information you would need
16509 to fix this kind of bug for someone else.
16510
16511 </li></ul>
16512
16513 <p>Please make an effort to produce a self-contained report, with
16514 something definite that can be tested or debugged.  Vague queries or
16515 piecemeal messages are difficult to act on and don&rsquo;t help the
16516 development effort.
16517 </p>
16518 <p>If your bug report is good, we will do our best to help you to get a
16519 corrected version of the software; if the bug report is poor, we won&rsquo;t
16520 do anything about it (apart from asking you to send better bug
16521 reports).
16522 </p>
16523 <p>If you think something in this manual is unclear, or downright
16524 incorrect, or if the language needs to be improved, please also send a
16525 note.
16526 </p>
16527 <p>Send your bug report to:
16528 </p>
16529 <div align="center">&lsquo;<samp>bugs@gnutls.org</samp>&rsquo;
16530 </div>
16531 <hr>
16532 <a name="Contributing"></a>
16533 <div class="header">
16534 <p>
16535 Next: <a href="#Certification" accesskey="n" rel="next">Certification</a>, Previous: <a href="#Bug-Reports" accesskey="p" rel="prev">Bug Reports</a>, Up: <a href="#Support" accesskey="u" rel="up">Support</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
16536 </div>
16537 <a name="Contributing-1"></a>
16538 <h3 class="section">B.4 Contributing</h3>
16539 <a name="index-contributing"></a>
16540 <a name="index-hacking"></a>
16541
16542 <p>If you want to submit a patch for inclusion &ndash; from solving a typo you
16543 discovered, up to adding support for a new feature &ndash; you should
16544 submit it as a bug report, using the process in <a href="#Bug-Reports">Bug Reports</a>.  There are some
16545 things that you can do to increase the chances for it to be included
16546 in the official package.
16547 </p>
16548 <p>Unless your patch is very small (say, under 10 lines) we require that
16549 you assign the copyright of your work to the Free Software Foundation.
16550 This is to protect the freedom of the project.  If you have not
16551 already signed papers, we will send you the necessary information when
16552 you submit your contribution.
16553 </p>
16554 <p>For contributions that doesn&rsquo;t consist of actual programming code, the
16555 only guidelines are common sense.
16556 For code contributions, a number of style guides will help you:
16557 </p>
16558 <ul>
16559 <li> Coding Style.
16560 Follow the GNU Standards document.
16561
16562 <p>If you normally code using another coding standard, there is no
16563 problem, but you should use &lsquo;<samp>indent</samp>&rsquo; to reformat the code
16564 before submitting your work.
16565 </p>
16566 </li><li> Use the unified diff format &lsquo;<samp>diff -u</samp>&rsquo;.
16567
16568 </li><li> Return errors.
16569 No reason whatsoever should abort the execution of the library.  Even
16570 memory allocation errors, e.g. when malloc return NULL, should work
16571 although result in an error code.
16572
16573 </li><li> Design with thread safety in mind.
16574 Don&rsquo;t use global variables.  Don&rsquo;t even write to per-handle global
16575 variables unless the documented behaviour of the function you write is
16576 to write to the per-handle global variable.
16577
16578 </li><li> Avoid using the C math library.
16579 It causes problems for embedded implementations, and in most
16580 situations it is very easy to avoid using it.
16581
16582 </li><li> Document your functions.
16583 Use comments before each function headers, that, if properly
16584 formatted, are extracted into Texinfo manuals and GTK-DOC web pages.
16585
16586 </li><li> Supply a ChangeLog and NEWS entries, where appropriate.
16587
16588 </li></ul>
16589
16590 <hr>
16591 <a name="Certification"></a>
16592 <div class="header">
16593 <p>
16594 Previous: <a href="#Contributing" accesskey="p" rel="prev">Contributing</a>, Up: <a href="#Support" accesskey="u" rel="up">Support</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
16595 </div>
16596 <a name="Certification-1"></a>
16597 <h3 class="section">B.5 Certification</h3>
16598 <a name="index-certification"></a>
16599
16600 <p>Many cryptographic libraries claim certifications from national or international bodies. These certifications are tied on a specific (and often restricted) version of the library or a
16601 specific product using the library, and typically in the case of software they assure that the algorithms implemented are correct. The major certifications known are:
16602 </p><ul>
16603 <li> USA&rsquo;s FIPS 140-2 at Level 1 which certifies that approved algorithms are used (see <a href="http://en.wikipedia.org/wiki/FIPS_140-2">http://en.wikipedia.org/wiki/FIPS_140-2</a>);
16604 </li><li> Common Criteria for Information Technology Security Evaluation (CC), an international standard for verification of elaborate security claims (see <a href="http://en.wikipedia.org/wiki/Common_Criteria">http://en.wikipedia.org/wiki/Common_Criteria</a>).
16605 </li></ul>
16606
16607 <p>Obtaining such a certification is an expensive and elaborate job that has no immediate value for a continuously developed free software library (as the certification is tied to the
16608 particular version tested). While, as a free software project, we are not actively pursuing this kind of certification, GnuTLS has been FIPS-140-2 certified in several systems by
16609 third parties. If you are, interested, see <a href="#Commercial-Support">Commercial Support</a>.
16610 </p>
16611 <hr>
16612 <a name="Error-codes"></a>
16613 <div class="header">
16614 <p>
16615 Next: <a href="#Supported-ciphersuites" accesskey="n" rel="next">Supported ciphersuites</a>, Previous: <a href="#Support" accesskey="p" rel="prev">Support</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
16616 </div>
16617 <a name="Error-Codes-and-Descriptions"></a>
16618 <h2 class="appendix">Appendix C Error Codes and Descriptions</h2>
16619 <a name="index-error-codes"></a>
16620
16621 <p>The error codes used throughout the library are described below.  The
16622 return code <code>GNUTLS_E_SUCCESS</code> indicates a successful operation, and
16623 is guaranteed to have the value 0, so you can use it in logical
16624 expressions.
16625 </p>
16626 <table>
16627 <tr><td width="15%">0</td><td width="40%">GNUTLS_E_SUCCESS</td><td width="37%">Success.</td></tr>
16628 <tr><td width="15%">-3</td><td width="40%">GNUTLS_E_UNKNOWN_COMPRESSION_ALGORITHM</td><td width="37%">Could not negotiate a supported compression method.</td></tr>
16629 <tr><td width="15%">-6</td><td width="40%">GNUTLS_E_UNKNOWN_CIPHER_TYPE</td><td width="37%">The cipher type is unsupported.</td></tr>
16630 <tr><td width="15%">-7</td><td width="40%">GNUTLS_E_LARGE_PACKET</td><td width="37%">The transmitted packet is too large (EMSGSIZE).</td></tr>
16631 <tr><td width="15%">-8</td><td width="40%">GNUTLS_E_UNSUPPORTED_VERSION_PACKET</td><td width="37%">A packet with illegal or unsupported version was received.</td></tr>
16632 <tr><td width="15%">-9</td><td width="40%">GNUTLS_E_UNEXPECTED_PACKET_LENGTH</td><td width="37%">A TLS packet with unexpected length was received.</td></tr>
16633 <tr><td width="15%">-10</td><td width="40%">GNUTLS_E_INVALID_SESSION</td><td width="37%">The specified session has been invalidated for some reason.</td></tr>
16634 <tr><td width="15%">-12</td><td width="40%">GNUTLS_E_FATAL_ALERT_RECEIVED</td><td width="37%">A TLS fatal alert has been received.</td></tr>
16635 <tr><td width="15%">-15</td><td width="40%">GNUTLS_E_UNEXPECTED_PACKET</td><td width="37%">An unexpected TLS packet was received.</td></tr>
16636 <tr><td width="15%">-16</td><td width="40%">GNUTLS_E_WARNING_ALERT_RECEIVED</td><td width="37%">A TLS warning alert has been received.</td></tr>
16637 <tr><td width="15%">-18</td><td width="40%">GNUTLS_E_ERROR_IN_FINISHED_PACKET</td><td width="37%">An error was encountered at the TLS Finished packet calculation.</td></tr>
16638 <tr><td width="15%">-19</td><td width="40%">GNUTLS_E_UNEXPECTED_HANDSHAKE_PACKET</td><td width="37%">An unexpected TLS handshake packet was received.</td></tr>
16639 <tr><td width="15%">-21</td><td width="40%">GNUTLS_E_UNKNOWN_CIPHER_SUITE</td><td width="37%">Could not negotiate a supported cipher suite.</td></tr>
16640 <tr><td width="15%">-22</td><td width="40%">GNUTLS_E_UNWANTED_ALGORITHM</td><td width="37%">An algorithm that is not enabled was negotiated.</td></tr>
16641 <tr><td width="15%">-23</td><td width="40%">GNUTLS_E_MPI_SCAN_FAILED</td><td width="37%">The scanning of a large integer has failed.</td></tr>
16642 <tr><td width="15%">-24</td><td width="40%">GNUTLS_E_DECRYPTION_FAILED</td><td width="37%">Decryption has failed.</td></tr>
16643 <tr><td width="15%">-25</td><td width="40%">GNUTLS_E_MEMORY_ERROR</td><td width="37%">Internal error in memory allocation.</td></tr>
16644 <tr><td width="15%">-26</td><td width="40%">GNUTLS_E_DECOMPRESSION_FAILED</td><td width="37%">Decompression of the TLS record packet has failed.</td></tr>
16645 <tr><td width="15%">-27</td><td width="40%">GNUTLS_E_COMPRESSION_FAILED</td><td width="37%">Compression of the TLS record packet has failed.</td></tr>
16646 <tr><td width="15%">-28</td><td width="40%">GNUTLS_E_AGAIN</td><td width="37%">Resource temporarily unavailable, try again.</td></tr>
16647 <tr><td width="15%">-29</td><td width="40%">GNUTLS_E_EXPIRED</td><td width="37%">The requested session has expired.</td></tr>
16648 <tr><td width="15%">-30</td><td width="40%">GNUTLS_E_DB_ERROR</td><td width="37%">Error in Database backend.</td></tr>
16649 <tr><td width="15%">-31</td><td width="40%">GNUTLS_E_SRP_PWD_ERROR</td><td width="37%">Error in password file.</td></tr>
16650 <tr><td width="15%">-32</td><td width="40%">GNUTLS_E_INSUFFICIENT_CREDENTIALS</td><td width="37%">Insufficient credentials for that request.</td></tr>
16651 <tr><td width="15%">-33</td><td width="40%">GNUTLS_E_HASH_FAILED</td><td width="37%">Hashing has failed.</td></tr>
16652 <tr><td width="15%">-34</td><td width="40%">GNUTLS_E_BASE64_DECODING_ERROR</td><td width="37%">Base64 decoding error.</td></tr>
16653 <tr><td width="15%">-35</td><td width="40%">GNUTLS_E_MPI_PRINT_FAILED</td><td width="37%">Could not export a large integer.</td></tr>
16654 <tr><td width="15%">-37</td><td width="40%">GNUTLS_E_REHANDSHAKE</td><td width="37%">Rehandshake was requested by the peer.</td></tr>
16655 <tr><td width="15%">-38</td><td width="40%">GNUTLS_E_GOT_APPLICATION_DATA</td><td width="37%">TLS Application data were received, while expecting handshake data.</td></tr>
16656 <tr><td width="15%">-39</td><td width="40%">GNUTLS_E_RECORD_LIMIT_REACHED</td><td width="37%">The upper limit of record packet sequence numbers has been reached. Wow!</td></tr>
16657 <tr><td width="15%">-40</td><td width="40%">GNUTLS_E_ENCRYPTION_FAILED</td><td width="37%">Encryption has failed.</td></tr>
16658 <tr><td width="15%">-43</td><td width="40%">GNUTLS_E_CERTIFICATE_ERROR</td><td width="37%">Error in the certificate.</td></tr>
16659 <tr><td width="15%">-44</td><td width="40%">GNUTLS_E_PK_ENCRYPTION_FAILED</td><td width="37%">Public key encryption has failed.</td></tr>
16660 <tr><td width="15%">-45</td><td width="40%">GNUTLS_E_PK_DECRYPTION_FAILED</td><td width="37%">Public key decryption has failed.</td></tr>
16661 <tr><td width="15%">-46</td><td width="40%">GNUTLS_E_PK_SIGN_FAILED</td><td width="37%">Public key signing has failed.</td></tr>
16662 <tr><td width="15%">-47</td><td width="40%">GNUTLS_E_X509_UNSUPPORTED_CRITICAL_EXTENSION</td><td width="37%">Unsupported critical extension in X.509 certificate.</td></tr>
16663 <tr><td width="15%">-48</td><td width="40%">GNUTLS_E_KEY_USAGE_VIOLATION</td><td width="37%">Key usage violation in certificate has been detected.</td></tr>
16664 <tr><td width="15%">-49</td><td width="40%">GNUTLS_E_NO_CERTIFICATE_FOUND</td><td width="37%">No certificate was found.</td></tr>
16665 <tr><td width="15%">-50</td><td width="40%">GNUTLS_E_INVALID_REQUEST</td><td width="37%">The request is invalid.</td></tr>
16666 <tr><td width="15%">-51</td><td width="40%">GNUTLS_E_SHORT_MEMORY_BUFFER</td><td width="37%">The given memory buffer is too short to hold parameters.</td></tr>
16667 <tr><td width="15%">-52</td><td width="40%">GNUTLS_E_INTERRUPTED</td><td width="37%">Function was interrupted.</td></tr>
16668 <tr><td width="15%">-53</td><td width="40%">GNUTLS_E_PUSH_ERROR</td><td width="37%">Error in the push function.</td></tr>
16669 <tr><td width="15%">-54</td><td width="40%">GNUTLS_E_PULL_ERROR</td><td width="37%">Error in the pull function.</td></tr>
16670 <tr><td width="15%">-55</td><td width="40%">GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER</td><td width="37%">An illegal parameter has been received.</td></tr>
16671 <tr><td width="15%">-56</td><td width="40%">GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</td><td width="37%">The requested data were not available.</td></tr>
16672 <tr><td width="15%">-57</td><td width="40%">GNUTLS_E_PKCS1_WRONG_PAD</td><td width="37%">Wrong padding in PKCS1 packet.</td></tr>
16673 <tr><td width="15%">-58</td><td width="40%">GNUTLS_E_RECEIVED_ILLEGAL_EXTENSION</td><td width="37%">An illegal TLS extension was received.</td></tr>
16674 <tr><td width="15%">-59</td><td width="40%">GNUTLS_E_INTERNAL_ERROR</td><td width="37%">GnuTLS internal error.</td></tr>
16675 <tr><td width="15%">-60</td><td width="40%">GNUTLS_E_CERTIFICATE_KEY_MISMATCH</td><td width="37%">The certificate and the given key do not match.</td></tr>
16676 <tr><td width="15%">-61</td><td width="40%">GNUTLS_E_UNSUPPORTED_CERTIFICATE_TYPE</td><td width="37%">The certificate type is not supported.</td></tr>
16677 <tr><td width="15%">-62</td><td width="40%">GNUTLS_E_X509_UNKNOWN_SAN</td><td width="37%">Unknown Subject Alternative name in X.509 certificate.</td></tr>
16678 <tr><td width="15%">-63</td><td width="40%">GNUTLS_E_DH_PRIME_UNACCEPTABLE</td><td width="37%">The Diffie-Hellman prime sent by the server is not acceptable (not long enough).</td></tr>
16679 <tr><td width="15%">-64</td><td width="40%">GNUTLS_E_FILE_ERROR</td><td width="37%">Error while reading file.</td></tr>
16680 <tr><td width="15%">-67</td><td width="40%">GNUTLS_E_ASN1_ELEMENT_NOT_FOUND</td><td width="37%">ASN1 parser: Element was not found.</td></tr>
16681 <tr><td width="15%">-68</td><td width="40%">GNUTLS_E_ASN1_IDENTIFIER_NOT_FOUND</td><td width="37%">ASN1 parser: Identifier was not found</td></tr>
16682 <tr><td width="15%">-69</td><td width="40%">GNUTLS_E_ASN1_DER_ERROR</td><td width="37%">ASN1 parser: Error in DER parsing.</td></tr>
16683 <tr><td width="15%">-70</td><td width="40%">GNUTLS_E_ASN1_VALUE_NOT_FOUND</td><td width="37%">ASN1 parser: Value was not found.</td></tr>
16684 <tr><td width="15%">-71</td><td width="40%">GNUTLS_E_ASN1_GENERIC_ERROR</td><td width="37%">ASN1 parser: Generic parsing error.</td></tr>
16685 <tr><td width="15%">-72</td><td width="40%">GNUTLS_E_ASN1_VALUE_NOT_VALID</td><td width="37%">ASN1 parser: Value is not valid.</td></tr>
16686 <tr><td width="15%">-73</td><td width="40%">GNUTLS_E_ASN1_TAG_ERROR</td><td width="37%">ASN1 parser: Error in TAG.</td></tr>
16687 <tr><td width="15%">-74</td><td width="40%">GNUTLS_E_ASN1_TAG_IMPLICIT</td><td width="37%">ASN1 parser: error in implicit tag</td></tr>
16688 <tr><td width="15%">-75</td><td width="40%">GNUTLS_E_ASN1_TYPE_ANY_ERROR</td><td width="37%">ASN1 parser: Error in type &rsquo;ANY&rsquo;.</td></tr>
16689 <tr><td width="15%">-76</td><td width="40%">GNUTLS_E_ASN1_SYNTAX_ERROR</td><td width="37%">ASN1 parser: Syntax error.</td></tr>
16690 <tr><td width="15%">-77</td><td width="40%">GNUTLS_E_ASN1_DER_OVERFLOW</td><td width="37%">ASN1 parser: Overflow in DER parsing.</td></tr>
16691 <tr><td width="15%">-78</td><td width="40%">GNUTLS_E_TOO_MANY_EMPTY_PACKETS</td><td width="37%">Too many empty record packets have been received.</td></tr>
16692 <tr><td width="15%">-79</td><td width="40%">GNUTLS_E_OPENPGP_UID_REVOKED</td><td width="37%">The OpenPGP User ID is revoked.</td></tr>
16693 <tr><td width="15%">-80</td><td width="40%">GNUTLS_E_UNKNOWN_PK_ALGORITHM</td><td width="37%">An unknown public key algorithm was encountered.</td></tr>
16694 <tr><td width="15%">-81</td><td width="40%">GNUTLS_E_TOO_MANY_HANDSHAKE_PACKETS</td><td width="37%">Too many handshake packets have been received.</td></tr>
16695 <tr><td width="15%">-84</td><td width="40%">GNUTLS_E_NO_TEMPORARY_RSA_PARAMS</td><td width="37%">No temporary RSA parameters were found.</td></tr>
16696 <tr><td width="15%">-86</td><td width="40%">GNUTLS_E_NO_COMPRESSION_ALGORITHMS</td><td width="37%">No supported compression algorithms have been found.</td></tr>
16697 <tr><td width="15%">-87</td><td width="40%">GNUTLS_E_NO_CIPHER_SUITES</td><td width="37%">No supported cipher suites have been found.</td></tr>
16698 <tr><td width="15%">-88</td><td width="40%">GNUTLS_E_OPENPGP_GETKEY_FAILED</td><td width="37%">Could not get OpenPGP key.</td></tr>
16699 <tr><td width="15%">-89</td><td width="40%">GNUTLS_E_PK_SIG_VERIFY_FAILED</td><td width="37%">Public key signature verification has failed.</td></tr>
16700 <tr><td width="15%">-90</td><td width="40%">GNUTLS_E_ILLEGAL_SRP_USERNAME</td><td width="37%">The SRP username supplied is illegal.</td></tr>
16701 <tr><td width="15%">-91</td><td width="40%">GNUTLS_E_SRP_PWD_PARSING_ERROR</td><td width="37%">Parsing error in password file.</td></tr>
16702 <tr><td width="15%">-93</td><td width="40%">GNUTLS_E_NO_TEMPORARY_DH_PARAMS</td><td width="37%">No temporary DH parameters were found.</td></tr>
16703 <tr><td width="15%">-94</td><td width="40%">GNUTLS_E_OPENPGP_FINGERPRINT_UNSUPPORTED</td><td width="37%">The OpenPGP fingerprint is not supported.</td></tr>
16704 <tr><td width="15%">-95</td><td width="40%">GNUTLS_E_X509_UNSUPPORTED_ATTRIBUTE</td><td width="37%">The certificate has unsupported attributes.</td></tr>
16705 <tr><td width="15%">-96</td><td width="40%">GNUTLS_E_UNKNOWN_HASH_ALGORITHM</td><td width="37%">The hash algorithm is unknown.</td></tr>
16706 <tr><td width="15%">-97</td><td width="40%">GNUTLS_E_UNKNOWN_PKCS_CONTENT_TYPE</td><td width="37%">The PKCS structure&rsquo;s content type is unknown.</td></tr>
16707 <tr><td width="15%">-98</td><td width="40%">GNUTLS_E_UNKNOWN_PKCS_BAG_TYPE</td><td width="37%">The PKCS structure&rsquo;s bag type is unknown.</td></tr>
16708 <tr><td width="15%">-99</td><td width="40%">GNUTLS_E_INVALID_PASSWORD</td><td width="37%">The given password contains invalid characters.</td></tr>
16709 <tr><td width="15%">-100</td><td width="40%">GNUTLS_E_MAC_VERIFY_FAILED</td><td width="37%">The Message Authentication Code verification failed.</td></tr>
16710 <tr><td width="15%">-101</td><td width="40%">GNUTLS_E_CONSTRAINT_ERROR</td><td width="37%">Some constraint limits were reached.</td></tr>
16711 <tr><td width="15%">-104</td><td width="40%">GNUTLS_E_IA_VERIFY_FAILED</td><td width="37%">Verifying TLS/IA phase checksum failed</td></tr>
16712 <tr><td width="15%">-105</td><td width="40%">GNUTLS_E_UNKNOWN_ALGORITHM</td><td width="37%">The specified algorithm or protocol is unknown.</td></tr>
16713 <tr><td width="15%">-106</td><td width="40%">GNUTLS_E_UNSUPPORTED_SIGNATURE_ALGORITHM</td><td width="37%">The signature algorithm is not supported.</td></tr>
16714 <tr><td width="15%">-107</td><td width="40%">GNUTLS_E_SAFE_RENEGOTIATION_FAILED</td><td width="37%">Safe renegotiation failed.</td></tr>
16715 <tr><td width="15%">-108</td><td width="40%">GNUTLS_E_UNSAFE_RENEGOTIATION_DENIED</td><td width="37%">Unsafe renegotiation denied.</td></tr>
16716 <tr><td width="15%">-109</td><td width="40%">GNUTLS_E_UNKNOWN_SRP_USERNAME</td><td width="37%">The SRP username supplied is unknown.</td></tr>
16717 <tr><td width="15%">-110</td><td width="40%">GNUTLS_E_PREMATURE_TERMINATION</td><td width="37%">The TLS connection was non-properly terminated.</td></tr>
16718 <tr><td width="15%">-201</td><td width="40%">GNUTLS_E_BASE64_ENCODING_ERROR</td><td width="37%">Base64 encoding error.</td></tr>
16719 <tr><td width="15%">-202</td><td width="40%">GNUTLS_E_INCOMPATIBLE_GCRYPT_LIBRARY</td><td width="37%">The crypto library version is too old.</td></tr>
16720 <tr><td width="15%">-203</td><td width="40%">GNUTLS_E_INCOMPATIBLE_LIBTASN1_LIBRARY</td><td width="37%">The tasn1 library version is too old.</td></tr>
16721 <tr><td width="15%">-204</td><td width="40%">GNUTLS_E_OPENPGP_KEYRING_ERROR</td><td width="37%">Error loading the keyring.</td></tr>
16722 <tr><td width="15%">-205</td><td width="40%">GNUTLS_E_X509_UNSUPPORTED_OID</td><td width="37%">The OID is not supported.</td></tr>
16723 <tr><td width="15%">-206</td><td width="40%">GNUTLS_E_RANDOM_FAILED</td><td width="37%">Failed to acquire random data.</td></tr>
16724 <tr><td width="15%">-207</td><td width="40%">GNUTLS_E_BASE64_UNEXPECTED_HEADER_ERROR</td><td width="37%">Base64 unexpected header error.</td></tr>
16725 <tr><td width="15%">-208</td><td width="40%">GNUTLS_E_OPENPGP_SUBKEY_ERROR</td><td width="37%">Could not find OpenPGP subkey.</td></tr>
16726 <tr><td width="15%">-209</td><td width="40%">GNUTLS_E_CRYPTO_ALREADY_REGISTERED</td><td width="37%">There is already a crypto algorithm with lower priority.</td></tr>
16727 <tr><td width="15%">-210</td><td width="40%">GNUTLS_E_HANDSHAKE_TOO_LARGE</td><td width="37%">The handshake data size is too large.</td></tr>
16728 <tr><td width="15%">-211</td><td width="40%">GNUTLS_E_CRYPTODEV_IOCTL_ERROR</td><td width="37%">Error interfacing with /dev/crypto</td></tr>
16729 <tr><td width="15%">-212</td><td width="40%">GNUTLS_E_CRYPTODEV_DEVICE_ERROR</td><td width="37%">Error opening /dev/crypto</td></tr>
16730 <tr><td width="15%">-213</td><td width="40%">GNUTLS_E_CHANNEL_BINDING_NOT_AVAILABLE</td><td width="37%">Channel binding data not available</td></tr>
16731 <tr><td width="15%">-214</td><td width="40%">GNUTLS_E_BAD_COOKIE</td><td width="37%">The cookie was bad.</td></tr>
16732 <tr><td width="15%">-215</td><td width="40%">GNUTLS_E_OPENPGP_PREFERRED_KEY_ERROR</td><td width="37%">The OpenPGP key has not a preferred key set.</td></tr>
16733 <tr><td width="15%">-216</td><td width="40%">GNUTLS_E_INCOMPAT_DSA_KEY_WITH_TLS_PROTOCOL</td><td width="37%">The given DSA key is incompatible with the selected TLS protocol.</td></tr>
16734 <tr><td width="15%">-292</td><td width="40%">GNUTLS_E_HEARTBEAT_PONG_RECEIVED</td><td width="37%">A heartbeat pong message was received.</td></tr>
16735 <tr><td width="15%">-293</td><td width="40%">GNUTLS_E_HEARTBEAT_PING_RECEIVED</td><td width="37%">A heartbeat ping message was received.</td></tr>
16736 <tr><td width="15%">-300</td><td width="40%">GNUTLS_E_PKCS11_ERROR</td><td width="37%">PKCS #11 error.</td></tr>
16737 <tr><td width="15%">-301</td><td width="40%">GNUTLS_E_PKCS11_LOAD_ERROR</td><td width="37%">PKCS #11 initialization error.</td></tr>
16738 <tr><td width="15%">-302</td><td width="40%">GNUTLS_E_PARSING_ERROR</td><td width="37%">Error in parsing.</td></tr>
16739 <tr><td width="15%">-303</td><td width="40%">GNUTLS_E_PKCS11_PIN_ERROR</td><td width="37%">Error in provided PIN.</td></tr>
16740 <tr><td width="15%">-305</td><td width="40%">GNUTLS_E_PKCS11_SLOT_ERROR</td><td width="37%">PKCS #11 error in slot</td></tr>
16741 <tr><td width="15%">-306</td><td width="40%">GNUTLS_E_LOCKING_ERROR</td><td width="37%">Thread locking error</td></tr>
16742 <tr><td width="15%">-307</td><td width="40%">GNUTLS_E_PKCS11_ATTRIBUTE_ERROR</td><td width="37%">PKCS #11 error in attribute</td></tr>
16743 <tr><td width="15%">-308</td><td width="40%">GNUTLS_E_PKCS11_DEVICE_ERROR</td><td width="37%">PKCS #11 error in device</td></tr>
16744 <tr><td width="15%">-309</td><td width="40%">GNUTLS_E_PKCS11_DATA_ERROR</td><td width="37%">PKCS #11 error in data</td></tr>
16745 <tr><td width="15%">-310</td><td width="40%">GNUTLS_E_PKCS11_UNSUPPORTED_FEATURE_ERROR</td><td width="37%">PKCS #11 unsupported feature</td></tr>
16746 <tr><td width="15%">-311</td><td width="40%">GNUTLS_E_PKCS11_KEY_ERROR</td><td width="37%">PKCS #11 error in key</td></tr>
16747 <tr><td width="15%">-312</td><td width="40%">GNUTLS_E_PKCS11_PIN_EXPIRED</td><td width="37%">PKCS #11 PIN expired</td></tr>
16748 <tr><td width="15%">-313</td><td width="40%">GNUTLS_E_PKCS11_PIN_LOCKED</td><td width="37%">PKCS #11 PIN locked</td></tr>
16749 <tr><td width="15%">-314</td><td width="40%">GNUTLS_E_PKCS11_SESSION_ERROR</td><td width="37%">PKCS #11 error in session</td></tr>
16750 <tr><td width="15%">-315</td><td width="40%">GNUTLS_E_PKCS11_SIGNATURE_ERROR</td><td width="37%">PKCS #11 error in signature</td></tr>
16751 <tr><td width="15%">-316</td><td width="40%">GNUTLS_E_PKCS11_TOKEN_ERROR</td><td width="37%">PKCS #11 error in token</td></tr>
16752 <tr><td width="15%">-317</td><td width="40%">GNUTLS_E_PKCS11_USER_ERROR</td><td width="37%">PKCS #11 user error</td></tr>
16753 <tr><td width="15%">-318</td><td width="40%">GNUTLS_E_CRYPTO_INIT_FAILED</td><td width="37%">The initialization of crypto backend has failed.</td></tr>
16754 <tr><td width="15%">-319</td><td width="40%">GNUTLS_E_TIMEDOUT</td><td width="37%">The operation timed out</td></tr>
16755 <tr><td width="15%">-320</td><td width="40%">GNUTLS_E_USER_ERROR</td><td width="37%">The operation was cancelled due to user error</td></tr>
16756 <tr><td width="15%">-321</td><td width="40%">GNUTLS_E_ECC_NO_SUPPORTED_CURVES</td><td width="37%">No supported ECC curves were found</td></tr>
16757 <tr><td width="15%">-322</td><td width="40%">GNUTLS_E_ECC_UNSUPPORTED_CURVE</td><td width="37%">The curve is unsupported</td></tr>
16758 <tr><td width="15%">-323</td><td width="40%">GNUTLS_E_PKCS11_REQUESTED_OBJECT_NOT_AVAILBLE</td><td width="37%">The requested PKCS #11 object is not available</td></tr>
16759 <tr><td width="15%">-324</td><td width="40%">GNUTLS_E_CERTIFICATE_LIST_UNSORTED</td><td width="37%">The provided X.509 certificate list is not sorted (in subject to issuer order)</td></tr>
16760 <tr><td width="15%">-325</td><td width="40%">GNUTLS_E_ILLEGAL_PARAMETER</td><td width="37%">An illegal parameter was found.</td></tr>
16761 <tr><td width="15%">-326</td><td width="40%">GNUTLS_E_NO_PRIORITIES_WERE_SET</td><td width="37%">No or insufficient priorities were set.</td></tr>
16762 <tr><td width="15%">-327</td><td width="40%">GNUTLS_E_X509_UNSUPPORTED_EXTENSION</td><td width="37%">Unsupported extension in X.509 certificate.</td></tr>
16763 <tr><td width="15%">-328</td><td width="40%">GNUTLS_E_SESSION_EOF</td><td width="37%">Peer has terminated the connection</td></tr>
16764 <tr><td width="15%">-329</td><td width="40%">GNUTLS_E_TPM_ERROR</td><td width="37%">TPM error.</td></tr>
16765 <tr><td width="15%">-330</td><td width="40%">GNUTLS_E_TPM_KEY_PASSWORD_ERROR</td><td width="37%">Error in provided password for key to be loaded in TPM.</td></tr>
16766 <tr><td width="15%">-331</td><td width="40%">GNUTLS_E_TPM_SRK_PASSWORD_ERROR</td><td width="37%">Error in provided SRK password for TPM.</td></tr>
16767 <tr><td width="15%">-332</td><td width="40%">GNUTLS_E_TPM_SESSION_ERROR</td><td width="37%">Cannot initialize a session with the TPM.</td></tr>
16768 <tr><td width="15%">-333</td><td width="40%">GNUTLS_E_TPM_KEY_NOT_FOUND</td><td width="37%">TPM key was not found in persistent storage.</td></tr>
16769 <tr><td width="15%">-334</td><td width="40%">GNUTLS_E_TPM_UNINITIALIZED</td><td width="37%">TPM is not initialized.</td></tr>
16770 <tr><td width="15%">-335</td><td width="40%">GNUTLS_E_TPM_NO_LIB</td><td width="37%">The TPM library (trousers) cannot be found.</td></tr>
16771 <tr><td width="15%">-340</td><td width="40%">GNUTLS_E_NO_CERTIFICATE_STATUS</td><td width="37%">There is no certificate status (OCSP).</td></tr>
16772 <tr><td width="15%">-341</td><td width="40%">GNUTLS_E_OCSP_RESPONSE_ERROR</td><td width="37%">The OCSP response is invalid</td></tr>
16773 <tr><td width="15%">-342</td><td width="40%">GNUTLS_E_RANDOM_DEVICE_ERROR</td><td width="37%">Error in the system&rsquo;s randomness device.</td></tr>
16774 <tr><td width="15%">-343</td><td width="40%">GNUTLS_E_AUTH_ERROR</td><td width="37%">Could not authenticate peer.</td></tr>
16775 <tr><td width="15%">-344</td><td width="40%">GNUTLS_E_NO_APPLICATION_PROTOCOL</td><td width="37%">No common application protocol could be negotiated.</td></tr>
16776 <tr><td width="15%">-345</td><td width="40%">GNUTLS_E_SOCKETS_INIT_ERROR</td><td width="37%">Error in sockets initialization.</td></tr>
16777 <tr><td width="15%">-400</td><td width="40%">GNUTLS_E_SELF_TEST_ERROR</td><td width="37%">Error while performing self checks.</td></tr>
16778 <tr><td width="15%">-401</td><td width="40%">GNUTLS_E_NO_SELF_TEST</td><td width="37%">There is no self test for this algorithm.</td></tr>
16779 <tr><td width="15%">-402</td><td width="40%">GNUTLS_E_LIB_IN_ERROR_STATE</td><td width="37%">An error has been detected in the library and cannot continue operations.</td></tr>
16780 <tr><td width="15%">-403</td><td width="40%">GNUTLS_E_PK_GENERATION_ERROR</td><td width="37%">Error in public key generation.</td></tr>
16781 </table>
16782
16783
16784 <hr>
16785 <a name="Supported-ciphersuites"></a>
16786 <div class="header">
16787 <p>
16788 Next: <a href="#API-reference" accesskey="n" rel="next">API reference</a>, Previous: <a href="#Error-codes" accesskey="p" rel="prev">Error codes</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
16789 </div>
16790 <a name="Supported-Ciphersuites"></a>
16791 <h2 class="appendix">Appendix D Supported Ciphersuites</h2>
16792 <a name="ciphersuites"></a><a name="index-ciphersuites"></a>
16793
16794 <a name="Ciphersuites"></a>
16795 <h3 class="heading">Ciphersuites</h3>
16796 <table>
16797 <thead><tr><th width="60%">Ciphersuite name</th><th width="20%">TLS ID</th><th width="20%">Since</th></tr></thead>
16798 <tr><td width="60%">TLS_RSA_NULL_MD5</td><td width="20%">0x00 0x01</td><td width="20%">SSL3.0</td></tr>
16799 <tr><td width="60%">TLS_RSA_NULL_SHA1</td><td width="20%">0x00 0x02</td><td width="20%">SSL3.0</td></tr>
16800 <tr><td width="60%">TLS_RSA_NULL_SHA256</td><td width="20%">0x00 0x3B</td><td width="20%">TLS1.2</td></tr>
16801 <tr><td width="60%">TLS_RSA_ARCFOUR_128_SHA1</td><td width="20%">0x00 0x05</td><td width="20%">SSL3.0</td></tr>
16802 <tr><td width="60%">TLS_RSA_ARCFOUR_128_MD5</td><td width="20%">0x00 0x04</td><td width="20%">SSL3.0</td></tr>
16803 <tr><td width="60%">TLS_RSA_3DES_EDE_CBC_SHA1</td><td width="20%">0x00 0x0A</td><td width="20%">SSL3.0</td></tr>
16804 <tr><td width="60%">TLS_RSA_AES_128_CBC_SHA1</td><td width="20%">0x00 0x2F</td><td width="20%">SSL3.0</td></tr>
16805 <tr><td width="60%">TLS_RSA_AES_256_CBC_SHA1</td><td width="20%">0x00 0x35</td><td width="20%">SSL3.0</td></tr>
16806 <tr><td width="60%">TLS_RSA_CAMELLIA_128_CBC_SHA256</td><td width="20%">0x00 0xBA</td><td width="20%">TLS1.2</td></tr>
16807 <tr><td width="60%">TLS_RSA_CAMELLIA_256_CBC_SHA256</td><td width="20%">0x00 0xC0</td><td width="20%">TLS1.2</td></tr>
16808 <tr><td width="60%">TLS_RSA_CAMELLIA_128_CBC_SHA1</td><td width="20%">0x00 0x41</td><td width="20%">SSL3.0</td></tr>
16809 <tr><td width="60%">TLS_RSA_CAMELLIA_256_CBC_SHA1</td><td width="20%">0x00 0x84</td><td width="20%">SSL3.0</td></tr>
16810 <tr><td width="60%">TLS_RSA_AES_128_CBC_SHA256</td><td width="20%">0x00 0x3C</td><td width="20%">TLS1.2</td></tr>
16811 <tr><td width="60%">TLS_RSA_AES_256_CBC_SHA256</td><td width="20%">0x00 0x3D</td><td width="20%">TLS1.2</td></tr>
16812 <tr><td width="60%">TLS_RSA_AES_128_GCM_SHA256</td><td width="20%">0x00 0x9C</td><td width="20%">TLS1.2</td></tr>
16813 <tr><td width="60%">TLS_RSA_AES_256_GCM_SHA384</td><td width="20%">0x00 0x9D</td><td width="20%">TLS1.2</td></tr>
16814 <tr><td width="60%">TLS_RSA_CAMELLIA_128_GCM_SHA256</td><td width="20%">0xC0 0x7A</td><td width="20%">TLS1.2</td></tr>
16815 <tr><td width="60%">TLS_RSA_CAMELLIA_256_GCM_SHA384</td><td width="20%">0xC0 0x7B</td><td width="20%">TLS1.2</td></tr>
16816 <tr><td width="60%">TLS_RSA_SALSA20_256_SHA1</td><td width="20%">0xE4 0x11</td><td width="20%">SSL3.0</td></tr>
16817 <tr><td width="60%">TLS_RSA_ESTREAM_SALSA20_256_SHA1</td><td width="20%">0xE4 0x10</td><td width="20%">SSL3.0</td></tr>
16818 <tr><td width="60%">TLS_DHE_DSS_ARCFOUR_128_SHA1</td><td width="20%">0x00 0x66</td><td width="20%">SSL3.0</td></tr>
16819 <tr><td width="60%">TLS_DHE_DSS_3DES_EDE_CBC_SHA1</td><td width="20%">0x00 0x13</td><td width="20%">SSL3.0</td></tr>
16820 <tr><td width="60%">TLS_DHE_DSS_AES_128_CBC_SHA1</td><td width="20%">0x00 0x32</td><td width="20%">SSL3.0</td></tr>
16821 <tr><td width="60%">TLS_DHE_DSS_AES_256_CBC_SHA1</td><td width="20%">0x00 0x38</td><td width="20%">SSL3.0</td></tr>
16822 <tr><td width="60%">TLS_DHE_DSS_CAMELLIA_128_CBC_SHA256</td><td width="20%">0x00 0xBD</td><td width="20%">TLS1.2</td></tr>
16823 <tr><td width="60%">TLS_DHE_DSS_CAMELLIA_256_CBC_SHA256</td><td width="20%">0x00 0xC3</td><td width="20%">TLS1.2</td></tr>
16824 <tr><td width="60%">TLS_DHE_DSS_CAMELLIA_128_CBC_SHA1</td><td width="20%">0x00 0x44</td><td width="20%">SSL3.0</td></tr>
16825 <tr><td width="60%">TLS_DHE_DSS_CAMELLIA_256_CBC_SHA1</td><td width="20%">0x00 0x87</td><td width="20%">SSL3.0</td></tr>
16826 <tr><td width="60%">TLS_DHE_DSS_AES_128_CBC_SHA256</td><td width="20%">0x00 0x40</td><td width="20%">TLS1.2</td></tr>
16827 <tr><td width="60%">TLS_DHE_DSS_AES_256_CBC_SHA256</td><td width="20%">0x00 0x6A</td><td width="20%">TLS1.2</td></tr>
16828 <tr><td width="60%">TLS_DHE_DSS_AES_128_GCM_SHA256</td><td width="20%">0x00 0xA2</td><td width="20%">TLS1.2</td></tr>
16829 <tr><td width="60%">TLS_DHE_DSS_AES_256_GCM_SHA384</td><td width="20%">0x00 0xA3</td><td width="20%">TLS1.2</td></tr>
16830 <tr><td width="60%">TLS_DHE_DSS_CAMELLIA_128_GCM_SHA256</td><td width="20%">0xC0 0x80</td><td width="20%">TLS1.2</td></tr>
16831 <tr><td width="60%">TLS_DHE_DSS_CAMELLIA_256_GCM_SHA384</td><td width="20%">0xC0 0x81</td><td width="20%">TLS1.2</td></tr>
16832 <tr><td width="60%">TLS_DHE_RSA_3DES_EDE_CBC_SHA1</td><td width="20%">0x00 0x16</td><td width="20%">SSL3.0</td></tr>
16833 <tr><td width="60%">TLS_DHE_RSA_AES_128_CBC_SHA1</td><td width="20%">0x00 0x33</td><td width="20%">SSL3.0</td></tr>
16834 <tr><td width="60%">TLS_DHE_RSA_AES_256_CBC_SHA1</td><td width="20%">0x00 0x39</td><td width="20%">SSL3.0</td></tr>
16835 <tr><td width="60%">TLS_DHE_RSA_CAMELLIA_128_CBC_SHA256</td><td width="20%">0x00 0xBE</td><td width="20%">TLS1.2</td></tr>
16836 <tr><td width="60%">TLS_DHE_RSA_CAMELLIA_256_CBC_SHA256</td><td width="20%">0x00 0xC4</td><td width="20%">TLS1.2</td></tr>
16837 <tr><td width="60%">TLS_DHE_RSA_CAMELLIA_128_CBC_SHA1</td><td width="20%">0x00 0x45</td><td width="20%">SSL3.0</td></tr>
16838 <tr><td width="60%">TLS_DHE_RSA_CAMELLIA_256_CBC_SHA1</td><td width="20%">0x00 0x88</td><td width="20%">SSL3.0</td></tr>
16839 <tr><td width="60%">TLS_DHE_RSA_AES_128_CBC_SHA256</td><td width="20%">0x00 0x67</td><td width="20%">TLS1.2</td></tr>
16840 <tr><td width="60%">TLS_DHE_RSA_AES_256_CBC_SHA256</td><td width="20%">0x00 0x6B</td><td width="20%">TLS1.2</td></tr>
16841 <tr><td width="60%">TLS_DHE_RSA_AES_128_GCM_SHA256</td><td width="20%">0x00 0x9E</td><td width="20%">TLS1.2</td></tr>
16842 <tr><td width="60%">TLS_DHE_RSA_AES_256_GCM_SHA384</td><td width="20%">0x00 0x9F</td><td width="20%">TLS1.2</td></tr>
16843 <tr><td width="60%">TLS_DHE_RSA_CAMELLIA_128_GCM_SHA256</td><td width="20%">0xC0 0x7C</td><td width="20%">TLS1.2</td></tr>
16844 <tr><td width="60%">TLS_DHE_RSA_CAMELLIA_256_GCM_SHA384</td><td width="20%">0xC0 0x7D</td><td width="20%">TLS1.2</td></tr>
16845 <tr><td width="60%">TLS_ECDHE_RSA_NULL_SHA1</td><td width="20%">0xC0 0x10</td><td width="20%">SSL3.0</td></tr>
16846 <tr><td width="60%">TLS_ECDHE_RSA_3DES_EDE_CBC_SHA1</td><td width="20%">0xC0 0x12</td><td width="20%">SSL3.0</td></tr>
16847 <tr><td width="60%">TLS_ECDHE_RSA_AES_128_CBC_SHA1</td><td width="20%">0xC0 0x13</td><td width="20%">SSL3.0</td></tr>
16848 <tr><td width="60%">TLS_ECDHE_RSA_AES_256_CBC_SHA1</td><td width="20%">0xC0 0x14</td><td width="20%">SSL3.0</td></tr>
16849 <tr><td width="60%">TLS_ECDHE_RSA_AES_256_CBC_SHA384</td><td width="20%">0xC0 0x28</td><td width="20%">TLS1.2</td></tr>
16850 <tr><td width="60%">TLS_ECDHE_RSA_ARCFOUR_128_SHA1</td><td width="20%">0xC0 0x11</td><td width="20%">SSL3.0</td></tr>
16851 <tr><td width="60%">TLS_ECDHE_RSA_CAMELLIA_128_CBC_SHA256</td><td width="20%">0xC0 0x76</td><td width="20%">TLS1.2</td></tr>
16852 <tr><td width="60%">TLS_ECDHE_RSA_CAMELLIA_256_CBC_SHA384</td><td width="20%">0xC0 0x77</td><td width="20%">TLS1.2</td></tr>
16853 <tr><td width="60%">TLS_ECDHE_ECDSA_NULL_SHA1</td><td width="20%">0xC0 0x06</td><td width="20%">SSL3.0</td></tr>
16854 <tr><td width="60%">TLS_ECDHE_ECDSA_3DES_EDE_CBC_SHA1</td><td width="20%">0xC0 0x08</td><td width="20%">SSL3.0</td></tr>
16855 <tr><td width="60%">TLS_ECDHE_ECDSA_AES_128_CBC_SHA1</td><td width="20%">0xC0 0x09</td><td width="20%">SSL3.0</td></tr>
16856 <tr><td width="60%">TLS_ECDHE_ECDSA_AES_256_CBC_SHA1</td><td width="20%">0xC0 0x0A</td><td width="20%">SSL3.0</td></tr>
16857 <tr><td width="60%">TLS_ECDHE_ECDSA_ARCFOUR_128_SHA1</td><td width="20%">0xC0 0x07</td><td width="20%">SSL3.0</td></tr>
16858 <tr><td width="60%">TLS_ECDHE_ECDSA_CAMELLIA_128_CBC_SHA256</td><td width="20%">0xC0 0x72</td><td width="20%">TLS1.2</td></tr>
16859 <tr><td width="60%">TLS_ECDHE_ECDSA_CAMELLIA_256_CBC_SHA384</td><td width="20%">0xC0 0x73</td><td width="20%">TLS1.2</td></tr>
16860 <tr><td width="60%">TLS_ECDHE_ECDSA_AES_128_CBC_SHA256</td><td width="20%">0xC0 0x23</td><td width="20%">TLS1.2</td></tr>
16861 <tr><td width="60%">TLS_ECDHE_RSA_AES_128_CBC_SHA256</td><td width="20%">0xC0 0x27</td><td width="20%">TLS1.2</td></tr>
16862 <tr><td width="60%">TLS_ECDHE_ECDSA_CAMELLIA_128_GCM_SHA256</td><td width="20%">0xC0 0x86</td><td width="20%">TLS1.2</td></tr>
16863 <tr><td width="60%">TLS_ECDHE_ECDSA_CAMELLIA_256_GCM_SHA384</td><td width="20%">0xC0 0x87</td><td width="20%">TLS1.2</td></tr>
16864 <tr><td width="60%">TLS_ECDHE_ECDSA_AES_128_GCM_SHA256</td><td width="20%">0xC0 0x2B</td><td width="20%">TLS1.2</td></tr>
16865 <tr><td width="60%">TLS_ECDHE_ECDSA_AES_256_GCM_SHA384</td><td width="20%">0xC0 0x2C</td><td width="20%">TLS1.2</td></tr>
16866 <tr><td width="60%">TLS_ECDHE_RSA_AES_128_GCM_SHA256</td><td width="20%">0xC0 0x2F</td><td width="20%">TLS1.2</td></tr>
16867 <tr><td width="60%">TLS_ECDHE_RSA_AES_256_GCM_SHA384</td><td width="20%">0xC0 0x30</td><td width="20%">TLS1.2</td></tr>
16868 <tr><td width="60%">TLS_ECDHE_ECDSA_AES_256_CBC_SHA384</td><td width="20%">0xC0 0x24</td><td width="20%">TLS1.2</td></tr>
16869 <tr><td width="60%">TLS_ECDHE_RSA_CAMELLIA_128_GCM_SHA256</td><td width="20%">0xC0 0x8A</td><td width="20%">TLS1.2</td></tr>
16870 <tr><td width="60%">TLS_ECDHE_RSA_CAMELLIA_256_GCM_SHA384</td><td width="20%">0xC0 0x8B</td><td width="20%">TLS1.2</td></tr>
16871 <tr><td width="60%">TLS_ECDHE_RSA_SALSA20_256_SHA1</td><td width="20%">0xE4 0x13</td><td width="20%">SSL3.0</td></tr>
16872 <tr><td width="60%">TLS_ECDHE_ECDSA_SALSA20_256_SHA1</td><td width="20%">0xE4 0x15</td><td width="20%">SSL3.0</td></tr>
16873 <tr><td width="60%">TLS_ECDHE_RSA_ESTREAM_SALSA20_256_SHA1</td><td width="20%">0xE4 0x12</td><td width="20%">SSL3.0</td></tr>
16874 <tr><td width="60%">TLS_ECDHE_ECDSA_ESTREAM_SALSA20_256_SHA1</td><td width="20%">0xE4 0x14</td><td width="20%">SSL3.0</td></tr>
16875 <tr><td width="60%">TLS_ECDHE_PSK_3DES_EDE_CBC_SHA1</td><td width="20%">0xC0 0x34</td><td width="20%">SSL3.0</td></tr>
16876 <tr><td width="60%">TLS_ECDHE_PSK_AES_128_CBC_SHA1</td><td width="20%">0xC0 0x35</td><td width="20%">SSL3.0</td></tr>
16877 <tr><td width="60%">TLS_ECDHE_PSK_AES_256_CBC_SHA1</td><td width="20%">0xC0 0x36</td><td width="20%">SSL3.0</td></tr>
16878 <tr><td width="60%">TLS_ECDHE_PSK_AES_128_CBC_SHA256</td><td width="20%">0xC0 0x37</td><td width="20%">TLS1.2</td></tr>
16879 <tr><td width="60%">TLS_ECDHE_PSK_AES_256_CBC_SHA384</td><td width="20%">0xC0 0x38</td><td width="20%">TLS1.2</td></tr>
16880 <tr><td width="60%">TLS_ECDHE_PSK_ARCFOUR_128_SHA1</td><td width="20%">0xC0 0x33</td><td width="20%">SSL3.0</td></tr>
16881 <tr><td width="60%">TLS_ECDHE_PSK_NULL_SHA1</td><td width="20%">0xC0 0x39</td><td width="20%">SSL3.0</td></tr>
16882 <tr><td width="60%">TLS_ECDHE_PSK_NULL_SHA256</td><td width="20%">0xC0 0x3A</td><td width="20%">TLS1.2</td></tr>
16883 <tr><td width="60%">TLS_ECDHE_PSK_NULL_SHA384</td><td width="20%">0xC0 0x3B</td><td width="20%">TLS1.0</td></tr>
16884 <tr><td width="60%">TLS_ECDHE_PSK_CAMELLIA_128_CBC_SHA256</td><td width="20%">0xC0 0x9A</td><td width="20%">TLS1.2</td></tr>
16885 <tr><td width="60%">TLS_ECDHE_PSK_CAMELLIA_256_CBC_SHA384</td><td width="20%">0xC0 0x9B</td><td width="20%">TLS1.2</td></tr>
16886 <tr><td width="60%">TLS_ECDHE_PSK_SALSA20_256_SHA1</td><td width="20%">0xE4 0x19</td><td width="20%">SSL3.0</td></tr>
16887 <tr><td width="60%">TLS_ECDHE_PSK_ESTREAM_SALSA20_256_SHA1</td><td width="20%">0xE4 0x18</td><td width="20%">SSL3.0</td></tr>
16888 <tr><td width="60%">TLS_PSK_ARCFOUR_128_SHA1</td><td width="20%">0x00 0x8A</td><td width="20%">SSL3.0</td></tr>
16889 <tr><td width="60%">TLS_PSK_3DES_EDE_CBC_SHA1</td><td width="20%">0x00 0x8B</td><td width="20%">SSL3.0</td></tr>
16890 <tr><td width="60%">TLS_PSK_AES_128_CBC_SHA1</td><td width="20%">0x00 0x8C</td><td width="20%">SSL3.0</td></tr>
16891 <tr><td width="60%">TLS_PSK_AES_256_CBC_SHA1</td><td width="20%">0x00 0x8D</td><td width="20%">SSL3.0</td></tr>
16892 <tr><td width="60%">TLS_PSK_AES_128_CBC_SHA256</td><td width="20%">0x00 0xAE</td><td width="20%">TLS1.2</td></tr>
16893 <tr><td width="60%">TLS_PSK_AES_256_GCM_SHA384</td><td width="20%">0x00 0xA9</td><td width="20%">TLS1.2</td></tr>
16894 <tr><td width="60%">TLS_PSK_CAMELLIA_128_GCM_SHA256</td><td width="20%">0xC0 0x8E</td><td width="20%">TLS1.2</td></tr>
16895 <tr><td width="60%">TLS_PSK_CAMELLIA_256_GCM_SHA384</td><td width="20%">0xC0 0x8F</td><td width="20%">TLS1.2</td></tr>
16896 <tr><td width="60%">TLS_PSK_AES_128_GCM_SHA256</td><td width="20%">0x00 0xA8</td><td width="20%">TLS1.2</td></tr>
16897 <tr><td width="60%">TLS_PSK_NULL_SHA1</td><td width="20%">0x00 0x2C</td><td width="20%">SSL3.0</td></tr>
16898 <tr><td width="60%">TLS_PSK_NULL_SHA256</td><td width="20%">0x00 0xB0</td><td width="20%">TLS1.2</td></tr>
16899 <tr><td width="60%">TLS_PSK_CAMELLIA_128_CBC_SHA256</td><td width="20%">0xC0 0x94</td><td width="20%">TLS1.2</td></tr>
16900 <tr><td width="60%">TLS_PSK_CAMELLIA_256_CBC_SHA384</td><td width="20%">0xC0 0x95</td><td width="20%">TLS1.2</td></tr>
16901 <tr><td width="60%">TLS_PSK_SALSA20_256_SHA1</td><td width="20%">0xE4 0x17</td><td width="20%">SSL3.0</td></tr>
16902 <tr><td width="60%">TLS_PSK_ESTREAM_SALSA20_256_SHA1</td><td width="20%">0xE4 0x16</td><td width="20%">SSL3.0</td></tr>
16903 <tr><td width="60%">TLS_PSK_AES_256_CBC_SHA384</td><td width="20%">0x00 0xAF</td><td width="20%">TLS1.2</td></tr>
16904 <tr><td width="60%">TLS_PSK_NULL_SHA384</td><td width="20%">0x00 0xB1</td><td width="20%">TLS1.2</td></tr>
16905 <tr><td width="60%">TLS_RSA_PSK_ARCFOUR_128_SHA1</td><td width="20%">0x00 0x92</td><td width="20%">TLS1.0</td></tr>
16906 <tr><td width="60%">TLS_RSA_PSK_3DES_EDE_CBC_SHA1</td><td width="20%">0x00 0x93</td><td width="20%">TLS1.0</td></tr>
16907 <tr><td width="60%">TLS_RSA_PSK_AES_128_CBC_SHA1</td><td width="20%">0x00 0x94</td><td width="20%">TLS1.0</td></tr>
16908 <tr><td width="60%">TLS_RSA_PSK_AES_256_CBC_SHA1</td><td width="20%">0x00 0x95</td><td width="20%">TLS1.0</td></tr>
16909 <tr><td width="60%">TLS_RSA_PSK_CAMELLIA_128_GCM_SHA256</td><td width="20%">0xC0 0x92</td><td width="20%">TLS1.2</td></tr>
16910 <tr><td width="60%">TLS_RSA_PSK_CAMELLIA_256_GCM_SHA384</td><td width="20%">0xC0 0x93</td><td width="20%">TLS1.2</td></tr>
16911 <tr><td width="60%">TLS_RSA_PSK_AES_128_GCM_SHA256</td><td width="20%">0x00 0xAC</td><td width="20%">TLS1.2</td></tr>
16912 <tr><td width="60%">TLS_RSA_PSK_AES_128_CBC_SHA256</td><td width="20%">0x00 0xB6</td><td width="20%">TLS1.2</td></tr>
16913 <tr><td width="60%">TLS_RSA_PSK_NULL_SHA1</td><td width="20%">0x00 0x2E</td><td width="20%">TLS1.0</td></tr>
16914 <tr><td width="60%">TLS_RSA_PSK_NULL_SHA256</td><td width="20%">0x00 0xB8</td><td width="20%">TLS1.2</td></tr>
16915 <tr><td width="60%">TLS_RSA_PSK_AES_256_GCM_SHA384</td><td width="20%">0x00 0xAD</td><td width="20%">TLS1.2</td></tr>
16916 <tr><td width="60%">TLS_RSA_PSK_AES_256_CBC_SHA384</td><td width="20%">0x00 0xB7</td><td width="20%">TLS1.2</td></tr>
16917 <tr><td width="60%">TLS_RSA_PSK_NULL_SHA384</td><td width="20%">0x00 0xB9</td><td width="20%">TLS1.2</td></tr>
16918 <tr><td width="60%">TLS_RSA_PSK_CAMELLIA_128_CBC_SHA256</td><td width="20%">0xC0 0x98</td><td width="20%">TLS1.2</td></tr>
16919 <tr><td width="60%">TLS_RSA_PSK_CAMELLIA_256_CBC_SHA384</td><td width="20%">0xC0 0x99</td><td width="20%">TLS1.2</td></tr>
16920 <tr><td width="60%">TLS_DHE_PSK_ARCFOUR_128_SHA1</td><td width="20%">0x00 0x8E</td><td width="20%">SSL3.0</td></tr>
16921 <tr><td width="60%">TLS_DHE_PSK_3DES_EDE_CBC_SHA1</td><td width="20%">0x00 0x8F</td><td width="20%">SSL3.0</td></tr>
16922 <tr><td width="60%">TLS_DHE_PSK_AES_128_CBC_SHA1</td><td width="20%">0x00 0x90</td><td width="20%">SSL3.0</td></tr>
16923 <tr><td width="60%">TLS_DHE_PSK_AES_256_CBC_SHA1</td><td width="20%">0x00 0x91</td><td width="20%">SSL3.0</td></tr>
16924 <tr><td width="60%">TLS_DHE_PSK_AES_128_CBC_SHA256</td><td width="20%">0x00 0xB2</td><td width="20%">TLS1.2</td></tr>
16925 <tr><td width="60%">TLS_DHE_PSK_AES_128_GCM_SHA256</td><td width="20%">0x00 0xAA</td><td width="20%">TLS1.2</td></tr>
16926 <tr><td width="60%">TLS_DHE_PSK_NULL_SHA1</td><td width="20%">0x00 0x2D</td><td width="20%">SSL3.0</td></tr>
16927 <tr><td width="60%">TLS_DHE_PSK_NULL_SHA256</td><td width="20%">0x00 0xB4</td><td width="20%">TLS1.2</td></tr>
16928 <tr><td width="60%">TLS_DHE_PSK_NULL_SHA384</td><td width="20%">0x00 0xB5</td><td width="20%">TLS1.2</td></tr>
16929 <tr><td width="60%">TLS_DHE_PSK_AES_256_CBC_SHA384</td><td width="20%">0x00 0xB3</td><td width="20%">TLS1.2</td></tr>
16930 <tr><td width="60%">TLS_DHE_PSK_AES_256_GCM_SHA384</td><td width="20%">0x00 0xAB</td><td width="20%">TLS1.2</td></tr>
16931 <tr><td width="60%">TLS_DHE_PSK_CAMELLIA_128_CBC_SHA256</td><td width="20%">0xC0 0x96</td><td width="20%">TLS1.2</td></tr>
16932 <tr><td width="60%">TLS_DHE_PSK_CAMELLIA_256_CBC_SHA384</td><td width="20%">0xC0 0x97</td><td width="20%">TLS1.2</td></tr>
16933 <tr><td width="60%">TLS_DHE_PSK_CAMELLIA_128_GCM_SHA256</td><td width="20%">0xC0 0x90</td><td width="20%">TLS1.2</td></tr>
16934 <tr><td width="60%">TLS_DHE_PSK_CAMELLIA_256_GCM_SHA384</td><td width="20%">0xC0 0x91</td><td width="20%">TLS1.2</td></tr>
16935 <tr><td width="60%">TLS_DH_ANON_ARCFOUR_128_MD5</td><td width="20%">0x00 0x18</td><td width="20%">SSL3.0</td></tr>
16936 <tr><td width="60%">TLS_DH_ANON_3DES_EDE_CBC_SHA1</td><td width="20%">0x00 0x1B</td><td width="20%">SSL3.0</td></tr>
16937 <tr><td width="60%">TLS_DH_ANON_AES_128_CBC_SHA1</td><td width="20%">0x00 0x34</td><td width="20%">SSL3.0</td></tr>
16938 <tr><td width="60%">TLS_DH_ANON_AES_256_CBC_SHA1</td><td width="20%">0x00 0x3A</td><td width="20%">SSL3.0</td></tr>
16939 <tr><td width="60%">TLS_DH_ANON_CAMELLIA_128_CBC_SHA256</td><td width="20%">0x00 0xBF</td><td width="20%">TLS1.2</td></tr>
16940 <tr><td width="60%">TLS_DH_ANON_CAMELLIA_256_CBC_SHA256</td><td width="20%">0x00 0xC5</td><td width="20%">TLS1.2</td></tr>
16941 <tr><td width="60%">TLS_DH_ANON_CAMELLIA_128_CBC_SHA1</td><td width="20%">0x00 0x46</td><td width="20%">SSL3.0</td></tr>
16942 <tr><td width="60%">TLS_DH_ANON_CAMELLIA_256_CBC_SHA1</td><td width="20%">0x00 0x89</td><td width="20%">SSL3.0</td></tr>
16943 <tr><td width="60%">TLS_DH_ANON_AES_128_CBC_SHA256</td><td width="20%">0x00 0x6C</td><td width="20%">TLS1.2</td></tr>
16944 <tr><td width="60%">TLS_DH_ANON_AES_256_CBC_SHA256</td><td width="20%">0x00 0x6D</td><td width="20%">TLS1.2</td></tr>
16945 <tr><td width="60%">TLS_DH_ANON_AES_128_GCM_SHA256</td><td width="20%">0x00 0xA6</td><td width="20%">TLS1.2</td></tr>
16946 <tr><td width="60%">TLS_DH_ANON_AES_256_GCM_SHA384</td><td width="20%">0x00 0xA7</td><td width="20%">TLS1.2</td></tr>
16947 <tr><td width="60%">TLS_DH_ANON_CAMELLIA_128_GCM_SHA256</td><td width="20%">0xC0 0x84</td><td width="20%">TLS1.2</td></tr>
16948 <tr><td width="60%">TLS_DH_ANON_CAMELLIA_256_GCM_SHA384</td><td width="20%">0xC0 0x85</td><td width="20%">TLS1.2</td></tr>
16949 <tr><td width="60%">TLS_ECDH_ANON_NULL_SHA1</td><td width="20%">0xC0 0x15</td><td width="20%">SSL3.0</td></tr>
16950 <tr><td width="60%">TLS_ECDH_ANON_3DES_EDE_CBC_SHA1</td><td width="20%">0xC0 0x17</td><td width="20%">SSL3.0</td></tr>
16951 <tr><td width="60%">TLS_ECDH_ANON_AES_128_CBC_SHA1</td><td width="20%">0xC0 0x18</td><td width="20%">SSL3.0</td></tr>
16952 <tr><td width="60%">TLS_ECDH_ANON_AES_256_CBC_SHA1</td><td width="20%">0xC0 0x19</td><td width="20%">SSL3.0</td></tr>
16953 <tr><td width="60%">TLS_ECDH_ANON_ARCFOUR_128_SHA1</td><td width="20%">0xC0 0x16</td><td width="20%">SSL3.0</td></tr>
16954 <tr><td width="60%">TLS_SRP_SHA_3DES_EDE_CBC_SHA1</td><td width="20%">0xC0 0x1A</td><td width="20%">SSL3.0</td></tr>
16955 <tr><td width="60%">TLS_SRP_SHA_AES_128_CBC_SHA1</td><td width="20%">0xC0 0x1D</td><td width="20%">SSL3.0</td></tr>
16956 <tr><td width="60%">TLS_SRP_SHA_AES_256_CBC_SHA1</td><td width="20%">0xC0 0x20</td><td width="20%">SSL3.0</td></tr>
16957 <tr><td width="60%">TLS_SRP_SHA_DSS_3DES_EDE_CBC_SHA1</td><td width="20%">0xC0 0x1C</td><td width="20%">SSL3.0</td></tr>
16958 <tr><td width="60%">TLS_SRP_SHA_RSA_3DES_EDE_CBC_SHA1</td><td width="20%">0xC0 0x1B</td><td width="20%">SSL3.0</td></tr>
16959 <tr><td width="60%">TLS_SRP_SHA_DSS_AES_128_CBC_SHA1</td><td width="20%">0xC0 0x1F</td><td width="20%">SSL3.0</td></tr>
16960 <tr><td width="60%">TLS_SRP_SHA_RSA_AES_128_CBC_SHA1</td><td width="20%">0xC0 0x1E</td><td width="20%">SSL3.0</td></tr>
16961 <tr><td width="60%">TLS_SRP_SHA_DSS_AES_256_CBC_SHA1</td><td width="20%">0xC0 0x22</td><td width="20%">SSL3.0</td></tr>
16962 <tr><td width="60%">TLS_SRP_SHA_RSA_AES_256_CBC_SHA1</td><td width="20%">0xC0 0x21</td><td width="20%">SSL3.0</td></tr>
16963 </table>
16964
16965
16966 <a name="Certificate-types"></a>
16967 <h3 class="heading">Certificate types</h3>
16968 <dl compact="compact">
16969 <dt><code>X.509</code></dt>
16970 <dt><code>OPENPGP</code></dt>
16971 </dl>
16972
16973 <a name="Protocols"></a>
16974 <h3 class="heading">Protocols</h3>
16975 <dl compact="compact">
16976 <dt><code>SSL3.0</code></dt>
16977 <dt><code>TLS1.0</code></dt>
16978 <dt><code>TLS1.1</code></dt>
16979 <dt><code>TLS1.2</code></dt>
16980 <dt><code>DTLS0.9</code></dt>
16981 <dt><code>DTLS1.0</code></dt>
16982 <dt><code>DTLS1.2</code></dt>
16983 </dl>
16984
16985 <a name="Ciphers"></a>
16986 <h3 class="heading">Ciphers</h3>
16987 <dl compact="compact">
16988 <dt><code>AES-256-CBC</code></dt>
16989 <dt><code>AES-192-CBC</code></dt>
16990 <dt><code>AES-128-CBC</code></dt>
16991 <dt><code>AES-128-GCM</code></dt>
16992 <dt><code>AES-256-GCM</code></dt>
16993 <dt><code>ARCFOUR-128</code></dt>
16994 <dt><code>ESTREAM-SALSA20-256</code></dt>
16995 <dt><code>SALSA20-256</code></dt>
16996 <dt><code>CAMELLIA-256-CBC</code></dt>
16997 <dt><code>CAMELLIA-192-CBC</code></dt>
16998 <dt><code>CAMELLIA-128-CBC</code></dt>
16999 <dt><code>CAMELLIA-128-GCM</code></dt>
17000 <dt><code>CAMELLIA-256-GCM</code></dt>
17001 <dt><code>3DES-CBC</code></dt>
17002 <dt><code>DES-CBC</code></dt>
17003 <dt><code>ARCFOUR-40</code></dt>
17004 <dt><code>RC2-40</code></dt>
17005 <dt><code>NULL</code></dt>
17006 </dl>
17007
17008 <a name="MAC-algorithms"></a>
17009 <h3 class="heading">MAC algorithms</h3>
17010 <dl compact="compact">
17011 <dt><code>SHA1</code></dt>
17012 <dt><code>MD5</code></dt>
17013 <dt><code>SHA256</code></dt>
17014 <dt><code>SHA384</code></dt>
17015 <dt><code>SHA512</code></dt>
17016 <dt><code>SHA224</code></dt>
17017 <dt><code>UMAC-96</code></dt>
17018 <dt><code>UMAC-128</code></dt>
17019 <dt><code>AEAD</code></dt>
17020 </dl>
17021
17022 <a name="Key-exchange-methods"></a>
17023 <h3 class="heading">Key exchange methods</h3>
17024 <dl compact="compact">
17025 <dt><code>ANON-DH</code></dt>
17026 <dt><code>ANON-ECDH</code></dt>
17027 <dt><code>RSA</code></dt>
17028 <dt><code>DHE-RSA</code></dt>
17029 <dt><code>DHE-DSS</code></dt>
17030 <dt><code>ECDHE-RSA</code></dt>
17031 <dt><code>ECDHE-ECDSA</code></dt>
17032 <dt><code>SRP-DSS</code></dt>
17033 <dt><code>SRP-RSA</code></dt>
17034 <dt><code>SRP</code></dt>
17035 <dt><code>PSK</code></dt>
17036 <dt><code>RSA-PSK</code></dt>
17037 <dt><code>DHE-PSK</code></dt>
17038 <dt><code>ECDHE-PSK</code></dt>
17039 <dt><code>RSA-EXPORT</code></dt>
17040 </dl>
17041
17042 <a name="Public-key-algorithms-2"></a>
17043 <h3 class="heading">Public key algorithms</h3>
17044 <dl compact="compact">
17045 <dt><code>RSA</code></dt>
17046 <dt><code>DSA</code></dt>
17047 <dt><code>EC</code></dt>
17048 </dl>
17049
17050 <a name="Public-key-signature-algorithms"></a>
17051 <h3 class="heading">Public key signature algorithms</h3>
17052 <dl compact="compact">
17053 <dt><code>RSA-SHA1</code></dt>
17054 <dt><code>RSA-SHA1</code></dt>
17055 <dt><code>RSA-SHA224</code></dt>
17056 <dt><code>RSA-SHA256</code></dt>
17057 <dt><code>RSA-SHA384</code></dt>
17058 <dt><code>RSA-SHA512</code></dt>
17059 <dt><code>RSA-RMD160</code></dt>
17060 <dt><code>DSA-SHA1</code></dt>
17061 <dt><code>DSA-SHA1</code></dt>
17062 <dt><code>DSA-SHA224</code></dt>
17063 <dt><code>DSA-SHA256</code></dt>
17064 <dt><code>RSA-MD5</code></dt>
17065 <dt><code>RSA-MD5</code></dt>
17066 <dt><code>RSA-MD2</code></dt>
17067 <dt><code>ECDSA-SHA1</code></dt>
17068 <dt><code>ECDSA-SHA224</code></dt>
17069 <dt><code>ECDSA-SHA256</code></dt>
17070 <dt><code>ECDSA-SHA384</code></dt>
17071 <dt><code>ECDSA-SHA512</code></dt>
17072 </dl>
17073
17074 <a name="Elliptic-curves"></a>
17075 <h3 class="heading">Elliptic curves</h3>
17076 <dl compact="compact">
17077 <dt><code>SECP192R1</code></dt>
17078 <dt><code>SECP224R1</code></dt>
17079 <dt><code>SECP256R1</code></dt>
17080 <dt><code>SECP384R1</code></dt>
17081 <dt><code>SECP521R1</code></dt>
17082 </dl>
17083
17084 <a name="Compression-methods"></a>
17085 <h3 class="heading">Compression methods</h3>
17086 <dl compact="compact">
17087 <dt><code>DEFLATE</code></dt>
17088 <dt><code>NULL</code></dt>
17089 </dl>
17090
17091
17092 <hr>
17093 <a name="API-reference"></a>
17094 <div class="header">
17095 <p>
17096 Next: <a href="#Copying-Information" accesskey="n" rel="next">Copying Information</a>, Previous: <a href="#Supported-ciphersuites" accesskey="p" rel="prev">Supported ciphersuites</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
17097 </div>
17098 <a name="API-reference-1"></a>
17099 <h2 class="appendix">Appendix E API reference</h2>
17100 <a name="index-API-reference"></a>
17101
17102 <table class="menu" border="0" cellspacing="0">
17103 <tr><td align="left" valign="top">&bull; <a href="#Core-TLS-API" accesskey="1">Core TLS API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
17104 </td></tr>
17105 <tr><td align="left" valign="top">&bull; <a href="#Datagram-TLS-API" accesskey="2">Datagram TLS API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
17106 </td></tr>
17107 <tr><td align="left" valign="top">&bull; <a href="#X509-certificate-API" accesskey="3">X509 certificate API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
17108 </td></tr>
17109 <tr><td align="left" valign="top">&bull; <a href="#OCSP-API" accesskey="4">OCSP API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
17110 </td></tr>
17111 <tr><td align="left" valign="top">&bull; <a href="#OpenPGP-API" accesskey="5">OpenPGP API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
17112 </td></tr>
17113 <tr><td align="left" valign="top">&bull; <a href="#PKCS-12-API" accesskey="6">PKCS 12 API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
17114 </td></tr>
17115 <tr><td align="left" valign="top">&bull; <a href="#PKCS-11-API" accesskey="7">PKCS 11 API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
17116 </td></tr>
17117 <tr><td align="left" valign="top">&bull; <a href="#TPM-API" accesskey="8">TPM API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
17118 </td></tr>
17119 <tr><td align="left" valign="top">&bull; <a href="#Abstract-key-API" accesskey="9">Abstract key API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
17120 </td></tr>
17121 <tr><td align="left" valign="top">&bull; <a href="#DANE-API">DANE API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
17122 </td></tr>
17123 <tr><td align="left" valign="top">&bull; <a href="#Cryptographic-API">Cryptographic API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
17124 </td></tr>
17125 <tr><td align="left" valign="top">&bull; <a href="#Compatibility-API">Compatibility API</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
17126 </td></tr>
17127 </table>
17128
17129 <hr>
17130 <a name="Core-TLS-API"></a>
17131 <div class="header">
17132 <p>
17133 Next: <a href="#Datagram-TLS-API" accesskey="n" rel="next">Datagram TLS API</a>, Up: <a href="#API-reference" accesskey="u" rel="up">API reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
17134 </div>
17135 <a name="Core-TLS-API-1"></a>
17136 <h3 class="section">E.1 Core TLS API</h3>
17137
17138 <p>The prototypes for the following functions lie in
17139 <samp>gnutls/gnutls.h</samp>.
17140 </p>
17141
17142 <a name="gnutls_005falert_005fget-1"></a>
17143 <h4 class="subheading">gnutls_alert_get</h4>
17144 <a name="gnutls_005falert_005fget"></a><dl>
17145 <dt><a name="index-gnutls_005falert_005fget-1"></a>Function: <em>gnutls_alert_description_t</em> <strong>gnutls_alert_get</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
17146 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
17147 </p>
17148 <p>This function will return the last alert number received.  This
17149 function should be called when <code>GNUTLS_E_WARNING_ALERT_RECEIVED</code>  or
17150 <code>GNUTLS_E_FATAL_ALERT_RECEIVED</code>  errors are returned by a gnutls
17151 function.  The peer may send alerts if he encounters an error.
17152 If no alert has been received the returned value is undefined.
17153 </p>
17154 <p><strong>Returns:</strong> the last alert received, a
17155 <code>gnutls_alert_description_t</code>  value.
17156 </p></dd></dl>
17157
17158 <a name="gnutls_005falert_005fget_005fname-1"></a>
17159 <h4 class="subheading">gnutls_alert_get_name</h4>
17160 <a name="gnutls_005falert_005fget_005fname"></a><dl>
17161 <dt><a name="index-gnutls_005falert_005fget_005fname-1"></a>Function: <em>const char *</em> <strong>gnutls_alert_get_name</strong> <em>(gnutls_alert_description_t <var>alert</var>)</em></dt>
17162 <dd><p><var>alert</var>: is an alert number.
17163 </p>
17164 <p>This function will return a string that describes the given alert
17165 number, or <code>NULL</code> .  See <code>gnutls_alert_get()</code> .
17166 </p>
17167 <p><strong>Returns:</strong> string corresponding to <code>gnutls_alert_description_t</code>  value.
17168 </p></dd></dl>
17169
17170 <a name="gnutls_005falert_005fget_005fstrname-1"></a>
17171 <h4 class="subheading">gnutls_alert_get_strname</h4>
17172 <a name="gnutls_005falert_005fget_005fstrname"></a><dl>
17173 <dt><a name="index-gnutls_005falert_005fget_005fstrname"></a>Function: <em>const char *</em> <strong>gnutls_alert_get_strname</strong> <em>(gnutls_alert_description_t <var>alert</var>)</em></dt>
17174 <dd><p><var>alert</var>: is an alert number.
17175 </p>
17176 <p>This function will return a string of the name of the alert.
17177 </p>
17178 <p><strong>Returns:</strong> string corresponding to <code>gnutls_alert_description_t</code>  value.
17179 </p>
17180 <p><strong>Since:</strong> 3.0
17181 </p></dd></dl>
17182
17183 <a name="gnutls_005falert_005fsend-1"></a>
17184 <h4 class="subheading">gnutls_alert_send</h4>
17185 <a name="gnutls_005falert_005fsend"></a><dl>
17186 <dt><a name="index-gnutls_005falert_005fsend-1"></a>Function: <em>int</em> <strong>gnutls_alert_send</strong> <em>(gnutls_session_t <var>session</var>, gnutls_alert_level_t <var>level</var>, gnutls_alert_description_t <var>desc</var>)</em></dt>
17187 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
17188 </p>
17189 <p><var>level</var>: is the level of the alert
17190 </p>
17191 <p><var>desc</var>: is the alert description
17192 </p>
17193 <p>This function will send an alert to the peer in order to inform
17194 him of something important (eg. his Certificate could not be verified).
17195 If the alert level is Fatal then the peer is expected to close the
17196 connection, otherwise he may ignore the alert and continue.
17197 </p>
17198 <p>The error code of the underlying record send function will be
17199 returned, so you may also receive <code>GNUTLS_E_INTERRUPTED</code>  or
17200 <code>GNUTLS_E_AGAIN</code>  as well.
17201 </p>
17202 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
17203 an error code is returned.
17204 </p></dd></dl>
17205
17206 <a name="gnutls_005falert_005fsend_005fappropriate-1"></a>
17207 <h4 class="subheading">gnutls_alert_send_appropriate</h4>
17208 <a name="gnutls_005falert_005fsend_005fappropriate"></a><dl>
17209 <dt><a name="index-gnutls_005falert_005fsend_005fappropriate"></a>Function: <em>int</em> <strong>gnutls_alert_send_appropriate</strong> <em>(gnutls_session_t <var>session</var>, int <var>err</var>)</em></dt>
17210 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
17211 </p>
17212 <p><var>err</var>: is an integer
17213 </p>
17214 <p>Sends an alert to the peer depending on the error code returned by
17215 a gnutls function. This function will call <code>gnutls_error_to_alert()</code>
17216 to determine the appropriate alert to send.
17217 </p>
17218 <p>This function may also return <code>GNUTLS_E_AGAIN</code> , or
17219 <code>GNUTLS_E_INTERRUPTED</code> .
17220 </p>
17221 <p>If the return value is <code>GNUTLS_E_INVALID_REQUEST</code> , then no alert has
17222 been sent to the peer.
17223 </p>
17224 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
17225 an error code is returned.
17226 </p></dd></dl>
17227
17228 <a name="gnutls_005falpn_005fget_005fselected_005fprotocol-1"></a>
17229 <h4 class="subheading">gnutls_alpn_get_selected_protocol</h4>
17230 <a name="gnutls_005falpn_005fget_005fselected_005fprotocol"></a><dl>
17231 <dt><a name="index-gnutls_005falpn_005fget_005fselected_005fprotocol"></a>Function: <em>int</em> <strong>gnutls_alpn_get_selected_protocol</strong> <em>(gnutls_session_t <var>session</var>, gnutls_datum_t * <var>protocol</var>)</em></dt>
17232 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
17233 </p>
17234 <p><var>protocol</var>: will hold the protocol name
17235 </p>
17236 <p>This function allows you to get the negotiated protocol name. The
17237 returned protocol should be treated as opaque, constant value and
17238 only valid during the session life.
17239 </p>
17240 <p>The selected protocol is the first supported by the list sent
17241 by the client.
17242 </p>
17243 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
17244 otherwise a negative error code is returned.
17245 </p>
17246 <p>Since 3.2.0
17247 </p></dd></dl>
17248
17249 <a name="gnutls_005falpn_005fset_005fprotocols-1"></a>
17250 <h4 class="subheading">gnutls_alpn_set_protocols</h4>
17251 <a name="gnutls_005falpn_005fset_005fprotocols"></a><dl>
17252 <dt><a name="index-gnutls_005falpn_005fset_005fprotocols"></a>Function: <em>int</em> <strong>gnutls_alpn_set_protocols</strong> <em>(gnutls_session_t <var>session</var>, const gnutls_datum_t * <var>protocols</var>, unsigned <var>protocols_size</var>, unsigned int <var>flags</var>)</em></dt>
17253 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
17254 </p>
17255 <p><var>protocols</var>: is the protocol names to add.
17256 </p>
17257 <p><var>protocols_size</var>: the number of protocols to add.
17258 </p>
17259 <p><var>flags</var>: zero or <code>GNUTLS_ALPN_</code> *
17260 </p>
17261 <p>This function is to be used by both clients and servers, to declare
17262 the supported ALPN protocols, which are used during negotiation with peer.
17263 </p>
17264 <p>If <code>GNUTLS_ALPN_MAND</code>  is specified the connection will be aborted
17265 if no matching ALPN protocol is found.
17266 </p>
17267 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
17268 otherwise a negative error code is returned.
17269 </p>
17270 <p>Since 3.2.0
17271 </p></dd></dl>
17272
17273 <a name="gnutls_005fanon_005fallocate_005fclient_005fcredentials-1"></a>
17274 <h4 class="subheading">gnutls_anon_allocate_client_credentials</h4>
17275 <a name="gnutls_005fanon_005fallocate_005fclient_005fcredentials"></a><dl>
17276 <dt><a name="index-gnutls_005fanon_005fallocate_005fclient_005fcredentials"></a>Function: <em>int</em> <strong>gnutls_anon_allocate_client_credentials</strong> <em>(gnutls_anon_client_credentials_t *      <var>sc</var>)</em></dt>
17277 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_anon_client_credentials_t</code>  structure.
17278 </p>
17279 <p>This structure is complex enough to manipulate directly thus
17280 this helper function is provided in order to allocate it.
17281 </p>
17282 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
17283 </p></dd></dl>
17284
17285 <a name="gnutls_005fanon_005fallocate_005fserver_005fcredentials-1"></a>
17286 <h4 class="subheading">gnutls_anon_allocate_server_credentials</h4>
17287 <a name="gnutls_005fanon_005fallocate_005fserver_005fcredentials"></a><dl>
17288 <dt><a name="index-gnutls_005fanon_005fallocate_005fserver_005fcredentials"></a>Function: <em>int</em> <strong>gnutls_anon_allocate_server_credentials</strong> <em>(gnutls_anon_server_credentials_t *      <var>sc</var>)</em></dt>
17289 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_anon_server_credentials_t</code>  structure.
17290 </p>
17291 <p>This structure is complex enough to manipulate directly thus this
17292 helper function is provided in order to allocate it.
17293 </p>
17294 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
17295 </p></dd></dl>
17296
17297 <a name="gnutls_005fanon_005ffree_005fclient_005fcredentials-1"></a>
17298 <h4 class="subheading">gnutls_anon_free_client_credentials</h4>
17299 <a name="gnutls_005fanon_005ffree_005fclient_005fcredentials"></a><dl>
17300 <dt><a name="index-gnutls_005fanon_005ffree_005fclient_005fcredentials"></a>Function: <em>void</em> <strong>gnutls_anon_free_client_credentials</strong> <em>(gnutls_anon_client_credentials_t <var>sc</var>)</em></dt>
17301 <dd><p><var>sc</var>: is a <code>gnutls_anon_client_credentials_t</code>  structure.
17302 </p>
17303 <p>This structure is complex enough to manipulate directly thus this
17304 helper function is provided in order to free (deallocate) it.
17305 </p></dd></dl>
17306
17307 <a name="gnutls_005fanon_005ffree_005fserver_005fcredentials-1"></a>
17308 <h4 class="subheading">gnutls_anon_free_server_credentials</h4>
17309 <a name="gnutls_005fanon_005ffree_005fserver_005fcredentials"></a><dl>
17310 <dt><a name="index-gnutls_005fanon_005ffree_005fserver_005fcredentials"></a>Function: <em>void</em> <strong>gnutls_anon_free_server_credentials</strong> <em>(gnutls_anon_server_credentials_t <var>sc</var>)</em></dt>
17311 <dd><p><var>sc</var>: is a <code>gnutls_anon_server_credentials_t</code>  structure.
17312 </p>
17313 <p>This structure is complex enough to manipulate directly thus this
17314 helper function is provided in order to free (deallocate) it.
17315 </p></dd></dl>
17316
17317 <a name="gnutls_005fanon_005fset_005fparams_005ffunction-1"></a>
17318 <h4 class="subheading">gnutls_anon_set_params_function</h4>
17319 <a name="gnutls_005fanon_005fset_005fparams_005ffunction"></a><dl>
17320 <dt><a name="index-gnutls_005fanon_005fset_005fparams_005ffunction"></a>Function: <em>void</em> <strong>gnutls_anon_set_params_function</strong> <em>(gnutls_anon_server_credentials_t <var>res</var>, gnutls_params_function * <var>func</var>)</em></dt>
17321 <dd><p><var>res</var>: is a gnutls_anon_server_credentials_t structure
17322 </p>
17323 <p><var>func</var>: is the function to be called
17324 </p>
17325 <p>This function will set a callback in order for the server to get
17326 the Diffie-Hellman or RSA parameters for anonymous authentication.
17327 The callback should return <code>GNUTLS_E_SUCCESS</code>  (0) on success.
17328 </p></dd></dl>
17329
17330 <a name="gnutls_005fanon_005fset_005fserver_005fdh_005fparams-1"></a>
17331 <h4 class="subheading">gnutls_anon_set_server_dh_params</h4>
17332 <a name="gnutls_005fanon_005fset_005fserver_005fdh_005fparams"></a><dl>
17333 <dt><a name="index-gnutls_005fanon_005fset_005fserver_005fdh_005fparams"></a>Function: <em>void</em> <strong>gnutls_anon_set_server_dh_params</strong> <em>(gnutls_anon_server_credentials_t <var>res</var>, gnutls_dh_params_t <var>dh_params</var>)</em></dt>
17334 <dd><p><var>res</var>: is a gnutls_anon_server_credentials_t structure
17335 </p>
17336 <p><var>dh_params</var>: is a structure that holds Diffie-Hellman parameters.
17337 </p>
17338 <p>This function will set the Diffie-Hellman parameters for an
17339 anonymous server to use.  These parameters will be used in
17340 Anonymous Diffie-Hellman cipher suites.
17341 </p></dd></dl>
17342
17343 <a name="gnutls_005fanon_005fset_005fserver_005fparams_005ffunction-1"></a>
17344 <h4 class="subheading">gnutls_anon_set_server_params_function</h4>
17345 <a name="gnutls_005fanon_005fset_005fserver_005fparams_005ffunction"></a><dl>
17346 <dt><a name="index-gnutls_005fanon_005fset_005fserver_005fparams_005ffunction"></a>Function: <em>void</em> <strong>gnutls_anon_set_server_params_function</strong> <em>(gnutls_anon_server_credentials_t            <var>res</var>, gnutls_params_function * <var>func</var>)</em></dt>
17347 <dd><p><var>res</var>: is a gnutls_certificate_credentials_t structure
17348 </p>
17349 <p><var>func</var>: is the function to be called
17350 </p>
17351 <p>This function will set a callback in order for the server to get
17352 the Diffie-Hellman parameters for anonymous authentication.  The
17353 callback should return <code>GNUTLS_E_SUCCESS</code>  (0) on success.
17354 </p></dd></dl>
17355
17356 <a name="gnutls_005fauth_005fclient_005fget_005ftype-1"></a>
17357 <h4 class="subheading">gnutls_auth_client_get_type</h4>
17358 <a name="gnutls_005fauth_005fclient_005fget_005ftype"></a><dl>
17359 <dt><a name="index-gnutls_005fauth_005fclient_005fget_005ftype"></a>Function: <em>gnutls_credentials_type_t</em> <strong>gnutls_auth_client_get_type</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
17360 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
17361 </p>
17362 <p>Returns the type of credentials that were used for client authentication.
17363 The returned information is to be used to distinguish the function used
17364 to access authentication data.
17365 </p>
17366 <p><strong>Returns:</strong> The type of credentials for the client authentication
17367 schema, a <code>gnutls_credentials_type_t</code>  type.
17368 </p></dd></dl>
17369
17370 <a name="gnutls_005fauth_005fget_005ftype-1"></a>
17371 <h4 class="subheading">gnutls_auth_get_type</h4>
17372 <a name="gnutls_005fauth_005fget_005ftype"></a><dl>
17373 <dt><a name="index-gnutls_005fauth_005fget_005ftype"></a>Function: <em>gnutls_credentials_type_t</em> <strong>gnutls_auth_get_type</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
17374 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
17375 </p>
17376 <p>Returns type of credentials for the current authentication schema.
17377 The returned information is to be used to distinguish the function used
17378 to access authentication data.
17379 </p>
17380 <p>Eg. for CERTIFICATE ciphersuites (key exchange algorithms:
17381 <code>GNUTLS_KX_RSA</code> , <code>GNUTLS_KX_DHE_RSA</code> ), the same function are to be
17382 used to access the authentication data.
17383 </p>
17384 <p><strong>Returns:</strong> The type of credentials for the current authentication
17385 schema, a <code>gnutls_credentials_type_t</code>  type.
17386 </p></dd></dl>
17387
17388 <a name="gnutls_005fauth_005fserver_005fget_005ftype-1"></a>
17389 <h4 class="subheading">gnutls_auth_server_get_type</h4>
17390 <a name="gnutls_005fauth_005fserver_005fget_005ftype"></a><dl>
17391 <dt><a name="index-gnutls_005fauth_005fserver_005fget_005ftype"></a>Function: <em>gnutls_credentials_type_t</em> <strong>gnutls_auth_server_get_type</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
17392 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
17393 </p>
17394 <p>Returns the type of credentials that were used for server authentication.
17395 The returned information is to be used to distinguish the function used
17396 to access authentication data.
17397 </p>
17398 <p><strong>Returns:</strong> The type of credentials for the server authentication
17399 schema, a <code>gnutls_credentials_type_t</code>  type.
17400 </p></dd></dl>
17401
17402 <a name="gnutls_005fbye-1"></a>
17403 <h4 class="subheading">gnutls_bye</h4>
17404 <a name="gnutls_005fbye"></a><dl>
17405 <dt><a name="index-gnutls_005fbye-1"></a>Function: <em>int</em> <strong>gnutls_bye</strong> <em>(gnutls_session_t <var>session</var>, gnutls_close_request_t <var>how</var>)</em></dt>
17406 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
17407 </p>
17408 <p><var>how</var>: is an integer
17409 </p>
17410 <p>Terminates the current TLS/SSL connection. The connection should
17411 have been initiated using <code>gnutls_handshake()</code> .   <code>how</code> should be one
17412 of <code>GNUTLS_SHUT_RDWR</code> , <code>GNUTLS_SHUT_WR</code> .
17413 </p>
17414 <p>In case of <code>GNUTLS_SHUT_RDWR</code>  the TLS session gets
17415 terminated and further receives and sends will be disallowed.  If
17416 the return value is zero you may continue using the underlying
17417 transport layer. <code>GNUTLS_SHUT_RDWR</code>  sends an alert containing a close
17418 request and waits for the peer to reply with the same message.
17419 </p>
17420 <p>In case of <code>GNUTLS_SHUT_WR</code>  the TLS session gets terminated
17421 and further sends will be disallowed. In order to reuse the
17422 connection you should wait for an EOF from the peer.
17423 <code>GNUTLS_SHUT_WR</code>  sends an alert containing a close request.
17424 </p>
17425 <p>Note that not all implementations will properly terminate a TLS
17426 connection.  Some of them, usually for performance reasons, will
17427 terminate only the underlying transport layer, and thus not
17428 distinguishing between a malicious party prematurely terminating
17429 the connection and normal termination.
17430 </p>
17431 <p>This function may also return <code>GNUTLS_E_AGAIN</code>  or
17432 <code>GNUTLS_E_INTERRUPTED</code> ; cf.  <code>gnutls_record_get_direction()</code> .
17433 </p>
17434 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code, see
17435 function documentation for entire semantics.
17436 </p></dd></dl>
17437
17438 <a name="gnutls_005fcertificate_005factivation_005ftime_005fpeers-1"></a>
17439 <h4 class="subheading">gnutls_certificate_activation_time_peers</h4>
17440 <a name="gnutls_005fcertificate_005factivation_005ftime_005fpeers"></a><dl>
17441 <dt><a name="index-gnutls_005fcertificate_005factivation_005ftime_005fpeers"></a>Function: <em>time_t</em> <strong>gnutls_certificate_activation_time_peers</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
17442 <dd><p><var>session</var>: is a gnutls session
17443 </p>
17444 <p>This function will return the peer&rsquo;s certificate activation time.
17445 This is the creation time for openpgp keys.
17446 </p>
17447 <p><strong>Returns:</strong> (time_t)-1 on error.
17448 </p>
17449 <p><strong>Deprecated:</strong> <code>gnutls_certificate_verify_peers2()</code>  now verifies activation times.
17450 </p></dd></dl>
17451
17452 <a name="gnutls_005fcertificate_005fallocate_005fcredentials-1"></a>
17453 <h4 class="subheading">gnutls_certificate_allocate_credentials</h4>
17454 <a name="gnutls_005fcertificate_005fallocate_005fcredentials"></a><dl>
17455 <dt><a name="index-gnutls_005fcertificate_005fallocate_005fcredentials"></a>Function: <em>int</em> <strong>gnutls_certificate_allocate_credentials</strong> <em>(gnutls_certificate_credentials_t *      <var>res</var>)</em></dt>
17456 <dd><p><var>res</var>: is a pointer to a <code>gnutls_certificate_credentials_t</code>  structure.
17457 </p>
17458 <p>This structure is complex enough to manipulate directly thus this
17459 helper function is provided in order to allocate it.
17460 </p>
17461 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
17462 </p></dd></dl>
17463
17464 <a name="gnutls_005fcertificate_005fclient_005fget_005frequest_005fstatus-1"></a>
17465 <h4 class="subheading">gnutls_certificate_client_get_request_status</h4>
17466 <a name="gnutls_005fcertificate_005fclient_005fget_005frequest_005fstatus"></a><dl>
17467 <dt><a name="index-gnutls_005fcertificate_005fclient_005fget_005frequest_005fstatus"></a>Function: <em>int</em> <strong>gnutls_certificate_client_get_request_status</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
17468 <dd><p><var>session</var>: is a gnutls session
17469 </p>
17470 <p>Get whether client certificate is requested or not.
17471 </p>
17472 <p><strong>Returns:</strong> 0 if the peer (server) did not request client
17473 authentication or 1 otherwise.
17474 </p></dd></dl>
17475
17476 <a name="gnutls_005fcertificate_005fexpiration_005ftime_005fpeers-1"></a>
17477 <h4 class="subheading">gnutls_certificate_expiration_time_peers</h4>
17478 <a name="gnutls_005fcertificate_005fexpiration_005ftime_005fpeers"></a><dl>
17479 <dt><a name="index-gnutls_005fcertificate_005fexpiration_005ftime_005fpeers"></a>Function: <em>time_t</em> <strong>gnutls_certificate_expiration_time_peers</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
17480 <dd><p><var>session</var>: is a gnutls session
17481 </p>
17482 <p>This function will return the peer&rsquo;s certificate expiration time.
17483 </p>
17484 <p><strong>Returns:</strong> (time_t)-1 on error.
17485 </p>
17486 <p><strong>Deprecated:</strong> <code>gnutls_certificate_verify_peers2()</code>  now verifies expiration times.
17487 </p></dd></dl>
17488
17489 <a name="gnutls_005fcertificate_005ffree_005fca_005fnames-1"></a>
17490 <h4 class="subheading">gnutls_certificate_free_ca_names</h4>
17491 <a name="gnutls_005fcertificate_005ffree_005fca_005fnames"></a><dl>
17492 <dt><a name="index-gnutls_005fcertificate_005ffree_005fca_005fnames"></a>Function: <em>void</em> <strong>gnutls_certificate_free_ca_names</strong> <em>(gnutls_certificate_credentials_t <var>sc</var>)</em></dt>
17493 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17494 </p>
17495 <p>This function will delete all the CA name in the given
17496 credentials. Clients may call this to save some memory since in
17497 client side the CA names are not used. Servers might want to use
17498 this function if a large list of trusted CAs is present and
17499 sending the names of it would just consume bandwidth without providing
17500 information to client.
17501 </p>
17502 <p>CA names are used by servers to advertise the CAs they support to
17503 clients.
17504 </p></dd></dl>
17505
17506 <a name="gnutls_005fcertificate_005ffree_005fcas-1"></a>
17507 <h4 class="subheading">gnutls_certificate_free_cas</h4>
17508 <a name="gnutls_005fcertificate_005ffree_005fcas"></a><dl>
17509 <dt><a name="index-gnutls_005fcertificate_005ffree_005fcas"></a>Function: <em>void</em> <strong>gnutls_certificate_free_cas</strong> <em>(gnutls_certificate_credentials_t <var>sc</var>)</em></dt>
17510 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17511 </p>
17512 <p>This function will delete all the CAs associated with the given
17513 credentials. Servers that do not use
17514 <code>gnutls_certificate_verify_peers2()</code>  may call this to save some
17515 memory.
17516 </p></dd></dl>
17517
17518 <a name="gnutls_005fcertificate_005ffree_005fcredentials-1"></a>
17519 <h4 class="subheading">gnutls_certificate_free_credentials</h4>
17520 <a name="gnutls_005fcertificate_005ffree_005fcredentials"></a><dl>
17521 <dt><a name="index-gnutls_005fcertificate_005ffree_005fcredentials"></a>Function: <em>void</em> <strong>gnutls_certificate_free_credentials</strong> <em>(gnutls_certificate_credentials_t <var>sc</var>)</em></dt>
17522 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17523 </p>
17524 <p>This structure is complex enough to manipulate directly thus this
17525 helper function is provided in order to free (deallocate) it.
17526 </p>
17527 <p>This function does not free any temporary parameters associated
17528 with this structure (ie RSA and DH parameters are not freed by this
17529 function).
17530 </p></dd></dl>
17531
17532 <a name="gnutls_005fcertificate_005ffree_005fcrls-1"></a>
17533 <h4 class="subheading">gnutls_certificate_free_crls</h4>
17534 <a name="gnutls_005fcertificate_005ffree_005fcrls"></a><dl>
17535 <dt><a name="index-gnutls_005fcertificate_005ffree_005fcrls"></a>Function: <em>void</em> <strong>gnutls_certificate_free_crls</strong> <em>(gnutls_certificate_credentials_t <var>sc</var>)</em></dt>
17536 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17537 </p>
17538 <p>This function will delete all the CRLs associated
17539 with the given credentials.
17540 </p></dd></dl>
17541
17542 <a name="gnutls_005fcertificate_005ffree_005fkeys-1"></a>
17543 <h4 class="subheading">gnutls_certificate_free_keys</h4>
17544 <a name="gnutls_005fcertificate_005ffree_005fkeys"></a><dl>
17545 <dt><a name="index-gnutls_005fcertificate_005ffree_005fkeys"></a>Function: <em>void</em> <strong>gnutls_certificate_free_keys</strong> <em>(gnutls_certificate_credentials_t <var>sc</var>)</em></dt>
17546 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17547 </p>
17548 <p>This function will delete all the keys and the certificates associated
17549 with the given credentials. This function must not be called when a
17550 TLS negotiation that uses the credentials is in progress.
17551 </p></dd></dl>
17552
17553 <a name="gnutls_005fcertificate_005fget_005fcrt_005fraw-1"></a>
17554 <h4 class="subheading">gnutls_certificate_get_crt_raw</h4>
17555 <a name="gnutls_005fcertificate_005fget_005fcrt_005fraw"></a><dl>
17556 <dt><a name="index-gnutls_005fcertificate_005fget_005fcrt_005fraw"></a>Function: <em>int</em> <strong>gnutls_certificate_get_crt_raw</strong> <em>(gnutls_certificate_credentials_t <var>sc</var>, unsigned <var>idx1</var>, unsigned <var>idx2</var>, gnutls_datum_t * <var>cert</var>)</em></dt>
17557 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17558 </p>
17559 <p><var>idx1</var>: the index of the certificate if multiple are present
17560 </p>
17561 <p><var>idx2</var>: the index in the certificate list. Zero gives the server&rsquo;s certificate.
17562 </p>
17563 <p><var>cert</var>: Will hold the DER encoded certificate.
17564 </p>
17565 <p>This function will return the DER encoded certificate of the
17566 server or any other certificate on its certificate chain (based on  <code>idx2</code> ).
17567 The returned data should be treated as constant and only accessible during the lifetime
17568 of  <code>sc</code> .
17569 </p>
17570 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
17571 negative error value. In case the indexes are out of bounds <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
17572 is returned.
17573 </p>
17574 <p><strong>Since:</strong> 3.2.5
17575 </p></dd></dl>
17576
17577 <a name="gnutls_005fcertificate_005fget_005fissuer-1"></a>
17578 <h4 class="subheading">gnutls_certificate_get_issuer</h4>
17579 <a name="gnutls_005fcertificate_005fget_005fissuer"></a><dl>
17580 <dt><a name="index-gnutls_005fcertificate_005fget_005fissuer"></a>Function: <em>int</em> <strong>gnutls_certificate_get_issuer</strong> <em>(gnutls_certificate_credentials_t <var>sc</var>, gnutls_x509_crt_t <var>cert</var>, gnutls_x509_crt_t * <var>issuer</var>, unsigned int <var>flags</var>)</em></dt>
17581 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17582 </p>
17583 <p><var>cert</var>: is the certificate to find issuer for
17584 </p>
17585 <p><var>issuer</var>: Will hold the issuer if any. Should be treated as constant.
17586 </p>
17587 <p><var>flags</var>: Use zero or <code>GNUTLS_TL_GET_COPY</code>
17588 </p>
17589 <p>This function will return the issuer of a given certificate.
17590 As with <code>gnutls_x509_trust_list_get_issuer()</code>  this function requires
17591 the <code>GNUTLS_TL_GET_COPY</code>  flag in order to operate with PKCS <code>11</code>  trust
17592 lists. In that case the issuer must be freed using <code>gnutls_x509_crt_deinit()</code> .
17593 </p>
17594 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
17595 negative error value.
17596 </p>
17597 <p><strong>Since:</strong> 3.0
17598 </p></dd></dl>
17599
17600 <a name="gnutls_005fcertificate_005fget_005fours-1"></a>
17601 <h4 class="subheading">gnutls_certificate_get_ours</h4>
17602 <a name="gnutls_005fcertificate_005fget_005fours"></a><dl>
17603 <dt><a name="index-gnutls_005fcertificate_005fget_005fours"></a>Function: <em>const gnutls_datum_t *</em> <strong>gnutls_certificate_get_ours</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
17604 <dd><p><var>session</var>: is a gnutls session
17605 </p>
17606 <p>Gets the certificate as sent to the peer in the last handshake.
17607 The certificate is in raw (DER) format.  No certificate
17608 list is being returned. Only the first certificate.
17609 </p>
17610 <p><strong>Returns:</strong> a pointer to a <code>gnutls_datum_t</code>  containing our
17611 certificate, or <code>NULL</code>  in case of an error or if no certificate
17612 was used.
17613 </p></dd></dl>
17614
17615 <a name="gnutls_005fcertificate_005fget_005fpeers-1"></a>
17616 <h4 class="subheading">gnutls_certificate_get_peers</h4>
17617 <a name="gnutls_005fcertificate_005fget_005fpeers"></a><dl>
17618 <dt><a name="index-gnutls_005fcertificate_005fget_005fpeers"></a>Function: <em>const gnutls_datum_t *</em> <strong>gnutls_certificate_get_peers</strong> <em>(gnutls_session_t          <var>session</var>, unsigned int * <var>list_size</var>)</em></dt>
17619 <dd><p><var>session</var>: is a gnutls session
17620 </p>
17621 <p><var>list_size</var>: is the length of the certificate list (may be <code>NULL</code> )
17622 </p>
17623 <p>Get the peer&rsquo;s raw certificate (chain) as sent by the peer.  These
17624 certificates are in raw format (DER encoded for X.509).  In case of
17625 a X.509 then a certificate list may be present.  The first
17626 certificate in the list is the peer&rsquo;s certificate, following the
17627 issuer&rsquo;s certificate, then the issuer&rsquo;s issuer etc.
17628 </p>
17629 <p>In case of OpenPGP keys a single key will be returned in raw
17630 format.
17631 </p>
17632 <p><strong>Returns:</strong> a pointer to a <code>gnutls_datum_t</code>  containing the peer&rsquo;s
17633 certificates, or <code>NULL</code>  in case of an error or if no certificate
17634 was used.
17635 </p></dd></dl>
17636
17637 <a name="gnutls_005fcertificate_005fget_005fpeers_005fsubkey_005fid-1"></a>
17638 <h4 class="subheading">gnutls_certificate_get_peers_subkey_id</h4>
17639 <a name="gnutls_005fcertificate_005fget_005fpeers_005fsubkey_005fid"></a><dl>
17640 <dt><a name="index-gnutls_005fcertificate_005fget_005fpeers_005fsubkey_005fid"></a>Function: <em>int</em> <strong>gnutls_certificate_get_peers_subkey_id</strong> <em>(gnutls_session_t <var>session</var>, gnutls_datum_t * <var>id</var>)</em></dt>
17641 <dd><p><var>session</var>: is a gnutls session
17642 </p>
17643 <p><var>id</var>: will contain the ID
17644 </p>
17645 <p>Get the peer&rsquo;s subkey ID when OpenPGP certificates are
17646 used. The returned  <code>id</code> should be treated as constant.
17647 </p>
17648 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
17649 an error code is returned.
17650 </p>
17651 <p><strong>Since:</strong> 3.1.3
17652 </p></dd></dl>
17653
17654 <a name="gnutls_005fcertificate_005fsend_005fx509_005frdn_005fsequence-1"></a>
17655 <h4 class="subheading">gnutls_certificate_send_x509_rdn_sequence</h4>
17656 <a name="gnutls_005fcertificate_005fsend_005fx509_005frdn_005fsequence"></a><dl>
17657 <dt><a name="index-gnutls_005fcertificate_005fsend_005fx509_005frdn_005fsequence-1"></a>Function: <em>void</em> <strong>gnutls_certificate_send_x509_rdn_sequence</strong> <em>(gnutls_session_t <var>session</var>, int <var>status</var>)</em></dt>
17658 <dd><p><var>session</var>: is a pointer to a <code>gnutls_session_t</code>  structure.
17659 </p>
17660 <p><var>status</var>: is 0 or 1
17661 </p>
17662 <p>If status is non zero, this function will order gnutls not to send
17663 the rdnSequence in the certificate request message. That is the
17664 server will not advertise its trusted CAs to the peer. If status
17665 is zero then the default behaviour will take effect, which is to
17666 advertise the server&rsquo;s trusted CAs.
17667 </p>
17668 <p>This function has no effect in clients, and in authentication
17669 methods other than certificate with X.509 certificates.
17670 </p></dd></dl>
17671
17672 <a name="gnutls_005fcertificate_005fserver_005fset_005frequest-1"></a>
17673 <h4 class="subheading">gnutls_certificate_server_set_request</h4>
17674 <a name="gnutls_005fcertificate_005fserver_005fset_005frequest"></a><dl>
17675 <dt><a name="index-gnutls_005fcertificate_005fserver_005fset_005frequest-1"></a>Function: <em>void</em> <strong>gnutls_certificate_server_set_request</strong> <em>(gnutls_session_t <var>session</var>, gnutls_certificate_request_t <var>req</var>)</em></dt>
17676 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
17677 </p>
17678 <p><var>req</var>: is one of GNUTLS_CERT_REQUEST, GNUTLS_CERT_REQUIRE
17679 </p>
17680 <p>This function specifies if we (in case of a server) are going to
17681 send a certificate request message to the client. If  <code>req</code> is
17682 GNUTLS_CERT_REQUIRE then the server will return an error if the
17683 peer does not provide a certificate. If you do not call this
17684 function then the client will not be asked to send a certificate.
17685 </p></dd></dl>
17686
17687 <a name="gnutls_005fcertificate_005fset_005fdh_005fparams-1"></a>
17688 <h4 class="subheading">gnutls_certificate_set_dh_params</h4>
17689 <a name="gnutls_005fcertificate_005fset_005fdh_005fparams"></a><dl>
17690 <dt><a name="index-gnutls_005fcertificate_005fset_005fdh_005fparams"></a>Function: <em>void</em> <strong>gnutls_certificate_set_dh_params</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, gnutls_dh_params_t <var>dh_params</var>)</em></dt>
17691 <dd><p><var>res</var>: is a gnutls_certificate_credentials_t structure
17692 </p>
17693 <p><var>dh_params</var>: is a structure that holds Diffie-Hellman parameters.
17694 </p>
17695 <p>This function will set the Diffie-Hellman parameters for a
17696 certificate server to use. These parameters will be used in
17697 Ephemeral Diffie-Hellman cipher suites.  Note that only a pointer
17698 to the parameters are stored in the certificate handle, so you
17699 must not deallocate the parameters before the certificate is deallocated.
17700 </p></dd></dl>
17701
17702 <a name="gnutls_005fcertificate_005fset_005focsp_005fstatus_005frequest_005ffile-1"></a>
17703 <h4 class="subheading">gnutls_certificate_set_ocsp_status_request_file</h4>
17704 <a name="gnutls_005fcertificate_005fset_005focsp_005fstatus_005frequest_005ffile"></a><dl>
17705 <dt><a name="index-gnutls_005fcertificate_005fset_005focsp_005fstatus_005frequest_005ffile"></a>Function: <em>int</em> <strong>gnutls_certificate_set_ocsp_status_request_file</strong> <em>(gnutls_certificate_credentials_t <var>sc</var>, const char * <var>response_file</var>, unsigned int <var>flags</var>)</em></dt>
17706 <dd><p><var>sc</var>: is a credentials structure.
17707 </p>
17708 <p><var>response_file</var>: a filename of the OCSP response
17709 </p>
17710 <p><var>flags</var>: should be zero
17711 </p>
17712 <p>This function sets the filename of an OCSP response, that will be
17713 sent to the client if requests an OCSP certificate status. This is
17714 a convenience function which is inefficient on busy servers since
17715 the file is opened on every access. Use
17716 <code>gnutls_certificate_set_ocsp_status_request_function()</code>  to fine-tune
17717 file accesses.
17718 </p>
17719 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
17720 otherwise a negative error code is returned.
17721 </p>
17722 <p><strong>Since:</strong> 3.1.3
17723 </p></dd></dl>
17724
17725 <a name="gnutls_005fcertificate_005fset_005focsp_005fstatus_005frequest_005ffunction-1"></a>
17726 <h4 class="subheading">gnutls_certificate_set_ocsp_status_request_function</h4>
17727 <a name="gnutls_005fcertificate_005fset_005focsp_005fstatus_005frequest_005ffunction"></a><dl>
17728 <dt><a name="index-gnutls_005fcertificate_005fset_005focsp_005fstatus_005frequest_005ffunction"></a>Function: <em>void</em> <strong>gnutls_certificate_set_ocsp_status_request_function</strong> <em>(gnutls_certificate_credentials_t <var>sc</var>, gnutls_status_request_ocsp_func <var>ocsp_func</var>, void * <var>ptr</var>)</em></dt>
17729 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17730 </p>
17731 <p><var>ocsp_func</var>: function pointer to OCSP status request callback.
17732 </p>
17733 <p><var>ptr</var>: opaque pointer passed to callback function
17734 </p>
17735 <p>This function is to be used by server to register a callback to
17736 handle OCSP status requests from the client.  The callback will be
17737 invoked if the client supplied a status-request OCSP extension.
17738 The callback function prototype is:
17739 </p>
17740 <p>typedef int (*gnutls_status_request_ocsp_func)
17741 (gnutls_session_t session, void *ptr, gnutls_datum_t *ocsp_response);
17742 </p>
17743 <p>The callback will be invoked if the client requests an OCSP certificate
17744 status.  The callback may return <code>GNUTLS_E_NO_CERTIFICATE_STATUS</code> , if
17745 there is no recent OCSP response. If the callback returns <code>GNUTLS_E_SUCCESS</code> ,
17746 the server will provide the client with the ocsp_response.
17747 </p>
17748 <p>The response must be a value allocated using <code>gnutls_malloc()</code> , and will be
17749 deinitialized when needed.
17750 </p>
17751 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
17752 otherwise a negative error code is returned.
17753 </p>
17754 <p><strong>Since:</strong> 3.1.3
17755 </p></dd></dl>
17756
17757 <a name="gnutls_005fcertificate_005fset_005fparams_005ffunction-1"></a>
17758 <h4 class="subheading">gnutls_certificate_set_params_function</h4>
17759 <a name="gnutls_005fcertificate_005fset_005fparams_005ffunction"></a><dl>
17760 <dt><a name="index-gnutls_005fcertificate_005fset_005fparams_005ffunction-1"></a>Function: <em>void</em> <strong>gnutls_certificate_set_params_function</strong> <em>(gnutls_certificate_credentials_t            <var>res</var>, gnutls_params_function * <var>func</var>)</em></dt>
17761 <dd><p><var>res</var>: is a gnutls_certificate_credentials_t structure
17762 </p>
17763 <p><var>func</var>: is the function to be called
17764 </p>
17765 <p>This function will set a callback in order for the server to get
17766 the Diffie-Hellman or RSA parameters for certificate
17767 authentication.  The callback should return <code>GNUTLS_E_SUCCESS</code>  (0) on success.
17768 </p></dd></dl>
17769
17770 <a name="gnutls_005fcertificate_005fset_005fpin_005ffunction-1"></a>
17771 <h4 class="subheading">gnutls_certificate_set_pin_function</h4>
17772 <a name="gnutls_005fcertificate_005fset_005fpin_005ffunction"></a><dl>
17773 <dt><a name="index-gnutls_005fcertificate_005fset_005fpin_005ffunction-1"></a>Function: <em>void</em> <strong>gnutls_certificate_set_pin_function</strong> <em>(gnutls_certificate_credentials_t       <var>cred</var>, gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</em></dt>
17774 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17775 </p>
17776 <p><var>fn</var>: A PIN callback
17777 </p>
17778 <p><var>userdata</var>: Data to be passed in the callback
17779 </p>
17780 <p>This function will set a callback function to be used when
17781 required to access a protected object. This function overrides any other
17782 global PIN functions.
17783 </p>
17784 <p>Note that this function must be called right after initialization
17785 to have effect.
17786 </p>
17787 <p><strong>Since:</strong> 3.1.0
17788 </p></dd></dl>
17789
17790 <a name="gnutls_005fcertificate_005fset_005fretrieve_005ffunction-1"></a>
17791 <h4 class="subheading">gnutls_certificate_set_retrieve_function</h4>
17792 <a name="gnutls_005fcertificate_005fset_005fretrieve_005ffunction"></a><dl>
17793 <dt><a name="index-gnutls_005fcertificate_005fset_005fretrieve_005ffunction"></a>Function: <em>void</em> <strong>gnutls_certificate_set_retrieve_function</strong> <em>(gnutls_certificate_credentials_t <var>cred</var>, gnutls_certificate_retrieve_function * <var>func</var>)</em></dt>
17794 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17795 </p>
17796 <p><var>func</var>: is the callback function
17797 </p>
17798 <p>This function sets a callback to be called in order to retrieve the
17799 certificate to be used in the handshake. You are advised
17800 to use <code>gnutls_certificate_set_retrieve_function2()</code>  because it
17801 is much more efficient in the processing it requires from gnutls.
17802 </p>
17803 <p>The callback&rsquo;s function prototype is:
17804 int (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int nreqs,
17805 const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length, gnutls_retr2_st* st);
17806 </p>
17807 <p><code>req_ca_dn</code> is only used in X.509 certificates.
17808 Contains a list with the CA names that the server considers trusted.
17809 Normally we should send a certificate that is signed
17810 by one of these CAs. These names are DER encoded. To get a more
17811 meaningful value use the function <code>gnutls_x509_rdn_get()</code> .
17812 </p>
17813 <p><code>pk_algos</code> contains a list with server&rsquo;s acceptable signature algorithms.
17814 The certificate returned should support the server&rsquo;s given algorithms.
17815 </p>
17816 <p><code>st</code> should contain the certificates and private keys.
17817 </p>
17818 <p>If the callback function is provided then gnutls will call it, in the
17819 handshake, after the certificate request message has been received.
17820 </p>
17821 <p>In server side pk_algos and req_ca_dn are NULL.
17822 </p>
17823 <p>The callback function should set the certificate list to be sent,
17824 and return 0 on success. If no certificate was selected then the
17825 number of certificates should be set to zero. The value (-1)
17826 indicates error and the handshake will be terminated.
17827 </p>
17828 <p><strong>Since:</strong> 3.0
17829 </p></dd></dl>
17830
17831 <a name="gnutls_005fcertificate_005fset_005fverify_005fflags-1"></a>
17832 <h4 class="subheading">gnutls_certificate_set_verify_flags</h4>
17833 <a name="gnutls_005fcertificate_005fset_005fverify_005fflags"></a><dl>
17834 <dt><a name="index-gnutls_005fcertificate_005fset_005fverify_005fflags"></a>Function: <em>void</em> <strong>gnutls_certificate_set_verify_flags</strong> <em>(gnutls_certificate_credentials_t         <var>res</var>, unsigned int <var>flags</var>)</em></dt>
17835 <dd><p><var>res</var>: is a gnutls_certificate_credentials_t structure
17836 </p>
17837 <p><var>flags</var>: are the flags
17838 </p>
17839 <p>This function will set the flags to be used for verification
17840 of certificates and override any defaults.  The provided flags must be an OR of the
17841 <code>gnutls_certificate_verify_flags</code>  enumerations.
17842 </p></dd></dl>
17843
17844 <a name="gnutls_005fcertificate_005fset_005fverify_005ffunction-1"></a>
17845 <h4 class="subheading">gnutls_certificate_set_verify_function</h4>
17846 <a name="gnutls_005fcertificate_005fset_005fverify_005ffunction"></a><dl>
17847 <dt><a name="index-gnutls_005fcertificate_005fset_005fverify_005ffunction-1"></a>Function: <em>void</em> <strong>gnutls_certificate_set_verify_function</strong> <em>(gnutls_certificate_credentials_t <var>cred</var>, gnutls_certificate_verify_function * <var>func</var>)</em></dt>
17848 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17849 </p>
17850 <p><var>func</var>: is the callback function
17851 </p>
17852 <p>This function sets a callback to be called when peer&rsquo;s certificate
17853 has been received in order to verify it on receipt rather than
17854 doing after the handshake is completed.
17855 </p>
17856 <p>The callback&rsquo;s function prototype is:
17857 int (*callback)(gnutls_session_t);
17858 </p>
17859 <p>If the callback function is provided then gnutls will call it, in the
17860 handshake, just after the certificate message has been received.
17861 To verify or obtain the certificate the <code>gnutls_certificate_verify_peers2()</code> ,
17862 <code>gnutls_certificate_type_get()</code> , <code>gnutls_certificate_get_peers()</code>  functions
17863 can be used.
17864 </p>
17865 <p>The callback function should return 0 for the handshake to continue
17866 or non-zero to terminate.
17867 </p>
17868 <p><strong>Since:</strong> 2.10.0
17869 </p></dd></dl>
17870
17871 <a name="gnutls_005fcertificate_005fset_005fverify_005flimits-1"></a>
17872 <h4 class="subheading">gnutls_certificate_set_verify_limits</h4>
17873 <a name="gnutls_005fcertificate_005fset_005fverify_005flimits"></a><dl>
17874 <dt><a name="index-gnutls_005fcertificate_005fset_005fverify_005flimits"></a>Function: <em>void</em> <strong>gnutls_certificate_set_verify_limits</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, unsigned int <var>max_bits</var>, unsigned int <var>max_depth</var>)</em></dt>
17875 <dd><p><var>res</var>: is a gnutls_certificate_credentials structure
17876 </p>
17877 <p><var>max_bits</var>: is the number of bits of an acceptable certificate (default 8200)
17878 </p>
17879 <p><var>max_depth</var>: is maximum depth of the verification of a certificate chain (default 5)
17880 </p>
17881 <p>This function will set some upper limits for the default
17882 verification function, <code>gnutls_certificate_verify_peers2()</code> , to avoid
17883 denial of service attacks.  You can set them to zero to disable
17884 limits.
17885 </p></dd></dl>
17886
17887 <a name="gnutls_005fcertificate_005fset_005fx509_005fcrl-1"></a>
17888 <h4 class="subheading">gnutls_certificate_set_x509_crl</h4>
17889 <a name="gnutls_005fcertificate_005fset_005fx509_005fcrl"></a><dl>
17890 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005fcrl"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_crl</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, gnutls_x509_crl_t * <var>crl_list</var>, int <var>crl_list_size</var>)</em></dt>
17891 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17892 </p>
17893 <p><var>crl_list</var>: is a list of trusted CRLs. They should have been verified before.
17894 </p>
17895 <p><var>crl_list_size</var>: holds the size of the crl_list
17896 </p>
17897 <p>This function adds the trusted CRLs in order to verify client or
17898 server certificates.  In case of a client this is not required to
17899 be called if the certificates are not verified using
17900 <code>gnutls_certificate_verify_peers2()</code> .  This function may be called
17901 multiple times.
17902 </p>
17903 <p><strong>Returns:</strong> number of CRLs processed, or a negative error code on error.
17904 </p>
17905 <p><strong>Since:</strong> 2.4.0
17906 </p></dd></dl>
17907
17908 <a name="gnutls_005fcertificate_005fset_005fx509_005fcrl_005ffile-1"></a>
17909 <h4 class="subheading">gnutls_certificate_set_x509_crl_file</h4>
17910 <a name="gnutls_005fcertificate_005fset_005fx509_005fcrl_005ffile"></a><dl>
17911 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005fcrl_005ffile"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_crl_file</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, const char * <var>crlfile</var>, gnutls_x509_crt_fmt_t <var>type</var>)</em></dt>
17912 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17913 </p>
17914 <p><var>crlfile</var>: is a file containing the list of verified CRLs (DER or PEM list)
17915 </p>
17916 <p><var>type</var>: is PEM or DER
17917 </p>
17918 <p>This function adds the trusted CRLs in order to verify client or server
17919 certificates.  In case of a client this is not required
17920 to be called if the certificates are not verified using
17921 <code>gnutls_certificate_verify_peers2()</code> .
17922 This function may be called multiple times.
17923 </p>
17924 <p><strong>Returns:</strong> number of CRLs processed or a negative error code on error.
17925 </p></dd></dl>
17926
17927 <a name="gnutls_005fcertificate_005fset_005fx509_005fcrl_005fmem-1"></a>
17928 <h4 class="subheading">gnutls_certificate_set_x509_crl_mem</h4>
17929 <a name="gnutls_005fcertificate_005fset_005fx509_005fcrl_005fmem"></a><dl>
17930 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005fcrl_005fmem"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_crl_mem</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, const gnutls_datum_t * <var>CRL</var>, gnutls_x509_crt_fmt_t <var>type</var>)</em></dt>
17931 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17932 </p>
17933 <p><var>CRL</var>: is a list of trusted CRLs. They should have been verified before.
17934 </p>
17935 <p><var>type</var>: is DER or PEM
17936 </p>
17937 <p>This function adds the trusted CRLs in order to verify client or
17938 server certificates.  In case of a client this is not required to
17939 be called if the certificates are not verified using
17940 <code>gnutls_certificate_verify_peers2()</code> .  This function may be called
17941 multiple times.
17942 </p>
17943 <p><strong>Returns:</strong> number of CRLs processed, or a negative error code on error.
17944 </p></dd></dl>
17945
17946 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey-1"></a>
17947 <h4 class="subheading">gnutls_certificate_set_x509_key</h4>
17948 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey"></a><dl>
17949 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005fkey"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_key</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, gnutls_x509_crt_t * <var>cert_list</var>, int <var>cert_list_size</var>, gnutls_x509_privkey_t <var>key</var>)</em></dt>
17950 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17951 </p>
17952 <p><var>cert_list</var>: contains a certificate list (path) for the specified private key
17953 </p>
17954 <p><var>cert_list_size</var>: holds the size of the certificate list
17955 </p>
17956 <p><var>key</var>: is a <code>gnutls_x509_privkey_t</code>  key
17957 </p>
17958 <p>This function sets a certificate/private key pair in the
17959 gnutls_certificate_credentials_t structure.  This function may be
17960 called more than once, in case multiple keys/certificates exist for
17961 the server.  For clients that wants to send more than their own end
17962 entity certificate (e.g., also an intermediate CA cert) then put
17963 the certificate chain in  <code>cert_list</code> .
17964 </p>
17965 <p>Note that the certificates and keys provided, can be safely deinitialized
17966 after this function is called.
17967 </p>
17968 <p>If that function fails to load the  <code>res</code> structure is at an undefined state, it must
17969 not be reused to load other keys or certificates.
17970 </p>
17971 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success, or a negative error code.
17972 </p>
17973 <p><strong>Since:</strong> 2.4.0
17974 </p></dd></dl>
17975
17976 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile-1"></a>
17977 <h4 class="subheading">gnutls_certificate_set_x509_key_file</h4>
17978 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile"></a><dl>
17979 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_key_file</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, const char * <var>certfile</var>, const char * <var>keyfile</var>, gnutls_x509_crt_fmt_t <var>type</var>)</em></dt>
17980 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
17981 </p>
17982 <p><var>certfile</var>: is a file that containing the certificate list (path) for
17983 the specified private key, in PKCS7 format, or a list of certificates
17984 </p>
17985 <p><var>keyfile</var>: is a file that contains the private key
17986 </p>
17987 <p><var>type</var>: is PEM or DER
17988 </p>
17989 <p>This function sets a certificate/private key pair in the
17990 gnutls_certificate_credentials_t structure.  This function may be
17991 called more than once, in case multiple keys/certificates exist for
17992 the server.  For clients that need to send more than its own end
17993 entity certificate, e.g., also an intermediate CA cert, then the
17994  <code>certfile</code> must contain the ordered certificate chain.
17995 </p>
17996 <p>Note that the names in the certificate provided will be considered
17997 when selecting the appropriate certificate to use (in case of multiple
17998 certificate/key pairs).
17999 </p>
18000 <p>This function can also accept URLs at  <code>keyfile</code> and  <code>certfile</code> . In that case it
18001 will import the private key and certificate indicated by the URLs. Note
18002 that the supported URLs are the ones indicated by <code>gnutls_url_is_supported()</code> .
18003 </p>
18004 <p>In case the  <code>certfile</code> is provided as a PKCS <code>11</code>  URL, then the certificate, and its
18005 present issuers in the token are are imported (i.e., the required trust chain).
18006 </p>
18007 <p>If that function fails to load the  <code>res</code> structure is at an undefined state, it must
18008 not be reused to load other keys or certificates.
18009 </p>
18010 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success, or a negative error code.
18011 </p></dd></dl>
18012
18013 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile2-1"></a>
18014 <h4 class="subheading">gnutls_certificate_set_x509_key_file2</h4>
18015 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile2"></a><dl>
18016 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile2"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_key_file2</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, const char * <var>certfile</var>, const char * <var>keyfile</var>, gnutls_x509_crt_fmt_t <var>type</var>, const char * <var>pass</var>, unsigned int <var>flags</var>)</em></dt>
18017 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
18018 </p>
18019 <p><var>certfile</var>: is a file that containing the certificate list (path) for
18020 the specified private key, in PKCS7 format, or a list of certificates
18021 </p>
18022 <p><var>keyfile</var>: is a file that contains the private key
18023 </p>
18024 <p><var>type</var>: is PEM or DER
18025 </p>
18026 <p><var>pass</var>: is the password of the key
18027 </p>
18028 <p><var>flags</var>: an ORed sequence of gnutls_pkcs_encrypt_flags_t
18029 </p>
18030 <p>This function sets a certificate/private key pair in the
18031 gnutls_certificate_credentials_t structure.  This function may be
18032 called more than once, in case multiple keys/certificates exist for
18033 the server.  For clients that need to send more than its own end
18034 entity certificate, e.g., also an intermediate CA cert, then the
18035  <code>certfile</code> must contain the ordered certificate chain.
18036 </p>
18037 <p>Note that the names in the certificate provided will be considered
18038 when selecting the appropriate certificate to use (in case of multiple
18039 certificate/key pairs).
18040 </p>
18041 <p>This function can also accept URLs at  <code>keyfile</code> and  <code>certfile</code> . In that case it
18042 will import the private key and certificate indicated by the URLs. Note
18043 that the supported URLs are the ones indicated by <code>gnutls_url_is_supported()</code> .
18044 </p>
18045 <p>In case the  <code>certfile</code> is provided as a PKCS <code>11</code>  URL, then the certificate, and its
18046 present issuers in the token are are imported (i.e., the required trust chain).
18047 </p>
18048 <p>If that function fails to load the  <code>res</code> structure is at an undefined state, it must
18049 not be reused to load other keys or certificates.
18050 </p>
18051 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success, or a negative error code.
18052 </p></dd></dl>
18053
18054 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey_005fmem-1"></a>
18055 <h4 class="subheading">gnutls_certificate_set_x509_key_mem</h4>
18056 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey_005fmem"></a><dl>
18057 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005fkey_005fmem"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_key_mem</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, const gnutls_datum_t * <var>cert</var>, const gnutls_datum_t * <var>key</var>, gnutls_x509_crt_fmt_t <var>type</var>)</em></dt>
18058 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
18059 </p>
18060 <p><var>cert</var>: contains a certificate list (path) for the specified private key
18061 </p>
18062 <p><var>key</var>: is the private key, or <code>NULL</code>
18063 </p>
18064 <p><var>type</var>: is PEM or DER
18065 </p>
18066 <p>This function sets a certificate/private key pair in the
18067 gnutls_certificate_credentials_t structure. This function may be called
18068 more than once, in case multiple keys/certificates exist for the
18069 server.
18070 </p>
18071 <p>Note that the keyUsage (2.5.29.15) PKIX extension in X.509 certificates
18072 is supported. This means that certificates intended for signing cannot
18073 be used for ciphersuites that require encryption.
18074 </p>
18075 <p>If the certificate and the private key are given in PEM encoding
18076 then the strings that hold their values must be null terminated.
18077 </p>
18078 <p>The  <code>key</code> may be <code>NULL</code>  if you are using a sign callback, see
18079 <code>gnutls_sign_callback_set()</code> .
18080 </p>
18081 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success, or a negative error code.
18082 </p></dd></dl>
18083
18084 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey_005fmem2-1"></a>
18085 <h4 class="subheading">gnutls_certificate_set_x509_key_mem2</h4>
18086 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey_005fmem2"></a><dl>
18087 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005fkey_005fmem2"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_key_mem2</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, const gnutls_datum_t * <var>cert</var>, const gnutls_datum_t * <var>key</var>, gnutls_x509_crt_fmt_t <var>type</var>, const char * <var>pass</var>, unsigned int <var>flags</var>)</em></dt>
18088 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
18089 </p>
18090 <p><var>cert</var>: contains a certificate list (path) for the specified private key
18091 </p>
18092 <p><var>key</var>: is the private key, or <code>NULL</code>
18093 </p>
18094 <p><var>type</var>: is PEM or DER
18095 </p>
18096 <p><var>pass</var>: is the key&rsquo;s password
18097 </p>
18098 <p><var>flags</var>: an ORed sequence of gnutls_pkcs_encrypt_flags_t
18099 </p>
18100 <p>This function sets a certificate/private key pair in the
18101 gnutls_certificate_credentials_t structure. This function may be called
18102 more than once, in case multiple keys/certificates exist for the
18103 server.
18104 </p>
18105 <p>Note that the keyUsage (2.5.29.15) PKIX extension in X.509 certificates
18106 is supported. This means that certificates intended for signing cannot
18107 be used for ciphersuites that require encryption.
18108 </p>
18109 <p>If the certificate and the private key are given in PEM encoding
18110 then the strings that hold their values must be null terminated.
18111 </p>
18112 <p>The  <code>key</code> may be <code>NULL</code>  if you are using a sign callback, see
18113 <code>gnutls_sign_callback_set()</code> .
18114 </p>
18115 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success, or a negative error code.
18116 </p></dd></dl>
18117
18118 <a name="gnutls_005fcertificate_005fset_005fx509_005fsimple_005fpkcs12_005ffile-1"></a>
18119 <h4 class="subheading">gnutls_certificate_set_x509_simple_pkcs12_file</h4>
18120 <a name="gnutls_005fcertificate_005fset_005fx509_005fsimple_005fpkcs12_005ffile"></a><dl>
18121 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005fsimple_005fpkcs12_005ffile"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_simple_pkcs12_file</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, const char * <var>pkcs12file</var>, gnutls_x509_crt_fmt_t <var>type</var>, const char * <var>password</var>)</em></dt>
18122 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
18123 </p>
18124 <p><var>pkcs12file</var>: filename of file containing PKCS<code>12</code>  blob.
18125 </p>
18126 <p><var>type</var>: is PEM or DER of the  <code>pkcs12file</code> .
18127 </p>
18128 <p><var>password</var>: optional password used to decrypt PKCS<code>12</code>  file, bags and keys.
18129 </p>
18130 <p>This function sets a certificate/private key pair and/or a CRL in
18131 the gnutls_certificate_credentials_t structure.  This function may
18132 be called more than once (in case multiple keys/certificates exist
18133 for the server).
18134 </p>
18135 <p>PKCS<code>12</code>  files with a MAC, encrypted bags and PKCS <code>8</code>
18136 private keys are supported. However,
18137 only password based security, and the same password for all
18138 operations, are supported.
18139 </p>
18140 <p>PKCS<code>12</code>  file may contain many keys and/or certificates, and this
18141 function will try to auto-detect based on the key ID the certificate
18142 and key pair to use. If the PKCS<code>12</code>  file contain the issuer of
18143 the selected certificate, it will be appended to the certificate
18144 to form a chain.
18145 </p>
18146 <p>If more than one private keys are stored in the PKCS<code>12</code>  file,
18147 then only one key will be read (and it is undefined which one).
18148 </p>
18149 <p>It is believed that the limitations of this function is acceptable
18150 for most usage, and that any more flexibility would introduce
18151 complexity that would make it harder to use this functionality at
18152 all.
18153 </p>
18154 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success, or a negative error code.
18155 </p></dd></dl>
18156
18157 <a name="gnutls_005fcertificate_005fset_005fx509_005fsimple_005fpkcs12_005fmem-1"></a>
18158 <h4 class="subheading">gnutls_certificate_set_x509_simple_pkcs12_mem</h4>
18159 <a name="gnutls_005fcertificate_005fset_005fx509_005fsimple_005fpkcs12_005fmem"></a><dl>
18160 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005fsimple_005fpkcs12_005fmem"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_simple_pkcs12_mem</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, const gnutls_datum_t * <var>p12blob</var>, gnutls_x509_crt_fmt_t <var>type</var>, const char * <var>password</var>)</em></dt>
18161 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
18162 </p>
18163 <p><var>p12blob</var>: the PKCS<code>12</code>  blob.
18164 </p>
18165 <p><var>type</var>: is PEM or DER of the  <code>pkcs12file</code> .
18166 </p>
18167 <p><var>password</var>: optional password used to decrypt PKCS<code>12</code>  file, bags and keys.
18168 </p>
18169 <p>This function sets a certificate/private key pair and/or a CRL in
18170 the gnutls_certificate_credentials_t structure.  This function may
18171 be called more than once (in case multiple keys/certificates exist
18172 for the server).
18173 </p>
18174 <p>Encrypted PKCS<code>12</code>  bags and PKCS<code>8</code>  private keys are supported.  However,
18175 only password based security, and the same password for all
18176 operations, are supported.
18177 </p>
18178 <p>PKCS<code>12</code>  file may contain many keys and/or certificates, and this
18179 function will try to auto-detect based on the key ID the certificate
18180 and key pair to use. If the PKCS<code>12</code>  file contain the issuer of
18181 the selected certificate, it will be appended to the certificate
18182 to form a chain.
18183 </p>
18184 <p>If more than one private keys are stored in the PKCS<code>12</code>  file,
18185 then only one key will be read (and it is undefined which one).
18186 </p>
18187 <p>It is believed that the limitations of this function is acceptable
18188 for most usage, and that any more flexibility would introduce
18189 complexity that would make it harder to use this functionality at
18190 all.
18191 </p>
18192 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success, or a negative error code.
18193 </p>
18194 <p><strong>Since:</strong> 2.8.0
18195 </p></dd></dl>
18196
18197 <a name="gnutls_005fcertificate_005fset_005fx509_005fsystem_005ftrust-1"></a>
18198 <h4 class="subheading">gnutls_certificate_set_x509_system_trust</h4>
18199 <a name="gnutls_005fcertificate_005fset_005fx509_005fsystem_005ftrust"></a><dl>
18200 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005fsystem_005ftrust-1"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_system_trust</strong> <em>(gnutls_certificate_credentials_t       <var>cred</var>)</em></dt>
18201 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
18202 </p>
18203 <p>This function adds the system&rsquo;s default trusted CAs in order to
18204 verify client or server certificates.
18205 </p>
18206 <p>In the case the system is currently unsupported <code>GNUTLS_E_UNIMPLEMENTED_FEATURE</code>
18207 is returned.
18208 </p>
18209 <p><strong>Returns:</strong> the number of certificates processed or a negative error code
18210 on error.
18211 </p>
18212 <p><strong>Since:</strong> 3.0.20
18213 </p></dd></dl>
18214
18215 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust-1"></a>
18216 <h4 class="subheading">gnutls_certificate_set_x509_trust</h4>
18217 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust"></a><dl>
18218 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005ftrust"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_trust</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, gnutls_x509_crt_t * <var>ca_list</var>, int <var>ca_list_size</var>)</em></dt>
18219 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
18220 </p>
18221 <p><var>ca_list</var>: is a list of trusted CAs
18222 </p>
18223 <p><var>ca_list_size</var>: holds the size of the CA list
18224 </p>
18225 <p>This function adds the trusted CAs in order to verify client
18226 or server certificates. In case of a client this is not required
18227 to be called if the certificates are not verified using
18228 <code>gnutls_certificate_verify_peers2()</code> .
18229 This function may be called multiple times.
18230 </p>
18231 <p>In case of a server the CAs set here will be sent to the client if
18232 a certificate request is sent. This can be disabled using
18233 <code>gnutls_certificate_send_x509_rdn_sequence()</code> .
18234 </p>
18235 <p><strong>Returns:</strong> the number of certificates processed or a negative error code
18236 on error.
18237 </p>
18238 <p><strong>Since:</strong> 2.4.0
18239 </p></dd></dl>
18240
18241 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust_005fdir-1"></a>
18242 <h4 class="subheading">gnutls_certificate_set_x509_trust_dir</h4>
18243 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust_005fdir"></a><dl>
18244 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005ftrust_005fdir"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_trust_dir</strong> <em>(gnutls_certificate_credentials_t <var>cred</var>, const char * <var>ca_dir</var>, gnutls_x509_crt_fmt_t <var>type</var>)</em></dt>
18245 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
18246 </p>
18247 <p><var>ca_dir</var>: is a directory containing the list of trusted CAs (DER or PEM list)
18248 </p>
18249 <p><var>type</var>: is PEM or DER
18250 </p>
18251 <p>This function adds the trusted CAs present in the directory in order to
18252 verify client or server certificates. This function is identical
18253 to <code>gnutls_certificate_set_x509_trust_file()</code>  but loads all certificates
18254 in a directory.
18255 </p>
18256 <p><strong>Returns:</strong> the number of certificates processed
18257 </p>
18258 <p><strong>Since:</strong> 3.3.6
18259 </p></dd></dl>
18260
18261 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust_005ffile-1"></a>
18262 <h4 class="subheading">gnutls_certificate_set_x509_trust_file</h4>
18263 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust_005ffile"></a><dl>
18264 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005ftrust_005ffile"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_trust_file</strong> <em>(gnutls_certificate_credentials_t            <var>cred</var>, const char * <var>cafile</var>, gnutls_x509_crt_fmt_t <var>type</var>)</em></dt>
18265 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
18266 </p>
18267 <p><var>cafile</var>: is a file containing the list of trusted CAs (DER or PEM list)
18268 </p>
18269 <p><var>type</var>: is PEM or DER
18270 </p>
18271 <p>This function adds the trusted CAs in order to verify client or
18272 server certificates. In case of a client this is not required to
18273 be called if the certificates are not verified using
18274 <code>gnutls_certificate_verify_peers2()</code> .  This function may be called
18275 multiple times.
18276 </p>
18277 <p>In case of a server the names of the CAs set here will be sent to
18278 the client if a certificate request is sent. This can be disabled
18279 using <code>gnutls_certificate_send_x509_rdn_sequence()</code> .
18280 </p>
18281 <p>This function can also accept URLs. In that case it
18282 will import all certificates that are marked as trusted. Note
18283 that the supported URLs are the ones indicated by <code>gnutls_url_is_supported()</code> .
18284 </p>
18285 <p><strong>Returns:</strong> the number of certificates processed
18286 </p></dd></dl>
18287
18288 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust_005fmem-1"></a>
18289 <h4 class="subheading">gnutls_certificate_set_x509_trust_mem</h4>
18290 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust_005fmem"></a><dl>
18291 <dt><a name="index-gnutls_005fcertificate_005fset_005fx509_005ftrust_005fmem"></a>Function: <em>int</em> <strong>gnutls_certificate_set_x509_trust_mem</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, const gnutls_datum_t * <var>ca</var>, gnutls_x509_crt_fmt_t <var>type</var>)</em></dt>
18292 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
18293 </p>
18294 <p><var>ca</var>: is a list of trusted CAs or a DER certificate
18295 </p>
18296 <p><var>type</var>: is DER or PEM
18297 </p>
18298 <p>This function adds the trusted CAs in order to verify client or
18299 server certificates. In case of a client this is not required to be
18300 called if the certificates are not verified using
18301 <code>gnutls_certificate_verify_peers2()</code> .  This function may be called
18302 multiple times.
18303 </p>
18304 <p>In case of a server the CAs set here will be sent to the client if
18305 a certificate request is sent. This can be disabled using
18306 <code>gnutls_certificate_send_x509_rdn_sequence()</code> .
18307 </p>
18308 <p><strong>Returns:</strong> the number of certificates processed or a negative error code
18309 on error.
18310 </p></dd></dl>
18311
18312 <a name="gnutls_005fcertificate_005ftype_005fget-1"></a>
18313 <h4 class="subheading">gnutls_certificate_type_get</h4>
18314 <a name="gnutls_005fcertificate_005ftype_005fget"></a><dl>
18315 <dt><a name="index-gnutls_005fcertificate_005ftype_005fget"></a>Function: <em>gnutls_certificate_type_t</em> <strong>gnutls_certificate_type_get</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
18316 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18317 </p>
18318 <p>The certificate type is by default X.509, unless it is negotiated
18319 as a TLS extension.
18320 </p>
18321 <p><strong>Returns:</strong> the currently used <code>gnutls_certificate_type_t</code>  certificate
18322 type.
18323 </p></dd></dl>
18324
18325 <a name="gnutls_005fcertificate_005ftype_005fget_005fid-1"></a>
18326 <h4 class="subheading">gnutls_certificate_type_get_id</h4>
18327 <a name="gnutls_005fcertificate_005ftype_005fget_005fid"></a><dl>
18328 <dt><a name="index-gnutls_005fcertificate_005ftype_005fget_005fid"></a>Function: <em>gnutls_certificate_type_t</em> <strong>gnutls_certificate_type_get_id</strong> <em>(const char * <var>name</var>)</em></dt>
18329 <dd><p><var>name</var>: is a certificate type name
18330 </p>
18331 <p>The names are compared in a case insensitive way.
18332 </p>
18333 <p><strong>Returns:</strong> a <code>gnutls_certificate_type_t</code>  for the specified in a
18334 string certificate type, or <code>GNUTLS_CRT_UNKNOWN</code>  on error.
18335 </p></dd></dl>
18336
18337 <a name="gnutls_005fcertificate_005ftype_005fget_005fname-1"></a>
18338 <h4 class="subheading">gnutls_certificate_type_get_name</h4>
18339 <a name="gnutls_005fcertificate_005ftype_005fget_005fname"></a><dl>
18340 <dt><a name="index-gnutls_005fcertificate_005ftype_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_certificate_type_get_name</strong> <em>(gnutls_certificate_type_t           <var>type</var>)</em></dt>
18341 <dd><p><var>type</var>: is a certificate type
18342 </p>
18343 <p>Convert a <code>gnutls_certificate_type_t</code>  type to a string.
18344 </p>
18345 <p><strong>Returns:</strong> a string that contains the name of the specified
18346 certificate type, or <code>NULL</code>  in case of unknown types.
18347 </p></dd></dl>
18348
18349 <a name="gnutls_005fcertificate_005ftype_005flist-1"></a>
18350 <h4 class="subheading">gnutls_certificate_type_list</h4>
18351 <a name="gnutls_005fcertificate_005ftype_005flist"></a><dl>
18352 <dt><a name="index-gnutls_005fcertificate_005ftype_005flist"></a>Function: <em>const gnutls_certificate_type_t *</em> <strong>gnutls_certificate_type_list</strong> <em>( <var>void</var>)</em></dt>
18353 <dd>
18354 <p>Get a list of certificate types.
18355 </p>
18356 <p><strong>Returns:</strong> a (0)-terminated list of <code>gnutls_certificate_type_t</code>
18357 integers indicating the available certificate types.
18358 </p></dd></dl>
18359
18360 <a name="gnutls_005fcertificate_005fverification_005fstatus_005fprint-1"></a>
18361 <h4 class="subheading">gnutls_certificate_verification_status_print</h4>
18362 <a name="gnutls_005fcertificate_005fverification_005fstatus_005fprint"></a><dl>
18363 <dt><a name="index-gnutls_005fcertificate_005fverification_005fstatus_005fprint"></a>Function: <em>int</em> <strong>gnutls_certificate_verification_status_print</strong> <em>(unsigned int <var>status</var>, gnutls_certificate_type_t           <var>type</var>, gnutls_datum_t * <var>out</var>, unsigned int <var>flags</var>)</em></dt>
18364 <dd><p><var>status</var>: The status flags to be printed
18365 </p>
18366 <p><var>type</var>: The certificate type
18367 </p>
18368 <p><var>out</var>: Newly allocated datum with (0) terminated string.
18369 </p>
18370 <p><var>flags</var>: should be zero
18371 </p>
18372 <p>This function will pretty print the status of a verification
18373 process &ndash; eg. the one obtained by <code>gnutls_certificate_verify_peers3()</code> .
18374 </p>
18375 <p>The output  <code>out</code> needs to be deallocated using <code>gnutls_free()</code> .
18376 </p>
18377 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
18378 negative error value.
18379 </p>
18380 <p><strong>Since:</strong> 3.1.4
18381 </p></dd></dl>
18382
18383 <a name="gnutls_005fcertificate_005fverify_005fpeers-1"></a>
18384 <h4 class="subheading">gnutls_certificate_verify_peers</h4>
18385 <a name="gnutls_005fcertificate_005fverify_005fpeers"></a><dl>
18386 <dt><a name="index-gnutls_005fcertificate_005fverify_005fpeers"></a>Function: <em>int</em> <strong>gnutls_certificate_verify_peers</strong> <em>(gnutls_session_t <var>session</var>, gnutls_typed_vdata_st * <var>data</var>, unsigned int <var>elements</var>, unsigned int * <var>status</var>)</em></dt>
18387 <dd><p><var>session</var>: is a gnutls session
18388 </p>
18389 <p><var>data</var>: an array of typed data
18390 </p>
18391 <p><var>elements</var>: the number of data elements
18392 </p>
18393 <p><var>status</var>: is the output of the verification
18394 </p>
18395 <p>This function will verify the peer&rsquo;s certificate and store the
18396 status in the  <code>status</code> variable as a bitwise or&rsquo;d gnutls_certificate_status_t
18397 values or zero if the certificate is trusted. Note that value in  <code>status</code> is set only when the return value of this function is success (i.e, failure
18398 to trust a certificate does not imply a negative return value).
18399 The default verification flags used by this function can be overridden
18400 using <code>gnutls_certificate_set_verify_flags()</code> . See the documentation
18401 of <code>gnutls_certificate_verify_peers2()</code>  for details in the verification process.
18402 </p>
18403 <p>The acceptable  <code>data</code> types are <code>GNUTLS_DT_DNS_HOSTNAME</code>  and <code>GNUTLS_DT_KEY_PURPOSE_OID</code> .
18404 The former accepts as data a null-terminated hostname, and the latter a null-terminated
18405 object identifier (e.g., <code>GNUTLS_KP_TLS_WWW_SERVER</code> ).
18406 If a DNS hostname is provided then this function will compare
18407 the hostname in the certificate against the given. If names do not match the
18408 <code>GNUTLS_CERT_UNEXPECTED_OWNER</code>  status flag will be set.
18409 If a key purpose OID is provided and the end-certificate contains the extended key
18410 usage PKIX extension, it will be required to be have the provided key purpose
18411 or be marked for any purpose, otherwise verification will fail with <code>GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE</code>  status.
18412 </p>
18413 <p><strong>Returns:</strong> a negative error code on error and <code>GNUTLS_E_SUCCESS</code>  (0)
18414 when the peer&rsquo;s certificate was successfully parsed, irrespective of whether
18415 it was verified.
18416 </p>
18417 <p><strong>Since:</strong> 3.3.0
18418 </p></dd></dl>
18419
18420 <a name="gnutls_005fcertificate_005fverify_005fpeers2-1"></a>
18421 <h4 class="subheading">gnutls_certificate_verify_peers2</h4>
18422 <a name="gnutls_005fcertificate_005fverify_005fpeers2"></a><dl>
18423 <dt><a name="index-gnutls_005fcertificate_005fverify_005fpeers2"></a>Function: <em>int</em> <strong>gnutls_certificate_verify_peers2</strong> <em>(gnutls_session_t <var>session</var>, unsigned int * <var>status</var>)</em></dt>
18424 <dd><p><var>session</var>: is a gnutls session
18425 </p>
18426 <p><var>status</var>: is the output of the verification
18427 </p>
18428 <p>This function will verify the peer&rsquo;s certificate and store
18429 the status in the  <code>status</code> variable as a bitwise or&rsquo;d gnutls_certificate_status_t
18430 values or zero if the certificate is trusted. Note that value in  <code>status</code> is set only when the return value of this function is success (i.e, failure
18431 to trust a certificate does not imply a negative return value).
18432 The default verification flags used by this function can be overridden
18433 using <code>gnutls_certificate_set_verify_flags()</code> .
18434 </p>
18435 <p>This function will take into account the OCSP Certificate Status TLS extension,
18436 as well as the following X.509 certificate extensions: Name Constraints,
18437 Key Usage, and Basic Constraints (pathlen).
18438 </p>
18439 <p>To avoid denial of service attacks some
18440 default upper limits regarding the certificate key size and chain
18441 size are set. To override them use <code>gnutls_certificate_set_verify_limits()</code> .
18442 </p>
18443 <p>Note that you must also check the peer&rsquo;s name in order to check if
18444 the verified certificate belongs to the actual peer, see <code>gnutls_x509_crt_check_hostname()</code> ,
18445 or use <code>gnutls_certificate_verify_peers3()</code> .
18446 </p>
18447 <p><strong>Returns:</strong> a negative error code on error and <code>GNUTLS_E_SUCCESS</code>  (0)
18448 when the peer&rsquo;s certificate was successfully parsed, irrespective of whether
18449 it was verified.
18450 </p></dd></dl>
18451
18452 <a name="gnutls_005fcertificate_005fverify_005fpeers3-1"></a>
18453 <h4 class="subheading">gnutls_certificate_verify_peers3</h4>
18454 <a name="gnutls_005fcertificate_005fverify_005fpeers3"></a><dl>
18455 <dt><a name="index-gnutls_005fcertificate_005fverify_005fpeers3-1"></a>Function: <em>int</em> <strong>gnutls_certificate_verify_peers3</strong> <em>(gnutls_session_t <var>session</var>, const char * <var>hostname</var>, unsigned int * <var>status</var>)</em></dt>
18456 <dd><p><var>session</var>: is a gnutls session
18457 </p>
18458 <p><var>hostname</var>: is the expected name of the peer; may be <code>NULL</code>
18459 </p>
18460 <p><var>status</var>: is the output of the verification
18461 </p>
18462 <p>This function will verify the peer&rsquo;s certificate and store the
18463 status in the  <code>status</code> variable as a bitwise or&rsquo;d gnutls_certificate_status_t
18464 values or zero if the certificate is trusted. Note that value in  <code>status</code> is set only when the return value of this function is success (i.e, failure
18465 to trust a certificate does not imply a negative return value).
18466 The default verification flags used by this function can be overridden
18467 using <code>gnutls_certificate_set_verify_flags()</code> . See the documentation
18468 of <code>gnutls_certificate_verify_peers2()</code>  for details in the verification process.
18469 </p>
18470 <p>If the  <code>hostname</code> provided is non-NULL then this function will compare
18471 the hostname in the certificate against the given. The comparison will
18472 be accurate for ascii names; non-ascii names are compared byte-by-byte.
18473 If names do not match the <code>GNUTLS_CERT_UNEXPECTED_OWNER</code>  status flag will be set.
18474 </p>
18475 <p>In order to verify the purpose of the end-certificate (by checking the extended
18476 key usage), use <code>gnutls_certificate_verify_peers()</code> .
18477 </p>
18478 <p><strong>Returns:</strong> a negative error code on error and <code>GNUTLS_E_SUCCESS</code>  (0)
18479 when the peer&rsquo;s certificate was successfully parsed, irrespective of whether
18480 it was verified.
18481 </p>
18482 <p><strong>Since:</strong> 3.1.4
18483 </p></dd></dl>
18484
18485 <a name="gnutls_005fcheck_005fversion-1"></a>
18486 <h4 class="subheading">gnutls_check_version</h4>
18487 <a name="gnutls_005fcheck_005fversion"></a><dl>
18488 <dt><a name="index-gnutls_005fcheck_005fversion"></a>Function: <em>const char *</em> <strong>gnutls_check_version</strong> <em>(const char * <var>req_version</var>)</em></dt>
18489 <dd><p><var>req_version</var>: version string to compare with, or <code>NULL</code> .
18490 </p>
18491 <p>Check GnuTLS Library version.
18492 </p>
18493 <p>See <code>GNUTLS_VERSION</code>  for a suitable  <code>req_version</code> string.
18494 </p>
18495 <p><strong>Returns:</strong> Check that the version of the library is at
18496 minimum the one given as a string in  <code>req_version</code> and return the
18497 actual version string of the library; return <code>NULL</code>  if the
18498 condition is not met.  If <code>NULL</code>  is passed to this function no
18499 check is done and only the version string is returned.
18500 </p></dd></dl>
18501
18502 <a name="gnutls_005fcipher_005fget-1"></a>
18503 <h4 class="subheading">gnutls_cipher_get</h4>
18504 <a name="gnutls_005fcipher_005fget"></a><dl>
18505 <dt><a name="index-gnutls_005fcipher_005fget"></a>Function: <em>gnutls_cipher_algorithm_t</em> <strong>gnutls_cipher_get</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
18506 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18507 </p>
18508 <p>Get currently used cipher.
18509 </p>
18510 <p><strong>Returns:</strong> the currently used cipher, a <code>gnutls_cipher_algorithm_t</code>
18511 type.
18512 </p></dd></dl>
18513
18514 <a name="gnutls_005fcipher_005fget_005fid-1"></a>
18515 <h4 class="subheading">gnutls_cipher_get_id</h4>
18516 <a name="gnutls_005fcipher_005fget_005fid"></a><dl>
18517 <dt><a name="index-gnutls_005fcipher_005fget_005fid"></a>Function: <em>gnutls_cipher_algorithm_t</em> <strong>gnutls_cipher_get_id</strong> <em>(const char * <var>name</var>)</em></dt>
18518 <dd><p><var>name</var>: is a cipher algorithm name
18519 </p>
18520 <p>The names are compared in a case insensitive way.
18521 </p>
18522 <p><strong>Returns:</strong> return a <code>gnutls_cipher_algorithm_t</code>  value corresponding to
18523 the specified cipher, or <code>GNUTLS_CIPHER_UNKNOWN</code>  on error.
18524 </p></dd></dl>
18525
18526 <a name="gnutls_005fcipher_005fget_005fkey_005fsize-1"></a>
18527 <h4 class="subheading">gnutls_cipher_get_key_size</h4>
18528 <a name="gnutls_005fcipher_005fget_005fkey_005fsize"></a><dl>
18529 <dt><a name="index-gnutls_005fcipher_005fget_005fkey_005fsize"></a>Function: <em>size_t</em> <strong>gnutls_cipher_get_key_size</strong> <em>(gnutls_cipher_algorithm_t <var>algorithm</var>)</em></dt>
18530 <dd><p><var>algorithm</var>: is an encryption algorithm
18531 </p>
18532 <p>Get key size for cipher.
18533 </p>
18534 <p><strong>Returns:</strong> length (in bytes) of the given cipher&rsquo;s key size, or 0 if
18535 the given cipher is invalid.
18536 </p></dd></dl>
18537
18538 <a name="gnutls_005fcipher_005fget_005fname-1"></a>
18539 <h4 class="subheading">gnutls_cipher_get_name</h4>
18540 <a name="gnutls_005fcipher_005fget_005fname"></a><dl>
18541 <dt><a name="index-gnutls_005fcipher_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_cipher_get_name</strong> <em>(gnutls_cipher_algorithm_t <var>algorithm</var>)</em></dt>
18542 <dd><p><var>algorithm</var>: is an encryption algorithm
18543 </p>
18544 <p>Convert a <code>gnutls_cipher_algorithm_t</code>  type to a string.
18545 </p>
18546 <p><strong>Returns:</strong> a pointer to a string that contains the name of the
18547 specified cipher, or <code>NULL</code> .
18548 </p></dd></dl>
18549
18550 <a name="gnutls_005fcipher_005flist-1"></a>
18551 <h4 class="subheading">gnutls_cipher_list</h4>
18552 <a name="gnutls_005fcipher_005flist"></a><dl>
18553 <dt><a name="index-gnutls_005fcipher_005flist"></a>Function: <em>const gnutls_cipher_algorithm_t *</em> <strong>gnutls_cipher_list</strong> <em>( <var>void</var>)</em></dt>
18554 <dd>
18555 <p>Get a list of supported cipher algorithms.  Note that not
18556 necessarily all ciphers are supported as TLS cipher suites.  For
18557 example, DES is not supported as a cipher suite, but is supported
18558 for other purposes (e.g., PKCS<code>8</code>  or similar).
18559 </p>
18560 <p>This function is not thread safe.
18561 </p>
18562 <p><strong>Returns:</strong> a (0)-terminated list of <code>gnutls_cipher_algorithm_t</code>
18563 integers indicating the available ciphers.
18564 </p></dd></dl>
18565
18566 <a name="gnutls_005fcipher_005fsuite_005fget_005fname-1"></a>
18567 <h4 class="subheading">gnutls_cipher_suite_get_name</h4>
18568 <a name="gnutls_005fcipher_005fsuite_005fget_005fname"></a><dl>
18569 <dt><a name="index-gnutls_005fcipher_005fsuite_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_cipher_suite_get_name</strong> <em>(gnutls_kx_algorithm_t       <var>kx_algorithm</var>, gnutls_cipher_algorithm_t       <var>cipher_algorithm</var>, gnutls_mac_algorithm_t       <var>mac_algorithm</var>)</em></dt>
18570 <dd><p><var>kx_algorithm</var>: is a Key exchange algorithm
18571 </p>
18572 <p><var>cipher_algorithm</var>: is a cipher algorithm
18573 </p>
18574 <p><var>mac_algorithm</var>: is a MAC algorithm
18575 </p>
18576 <p>Note that the full cipher suite name must be prepended by TLS or
18577 SSL depending of the protocol in use.
18578 </p>
18579 <p><strong>Returns:</strong> a string that contains the name of a TLS cipher suite,
18580 specified by the given algorithms, or <code>NULL</code> .
18581 </p></dd></dl>
18582
18583 <a name="gnutls_005fcipher_005fsuite_005finfo-1"></a>
18584 <h4 class="subheading">gnutls_cipher_suite_info</h4>
18585 <a name="gnutls_005fcipher_005fsuite_005finfo"></a><dl>
18586 <dt><a name="index-gnutls_005fcipher_005fsuite_005finfo"></a>Function: <em>const char *</em> <strong>gnutls_cipher_suite_info</strong> <em>(size_t <var>idx</var>, unsigned char * <var>cs_id</var>, gnutls_kx_algorithm_t * <var>kx</var>, gnutls_cipher_algorithm_t * <var>cipher</var>, gnutls_mac_algorithm_t * <var>mac</var>, gnutls_protocol_t * <var>min_version</var>)</em></dt>
18587 <dd><p><var>idx</var>: index of cipher suite to get information about, starts on 0.
18588 </p>
18589 <p><var>cs_id</var>: output buffer with room for 2 bytes, indicating cipher suite value
18590 </p>
18591 <p><var>kx</var>: output variable indicating key exchange algorithm, or <code>NULL</code> .
18592 </p>
18593 <p><var>cipher</var>: output variable indicating cipher, or <code>NULL</code> .
18594 </p>
18595 <p><var>mac</var>: output variable indicating MAC algorithm, or <code>NULL</code> .
18596 </p>
18597 <p><var>min_version</var>: output variable indicating TLS protocol version, or <code>NULL</code> .
18598 </p>
18599 <p>Get information about supported cipher suites.  Use the function
18600 iteratively to get information about all supported cipher suites.
18601 Call with idx=0 to get information about first cipher suite, then
18602 idx=1 and so on until the function returns NULL.
18603 </p>
18604 <p><strong>Returns:</strong> the name of  <code>idx</code> cipher suite, and set the information
18605 about the cipher suite in the output variables.  If  <code>idx</code> is out of
18606 bounds, <code>NULL</code>  is returned.
18607 </p></dd></dl>
18608
18609 <a name="gnutls_005fcompression_005fget-1"></a>
18610 <h4 class="subheading">gnutls_compression_get</h4>
18611 <a name="gnutls_005fcompression_005fget"></a><dl>
18612 <dt><a name="index-gnutls_005fcompression_005fget"></a>Function: <em>gnutls_compression_method_t</em> <strong>gnutls_compression_get</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
18613 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18614 </p>
18615 <p>Get currently used compression algorithm.
18616 </p>
18617 <p><strong>Returns:</strong> the currently used compression method, a
18618 <code>gnutls_compression_method_t</code>  value.
18619 </p></dd></dl>
18620
18621 <a name="gnutls_005fcompression_005fget_005fid-1"></a>
18622 <h4 class="subheading">gnutls_compression_get_id</h4>
18623 <a name="gnutls_005fcompression_005fget_005fid"></a><dl>
18624 <dt><a name="index-gnutls_005fcompression_005fget_005fid"></a>Function: <em>gnutls_compression_method_t</em> <strong>gnutls_compression_get_id</strong> <em>(const char * <var>name</var>)</em></dt>
18625 <dd><p><var>name</var>: is a compression method name
18626 </p>
18627 <p>The names are compared in a case insensitive way.
18628 </p>
18629 <p><strong>Returns:</strong> an id of the specified in a string compression method, or
18630 <code>GNUTLS_COMP_UNKNOWN</code>  on error.
18631 </p></dd></dl>
18632
18633 <a name="gnutls_005fcompression_005fget_005fname-1"></a>
18634 <h4 class="subheading">gnutls_compression_get_name</h4>
18635 <a name="gnutls_005fcompression_005fget_005fname"></a><dl>
18636 <dt><a name="index-gnutls_005fcompression_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_compression_get_name</strong> <em>(gnutls_compression_method_t      <var>algorithm</var>)</em></dt>
18637 <dd><p><var>algorithm</var>: is a Compression algorithm
18638 </p>
18639 <p>Convert a <code>gnutls_compression_method_t</code>  value to a string.
18640 </p>
18641 <p><strong>Returns:</strong> a pointer to a string that contains the name of the
18642 specified compression algorithm, or <code>NULL</code> .
18643 </p></dd></dl>
18644
18645 <a name="gnutls_005fcompression_005flist-1"></a>
18646 <h4 class="subheading">gnutls_compression_list</h4>
18647 <a name="gnutls_005fcompression_005flist"></a><dl>
18648 <dt><a name="index-gnutls_005fcompression_005flist"></a>Function: <em>const gnutls_compression_method_t *</em> <strong>gnutls_compression_list</strong> <em>( <var>void</var>)</em></dt>
18649 <dd>
18650 <p>Get a list of compression methods.
18651 </p>
18652 <p><strong>Returns:</strong> a zero-terminated list of <code>gnutls_compression_method_t</code>
18653 integers indicating the available compression methods.
18654 </p></dd></dl>
18655
18656 <a name="gnutls_005fcredentials_005fclear-1"></a>
18657 <h4 class="subheading">gnutls_credentials_clear</h4>
18658 <a name="gnutls_005fcredentials_005fclear"></a><dl>
18659 <dt><a name="index-gnutls_005fcredentials_005fclear"></a>Function: <em>void</em> <strong>gnutls_credentials_clear</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
18660 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18661 </p>
18662 <p>Clears all the credentials previously set in this session.
18663 </p></dd></dl>
18664
18665 <a name="gnutls_005fcredentials_005fget-1"></a>
18666 <h4 class="subheading">gnutls_credentials_get</h4>
18667 <a name="gnutls_005fcredentials_005fget"></a><dl>
18668 <dt><a name="index-gnutls_005fcredentials_005fget"></a>Function: <em>int</em> <strong>gnutls_credentials_get</strong> <em>(gnutls_session_t <var>session</var>, gnutls_credentials_type_t <var>type</var>, void ** <var>cred</var>)</em></dt>
18669 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18670 </p>
18671 <p><var>type</var>: is the type of the credentials to return
18672 </p>
18673 <p><var>cred</var>: will contain the pointer to the credentials structure.
18674 </p>
18675 <p>Returns the previously provided credentials structures.
18676 </p>
18677 <p>For <code>GNUTLS_CRD_ANON</code> ,  <code>cred</code> will be
18678 <code>gnutls_anon_client_credentials_t</code>  in case of a client.  In case of
18679 a server it should be <code>gnutls_anon_server_credentials_t</code> .
18680 </p>
18681 <p>For <code>GNUTLS_CRD_SRP</code> ,  <code>cred</code> will be <code>gnutls_srp_client_credentials_t</code>
18682 in case of a client, and <code>gnutls_srp_server_credentials_t</code> , in case
18683 of a server.
18684 </p>
18685 <p>For <code>GNUTLS_CRD_CERTIFICATE</code> ,  <code>cred</code> will be
18686 <code>gnutls_certificate_credentials_t</code> .
18687 </p>
18688 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
18689 otherwise a negative error code is returned.
18690 </p></dd></dl>
18691
18692 <a name="gnutls_005fcredentials_005fset-1"></a>
18693 <h4 class="subheading">gnutls_credentials_set</h4>
18694 <a name="gnutls_005fcredentials_005fset"></a><dl>
18695 <dt><a name="index-gnutls_005fcredentials_005fset-1"></a>Function: <em>int</em> <strong>gnutls_credentials_set</strong> <em>(gnutls_session_t <var>session</var>, gnutls_credentials_type_t <var>type</var>, void * <var>cred</var>)</em></dt>
18696 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18697 </p>
18698 <p><var>type</var>: is the type of the credentials
18699 </p>
18700 <p><var>cred</var>: is a pointer to a structure.
18701 </p>
18702 <p>Sets the needed credentials for the specified type.  Eg username,
18703 password - or public and private keys etc.  The  <code>cred</code> parameter is
18704 a structure that depends on the specified type and on the current
18705 session (client or server).
18706 </p>
18707 <p>In order to minimize memory usage, and share credentials between
18708 several threads gnutls keeps a pointer to cred, and not the whole
18709 cred structure.  Thus you will have to keep the structure allocated
18710 until you call <code>gnutls_deinit()</code> .
18711 </p>
18712 <p>For <code>GNUTLS_CRD_ANON</code> ,  <code>cred</code> should be
18713 <code>gnutls_anon_client_credentials_t</code>  in case of a client.  In case of
18714 a server it should be <code>gnutls_anon_server_credentials_t</code> .
18715 </p>
18716 <p>For <code>GNUTLS_CRD_SRP</code> ,  <code>cred</code> should be <code>gnutls_srp_client_credentials_t</code>
18717 in case of a client, and <code>gnutls_srp_server_credentials_t</code> , in case
18718 of a server.
18719 </p>
18720 <p>For <code>GNUTLS_CRD_CERTIFICATE</code> ,  <code>cred</code> should be
18721 <code>gnutls_certificate_credentials_t</code> .
18722 </p>
18723 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
18724 otherwise a negative error code is returned.
18725 </p></dd></dl>
18726
18727 <a name="gnutls_005fdb_005fcheck_005fentry-1"></a>
18728 <h4 class="subheading">gnutls_db_check_entry</h4>
18729 <a name="gnutls_005fdb_005fcheck_005fentry"></a><dl>
18730 <dt><a name="index-gnutls_005fdb_005fcheck_005fentry"></a>Function: <em>int</em> <strong>gnutls_db_check_entry</strong> <em>(gnutls_session_t <var>session</var>, gnutls_datum_t <var>session_entry</var>)</em></dt>
18731 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18732 </p>
18733 <p><var>session_entry</var>: is the session data (not key)
18734 </p>
18735 <p>This function has no effect.
18736 </p>
18737 <p><strong>Returns:</strong> Returns <code>GNUTLS_E_EXPIRED</code> , if the database entry has
18738 expired or 0 otherwise.
18739 </p></dd></dl>
18740
18741 <a name="gnutls_005fdb_005fcheck_005fentry_005ftime-1"></a>
18742 <h4 class="subheading">gnutls_db_check_entry_time</h4>
18743 <a name="gnutls_005fdb_005fcheck_005fentry_005ftime"></a><dl>
18744 <dt><a name="index-gnutls_005fdb_005fcheck_005fentry_005ftime"></a>Function: <em>time_t</em> <strong>gnutls_db_check_entry_time</strong> <em>(gnutls_datum_t * <var>entry</var>)</em></dt>
18745 <dd><p><var>entry</var>: is a pointer to a <code>gnutls_datum_t</code>  structure.
18746 </p>
18747 <p>This function returns the time that this entry was active.
18748 It can be used for database entry expiration.
18749 </p>
18750 <p><strong>Returns:</strong> The time this entry was created, or zero on error.
18751 </p></dd></dl>
18752
18753 <a name="gnutls_005fdb_005fget_005fdefault_005fcache_005fexpiration-1"></a>
18754 <h4 class="subheading">gnutls_db_get_default_cache_expiration</h4>
18755 <a name="gnutls_005fdb_005fget_005fdefault_005fcache_005fexpiration"></a><dl>
18756 <dt><a name="index-gnutls_005fdb_005fget_005fdefault_005fcache_005fexpiration"></a>Function: <em>unsigned</em> <strong>gnutls_db_get_default_cache_expiration</strong> <em>( <var>void</var>)</em></dt>
18757 <dd>
18758 <p>Returns the expiration time (in seconds) of stored sessions for resumption.
18759 </p></dd></dl>
18760
18761 <a name="gnutls_005fdb_005fget_005fptr-1"></a>
18762 <h4 class="subheading">gnutls_db_get_ptr</h4>
18763 <a name="gnutls_005fdb_005fget_005fptr"></a><dl>
18764 <dt><a name="index-gnutls_005fdb_005fget_005fptr"></a>Function: <em>void *</em> <strong>gnutls_db_get_ptr</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
18765 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18766 </p>
18767 <p>Get db function pointer.
18768 </p>
18769 <p><strong>Returns:</strong> the pointer that will be sent to db store, retrieve and
18770 delete functions, as the first argument.
18771 </p></dd></dl>
18772
18773 <a name="gnutls_005fdb_005fremove_005fsession-1"></a>
18774 <h4 class="subheading">gnutls_db_remove_session</h4>
18775 <a name="gnutls_005fdb_005fremove_005fsession"></a><dl>
18776 <dt><a name="index-gnutls_005fdb_005fremove_005fsession"></a>Function: <em>void</em> <strong>gnutls_db_remove_session</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
18777 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18778 </p>
18779 <p>This function will remove the current session data from the
18780 session database.  This will prevent future handshakes reusing
18781 these session data.  This function should be called if a session
18782 was terminated abnormally, and before <code>gnutls_deinit()</code>  is called.
18783 </p>
18784 <p>Normally <code>gnutls_deinit()</code>  will remove abnormally terminated
18785 sessions.
18786 </p></dd></dl>
18787
18788 <a name="gnutls_005fdb_005fset_005fcache_005fexpiration-1"></a>
18789 <h4 class="subheading">gnutls_db_set_cache_expiration</h4>
18790 <a name="gnutls_005fdb_005fset_005fcache_005fexpiration"></a><dl>
18791 <dt><a name="index-gnutls_005fdb_005fset_005fcache_005fexpiration"></a>Function: <em>void</em> <strong>gnutls_db_set_cache_expiration</strong> <em>(gnutls_session_t <var>session</var>, int <var>seconds</var>)</em></dt>
18792 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18793 </p>
18794 <p><var>seconds</var>: is the number of seconds.
18795 </p>
18796 <p>Set the expiration time for resumed sessions. The default is 3600
18797 (one hour) at the time of this writing.
18798 </p></dd></dl>
18799
18800 <a name="gnutls_005fdb_005fset_005fptr-1"></a>
18801 <h4 class="subheading">gnutls_db_set_ptr</h4>
18802 <a name="gnutls_005fdb_005fset_005fptr"></a><dl>
18803 <dt><a name="index-gnutls_005fdb_005fset_005fptr"></a>Function: <em>void</em> <strong>gnutls_db_set_ptr</strong> <em>(gnutls_session_t <var>session</var>, void * <var>ptr</var>)</em></dt>
18804 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18805 </p>
18806 <p><var>ptr</var>: is the pointer
18807 </p>
18808 <p>Sets the pointer that will be provided to db store, retrieve and
18809 delete functions, as the first argument.
18810 </p></dd></dl>
18811
18812 <a name="gnutls_005fdb_005fset_005fremove_005ffunction-1"></a>
18813 <h4 class="subheading">gnutls_db_set_remove_function</h4>
18814 <a name="gnutls_005fdb_005fset_005fremove_005ffunction"></a><dl>
18815 <dt><a name="index-gnutls_005fdb_005fset_005fremove_005ffunction"></a>Function: <em>void</em> <strong>gnutls_db_set_remove_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_db_remove_func <var>rem_func</var>)</em></dt>
18816 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18817 </p>
18818 <p><var>rem_func</var>: is the function.
18819 </p>
18820 <p>Sets the function that will be used to remove data from the
18821 resumed sessions database. This function must return 0 on success.
18822 </p>
18823 <p>The first argument to  <code>rem_func</code> will be null unless
18824 <code>gnutls_db_set_ptr()</code>  has been called.
18825 </p></dd></dl>
18826
18827 <a name="gnutls_005fdb_005fset_005fretrieve_005ffunction-1"></a>
18828 <h4 class="subheading">gnutls_db_set_retrieve_function</h4>
18829 <a name="gnutls_005fdb_005fset_005fretrieve_005ffunction"></a><dl>
18830 <dt><a name="index-gnutls_005fdb_005fset_005fretrieve_005ffunction"></a>Function: <em>void</em> <strong>gnutls_db_set_retrieve_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_db_retr_func <var>retr_func</var>)</em></dt>
18831 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18832 </p>
18833 <p><var>retr_func</var>: is the function.
18834 </p>
18835 <p>Sets the function that will be used to retrieve data from the
18836 resumed sessions database.  This function must return a
18837 gnutls_datum_t containing the data on success, or a gnutls_datum_t
18838 containing null and 0 on failure.
18839 </p>
18840 <p>The datum&rsquo;s data must be allocated using the function
18841 <code>gnutls_malloc()</code> .
18842 </p>
18843 <p>The first argument to  <code>retr_func</code> will be null unless
18844 <code>gnutls_db_set_ptr()</code>  has been called.
18845 </p></dd></dl>
18846
18847 <a name="gnutls_005fdb_005fset_005fstore_005ffunction-1"></a>
18848 <h4 class="subheading">gnutls_db_set_store_function</h4>
18849 <a name="gnutls_005fdb_005fset_005fstore_005ffunction"></a><dl>
18850 <dt><a name="index-gnutls_005fdb_005fset_005fstore_005ffunction"></a>Function: <em>void</em> <strong>gnutls_db_set_store_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_db_store_func <var>store_func</var>)</em></dt>
18851 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18852 </p>
18853 <p><var>store_func</var>: is the function
18854 </p>
18855 <p>Sets the function that will be used to store data in the resumed
18856 sessions database. This function must return 0 on success.
18857 </p>
18858 <p>The first argument to  <code>store_func</code> will be null unless
18859 <code>gnutls_db_set_ptr()</code>  has been called.
18860 </p></dd></dl>
18861
18862 <a name="gnutls_005fdeinit-1"></a>
18863 <h4 class="subheading">gnutls_deinit</h4>
18864 <a name="gnutls_005fdeinit"></a><dl>
18865 <dt><a name="index-gnutls_005fdeinit-1"></a>Function: <em>void</em> <strong>gnutls_deinit</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
18866 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
18867 </p>
18868 <p>This function clears all buffers associated with the  <code>session</code> .
18869 This function will also remove session data from the session
18870 database if the session was terminated abnormally.
18871 </p></dd></dl>
18872
18873 <a name="gnutls_005fdh_005fget_005fgroup-1"></a>
18874 <h4 class="subheading">gnutls_dh_get_group</h4>
18875 <a name="gnutls_005fdh_005fget_005fgroup"></a><dl>
18876 <dt><a name="index-gnutls_005fdh_005fget_005fgroup"></a>Function: <em>int</em> <strong>gnutls_dh_get_group</strong> <em>(gnutls_session_t <var>session</var>, gnutls_datum_t * <var>raw_gen</var>, gnutls_datum_t * <var>raw_prime</var>)</em></dt>
18877 <dd><p><var>session</var>: is a gnutls session
18878 </p>
18879 <p><var>raw_gen</var>: will hold the generator.
18880 </p>
18881 <p><var>raw_prime</var>: will hold the prime.
18882 </p>
18883 <p>This function will return the group parameters used in the last
18884 Diffie-Hellman key exchange with the peer.  These are the prime and
18885 the generator used.  This function should be used for both
18886 anonymous and ephemeral Diffie-Hellman.  The output parameters must
18887 be freed with <code>gnutls_free()</code> .
18888 </p>
18889 <p>Note, that the prime and generator are exported as non-negative
18890 integers and may include a leading zero byte.
18891 </p>
18892 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
18893 an error code is returned.
18894 </p></dd></dl>
18895
18896 <a name="gnutls_005fdh_005fget_005fpeers_005fpublic_005fbits-1"></a>
18897 <h4 class="subheading">gnutls_dh_get_peers_public_bits</h4>
18898 <a name="gnutls_005fdh_005fget_005fpeers_005fpublic_005fbits"></a><dl>
18899 <dt><a name="index-gnutls_005fdh_005fget_005fpeers_005fpublic_005fbits"></a>Function: <em>int</em> <strong>gnutls_dh_get_peers_public_bits</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
18900 <dd><p><var>session</var>: is a gnutls session
18901 </p>
18902 <p>Get the Diffie-Hellman public key bit size.  Can be used for both
18903 anonymous and ephemeral Diffie-Hellman.
18904 </p>
18905 <p><strong>Returns:</strong> The public key bit size used in the last Diffie-Hellman
18906 key exchange with the peer, or a negative error code in case of error.
18907 </p></dd></dl>
18908
18909 <a name="gnutls_005fdh_005fget_005fprime_005fbits-1"></a>
18910 <h4 class="subheading">gnutls_dh_get_prime_bits</h4>
18911 <a name="gnutls_005fdh_005fget_005fprime_005fbits"></a><dl>
18912 <dt><a name="index-gnutls_005fdh_005fget_005fprime_005fbits"></a>Function: <em>int</em> <strong>gnutls_dh_get_prime_bits</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
18913 <dd><p><var>session</var>: is a gnutls session
18914 </p>
18915 <p>This function will return the bits of the prime used in the last
18916 Diffie-Hellman key exchange with the peer.  Should be used for both
18917 anonymous and ephemeral Diffie-Hellman.  Note that some ciphers,
18918 like RSA and DSA without DHE, do not use a Diffie-Hellman key
18919 exchange, and then this function will return 0.
18920 </p>
18921 <p><strong>Returns:</strong> The Diffie-Hellman bit strength is returned, or 0 if no
18922 Diffie-Hellman key exchange was done, or a negative error code on
18923 failure.
18924 </p></dd></dl>
18925
18926 <a name="gnutls_005fdh_005fget_005fpubkey-1"></a>
18927 <h4 class="subheading">gnutls_dh_get_pubkey</h4>
18928 <a name="gnutls_005fdh_005fget_005fpubkey"></a><dl>
18929 <dt><a name="index-gnutls_005fdh_005fget_005fpubkey"></a>Function: <em>int</em> <strong>gnutls_dh_get_pubkey</strong> <em>(gnutls_session_t <var>session</var>, gnutls_datum_t * <var>raw_key</var>)</em></dt>
18930 <dd><p><var>session</var>: is a gnutls session
18931 </p>
18932 <p><var>raw_key</var>: will hold the public key.
18933 </p>
18934 <p>This function will return the peer&rsquo;s public key used in the last
18935 Diffie-Hellman key exchange.  This function should be used for both
18936 anonymous and ephemeral Diffie-Hellman.  The output parameters must
18937 be freed with <code>gnutls_free()</code> .
18938 </p>
18939 <p>Note, that public key is exported as non-negative
18940 integer and may include a leading zero byte.
18941 </p>
18942 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
18943 an error code is returned.
18944 </p></dd></dl>
18945
18946 <a name="gnutls_005fdh_005fget_005fsecret_005fbits-1"></a>
18947 <h4 class="subheading">gnutls_dh_get_secret_bits</h4>
18948 <a name="gnutls_005fdh_005fget_005fsecret_005fbits"></a><dl>
18949 <dt><a name="index-gnutls_005fdh_005fget_005fsecret_005fbits"></a>Function: <em>int</em> <strong>gnutls_dh_get_secret_bits</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
18950 <dd><p><var>session</var>: is a gnutls session
18951 </p>
18952 <p>This function will return the bits used in the last Diffie-Hellman
18953 key exchange with the peer.  Should be used for both anonymous and
18954 ephemeral Diffie-Hellman.
18955 </p>
18956 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
18957 an error code is returned.
18958 </p></dd></dl>
18959
18960 <a name="gnutls_005fdh_005fparams_005fcpy-1"></a>
18961 <h4 class="subheading">gnutls_dh_params_cpy</h4>
18962 <a name="gnutls_005fdh_005fparams_005fcpy"></a><dl>
18963 <dt><a name="index-gnutls_005fdh_005fparams_005fcpy"></a>Function: <em>int</em> <strong>gnutls_dh_params_cpy</strong> <em>(gnutls_dh_params_t <var>dst</var>, gnutls_dh_params_t <var>src</var>)</em></dt>
18964 <dd><p><var>dst</var>: Is the destination structure, which should be initialized.
18965 </p>
18966 <p><var>src</var>: Is the source structure
18967 </p>
18968 <p>This function will copy the DH parameters structure from source
18969 to destination.
18970 </p>
18971 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
18972 otherwise a negative error code is returned.
18973 </p></dd></dl>
18974
18975 <a name="gnutls_005fdh_005fparams_005fdeinit-1"></a>
18976 <h4 class="subheading">gnutls_dh_params_deinit</h4>
18977 <a name="gnutls_005fdh_005fparams_005fdeinit"></a><dl>
18978 <dt><a name="index-gnutls_005fdh_005fparams_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_dh_params_deinit</strong> <em>(gnutls_dh_params_t <var>dh_params</var>)</em></dt>
18979 <dd><p><var>dh_params</var>: Is a structure that holds the prime numbers
18980 </p>
18981 <p>This function will deinitialize the DH parameters structure.
18982 </p></dd></dl>
18983
18984 <a name="gnutls_005fdh_005fparams_005fexport2_005fpkcs3-1"></a>
18985 <h4 class="subheading">gnutls_dh_params_export2_pkcs3</h4>
18986 <a name="gnutls_005fdh_005fparams_005fexport2_005fpkcs3"></a><dl>
18987 <dt><a name="index-gnutls_005fdh_005fparams_005fexport2_005fpkcs3"></a>Function: <em>int</em> <strong>gnutls_dh_params_export2_pkcs3</strong> <em>(gnutls_dh_params_t <var>params</var>, gnutls_x509_crt_fmt_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
18988 <dd><p><var>params</var>: Holds the DH parameters
18989 </p>
18990 <p><var>format</var>: the format of output params. One of PEM or DER.
18991 </p>
18992 <p><var>out</var>: will contain a PKCS3 DHParams structure PEM or DER encoded
18993 </p>
18994 <p>This function will export the given dh parameters to a PKCS3
18995 DHParams structure. This is the format generated by &quot;openssl dhparam&quot; tool.
18996 The data in  <code>out</code> will be allocated using <code>gnutls_malloc()</code> .
18997 </p>
18998 <p>If the structure is PEM encoded, it will have a header
18999 of &quot;BEGIN DH PARAMETERS&quot;.
19000 </p>
19001 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
19002 otherwise a negative error code is returned.
19003 </p>
19004 <p><strong>Since:</strong> 3.1.3
19005 </p></dd></dl>
19006
19007 <a name="gnutls_005fdh_005fparams_005fexport_005fpkcs3-1"></a>
19008 <h4 class="subheading">gnutls_dh_params_export_pkcs3</h4>
19009 <a name="gnutls_005fdh_005fparams_005fexport_005fpkcs3"></a><dl>
19010 <dt><a name="index-gnutls_005fdh_005fparams_005fexport_005fpkcs3"></a>Function: <em>int</em> <strong>gnutls_dh_params_export_pkcs3</strong> <em>(gnutls_dh_params_t <var>params</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned char * <var>params_data</var>, size_t * <var>params_data_size</var>)</em></dt>
19011 <dd><p><var>params</var>: Holds the DH parameters
19012 </p>
19013 <p><var>format</var>: the format of output params. One of PEM or DER.
19014 </p>
19015 <p><var>params_data</var>: will contain a PKCS3 DHParams structure PEM or DER encoded
19016 </p>
19017 <p><var>params_data_size</var>: holds the size of params_data (and will be replaced by the actual size of parameters)
19018 </p>
19019 <p>This function will export the given dh parameters to a PKCS3
19020 DHParams structure. This is the format generated by &quot;openssl dhparam&quot; tool.
19021 If the buffer provided is not long enough to hold the output, then
19022 GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
19023 </p>
19024 <p>If the structure is PEM encoded, it will have a header
19025 of &quot;BEGIN DH PARAMETERS&quot;.
19026 </p>
19027 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
19028 otherwise a negative error code is returned.
19029 </p></dd></dl>
19030
19031 <a name="gnutls_005fdh_005fparams_005fexport_005fraw-1"></a>
19032 <h4 class="subheading">gnutls_dh_params_export_raw</h4>
19033 <a name="gnutls_005fdh_005fparams_005fexport_005fraw"></a><dl>
19034 <dt><a name="index-gnutls_005fdh_005fparams_005fexport_005fraw"></a>Function: <em>int</em> <strong>gnutls_dh_params_export_raw</strong> <em>(gnutls_dh_params_t <var>params</var>, gnutls_datum_t * <var>prime</var>, gnutls_datum_t * <var>generator</var>, unsigned int * <var>bits</var>)</em></dt>
19035 <dd><p><var>params</var>: Holds the DH parameters
19036 </p>
19037 <p><var>prime</var>: will hold the new prime
19038 </p>
19039 <p><var>generator</var>: will hold the new generator
19040 </p>
19041 <p><var>bits</var>: if non null will hold the secret key&rsquo;s number of bits
19042 </p>
19043 <p>This function will export the pair of prime and generator for use
19044 in the Diffie-Hellman key exchange.  The new parameters will be
19045 allocated using <code>gnutls_malloc()</code>  and will be stored in the
19046 appropriate datum.
19047 </p>
19048 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
19049 otherwise a negative error code is returned.
19050 </p></dd></dl>
19051
19052 <a name="gnutls_005fdh_005fparams_005fgenerate2-1"></a>
19053 <h4 class="subheading">gnutls_dh_params_generate2</h4>
19054 <a name="gnutls_005fdh_005fparams_005fgenerate2"></a><dl>
19055 <dt><a name="index-gnutls_005fdh_005fparams_005fgenerate2"></a>Function: <em>int</em> <strong>gnutls_dh_params_generate2</strong> <em>(gnutls_dh_params_t <var>dparams</var>, unsigned int <var>bits</var>)</em></dt>
19056 <dd><p><var>dparams</var>: Is the structure that the DH parameters will be stored
19057 </p>
19058 <p><var>bits</var>: is the prime&rsquo;s number of bits
19059 </p>
19060 <p>This function will generate a new pair of prime and generator for use in
19061 the Diffie-Hellman key exchange. The new parameters will be allocated using
19062 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
19063 This function is normally slow.
19064 </p>
19065 <p>Do not set the number of bits directly, use <code>gnutls_sec_param_to_pk_bits()</code>  to
19066 get bits for <code>GNUTLS_PK_DSA</code> .
19067 Also note that the DH parameters are only useful to servers.
19068 Since clients use the parameters sent by the server, it&rsquo;s of
19069 no use to call this in client side.
19070 </p>
19071 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
19072 otherwise a negative error code is returned.
19073 </p></dd></dl>
19074
19075 <a name="gnutls_005fdh_005fparams_005fimport_005fpkcs3-1"></a>
19076 <h4 class="subheading">gnutls_dh_params_import_pkcs3</h4>
19077 <a name="gnutls_005fdh_005fparams_005fimport_005fpkcs3"></a><dl>
19078 <dt><a name="index-gnutls_005fdh_005fparams_005fimport_005fpkcs3"></a>Function: <em>int</em> <strong>gnutls_dh_params_import_pkcs3</strong> <em>(gnutls_dh_params_t <var>params</var>, const gnutls_datum_t * <var>pkcs3_params</var>, gnutls_x509_crt_fmt_t <var>format</var>)</em></dt>
19079 <dd><p><var>params</var>: A structure where the parameters will be copied to
19080 </p>
19081 <p><var>pkcs3_params</var>: should contain a PKCS3 DHParams structure PEM or DER encoded
19082 </p>
19083 <p><var>format</var>: the format of params. PEM or DER.
19084 </p>
19085 <p>This function will extract the DHParams found in a PKCS3 formatted
19086 structure. This is the format generated by &quot;openssl dhparam&quot; tool.
19087 </p>
19088 <p>If the structure is PEM encoded, it should have a header
19089 of &quot;BEGIN DH PARAMETERS&quot;.
19090 </p>
19091 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
19092 otherwise a negative error code is returned.
19093 </p></dd></dl>
19094
19095 <a name="gnutls_005fdh_005fparams_005fimport_005fraw-1"></a>
19096 <h4 class="subheading">gnutls_dh_params_import_raw</h4>
19097 <a name="gnutls_005fdh_005fparams_005fimport_005fraw"></a><dl>
19098 <dt><a name="index-gnutls_005fdh_005fparams_005fimport_005fraw"></a>Function: <em>int</em> <strong>gnutls_dh_params_import_raw</strong> <em>(gnutls_dh_params_t <var>dh_params</var>, const gnutls_datum_t * <var>prime</var>, const gnutls_datum_t * <var>generator</var>)</em></dt>
19099 <dd><p><var>dh_params</var>: Is a structure that will hold the prime numbers
19100 </p>
19101 <p><var>prime</var>: holds the new prime
19102 </p>
19103 <p><var>generator</var>: holds the new generator
19104 </p>
19105 <p>This function will replace the pair of prime and generator for use
19106 in the Diffie-Hellman key exchange.  The new parameters should be
19107 stored in the appropriate gnutls_datum.
19108 </p>
19109 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
19110 otherwise a negative error code is returned.
19111 </p></dd></dl>
19112
19113 <a name="gnutls_005fdh_005fparams_005finit-1"></a>
19114 <h4 class="subheading">gnutls_dh_params_init</h4>
19115 <a name="gnutls_005fdh_005fparams_005finit"></a><dl>
19116 <dt><a name="index-gnutls_005fdh_005fparams_005finit"></a>Function: <em>int</em> <strong>gnutls_dh_params_init</strong> <em>(gnutls_dh_params_t * <var>dh_params</var>)</em></dt>
19117 <dd><p><var>dh_params</var>: Is a structure that will hold the prime numbers
19118 </p>
19119 <p>This function will initialize the DH parameters structure.
19120 </p>
19121 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
19122 otherwise a negative error code is returned.
19123 </p></dd></dl>
19124
19125 <a name="gnutls_005fdh_005fset_005fprime_005fbits-1"></a>
19126 <h4 class="subheading">gnutls_dh_set_prime_bits</h4>
19127 <a name="gnutls_005fdh_005fset_005fprime_005fbits"></a><dl>
19128 <dt><a name="index-gnutls_005fdh_005fset_005fprime_005fbits"></a>Function: <em>void</em> <strong>gnutls_dh_set_prime_bits</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>bits</var>)</em></dt>
19129 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19130 </p>
19131 <p><var>bits</var>: is the number of bits
19132 </p>
19133 <p>This function sets the number of bits, for use in a Diffie-Hellman
19134 key exchange.  This is used both in DH ephemeral and DH anonymous
19135 cipher suites.  This will set the minimum size of the prime that
19136 will be used for the handshake.
19137 </p>
19138 <p>In the client side it sets the minimum accepted number of bits.  If
19139 a server sends a prime with less bits than that
19140 <code>GNUTLS_E_DH_PRIME_UNACCEPTABLE</code>  will be returned by the handshake.
19141 </p>
19142 <p>Note that this function will warn via the audit log for value that
19143 are believed to be weak.
19144 </p>
19145 <p>The function has no effect in server side.
19146 </p>
19147 <p>Note that since 3.1.7 this function is deprecated. The minimum
19148 number of bits is set by the priority string level.
19149 Also this function must be called after <code>gnutls_priority_set_direct()</code>
19150 or the set value may be overridden by the selected priority options.
19151 </p></dd></dl>
19152
19153 <a name="gnutls_005fdigest_005fget_005fid-1"></a>
19154 <h4 class="subheading">gnutls_digest_get_id</h4>
19155 <a name="gnutls_005fdigest_005fget_005fid"></a><dl>
19156 <dt><a name="index-gnutls_005fdigest_005fget_005fid"></a>Function: <em>gnutls_digest_algorithm_t</em> <strong>gnutls_digest_get_id</strong> <em>(const char * <var>name</var>)</em></dt>
19157 <dd><p><var>name</var>: is a digest algorithm name
19158 </p>
19159 <p>Convert a string to a <code>gnutls_digest_algorithm_t</code>  value.  The names are
19160 compared in a case insensitive way.
19161 </p>
19162 <p><strong>Returns:</strong> a <code>gnutls_digest_algorithm_t</code>  id of the specified MAC
19163 algorithm string, or <code>GNUTLS_DIG_UNKNOWN</code>  on failures.
19164 </p></dd></dl>
19165
19166 <a name="gnutls_005fdigest_005fget_005fname-1"></a>
19167 <h4 class="subheading">gnutls_digest_get_name</h4>
19168 <a name="gnutls_005fdigest_005fget_005fname"></a><dl>
19169 <dt><a name="index-gnutls_005fdigest_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_digest_get_name</strong> <em>(gnutls_digest_algorithm_t <var>algorithm</var>)</em></dt>
19170 <dd><p><var>algorithm</var>: is a digest algorithm
19171 </p>
19172 <p>Convert a <code>gnutls_digest_algorithm_t</code>  value to a string.
19173 </p>
19174 <p><strong>Returns:</strong> a string that contains the name of the specified digest
19175 algorithm, or <code>NULL</code> .
19176 </p></dd></dl>
19177
19178 <a name="gnutls_005fdigest_005flist-1"></a>
19179 <h4 class="subheading">gnutls_digest_list</h4>
19180 <a name="gnutls_005fdigest_005flist"></a><dl>
19181 <dt><a name="index-gnutls_005fdigest_005flist"></a>Function: <em>const gnutls_digest_algorithm_t *</em> <strong>gnutls_digest_list</strong> <em>( <var>void</var>)</em></dt>
19182 <dd>
19183 <p>Get a list of hash (digest) algorithms supported by GnuTLS.
19184 </p>
19185 <p>This function is not thread safe.
19186 </p>
19187 <p><strong>Returns:</strong> Return a (0)-terminated list of <code>gnutls_digest_algorithm_t</code>
19188 integers indicating the available digests.
19189 </p></dd></dl>
19190
19191 <a name="gnutls_005fecc_005fcurve_005fget-1"></a>
19192 <h4 class="subheading">gnutls_ecc_curve_get</h4>
19193 <a name="gnutls_005fecc_005fcurve_005fget"></a><dl>
19194 <dt><a name="index-gnutls_005fecc_005fcurve_005fget"></a>Function: <em>gnutls_ecc_curve_t</em> <strong>gnutls_ecc_curve_get</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
19195 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19196 </p>
19197 <p>Returns the currently used elliptic curve. Only valid
19198 when using an elliptic curve ciphersuite.
19199 </p>
19200 <p><strong>Returns:</strong> the currently used curve, a <code>gnutls_ecc_curve_t</code>
19201 type.
19202 </p>
19203 <p><strong>Since:</strong> 3.0
19204 </p></dd></dl>
19205
19206 <a name="gnutls_005fecc_005fcurve_005fget_005fname-1"></a>
19207 <h4 class="subheading">gnutls_ecc_curve_get_name</h4>
19208 <a name="gnutls_005fecc_005fcurve_005fget_005fname"></a><dl>
19209 <dt><a name="index-gnutls_005fecc_005fcurve_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_ecc_curve_get_name</strong> <em>(gnutls_ecc_curve_t <var>curve</var>)</em></dt>
19210 <dd><p><var>curve</var>: is an ECC curve
19211 </p>
19212 <p>Convert a <code>gnutls_ecc_curve_t</code>  value to a string.
19213 </p>
19214 <p><strong>Returns:</strong> a string that contains the name of the specified
19215 curve or <code>NULL</code> .
19216 </p>
19217 <p><strong>Since:</strong> 3.0
19218 </p></dd></dl>
19219
19220 <a name="gnutls_005fecc_005fcurve_005fget_005fsize-1"></a>
19221 <h4 class="subheading">gnutls_ecc_curve_get_size</h4>
19222 <a name="gnutls_005fecc_005fcurve_005fget_005fsize"></a><dl>
19223 <dt><a name="index-gnutls_005fecc_005fcurve_005fget_005fsize"></a>Function: <em>int</em> <strong>gnutls_ecc_curve_get_size</strong> <em>(gnutls_ecc_curve_t <var>curve</var>)</em></dt>
19224 <dd><p><var>curve</var>: is an ECC curve
19225 </p>
19226 <p>Returns the size in bytes of the curve.
19227 </p>
19228 <p><strong>Returns:</strong> a the size or (0).
19229 </p>
19230 <p><strong>Since:</strong> 3.0
19231 </p></dd></dl>
19232
19233 <a name="gnutls_005fecc_005fcurve_005flist-1"></a>
19234 <h4 class="subheading">gnutls_ecc_curve_list</h4>
19235 <a name="gnutls_005fecc_005fcurve_005flist"></a><dl>
19236 <dt><a name="index-gnutls_005fecc_005fcurve_005flist"></a>Function: <em>const gnutls_ecc_curve_t *</em> <strong>gnutls_ecc_curve_list</strong> <em>( <var>void</var>)</em></dt>
19237 <dd>
19238 <p>Get the list of supported elliptic curves.
19239 </p>
19240 <p>This function is not thread safe.
19241 </p>
19242 <p><strong>Returns:</strong> Return a (0)-terminated list of <code>gnutls_ecc_curve_t</code>
19243 integers indicating the available curves.
19244 </p></dd></dl>
19245
19246 <a name="gnutls_005ferror_005fis_005ffatal-1"></a>
19247 <h4 class="subheading">gnutls_error_is_fatal</h4>
19248 <a name="gnutls_005ferror_005fis_005ffatal"></a><dl>
19249 <dt><a name="index-gnutls_005ferror_005fis_005ffatal-1"></a>Function: <em>int</em> <strong>gnutls_error_is_fatal</strong> <em>(int <var>error</var>)</em></dt>
19250 <dd><p><var>error</var>: is a GnuTLS error code, a negative error code
19251 </p>
19252 <p>If a GnuTLS function returns a negative error code you may feed that
19253 value to this function to see if the error condition is fatal to
19254 a TLS session (i.e., must be terminated).
19255 </p>
19256 <p>Note that you may also want to check the error code manually, since some
19257 non-fatal errors to the protocol (such as a warning alert or
19258 a rehandshake request) may be fatal for your program.
19259 </p>
19260 <p>This function is only useful if you are dealing with errors from
19261 functions that relate to a TLS session (e.g., record layer or handshake
19262 layer handling functions).
19263 </p>
19264 <p><strong>Returns:</strong> Non-zero value on fatal errors or zero on non-fatal.
19265 </p></dd></dl>
19266
19267 <a name="gnutls_005ferror_005fto_005falert-1"></a>
19268 <h4 class="subheading">gnutls_error_to_alert</h4>
19269 <a name="gnutls_005ferror_005fto_005falert"></a><dl>
19270 <dt><a name="index-gnutls_005ferror_005fto_005falert-1"></a>Function: <em>int</em> <strong>gnutls_error_to_alert</strong> <em>(int <var>err</var>, int * <var>level</var>)</em></dt>
19271 <dd><p><var>err</var>: is a negative integer
19272 </p>
19273 <p><var>level</var>: the alert level will be stored there
19274 </p>
19275 <p>Get an alert depending on the error code returned by a gnutls
19276 function.  All alerts sent by this function should be considered
19277 fatal.  The only exception is when  <code>err</code> is <code>GNUTLS_E_REHANDSHAKE</code> ,
19278 where a warning alert should be sent to the peer indicating that no
19279 renegotiation will be performed.
19280 </p>
19281 <p>If there is no mapping to a valid alert the alert to indicate
19282 internal error is returned.
19283 </p>
19284 <p><strong>Returns:</strong> the alert code to use for a particular error code.
19285 </p></dd></dl>
19286
19287 <a name="gnutls_005fest_005frecord_005foverhead_005fsize-1"></a>
19288 <h4 class="subheading">gnutls_est_record_overhead_size</h4>
19289 <a name="gnutls_005fest_005frecord_005foverhead_005fsize"></a><dl>
19290 <dt><a name="index-gnutls_005fest_005frecord_005foverhead_005fsize"></a>Function: <em>size_t</em> <strong>gnutls_est_record_overhead_size</strong> <em>(gnutls_protocol_t <var>version</var>, gnutls_cipher_algorithm_t <var>cipher</var>, gnutls_mac_algorithm_t <var>mac</var>, gnutls_compression_method_t <var>comp</var>, unsigned int <var>flags</var>)</em></dt>
19291 <dd><p><var>version</var>: is a <code>gnutls_protocol_t</code>  value
19292 </p>
19293 <p><var>cipher</var>: is a <code>gnutls_cipher_algorithm_t</code>  value
19294 </p>
19295 <p><var>mac</var>: is a <code>gnutls_mac_algorithm_t</code>  value
19296 </p>
19297 <p><var>comp</var>: is a <code>gnutls_compression_method_t</code>  value
19298 </p>
19299 <p><var>flags</var>: must be zero
19300 </p>
19301 <p>This function will return the set size in bytes of the overhead
19302 due to TLS (or DTLS) per record.
19303 </p>
19304 <p>Note that this function may provide inacurate values when TLS
19305 extensions that modify the record format are negotiated. In these
19306 cases a more accurate value can be obtained using <code>gnutls_record_overhead_size()</code>
19307 after a completed handshake.
19308 </p>
19309 <p><strong>Since:</strong> 3.2.2
19310 </p></dd></dl>
19311
19312 <a name="gnutls_005ffingerprint-1"></a>
19313 <h4 class="subheading">gnutls_fingerprint</h4>
19314 <a name="gnutls_005ffingerprint"></a><dl>
19315 <dt><a name="index-gnutls_005ffingerprint"></a>Function: <em>int</em> <strong>gnutls_fingerprint</strong> <em>(gnutls_digest_algorithm_t <var>algo</var>, const gnutls_datum_t * <var>data</var>, void * <var>result</var>, size_t * <var>result_size</var>)</em></dt>
19316 <dd><p><var>algo</var>: is a digest algorithm
19317 </p>
19318 <p><var>data</var>: is the data
19319 </p>
19320 <p><var>result</var>: is the place where the result will be copied (may be null).
19321 </p>
19322 <p><var>result_size</var>: should hold the size of the result. The actual size
19323 of the returned result will also be copied there.
19324 </p>
19325 <p>This function will calculate a fingerprint (actually a hash), of
19326 the given data.  The result is not printable data.  You should
19327 convert it to hex, or to something else printable.
19328 </p>
19329 <p>This is the usual way to calculate a fingerprint of an X.509 DER
19330 encoded certificate.  Note however that the fingerprint of an
19331 OpenPGP certificate is not just a hash and cannot be calculated with this
19332 function.
19333 </p>
19334 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
19335 an error code is returned.
19336 </p></dd></dl>
19337
19338 <a name="gnutls_005ffips140_005fmode_005fenabled-1"></a>
19339 <h4 class="subheading">gnutls_fips140_mode_enabled</h4>
19340 <a name="gnutls_005ffips140_005fmode_005fenabled"></a><dl>
19341 <dt><a name="index-gnutls_005ffips140_005fmode_005fenabled"></a>Function: <em>int</em> <strong>gnutls_fips140_mode_enabled</strong> <em>( <var>void</var>)</em></dt>
19342 <dd>
19343 <p>Checks whether this library is in FIPS140 mode.
19344 </p>
19345 <p><strong>Returns:</strong> return non-zero if true or zero if false.
19346 </p>
19347 <p><strong>Since:</strong> 3.3.0
19348 </p></dd></dl>
19349
19350 <a name="gnutls_005fglobal_005fdeinit-1"></a>
19351 <h4 class="subheading">gnutls_global_deinit</h4>
19352 <a name="gnutls_005fglobal_005fdeinit"></a><dl>
19353 <dt><a name="index-gnutls_005fglobal_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_global_deinit</strong> <em>( <var>void</var>)</em></dt>
19354 <dd>
19355 <p>This function deinitializes the global data, that were initialized
19356 using <code>gnutls_global_init()</code> .
19357 </p></dd></dl>
19358
19359 <a name="gnutls_005fglobal_005finit-1"></a>
19360 <h4 class="subheading">gnutls_global_init</h4>
19361 <a name="gnutls_005fglobal_005finit"></a><dl>
19362 <dt><a name="index-gnutls_005fglobal_005finit"></a>Function: <em>int</em> <strong>gnutls_global_init</strong> <em>( <var>void</var>)</em></dt>
19363 <dd>
19364 <p>This function performs any required precalculations, detects
19365 the supported CPU capabilities and initializes the underlying
19366 cryptographic backend. In order to free any resources
19367 taken by this call you should <code>gnutls_global_deinit()</code>
19368 when gnutls usage is no longer needed.
19369 </p>
19370 <p>This function increments a global counter, so that
19371 <code>gnutls_global_deinit()</code>  only releases resources when it has been
19372 called as many times as <code>gnutls_global_init()</code> .  This is useful when
19373 GnuTLS is used by more than one library in an application.  This
19374 function can be called many times, but will only do something the
19375 first time.
19376 </p>
19377 <p>Since GnuTLS 3.3.0 this function is only required in systems that
19378 do not support library constructors and static linking. This
19379 function also became thread safe.
19380 </p>
19381 <p>A subsequent call of this function if the initial has failed will
19382 return the same error code.
19383 </p>
19384 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
19385 otherwise a negative error code is returned.
19386 </p></dd></dl>
19387
19388 <a name="gnutls_005fglobal_005fset_005faudit_005flog_005ffunction-1"></a>
19389 <h4 class="subheading">gnutls_global_set_audit_log_function</h4>
19390 <a name="gnutls_005fglobal_005fset_005faudit_005flog_005ffunction"></a><dl>
19391 <dt><a name="index-gnutls_005fglobal_005fset_005faudit_005flog_005ffunction-1"></a>Function: <em>void</em> <strong>gnutls_global_set_audit_log_function</strong> <em>(gnutls_audit_log_func <var>log_func</var>)</em></dt>
19392 <dd><p><var>log_func</var>: it is the audit log function
19393 </p>
19394 <p>This is the function to set the audit logging function. This
19395 is a function to report important issues, such as possible
19396 attacks in the protocol. This is different from <code>gnutls_global_set_log_function()</code>
19397 because it will report also session-specific events. The session
19398 parameter will be null if there is no corresponding TLS session.
19399 </p>
19400 <p><code>gnutls_audit_log_func</code> is of the form,
19401 void (*gnutls_audit_log_func)( gnutls_session_t, const char*);
19402 </p>
19403 <p><strong>Since:</strong> 3.0
19404 </p></dd></dl>
19405
19406 <a name="gnutls_005fglobal_005fset_005flog_005ffunction-1"></a>
19407 <h4 class="subheading">gnutls_global_set_log_function</h4>
19408 <a name="gnutls_005fglobal_005fset_005flog_005ffunction"></a><dl>
19409 <dt><a name="index-gnutls_005fglobal_005fset_005flog_005ffunction"></a>Function: <em>void</em> <strong>gnutls_global_set_log_function</strong> <em>(gnutls_log_func <var>log_func</var>)</em></dt>
19410 <dd><p><var>log_func</var>: it&rsquo;s a log function
19411 </p>
19412 <p>This is the function where you set the logging function gnutls is
19413 going to use.  This function only accepts a character array.
19414 Normally you may not use this function since it is only used for
19415 debugging purposes.
19416 </p>
19417 <p><code>gnutls_log_func</code> is of the form,
19418 void (*gnutls_log_func)( int level, const char*);
19419 </p></dd></dl>
19420
19421 <a name="gnutls_005fglobal_005fset_005flog_005flevel-1"></a>
19422 <h4 class="subheading">gnutls_global_set_log_level</h4>
19423 <a name="gnutls_005fglobal_005fset_005flog_005flevel"></a><dl>
19424 <dt><a name="index-gnutls_005fglobal_005fset_005flog_005flevel"></a>Function: <em>void</em> <strong>gnutls_global_set_log_level</strong> <em>(int <var>level</var>)</em></dt>
19425 <dd><p><var>level</var>: it&rsquo;s an integer from 0 to 99.
19426 </p>
19427 <p>This is the function that allows you to set the log level.  The
19428 level is an integer between 0 and 9.  Higher values mean more
19429 verbosity. The default value is 0.  Larger values should only be
19430 used with care, since they may reveal sensitive information.
19431 </p>
19432 <p>Use a log level over 10 to enable all debugging options.
19433 </p></dd></dl>
19434
19435 <a name="gnutls_005fglobal_005fset_005fmutex-1"></a>
19436 <h4 class="subheading">gnutls_global_set_mutex</h4>
19437 <a name="gnutls_005fglobal_005fset_005fmutex"></a><dl>
19438 <dt><a name="index-gnutls_005fglobal_005fset_005fmutex-1"></a>Function: <em>void</em> <strong>gnutls_global_set_mutex</strong> <em>(mutex_init_func <var>init</var>, mutex_deinit_func <var>deinit</var>, mutex_lock_func <var>lock</var>, mutex_unlock_func <var>unlock</var>)</em></dt>
19439 <dd><p><var>init</var>: mutex initialization function
19440 </p>
19441 <p><var>deinit</var>: mutex deinitialization function
19442 </p>
19443 <p><var>lock</var>: mutex locking function
19444 </p>
19445 <p><var>unlock</var>: mutex unlocking function
19446 </p>
19447 <p>With this function you are allowed to override the default mutex
19448 locks used in some parts of gnutls and dependent libraries. This function
19449 should be used if you have complete control of your program and libraries.
19450 Do not call this function from a library, or preferrably from any application
19451 unless really needed to. GnuTLS will use the appropriate locks for the running
19452 system.
19453 </p>
19454 <p>This function must be called prior to any other gnutls function.
19455 </p>
19456 <p><strong>Since:</strong> 2.12.0
19457 </p></dd></dl>
19458
19459 <a name="gnutls_005fglobal_005fset_005ftime_005ffunction-1"></a>
19460 <h4 class="subheading">gnutls_global_set_time_function</h4>
19461 <a name="gnutls_005fglobal_005fset_005ftime_005ffunction"></a><dl>
19462 <dt><a name="index-gnutls_005fglobal_005fset_005ftime_005ffunction"></a>Function: <em>void</em> <strong>gnutls_global_set_time_function</strong> <em>(gnutls_time_func <var>time_func</var>)</em></dt>
19463 <dd><p><var>time_func</var>: it&rsquo;s the system time function, a <code>gnutls_time_func()</code>  callback.
19464 </p>
19465 <p>This is the function where you can override the default system time
19466 function.  The application provided function should behave the same
19467 as the standard function.
19468 </p>
19469 <p><strong>Since:</strong> 2.12.0
19470 </p></dd></dl>
19471
19472 <a name="gnutls_005fhandshake-1"></a>
19473 <h4 class="subheading">gnutls_handshake</h4>
19474 <a name="gnutls_005fhandshake"></a><dl>
19475 <dt><a name="index-gnutls_005fhandshake-1"></a>Function: <em>int</em> <strong>gnutls_handshake</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
19476 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19477 </p>
19478 <p>This function does the handshake of the TLS/SSL protocol, and
19479 initializes the TLS connection.
19480 </p>
19481 <p>This function will fail if any problem is encountered, and will
19482 return a negative error code. In case of a client, if the client
19483 has asked to resume a session, but the server couldn&rsquo;t, then a
19484 full handshake will be performed.
19485 </p>
19486 <p>The non-fatal errors expected by this function are:
19487 <code>GNUTLS_E_INTERRUPTED</code> , <code>GNUTLS_E_AGAIN</code> ,
19488 <code>GNUTLS_E_WARNING_ALERT_RECEIVED</code> , and <code>GNUTLS_E_GOT_APPLICATION_DATA</code> ,
19489 the latter only in a case of rehandshake.
19490 </p>
19491 <p>The former two interrupt the handshake procedure due to the lower
19492 layer being interrupted, and the latter because of an alert that
19493 may be sent by a server (it is always a good idea to check any
19494 received alerts). On these errors call this function again, until it
19495 returns 0; cf.  <code>gnutls_record_get_direction()</code>  and
19496 <code>gnutls_error_is_fatal()</code> . In DTLS sessions the non-fatal error
19497 <code>GNUTLS_E_LARGE_PACKET</code>  is also possible, and indicates that
19498 the MTU should be adjusted.
19499 </p>
19500 <p>If this function is called by a server after a rehandshake request
19501 then <code>GNUTLS_E_GOT_APPLICATION_DATA</code>  or
19502 <code>GNUTLS_E_WARNING_ALERT_RECEIVED</code>  may be returned.  Note that these
19503 are non fatal errors, only in the specific case of a rehandshake.
19504 Their meaning is that the client rejected the rehandshake request or
19505 in the case of <code>GNUTLS_E_GOT_APPLICATION_DATA</code>  it could also mean that
19506 some data were pending.
19507 </p>
19508 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
19509 </p></dd></dl>
19510
19511 <a name="gnutls_005fhandshake_005fdescription_005fget_005fname-1"></a>
19512 <h4 class="subheading">gnutls_handshake_description_get_name</h4>
19513 <a name="gnutls_005fhandshake_005fdescription_005fget_005fname"></a><dl>
19514 <dt><a name="index-gnutls_005fhandshake_005fdescription_005fget_005fname"></a>Function: <em>const char     *</em> <strong>gnutls_handshake_description_get_name</strong> <em>(gnutls_handshake_description_t         <var>type</var>)</em></dt>
19515 <dd><p><var>type</var>: is a handshake message description
19516 </p>
19517 <p>Convert a <code>gnutls_handshake_description_t</code>  value to a string.
19518 </p>
19519 <p><strong>Returns:</strong> a string that contains the name of the specified handshake
19520 message or <code>NULL</code> .
19521 </p></dd></dl>
19522
19523 <a name="gnutls_005fhandshake_005fget_005flast_005fin-1"></a>
19524 <h4 class="subheading">gnutls_handshake_get_last_in</h4>
19525 <a name="gnutls_005fhandshake_005fget_005flast_005fin"></a><dl>
19526 <dt><a name="index-gnutls_005fhandshake_005fget_005flast_005fin"></a>Function: <em>gnutls_handshake_description_t</em> <strong>gnutls_handshake_get_last_in</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
19527 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19528 </p>
19529 <p>This function is only useful to check where the last performed
19530 handshake failed.  If the previous handshake succeed or was not
19531 performed at all then no meaningful value will be returned.
19532 </p>
19533 <p>Check <code>gnutls_handshake_description_t</code>  in gnutls.h for the
19534 available handshake descriptions.
19535 </p>
19536 <p><strong>Returns:</strong> the last handshake message type received, a
19537 <code>gnutls_handshake_description_t</code> .
19538 </p></dd></dl>
19539
19540 <a name="gnutls_005fhandshake_005fget_005flast_005fout-1"></a>
19541 <h4 class="subheading">gnutls_handshake_get_last_out</h4>
19542 <a name="gnutls_005fhandshake_005fget_005flast_005fout"></a><dl>
19543 <dt><a name="index-gnutls_005fhandshake_005fget_005flast_005fout"></a>Function: <em>gnutls_handshake_description_t</em> <strong>gnutls_handshake_get_last_out</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
19544 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19545 </p>
19546 <p>This function is only useful to check where the last performed
19547 handshake failed.  If the previous handshake succeed or was not
19548 performed at all then no meaningful value will be returned.
19549 </p>
19550 <p>Check <code>gnutls_handshake_description_t</code>  in gnutls.h for the
19551 available handshake descriptions.
19552 </p>
19553 <p><strong>Returns:</strong> the last handshake message type sent, a
19554 <code>gnutls_handshake_description_t</code> .
19555 </p></dd></dl>
19556
19557 <a name="gnutls_005fhandshake_005fset_005fhook_005ffunction-1"></a>
19558 <h4 class="subheading">gnutls_handshake_set_hook_function</h4>
19559 <a name="gnutls_005fhandshake_005fset_005fhook_005ffunction"></a><dl>
19560 <dt><a name="index-gnutls_005fhandshake_005fset_005fhook_005ffunction"></a>Function: <em>void</em> <strong>gnutls_handshake_set_hook_function</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>htype</var>, int <var>post</var>, gnutls_handshake_hook_func <var>func</var>)</em></dt>
19561 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure
19562 </p>
19563 <p><var>htype</var>: the <code>gnutls_handshake_description_t</code>  of the message to hook at
19564 </p>
19565 <p><var>post</var>: <code>GNUTLS_HOOK_</code> * depending on when the hook function should be called
19566 </p>
19567 <p><var>func</var>: is the function to be called
19568 </p>
19569 <p>This function will set a callback to be called after or before the specified
19570 handshake message has been received or generated. This is a
19571 generalization of <code>gnutls_handshake_set_post_client_hello_function()</code> .
19572 </p>
19573 <p>To call the hook function prior to the message being sent/generated use
19574 <code>GNUTLS_HOOK_PRE</code>  as  <code>post</code> parameter, <code>GNUTLS_HOOK_POST</code>  to call
19575 after, and <code>GNUTLS_HOOK_BOTH</code>  for both cases.
19576 </p>
19577 <p>This callback must return 0 on success or a gnutls error code to
19578 terminate the handshake.
19579 </p>
19580 <p>Note to hook at all handshake messages use an  <code>htype</code> of <code>GNUTLS_HANDSHAKE_ANY</code> .
19581 </p>
19582 <p><strong>Warning:</strong> You should not use this function to terminate the
19583 handshake based on client input unless you know what you are
19584 doing. Before the handshake is finished there is no way to know if
19585 there is a man-in-the-middle attack being performed.
19586 </p></dd></dl>
19587
19588 <a name="gnutls_005fhandshake_005fset_005fmax_005fpacket_005flength-1"></a>
19589 <h4 class="subheading">gnutls_handshake_set_max_packet_length</h4>
19590 <a name="gnutls_005fhandshake_005fset_005fmax_005fpacket_005flength"></a><dl>
19591 <dt><a name="index-gnutls_005fhandshake_005fset_005fmax_005fpacket_005flength"></a>Function: <em>void</em> <strong>gnutls_handshake_set_max_packet_length</strong> <em>(gnutls_session_t <var>session</var>, size_t <var>max</var>)</em></dt>
19592 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19593 </p>
19594 <p><var>max</var>: is the maximum number.
19595 </p>
19596 <p>This function will set the maximum size of all handshake messages.
19597 Handshakes over this size are rejected with
19598 <code>GNUTLS_E_HANDSHAKE_TOO_LARGE</code>  error code.  The default value is
19599 128kb which is typically large enough.  Set this to 0 if you do not
19600 want to set an upper limit.
19601 </p>
19602 <p>The reason for restricting the handshake message sizes are to
19603 limit Denial of Service attacks.
19604 </p>
19605 <p>Note that the maximum handshake size was increased to 128kb
19606 from 48kb in GnuTLS 3.3.25.
19607 </p></dd></dl>
19608
19609 <a name="gnutls_005fhandshake_005fset_005fpost_005fclient_005fhello_005ffunction-1"></a>
19610 <h4 class="subheading">gnutls_handshake_set_post_client_hello_function</h4>
19611 <a name="gnutls_005fhandshake_005fset_005fpost_005fclient_005fhello_005ffunction"></a><dl>
19612 <dt><a name="index-gnutls_005fhandshake_005fset_005fpost_005fclient_005fhello_005ffunction"></a>Function: <em>void</em> <strong>gnutls_handshake_set_post_client_hello_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_handshake_post_client_hello_func       <var>func</var>)</em></dt>
19613 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19614 </p>
19615 <p><var>func</var>: is the function to be called
19616 </p>
19617 <p>This function will set a callback to be called after the client
19618 hello has been received (callback valid in server side only). This
19619 allows the server to adjust settings based on received extensions.
19620 </p>
19621 <p>Those settings could be ciphersuites, requesting certificate, or
19622 anything else except for version negotiation (this is done before
19623 the hello message is parsed).
19624 </p>
19625 <p>This callback must return 0 on success or a gnutls error code to
19626 terminate the handshake.
19627 </p>
19628 <p>Since GnuTLS 3.3.5 the callback is
19629 allowed to return <code>GNUTLS_E_AGAIN</code>  or <code>GNUTLS_E_INTERRUPTED</code>  to
19630 put the handshake on hold. In that case <code>gnutls_handshake()</code>
19631 will return <code>GNUTLS_E_INTERRUPTED</code>  and can be resumed when needed.
19632 </p>
19633 <p><strong>Warning:</strong> You should not use this function to terminate the
19634 handshake based on client input unless you know what you are
19635 doing. Before the handshake is finished there is no way to know if
19636 there is a man-in-the-middle attack being performed.
19637 </p></dd></dl>
19638
19639 <a name="gnutls_005fhandshake_005fset_005fprivate_005fextensions-1"></a>
19640 <h4 class="subheading">gnutls_handshake_set_private_extensions</h4>
19641 <a name="gnutls_005fhandshake_005fset_005fprivate_005fextensions"></a><dl>
19642 <dt><a name="index-gnutls_005fhandshake_005fset_005fprivate_005fextensions"></a>Function: <em>void</em> <strong>gnutls_handshake_set_private_extensions</strong> <em>(gnutls_session_t <var>session</var>, int <var>allow</var>)</em></dt>
19643 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19644 </p>
19645 <p><var>allow</var>: is an integer (0 or 1)
19646 </p>
19647 <p>This function will enable or disable the use of private cipher
19648 suites (the ones that start with 0xFF).  By default or if  <code>allow</code> is 0 then these cipher suites will not be advertised nor used.
19649 </p>
19650 <p>Currently GnuTLS does not include such cipher-suites or
19651 compression algorithms.
19652 </p>
19653 <p>Enabling the private ciphersuites when talking to other than
19654 gnutls servers and clients may cause interoperability problems.
19655 </p></dd></dl>
19656
19657 <a name="gnutls_005fhandshake_005fset_005frandom-1"></a>
19658 <h4 class="subheading">gnutls_handshake_set_random</h4>
19659 <a name="gnutls_005fhandshake_005fset_005frandom"></a><dl>
19660 <dt><a name="index-gnutls_005fhandshake_005fset_005frandom"></a>Function: <em>int</em> <strong>gnutls_handshake_set_random</strong> <em>(gnutls_session_t <var>session</var>, const gnutls_datum_t * <var>random</var>)</em></dt>
19661 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19662 </p>
19663 <p><var>random</var>: a random value of 32-bytes
19664 </p>
19665 <p>This function will explicitly set the server or client hello
19666 random value in the subsequent TLS handshake. The random value
19667 should be a 32-byte value.
19668 </p>
19669 <p>Note that this function should not normally be used as gnutls
19670 will select automatically a random value for the handshake.
19671 </p>
19672 <p>This function should not be used when resuming a session.
19673 </p>
19674 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
19675 </p>
19676 <p>Since 3.1.9
19677 </p></dd></dl>
19678
19679 <a name="gnutls_005fhandshake_005fset_005ftimeout-1"></a>
19680 <h4 class="subheading">gnutls_handshake_set_timeout</h4>
19681 <a name="gnutls_005fhandshake_005fset_005ftimeout"></a><dl>
19682 <dt><a name="index-gnutls_005fhandshake_005fset_005ftimeout-1"></a>Function: <em>void</em> <strong>gnutls_handshake_set_timeout</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>ms</var>)</em></dt>
19683 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19684 </p>
19685 <p><var>ms</var>: is a timeout value in milliseconds
19686 </p>
19687 <p>This function sets the timeout for the handshake process
19688 to the provided value. Use an  <code>ms</code> value of zero to disable
19689 timeout, or <code>GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT</code>  for a reasonable
19690 default value.
19691 </p>
19692 <p><strong>Since:</strong> 3.1.0
19693 </p></dd></dl>
19694
19695 <a name="gnutls_005fheartbeat_005fallowed-1"></a>
19696 <h4 class="subheading">gnutls_heartbeat_allowed</h4>
19697 <a name="gnutls_005fheartbeat_005fallowed"></a><dl>
19698 <dt><a name="index-gnutls_005fheartbeat_005fallowed"></a>Function: <em>int</em> <strong>gnutls_heartbeat_allowed</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>type</var>)</em></dt>
19699 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19700 </p>
19701 <p><var>type</var>: one of <code>GNUTLS_HB_LOCAL_ALLOWED_TO_SEND</code>  and <code>GNUTLS_HB_PEER_ALLOWED_TO_SEND</code>
19702 </p>
19703 <p>This function will check whether heartbeats are allowed
19704 to be sent or received in this session.
19705 </p>
19706 <p><strong>Returns:</strong> Non zero if heartbeats are allowed.
19707 </p>
19708 <p><strong>Since:</strong> 3.1.2
19709 </p></dd></dl>
19710
19711 <a name="gnutls_005fheartbeat_005fenable-1"></a>
19712 <h4 class="subheading">gnutls_heartbeat_enable</h4>
19713 <a name="gnutls_005fheartbeat_005fenable"></a><dl>
19714 <dt><a name="index-gnutls_005fheartbeat_005fenable"></a>Function: <em>void</em> <strong>gnutls_heartbeat_enable</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>type</var>)</em></dt>
19715 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19716 </p>
19717 <p><var>type</var>: one of the GNUTLS_HB_* flags
19718 </p>
19719 <p>If this function is called with the <code>GNUTLS_HB_PEER_ALLOWED_TO_SEND</code>
19720  <code>type</code> , GnuTLS will allow heartbeat messages to be received. Moreover it also
19721 request the peer to accept heartbeat messages.
19722 </p>
19723 <p>If the  <code>type</code> used is <code>GNUTLS_HB_LOCAL_ALLOWED_TO_SEND</code> , then the peer
19724 will be asked to accept heartbeat messages but not send ones.
19725 </p>
19726 <p>The function <code>gnutls_heartbeat_allowed()</code>  can be used to test Whether
19727 locally generated heartbeat messages can be accepted by the peer.
19728 </p>
19729 <p><strong>Since:</strong> 3.1.2
19730 </p></dd></dl>
19731
19732 <a name="gnutls_005fheartbeat_005fget_005ftimeout-1"></a>
19733 <h4 class="subheading">gnutls_heartbeat_get_timeout</h4>
19734 <a name="gnutls_005fheartbeat_005fget_005ftimeout"></a><dl>
19735 <dt><a name="index-gnutls_005fheartbeat_005fget_005ftimeout"></a>Function: <em>unsigned int</em> <strong>gnutls_heartbeat_get_timeout</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
19736 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19737 </p>
19738 <p>This function will return the milliseconds remaining
19739 for a retransmission of the previously sent ping
19740 message. This function is useful when ping is used in
19741 non-blocking mode, to estimate when to call <code>gnutls_heartbeat_ping()</code>
19742 if no packets have been received.
19743 </p>
19744 <p><strong>Returns:</strong> the remaining time in milliseconds.
19745 </p>
19746 <p><strong>Since:</strong> 3.1.2
19747 </p></dd></dl>
19748
19749 <a name="gnutls_005fheartbeat_005fping-1"></a>
19750 <h4 class="subheading">gnutls_heartbeat_ping</h4>
19751 <a name="gnutls_005fheartbeat_005fping"></a><dl>
19752 <dt><a name="index-gnutls_005fheartbeat_005fping"></a>Function: <em>int</em> <strong>gnutls_heartbeat_ping</strong> <em>(gnutls_session_t <var>session</var>, size_t <var>data_size</var>, unsigned int <var>max_tries</var>, unsigned int <var>flags</var>)</em></dt>
19753 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19754 </p>
19755 <p><var>data_size</var>: is the length of the ping payload.
19756 </p>
19757 <p><var>max_tries</var>: if flags is <code>GNUTLS_HEARTBEAT_WAIT</code>  then this sets the number of retransmissions. Use zero for indefinite (until timeout).
19758 </p>
19759 <p><var>flags</var>: if <code>GNUTLS_HEARTBEAT_WAIT</code>  then wait for pong or timeout instead of returning immediately.
19760 </p>
19761 <p>This function sends a ping to the peer. If the  <code>flags</code> is set
19762 to <code>GNUTLS_HEARTBEAT_WAIT</code>  then it waits for a reply from the peer.
19763 </p>
19764 <p>Note that it is highly recommended to use this function with the
19765 flag <code>GNUTLS_HEARTBEAT_WAIT</code> , or you need to handle retransmissions
19766 and timeouts manually.
19767 </p>
19768 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
19769 </p>
19770 <p><strong>Since:</strong> 3.1.2
19771 </p></dd></dl>
19772
19773 <a name="gnutls_005fheartbeat_005fpong-1"></a>
19774 <h4 class="subheading">gnutls_heartbeat_pong</h4>
19775 <a name="gnutls_005fheartbeat_005fpong"></a><dl>
19776 <dt><a name="index-gnutls_005fheartbeat_005fpong"></a>Function: <em>int</em> <strong>gnutls_heartbeat_pong</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>flags</var>)</em></dt>
19777 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19778 </p>
19779 <p><var>flags</var>: should be zero
19780 </p>
19781 <p>This function replies to a ping by sending a pong to the peer.
19782 </p>
19783 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
19784 </p>
19785 <p><strong>Since:</strong> 3.1.2
19786 </p></dd></dl>
19787
19788 <a name="gnutls_005fheartbeat_005fset_005ftimeouts-1"></a>
19789 <h4 class="subheading">gnutls_heartbeat_set_timeouts</h4>
19790 <a name="gnutls_005fheartbeat_005fset_005ftimeouts"></a><dl>
19791 <dt><a name="index-gnutls_005fheartbeat_005fset_005ftimeouts"></a>Function: <em>void</em> <strong>gnutls_heartbeat_set_timeouts</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>retrans_timeout</var>, unsigned int <var>total_timeout</var>)</em></dt>
19792 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19793 </p>
19794 <p><var>retrans_timeout</var>: The time at which a retransmission will occur in milliseconds
19795 </p>
19796 <p><var>total_timeout</var>: The time at which the connection will be aborted, in milliseconds.
19797 </p>
19798 <p>This function will override the timeouts for the DTLS heartbeat
19799 protocol. The retransmission timeout is the time after which a
19800 message from the peer is not received, the previous request will
19801 be retransmitted. The total timeout is the time after which the
19802 handshake will be aborted with <code>GNUTLS_E_TIMEDOUT</code> .
19803 </p>
19804 <p>If the retransmission timeout is zero then the handshake will operate
19805 in a non-blocking way, i.e., return <code>GNUTLS_E_AGAIN</code> .
19806 </p>
19807 <p><strong>Since:</strong> 3.1.2
19808 </p></dd></dl>
19809
19810 <a name="gnutls_005fhex2bin-1"></a>
19811 <h4 class="subheading">gnutls_hex2bin</h4>
19812 <a name="gnutls_005fhex2bin"></a><dl>
19813 <dt><a name="index-gnutls_005fhex2bin"></a>Function: <em>int</em> <strong>gnutls_hex2bin</strong> <em>(const char * <var>hex_data</var>, size_t <var>hex_size</var>, void * <var>bin_data</var>, size_t * <var>bin_size</var>)</em></dt>
19814 <dd><p><var>hex_data</var>: string with data in hex format
19815 </p>
19816 <p><var>hex_size</var>: size of hex data
19817 </p>
19818 <p><var>bin_data</var>: output array with binary data
19819 </p>
19820 <p><var>bin_size</var>: when calling should hold maximum size of  <code>bin_data</code> ,
19821 on return will hold actual length of  <code>bin_data</code> .
19822 </p>
19823 <p>Convert a buffer with hex data to binary data.
19824 </p>
19825 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
19826 </p>
19827 <p><strong>Since:</strong> 2.4.0
19828 </p></dd></dl>
19829
19830 <a name="gnutls_005fhex_005fdecode-1"></a>
19831 <h4 class="subheading">gnutls_hex_decode</h4>
19832 <a name="gnutls_005fhex_005fdecode"></a><dl>
19833 <dt><a name="index-gnutls_005fhex_005fdecode"></a>Function: <em>int</em> <strong>gnutls_hex_decode</strong> <em>(const gnutls_datum_t * <var>hex_data</var>, void * <var>result</var>, size_t * <var>result_size</var>)</em></dt>
19834 <dd><p><var>hex_data</var>: contain the encoded data
19835 </p>
19836 <p><var>result</var>: the place where decoded data will be copied
19837 </p>
19838 <p><var>result_size</var>: holds the size of the result
19839 </p>
19840 <p>This function will decode the given encoded data, using the hex
19841 encoding used by PSK password files.
19842 </p>
19843 <p>Note that hex_data should be null terminated.
19844 </p>
19845 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the buffer given is not
19846 long enough, or 0 on success.
19847 </p></dd></dl>
19848
19849 <a name="gnutls_005fhex_005fencode-1"></a>
19850 <h4 class="subheading">gnutls_hex_encode</h4>
19851 <a name="gnutls_005fhex_005fencode"></a><dl>
19852 <dt><a name="index-gnutls_005fhex_005fencode"></a>Function: <em>int</em> <strong>gnutls_hex_encode</strong> <em>(const gnutls_datum_t * <var>data</var>, char * <var>result</var>, size_t * <var>result_size</var>)</em></dt>
19853 <dd><p><var>data</var>: contain the raw data
19854 </p>
19855 <p><var>result</var>: the place where hex data will be copied
19856 </p>
19857 <p><var>result_size</var>: holds the size of the result
19858 </p>
19859 <p>This function will convert the given data to printable data, using
19860 the hex encoding, as used in the PSK password files.
19861 </p>
19862 <p>Note that the size of the result includes the null terminator.
19863 </p>
19864 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the buffer given is not
19865 long enough, or 0 on success.
19866 </p></dd></dl>
19867
19868 <a name="gnutls_005finit-1"></a>
19869 <h4 class="subheading">gnutls_init</h4>
19870 <a name="gnutls_005finit"></a><dl>
19871 <dt><a name="index-gnutls_005finit-1"></a>Function: <em>int</em> <strong>gnutls_init</strong> <em>(gnutls_session_t * <var>session</var>, unsigned int <var>flags</var>)</em></dt>
19872 <dd><p><var>session</var>: is a pointer to a <code>gnutls_session_t</code>  structure.
19873 </p>
19874 <p><var>flags</var>: indicate if this session is to be used for server or client.
19875 </p>
19876 <p>This function initializes the current session to null. Every
19877 session must be initialized before use, so internal structures can
19878 be allocated.  This function allocates structures which can only
19879 be free&rsquo;d by calling <code>gnutls_deinit()</code> .  Returns <code>GNUTLS_E_SUCCESS</code>  (0) on success.
19880 </p>
19881 <p><code>flags</code> can be one of <code>GNUTLS_CLIENT</code>  and <code>GNUTLS_SERVER</code> . For a DTLS
19882 entity, the flags <code>GNUTLS_DATAGRAM</code>  and  <code>GNUTLS_NONBLOCK</code>  are
19883 also available. The latter flag will enable a non-blocking
19884 operation of the DTLS timers.
19885 </p>
19886 <p>The flag <code>GNUTLS_NO_REPLAY_PROTECTION</code>  will disable any
19887 replay protection in DTLS mode. That must only used when
19888 replay protection is achieved using other means.
19889 </p>
19890 <p>Note that since version 3.1.2 this function enables some common
19891 TLS extensions such as session tickets and OCSP certificate status
19892 request in client side by default. To prevent that use the <code>GNUTLS_NO_EXTENSIONS</code>
19893 flag.
19894 </p>
19895 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
19896 </p></dd></dl>
19897
19898 <a name="gnutls_005fkey_005fgenerate-1"></a>
19899 <h4 class="subheading">gnutls_key_generate</h4>
19900 <a name="gnutls_005fkey_005fgenerate"></a><dl>
19901 <dt><a name="index-gnutls_005fkey_005fgenerate"></a>Function: <em>int</em> <strong>gnutls_key_generate</strong> <em>(gnutls_datum_t * <var>key</var>, unsigned int <var>key_size</var>)</em></dt>
19902 <dd><p><var>key</var>: is a pointer to a <code>gnutls_datum_t</code>  which will contain a newly
19903 created key.
19904 </p>
19905 <p><var>key_size</var>: The number of bytes of the key.
19906 </p>
19907 <p>Generates a random key of  <code>key_size</code> bytes.
19908 </p>
19909 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or an
19910 error code.
19911 </p>
19912 <p><strong>Since:</strong> 3.0
19913 </p></dd></dl>
19914
19915 <a name="gnutls_005fkx_005fget-1"></a>
19916 <h4 class="subheading">gnutls_kx_get</h4>
19917 <a name="gnutls_005fkx_005fget"></a><dl>
19918 <dt><a name="index-gnutls_005fkx_005fget"></a>Function: <em>gnutls_kx_algorithm_t</em> <strong>gnutls_kx_get</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
19919 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19920 </p>
19921 <p>Get currently used key exchange algorithm.
19922 </p>
19923 <p><strong>Returns:</strong> the key exchange algorithm used in the last handshake, a
19924 <code>gnutls_kx_algorithm_t</code>  value.
19925 </p></dd></dl>
19926
19927 <a name="gnutls_005fkx_005fget_005fid-1"></a>
19928 <h4 class="subheading">gnutls_kx_get_id</h4>
19929 <a name="gnutls_005fkx_005fget_005fid"></a><dl>
19930 <dt><a name="index-gnutls_005fkx_005fget_005fid"></a>Function: <em>gnutls_kx_algorithm_t</em> <strong>gnutls_kx_get_id</strong> <em>(const char * <var>name</var>)</em></dt>
19931 <dd><p><var>name</var>: is a KX name
19932 </p>
19933 <p>Convert a string to a <code>gnutls_kx_algorithm_t</code>  value.  The names are
19934 compared in a case insensitive way.
19935 </p>
19936 <p><strong>Returns:</strong> an id of the specified KX algorithm, or <code>GNUTLS_KX_UNKNOWN</code>
19937 on error.
19938 </p></dd></dl>
19939
19940 <a name="gnutls_005fkx_005fget_005fname-1"></a>
19941 <h4 class="subheading">gnutls_kx_get_name</h4>
19942 <a name="gnutls_005fkx_005fget_005fname"></a><dl>
19943 <dt><a name="index-gnutls_005fkx_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_kx_get_name</strong> <em>(gnutls_kx_algorithm_t <var>algorithm</var>)</em></dt>
19944 <dd><p><var>algorithm</var>: is a key exchange algorithm
19945 </p>
19946 <p>Convert a <code>gnutls_kx_algorithm_t</code>  value to a string.
19947 </p>
19948 <p><strong>Returns:</strong> a pointer to a string that contains the name of the
19949 specified key exchange algorithm, or <code>NULL</code> .
19950 </p></dd></dl>
19951
19952 <a name="gnutls_005fkx_005flist-1"></a>
19953 <h4 class="subheading">gnutls_kx_list</h4>
19954 <a name="gnutls_005fkx_005flist"></a><dl>
19955 <dt><a name="index-gnutls_005fkx_005flist"></a>Function: <em>const gnutls_kx_algorithm_t *</em> <strong>gnutls_kx_list</strong> <em>( <var>void</var>)</em></dt>
19956 <dd>
19957 <p>Get a list of supported key exchange algorithms.
19958 </p>
19959 <p>This function is not thread safe.
19960 </p>
19961 <p><strong>Returns:</strong> a (0)-terminated list of <code>gnutls_kx_algorithm_t</code>  integers
19962 indicating the available key exchange algorithms.
19963 </p></dd></dl>
19964
19965 <a name="gnutls_005fload_005ffile-1"></a>
19966 <h4 class="subheading">gnutls_load_file</h4>
19967 <a name="gnutls_005fload_005ffile"></a><dl>
19968 <dt><a name="index-gnutls_005fload_005ffile"></a>Function: <em>int</em> <strong>gnutls_load_file</strong> <em>(const char * <var>filename</var>, gnutls_datum_t * <var>data</var>)</em></dt>
19969 <dd><p><var>filename</var>: the name of the file to load
19970 </p>
19971 <p><var>data</var>: Where the file will be stored
19972 </p>
19973 <p>This function will load a file into a datum. The data are
19974 zero terminated but the terminating null is not included in length.
19975 The returned data are allocated using <code>gnutls_malloc()</code> .
19976 </p>
19977 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
19978 an error code is returned.
19979 </p>
19980 <p>Since 3.1.0
19981 </p></dd></dl>
19982
19983 <a name="gnutls_005fmac_005fget-1"></a>
19984 <h4 class="subheading">gnutls_mac_get</h4>
19985 <a name="gnutls_005fmac_005fget"></a><dl>
19986 <dt><a name="index-gnutls_005fmac_005fget"></a>Function: <em>gnutls_mac_algorithm_t</em> <strong>gnutls_mac_get</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
19987 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
19988 </p>
19989 <p>Get currently used MAC algorithm.
19990 </p>
19991 <p><strong>Returns:</strong> the currently used mac algorithm, a
19992 <code>gnutls_mac_algorithm_t</code>  value.
19993 </p></dd></dl>
19994
19995 <a name="gnutls_005fmac_005fget_005fid-1"></a>
19996 <h4 class="subheading">gnutls_mac_get_id</h4>
19997 <a name="gnutls_005fmac_005fget_005fid"></a><dl>
19998 <dt><a name="index-gnutls_005fmac_005fget_005fid"></a>Function: <em>gnutls_mac_algorithm_t</em> <strong>gnutls_mac_get_id</strong> <em>(const char * <var>name</var>)</em></dt>
19999 <dd><p><var>name</var>: is a MAC algorithm name
20000 </p>
20001 <p>Convert a string to a <code>gnutls_mac_algorithm_t</code>  value.  The names are
20002 compared in a case insensitive way.
20003 </p>
20004 <p><strong>Returns:</strong> a <code>gnutls_mac_algorithm_t</code>  id of the specified MAC
20005 algorithm string, or <code>GNUTLS_MAC_UNKNOWN</code>  on failures.
20006 </p></dd></dl>
20007
20008 <a name="gnutls_005fmac_005fget_005fkey_005fsize-1"></a>
20009 <h4 class="subheading">gnutls_mac_get_key_size</h4>
20010 <a name="gnutls_005fmac_005fget_005fkey_005fsize"></a><dl>
20011 <dt><a name="index-gnutls_005fmac_005fget_005fkey_005fsize"></a>Function: <em>size_t</em> <strong>gnutls_mac_get_key_size</strong> <em>(gnutls_mac_algorithm_t <var>algorithm</var>)</em></dt>
20012 <dd><p><var>algorithm</var>: is an encryption algorithm
20013 </p>
20014 <p>Returns the size of the MAC key used in TLS.
20015 </p>
20016 <p><strong>Returns:</strong> length (in bytes) of the given MAC key size, or 0 if the
20017 given MAC algorithm is invalid.
20018 </p></dd></dl>
20019
20020 <a name="gnutls_005fmac_005fget_005fname-1"></a>
20021 <h4 class="subheading">gnutls_mac_get_name</h4>
20022 <a name="gnutls_005fmac_005fget_005fname"></a><dl>
20023 <dt><a name="index-gnutls_005fmac_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_mac_get_name</strong> <em>(gnutls_mac_algorithm_t <var>algorithm</var>)</em></dt>
20024 <dd><p><var>algorithm</var>: is a MAC algorithm
20025 </p>
20026 <p>Convert a <code>gnutls_mac_algorithm_t</code>  value to a string.
20027 </p>
20028 <p><strong>Returns:</strong> a string that contains the name of the specified MAC
20029 algorithm, or <code>NULL</code> .
20030 </p></dd></dl>
20031
20032 <a name="gnutls_005fmac_005flist-1"></a>
20033 <h4 class="subheading">gnutls_mac_list</h4>
20034 <a name="gnutls_005fmac_005flist"></a><dl>
20035 <dt><a name="index-gnutls_005fmac_005flist"></a>Function: <em>const gnutls_mac_algorithm_t *</em> <strong>gnutls_mac_list</strong> <em>( <var>void</var>)</em></dt>
20036 <dd>
20037 <p>Get a list of hash algorithms for use as MACs.  Note that not
20038 necessarily all MACs are supported in TLS cipher suites.
20039 This function is not thread safe.
20040 </p>
20041 <p><strong>Returns:</strong> Return a (0)-terminated list of <code>gnutls_mac_algorithm_t</code>
20042 integers indicating the available MACs.
20043 </p></dd></dl>
20044
20045 <a name="gnutls_005focsp_005fstatus_005frequest_005fenable_005fclient-1"></a>
20046 <h4 class="subheading">gnutls_ocsp_status_request_enable_client</h4>
20047 <a name="gnutls_005focsp_005fstatus_005frequest_005fenable_005fclient"></a><dl>
20048 <dt><a name="index-gnutls_005focsp_005fstatus_005frequest_005fenable_005fclient"></a>Function: <em>int</em> <strong>gnutls_ocsp_status_request_enable_client</strong> <em>(gnutls_session_t <var>session</var>, gnutls_datum_t * <var>responder_id</var>, size_t <var>responder_id_size</var>, gnutls_datum_t * <var>extensions</var>)</em></dt>
20049 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
20050 </p>
20051 <p><var>responder_id</var>: array with <code>gnutls_datum_t</code>  with DER data of responder id
20052 </p>
20053 <p><var>responder_id_size</var>: number of members in  <code>responder_id</code> array
20054 </p>
20055 <p><var>extensions</var>: a <code>gnutls_datum_t</code>  with DER encoded OCSP extensions
20056 </p>
20057 <p>This function is to be used by clients to request OCSP response
20058 from the server, using the &quot;status_request&quot; TLS extension.  Only
20059 OCSP status type is supported. A typical server has a single
20060 OCSP response cached, so  <code>responder_id</code> and  <code>extensions</code> should be null.
20061 </p>
20062 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
20063 otherwise a negative error code is returned.
20064 </p>
20065 <p><strong>Since:</strong> 3.1.3
20066 </p></dd></dl>
20067
20068 <a name="gnutls_005focsp_005fstatus_005frequest_005fget-1"></a>
20069 <h4 class="subheading">gnutls_ocsp_status_request_get</h4>
20070 <a name="gnutls_005focsp_005fstatus_005frequest_005fget"></a><dl>
20071 <dt><a name="index-gnutls_005focsp_005fstatus_005frequest_005fget"></a>Function: <em>int</em> <strong>gnutls_ocsp_status_request_get</strong> <em>(gnutls_session_t <var>session</var>, gnutls_datum_t * <var>response</var>)</em></dt>
20072 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
20073 </p>
20074 <p><var>response</var>: a <code>gnutls_datum_t</code>  with DER encoded OCSP response
20075 </p>
20076 <p>This function returns the OCSP status response received
20077 from the TLS server. The  <code>response</code> should be treated as
20078 constant. If no OCSP response is available then
20079 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is returned.
20080 </p>
20081 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
20082 otherwise a negative error code is returned.
20083 </p>
20084 <p><strong>Since:</strong> 3.1.3
20085 </p></dd></dl>
20086
20087 <a name="gnutls_005focsp_005fstatus_005frequest_005fis_005fchecked-1"></a>
20088 <h4 class="subheading">gnutls_ocsp_status_request_is_checked</h4>
20089 <a name="gnutls_005focsp_005fstatus_005frequest_005fis_005fchecked"></a><dl>
20090 <dt><a name="index-gnutls_005focsp_005fstatus_005frequest_005fis_005fchecked"></a>Function: <em>int</em> <strong>gnutls_ocsp_status_request_is_checked</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>flags</var>)</em></dt>
20091 <dd><p><var>session</var>: is a gnutls session
20092 </p>
20093 <p><var>flags</var>: should be zero
20094 </p>
20095 <p>Check whether an OCSP status response was included in the handshake
20096 and whether it was checked and valid (not too old or superseded).
20097 This is a helper function when needing to decide whether to perform an
20098 OCSP validity check on the peer&rsquo;s certificate. Must be called after
20099 <code>gnutls_certificate_verify_peers3()</code>  is called.
20100 </p>
20101 <p><strong>Returns:</strong> non zero it was valid, or a zero if it wasn&rsquo;t sent,
20102 or sent and was invalid.
20103 </p></dd></dl>
20104
20105 <a name="gnutls_005fopenpgp_005fsend_005fcert-1"></a>
20106 <h4 class="subheading">gnutls_openpgp_send_cert</h4>
20107 <a name="gnutls_005fopenpgp_005fsend_005fcert"></a><dl>
20108 <dt><a name="index-gnutls_005fopenpgp_005fsend_005fcert"></a>Function: <em>void</em> <strong>gnutls_openpgp_send_cert</strong> <em>(gnutls_session_t <var>session</var>, gnutls_openpgp_crt_status_t <var>status</var>)</em></dt>
20109 <dd><p><var>session</var>: is a pointer to a <code>gnutls_session_t</code>  structure.
20110 </p>
20111 <p><var>status</var>: is one of GNUTLS_OPENPGP_CERT, or GNUTLS_OPENPGP_CERT_FINGERPRINT
20112 </p>
20113 <p>This function will order gnutls to send the key fingerprint
20114 instead of the key in the initial handshake procedure. This should
20115 be used with care and only when there is indication or knowledge
20116 that the server can obtain the client&rsquo;s key.
20117 </p></dd></dl>
20118
20119 <a name="gnutls_005fpacket_005fdeinit-1"></a>
20120 <h4 class="subheading">gnutls_packet_deinit</h4>
20121 <a name="gnutls_005fpacket_005fdeinit"></a><dl>
20122 <dt><a name="index-gnutls_005fpacket_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_packet_deinit</strong> <em>(gnutls_packet_t <var>packet</var>)</em></dt>
20123 <dd><p><var>packet</var>: is a pointer to a <code>gnutls_packet_st</code>  structure.
20124 </p>
20125 <p>This function will deinitialize all data associated with
20126 the received packet.
20127 </p>
20128 <p><strong>Since:</strong> 3.3.5
20129 </p></dd></dl>
20130
20131 <a name="gnutls_005fpacket_005fget-1"></a>
20132 <h4 class="subheading">gnutls_packet_get</h4>
20133 <a name="gnutls_005fpacket_005fget"></a><dl>
20134 <dt><a name="index-gnutls_005fpacket_005fget"></a>Function: <em>void</em> <strong>gnutls_packet_get</strong> <em>(gnutls_packet_t <var>packet</var>, gnutls_datum_t * <var>data</var>, unsigned char * <var>sequence</var>)</em></dt>
20135 <dd><p><var>packet</var>: is a <code>gnutls_packet_t</code>  structure.
20136 </p>
20137 <p><var>data</var>: will contain the data present in the  <code>packet</code> structure (may be <code>NULL</code> )
20138 </p>
20139 <p><var>sequence</var>: the 8-bytes of the packet sequence number (may be <code>NULL</code> )
20140 </p>
20141 <p>This function returns the data and sequence number associated with
20142 the received packet.
20143 </p>
20144 <p><strong>Since:</strong> 3.3.5
20145 </p></dd></dl>
20146
20147 <a name="gnutls_005fpem_005fbase64_005fdecode-1"></a>
20148 <h4 class="subheading">gnutls_pem_base64_decode</h4>
20149 <a name="gnutls_005fpem_005fbase64_005fdecode"></a><dl>
20150 <dt><a name="index-gnutls_005fpem_005fbase64_005fdecode"></a>Function: <em>int</em> <strong>gnutls_pem_base64_decode</strong> <em>(const char * <var>header</var>, const gnutls_datum_t * <var>b64_data</var>, unsigned char * <var>result</var>, size_t * <var>result_size</var>)</em></dt>
20151 <dd><p><var>header</var>: A null terminated string with the PEM header (eg. CERTIFICATE)
20152 </p>
20153 <p><var>b64_data</var>: contain the encoded data
20154 </p>
20155 <p><var>result</var>: the place where decoded data will be copied
20156 </p>
20157 <p><var>result_size</var>: holds the size of the result
20158 </p>
20159 <p>This function will decode the given encoded data.  If the header
20160 given is non null this function will search for &quot;&mdash;&ndash;BEGIN header&quot;
20161 and decode only this part.  Otherwise it will decode the first PEM
20162 packet found.
20163 </p>
20164 <p><strong>Returns:</strong> On success <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
20165 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  is returned if the buffer given is
20166 not long enough, or 0 on success.
20167 </p></dd></dl>
20168
20169 <a name="gnutls_005fpem_005fbase64_005fdecode_005falloc-1"></a>
20170 <h4 class="subheading">gnutls_pem_base64_decode_alloc</h4>
20171 <a name="gnutls_005fpem_005fbase64_005fdecode_005falloc"></a><dl>
20172 <dt><a name="index-gnutls_005fpem_005fbase64_005fdecode_005falloc"></a>Function: <em>int</em> <strong>gnutls_pem_base64_decode_alloc</strong> <em>(const char * <var>header</var>, const gnutls_datum_t * <var>b64_data</var>, gnutls_datum_t * <var>result</var>)</em></dt>
20173 <dd><p><var>header</var>: The PEM header (eg. CERTIFICATE)
20174 </p>
20175 <p><var>b64_data</var>: contains the encoded data
20176 </p>
20177 <p><var>result</var>: the place where decoded data lie
20178 </p>
20179 <p>This function will decode the given encoded data. The decoded data
20180 will be allocated, and stored into result.  If the header given is
20181 non null this function will search for &quot;&mdash;&ndash;BEGIN header&quot; and
20182 decode only this part. Otherwise it will decode the first PEM
20183 packet found.
20184 </p>
20185 <p>You should use <code>gnutls_free()</code>  to free the returned data.
20186 </p>
20187 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
20188 an error code is returned.
20189 </p></dd></dl>
20190
20191 <a name="gnutls_005fpem_005fbase64_005fencode-1"></a>
20192 <h4 class="subheading">gnutls_pem_base64_encode</h4>
20193 <a name="gnutls_005fpem_005fbase64_005fencode"></a><dl>
20194 <dt><a name="index-gnutls_005fpem_005fbase64_005fencode"></a>Function: <em>int</em> <strong>gnutls_pem_base64_encode</strong> <em>(const char * <var>msg</var>, const gnutls_datum_t * <var>data</var>, char * <var>result</var>, size_t * <var>result_size</var>)</em></dt>
20195 <dd><p><var>msg</var>: is a message to be put in the header
20196 </p>
20197 <p><var>data</var>: contain the raw data
20198 </p>
20199 <p><var>result</var>: the place where base64 data will be copied
20200 </p>
20201 <p><var>result_size</var>: holds the size of the result
20202 </p>
20203 <p>This function will convert the given data to printable data, using
20204 the base64 encoding. This is the encoding used in PEM messages.
20205 </p>
20206 <p>The output string will be null terminated, although the size will
20207 not include the terminating null.
20208 </p>
20209 <p><strong>Returns:</strong> On success <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
20210 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  is returned if the buffer given is
20211 not long enough, or 0 on success.
20212 </p></dd></dl>
20213
20214 <a name="gnutls_005fpem_005fbase64_005fencode_005falloc-1"></a>
20215 <h4 class="subheading">gnutls_pem_base64_encode_alloc</h4>
20216 <a name="gnutls_005fpem_005fbase64_005fencode_005falloc"></a><dl>
20217 <dt><a name="index-gnutls_005fpem_005fbase64_005fencode_005falloc"></a>Function: <em>int</em> <strong>gnutls_pem_base64_encode_alloc</strong> <em>(const char * <var>msg</var>, const gnutls_datum_t * <var>data</var>, gnutls_datum_t * <var>result</var>)</em></dt>
20218 <dd><p><var>msg</var>: is a message to be put in the encoded header
20219 </p>
20220 <p><var>data</var>: contains the raw data
20221 </p>
20222 <p><var>result</var>: will hold the newly allocated encoded data
20223 </p>
20224 <p>This function will convert the given data to printable data, using
20225 the base64 encoding.  This is the encoding used in PEM messages.
20226 This function will allocate the required memory to hold the encoded
20227 data.
20228 </p>
20229 <p>You should use <code>gnutls_free()</code>  to free the returned data.
20230 </p>
20231 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
20232 an error code is returned.
20233 </p></dd></dl>
20234
20235 <a name="gnutls_005fperror-1"></a>
20236 <h4 class="subheading">gnutls_perror</h4>
20237 <a name="gnutls_005fperror"></a><dl>
20238 <dt><a name="index-gnutls_005fperror"></a>Function: <em>void</em> <strong>gnutls_perror</strong> <em>(int <var>error</var>)</em></dt>
20239 <dd><p><var>error</var>: is a GnuTLS error code, a negative error code
20240 </p>
20241 <p>This function is like <code>perror()</code> . The only difference is that it
20242 accepts an error number returned by a gnutls function.
20243 </p></dd></dl>
20244
20245 <a name="gnutls_005fpk_005falgorithm_005fget_005fname-1"></a>
20246 <h4 class="subheading">gnutls_pk_algorithm_get_name</h4>
20247 <a name="gnutls_005fpk_005falgorithm_005fget_005fname"></a><dl>
20248 <dt><a name="index-gnutls_005fpk_005falgorithm_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_pk_algorithm_get_name</strong> <em>(gnutls_pk_algorithm_t <var>algorithm</var>)</em></dt>
20249 <dd><p><var>algorithm</var>: is a pk algorithm
20250 </p>
20251 <p>Convert a <code>gnutls_pk_algorithm_t</code>  value to a string.
20252 </p>
20253 <p><strong>Returns:</strong> a string that contains the name of the specified public
20254 key algorithm, or <code>NULL</code> .
20255 </p></dd></dl>
20256
20257 <a name="gnutls_005fpk_005fbits_005fto_005fsec_005fparam-1"></a>
20258 <h4 class="subheading">gnutls_pk_bits_to_sec_param</h4>
20259 <a name="gnutls_005fpk_005fbits_005fto_005fsec_005fparam"></a><dl>
20260 <dt><a name="index-gnutls_005fpk_005fbits_005fto_005fsec_005fparam-1"></a>Function: <em>gnutls_sec_param_t</em> <strong>gnutls_pk_bits_to_sec_param</strong> <em>(gnutls_pk_algorithm_t <var>algo</var>, unsigned int <var>bits</var>)</em></dt>
20261 <dd><p><var>algo</var>: is a public key algorithm
20262 </p>
20263 <p><var>bits</var>: is the number of bits
20264 </p>
20265 <p>This is the inverse of <code>gnutls_sec_param_to_pk_bits()</code> . Given an algorithm
20266 and the number of bits, it will return the security parameter. This is
20267 a rough indication.
20268 </p>
20269 <p><strong>Returns:</strong> The security parameter.
20270 </p>
20271 <p><strong>Since:</strong> 2.12.0
20272 </p></dd></dl>
20273
20274 <a name="gnutls_005fpk_005fget_005fid-1"></a>
20275 <h4 class="subheading">gnutls_pk_get_id</h4>
20276 <a name="gnutls_005fpk_005fget_005fid"></a><dl>
20277 <dt><a name="index-gnutls_005fpk_005fget_005fid"></a>Function: <em>gnutls_pk_algorithm_t</em> <strong>gnutls_pk_get_id</strong> <em>(const char * <var>name</var>)</em></dt>
20278 <dd><p><var>name</var>: is a string containing a public key algorithm name.
20279 </p>
20280 <p>Convert a string to a <code>gnutls_pk_algorithm_t</code>  value.  The names are
20281 compared in a case insensitive way.  For example,
20282 gnutls_pk_get_id(&quot;RSA&quot;) will return <code>GNUTLS_PK_RSA</code> .
20283 </p>
20284 <p><strong>Returns:</strong> a <code>gnutls_pk_algorithm_t</code>  id of the specified public key
20285 algorithm string, or <code>GNUTLS_PK_UNKNOWN</code>  on failures.
20286 </p>
20287 <p><strong>Since:</strong> 2.6.0
20288 </p></dd></dl>
20289
20290 <a name="gnutls_005fpk_005fget_005fname-1"></a>
20291 <h4 class="subheading">gnutls_pk_get_name</h4>
20292 <a name="gnutls_005fpk_005fget_005fname"></a><dl>
20293 <dt><a name="index-gnutls_005fpk_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_pk_get_name</strong> <em>(gnutls_pk_algorithm_t <var>algorithm</var>)</em></dt>
20294 <dd><p><var>algorithm</var>: is a public key algorithm
20295 </p>
20296 <p>Convert a <code>gnutls_pk_algorithm_t</code>  value to a string.
20297 </p>
20298 <p><strong>Returns:</strong> a pointer to a string that contains the name of the
20299 specified public key algorithm, or <code>NULL</code> .
20300 </p>
20301 <p><strong>Since:</strong> 2.6.0
20302 </p></dd></dl>
20303
20304 <a name="gnutls_005fpk_005flist-1"></a>
20305 <h4 class="subheading">gnutls_pk_list</h4>
20306 <a name="gnutls_005fpk_005flist"></a><dl>
20307 <dt><a name="index-gnutls_005fpk_005flist"></a>Function: <em>const gnutls_pk_algorithm_t *</em> <strong>gnutls_pk_list</strong> <em>( <var>void</var>)</em></dt>
20308 <dd>
20309 <p>Get a list of supported public key algorithms.
20310 </p>
20311 <p>This function is not thread safe.
20312 </p>
20313 <p><strong>Returns:</strong> a (0)-terminated list of <code>gnutls_pk_algorithm_t</code>  integers
20314 indicating the available ciphers.
20315 </p>
20316 <p><strong>Since:</strong> 2.6.0
20317 </p></dd></dl>
20318
20319 <a name="gnutls_005fpk_005fto_005fsign-1"></a>
20320 <h4 class="subheading">gnutls_pk_to_sign</h4>
20321 <a name="gnutls_005fpk_005fto_005fsign"></a><dl>
20322 <dt><a name="index-gnutls_005fpk_005fto_005fsign"></a>Function: <em>gnutls_sign_algorithm_t</em> <strong>gnutls_pk_to_sign</strong> <em>(gnutls_pk_algorithm_t <var>pk</var>, gnutls_digest_algorithm_t <var>hash</var>)</em></dt>
20323 <dd><p><var>pk</var>: is a public key algorithm
20324 </p>
20325 <p><var>hash</var>: a hash algorithm
20326 </p>
20327 <p>This function maps public key and hash algorithms combinations
20328 to signature algorithms.
20329 </p>
20330 <p><strong>Returns:</strong> return a <code>gnutls_sign_algorithm_t</code>  value, or <code>GNUTLS_SIGN_UNKNOWN</code>  on error.
20331 </p></dd></dl>
20332
20333 <a name="gnutls_005fprf-1"></a>
20334 <h4 class="subheading">gnutls_prf</h4>
20335 <a name="gnutls_005fprf"></a><dl>
20336 <dt><a name="index-gnutls_005fprf"></a>Function: <em>int</em> <strong>gnutls_prf</strong> <em>(gnutls_session_t <var>session</var>, size_t <var>label_size</var>, const char * <var>label</var>, int <var>server_random_first</var>, size_t <var>extra_size</var>, const char * <var>extra</var>, size_t <var>outsize</var>, char * <var>out</var>)</em></dt>
20337 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
20338 </p>
20339 <p><var>label_size</var>: length of the  <code>label</code> variable.
20340 </p>
20341 <p><var>label</var>: label used in PRF computation, typically a short string.
20342 </p>
20343 <p><var>server_random_first</var>: non-zero if server random field should be first in seed
20344 </p>
20345 <p><var>extra_size</var>: length of the  <code>extra</code> variable.
20346 </p>
20347 <p><var>extra</var>: optional extra data to seed the PRF with.
20348 </p>
20349 <p><var>outsize</var>: size of pre-allocated output buffer to hold the output.
20350 </p>
20351 <p><var>out</var>: pre-allocated buffer to hold the generated data.
20352 </p>
20353 <p>Applies the TLS Pseudo-Random-Function (PRF) on the master secret
20354 and the provided data, seeded with the client and server random fields.
20355 </p>
20356 <p>The output of this function is identical to RFC5705 extractor if  <code>extra</code> and  <code>extra_size</code> are set to zero. Otherwise,  <code>extra</code> should contain the context
20357 value prefixed by a two-byte length.
20358 </p>
20359 <p>The  <code>label</code> variable usually contains a string denoting the purpose
20360 for the generated data.  The  <code>server_random_first</code> indicates whether
20361 the client random field or the server random field should be first
20362 in the seed.  Non-zero indicates that the server random field is first,
20363 0 that the client random field is first.
20364 </p>
20365 <p>The  <code>extra</code> variable can be used to add more data to the seed, after
20366 the random variables.  It can be used to make sure the
20367 generated output is strongly connected to some additional data
20368 (e.g., a string used in user authentication).
20369 </p>
20370 <p>The output is placed in  <code>out</code> , which must be pre-allocated.
20371 </p>
20372 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
20373 </p></dd></dl>
20374
20375 <a name="gnutls_005fprf_005fraw-1"></a>
20376 <h4 class="subheading">gnutls_prf_raw</h4>
20377 <a name="gnutls_005fprf_005fraw"></a><dl>
20378 <dt><a name="index-gnutls_005fprf_005fraw"></a>Function: <em>int</em> <strong>gnutls_prf_raw</strong> <em>(gnutls_session_t <var>session</var>, size_t <var>label_size</var>, const char * <var>label</var>, size_t <var>seed_size</var>, const char * <var>seed</var>, size_t <var>outsize</var>, char * <var>out</var>)</em></dt>
20379 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
20380 </p>
20381 <p><var>label_size</var>: length of the  <code>label</code> variable.
20382 </p>
20383 <p><var>label</var>: label used in PRF computation, typically a short string.
20384 </p>
20385 <p><var>seed_size</var>: length of the  <code>seed</code> variable.
20386 </p>
20387 <p><var>seed</var>: optional extra data to seed the PRF with.
20388 </p>
20389 <p><var>outsize</var>: size of pre-allocated output buffer to hold the output.
20390 </p>
20391 <p><var>out</var>: pre-allocated buffer to hold the generated data.
20392 </p>
20393 <p>Apply the TLS Pseudo-Random-Function (PRF) on the master secret
20394 and the provided data.
20395 </p>
20396 <p>The  <code>label</code> variable usually contains a string denoting the purpose
20397 for the generated data.  The  <code>seed</code> usually contains data such as the
20398 client and server random, perhaps together with some additional
20399 data that is added to guarantee uniqueness of the output for a
20400 particular purpose.
20401 </p>
20402 <p>Because the output is not guaranteed to be unique for a particular
20403 session unless  <code>seed</code> includes the client random and server random
20404 fields (the PRF would output the same data on another connection
20405 resumed from the first one), it is not recommended to use this
20406 function directly.  The <code>gnutls_prf()</code>  function seeds the PRF with the
20407 client and server random fields directly, and is recommended if you
20408 want to generate pseudo random data unique for each session.
20409 </p>
20410 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
20411 </p></dd></dl>
20412
20413 <a name="gnutls_005fpriority_005fcertificate_005ftype_005flist-1"></a>
20414 <h4 class="subheading">gnutls_priority_certificate_type_list</h4>
20415 <a name="gnutls_005fpriority_005fcertificate_005ftype_005flist"></a><dl>
20416 <dt><a name="index-gnutls_005fpriority_005fcertificate_005ftype_005flist"></a>Function: <em>int</em> <strong>gnutls_priority_certificate_type_list</strong> <em>(gnutls_priority_t <var>pcache</var>, const unsigned int ** <var>list</var>)</em></dt>
20417 <dd><p><var>pcache</var>: is a <code>gnutls_prioritity_t</code>  structure.
20418 </p>
20419 <p><var>list</var>: will point to an integer list
20420 </p>
20421 <p>Get a list of available certificate types in the priority
20422 structure.
20423 </p>
20424 <p><strong>Returns:</strong> the number of certificate types, or an error code.
20425 </p>
20426 <p><strong>Since:</strong> 3.0
20427 </p></dd></dl>
20428
20429 <a name="gnutls_005fpriority_005fcipher_005flist-1"></a>
20430 <h4 class="subheading">gnutls_priority_cipher_list</h4>
20431 <a name="gnutls_005fpriority_005fcipher_005flist"></a><dl>
20432 <dt><a name="index-gnutls_005fpriority_005fcipher_005flist"></a>Function: <em>int</em> <strong>gnutls_priority_cipher_list</strong> <em>(gnutls_priority_t <var>pcache</var>, const unsigned int ** <var>list</var>)</em></dt>
20433 <dd><p><var>pcache</var>: is a <code>gnutls_prioritity_t</code>  structure.
20434 </p>
20435 <p><var>list</var>: will point to an integer list
20436 </p>
20437 <p>Get a list of available ciphers in the priority
20438 structure.
20439 </p>
20440 <p><strong>Returns:</strong> the number of curves, or an error code.
20441 </p>
20442 <p><strong>Since:</strong> 3.2.3
20443 </p></dd></dl>
20444
20445 <a name="gnutls_005fpriority_005fcompression_005flist-1"></a>
20446 <h4 class="subheading">gnutls_priority_compression_list</h4>
20447 <a name="gnutls_005fpriority_005fcompression_005flist"></a><dl>
20448 <dt><a name="index-gnutls_005fpriority_005fcompression_005flist"></a>Function: <em>int</em> <strong>gnutls_priority_compression_list</strong> <em>(gnutls_priority_t <var>pcache</var>, const unsigned int ** <var>list</var>)</em></dt>
20449 <dd><p><var>pcache</var>: is a <code>gnutls_prioritity_t</code>  structure.
20450 </p>
20451 <p><var>list</var>: will point to an integer list
20452 </p>
20453 <p>Get a list of available compression method in the priority
20454 structure.
20455 </p>
20456 <p><strong>Returns:</strong> the number of methods, or an error code.
20457 </p>
20458 <p><strong>Since:</strong> 3.0
20459 </p></dd></dl>
20460
20461 <a name="gnutls_005fpriority_005fdeinit-1"></a>
20462 <h4 class="subheading">gnutls_priority_deinit</h4>
20463 <a name="gnutls_005fpriority_005fdeinit"></a><dl>
20464 <dt><a name="index-gnutls_005fpriority_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_priority_deinit</strong> <em>(gnutls_priority_t <var>priority_cache</var>)</em></dt>
20465 <dd><p><var>priority_cache</var>: is a <code>gnutls_prioritity_t</code>  structure.
20466 </p>
20467 <p>Deinitializes the priority cache.
20468 </p></dd></dl>
20469
20470 <a name="gnutls_005fpriority_005fecc_005fcurve_005flist-1"></a>
20471 <h4 class="subheading">gnutls_priority_ecc_curve_list</h4>
20472 <a name="gnutls_005fpriority_005fecc_005fcurve_005flist"></a><dl>
20473 <dt><a name="index-gnutls_005fpriority_005fecc_005fcurve_005flist"></a>Function: <em>int</em> <strong>gnutls_priority_ecc_curve_list</strong> <em>(gnutls_priority_t <var>pcache</var>, const unsigned int ** <var>list</var>)</em></dt>
20474 <dd><p><var>pcache</var>: is a <code>gnutls_prioritity_t</code>  structure.
20475 </p>
20476 <p><var>list</var>: will point to an integer list
20477 </p>
20478 <p>Get a list of available elliptic curves in the priority
20479 structure.
20480 </p>
20481 <p><strong>Returns:</strong> the number of curves, or an error code.
20482 </p>
20483 <p><strong>Since:</strong> 3.0
20484 </p></dd></dl>
20485
20486 <a name="gnutls_005fpriority_005fget_005fcipher_005fsuite_005findex-1"></a>
20487 <h4 class="subheading">gnutls_priority_get_cipher_suite_index</h4>
20488 <a name="gnutls_005fpriority_005fget_005fcipher_005fsuite_005findex"></a><dl>
20489 <dt><a name="index-gnutls_005fpriority_005fget_005fcipher_005fsuite_005findex"></a>Function: <em>int</em> <strong>gnutls_priority_get_cipher_suite_index</strong> <em>(gnutls_priority_t <var>pcache</var>, unsigned int <var>idx</var>, unsigned int * <var>sidx</var>)</em></dt>
20490 <dd><p><var>pcache</var>: is a <code>gnutls_prioritity_t</code>  structure.
20491 </p>
20492 <p><var>idx</var>: is an index number.
20493 </p>
20494 <p><var>sidx</var>: internal index of cipher suite to get information about.
20495 </p>
20496 <p>Provides the internal ciphersuite index to be used with
20497 <code>gnutls_cipher_suite_info()</code> . The index  <code>idx</code> provided is an
20498 index kept at the priorities structure. It might be that a valid
20499 priorities index does not correspond to a ciphersuite and in
20500 that case <code>GNUTLS_E_UNKNOWN_CIPHER_SUITE</code>  will be returned.
20501 Once the last available index is crossed then
20502 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be returned.
20503 </p>
20504 <p><strong>Returns:</strong> On success it returns <code>GNUTLS_E_SUCCESS</code>  (0), or a negative error value otherwise.
20505 </p></dd></dl>
20506
20507 <a name="gnutls_005fpriority_005finit-1"></a>
20508 <h4 class="subheading">gnutls_priority_init</h4>
20509 <a name="gnutls_005fpriority_005finit"></a><dl>
20510 <dt><a name="index-gnutls_005fpriority_005finit"></a>Function: <em>int</em> <strong>gnutls_priority_init</strong> <em>(gnutls_priority_t * <var>priority_cache</var>, const char * <var>priorities</var>, const char ** <var>err_pos</var>)</em></dt>
20511 <dd><p><var>priority_cache</var>: is a <code>gnutls_prioritity_t</code>  structure.
20512 </p>
20513 <p><var>priorities</var>: is a string describing priorities (may be <code>NULL</code> )
20514 </p>
20515 <p><var>err_pos</var>: In case of an error this will have the position in the string the error occurred
20516 </p>
20517 <p>Sets priorities for the ciphers, key exchange methods, macs and
20518 compression methods.
20519 </p>
20520 <p>The <code>priorities</code>  option allows you to specify a colon
20521 separated list of the cipher priorities to enable.
20522 Some keywords are defined to provide quick access
20523 to common preferences.
20524 </p>
20525 <p>Unless there is a special need, use the &quot;NORMAL&quot; keyword to
20526 apply a reasonable security level, or &quot;NORMAL:<code>COMPAT</code> &quot; for compatibility.
20527 </p>
20528 <p>&quot;PERFORMANCE&quot; means all the &quot;secure&quot; ciphersuites are enabled,
20529 limited to 128 bit ciphers and sorted by terms of speed
20530 performance.
20531 </p>
20532 <p>&quot;LEGACY&quot; the NORMAL settings for GnuTLS 3.2.x or earlier. There is
20533 no verification profile set, and the allowed DH primes are considered
20534 weak today.
20535 </p>
20536 <p>&quot;NORMAL&quot; means all &quot;secure&quot; ciphersuites. The 256-bit ciphers are
20537 included as a fallback only.  The ciphers are sorted by security
20538 margin.
20539 </p>
20540 <p>&quot;PFS&quot; means all &quot;secure&quot; ciphersuites that support perfect forward secrecy.
20541 The 256-bit ciphers are included as a fallback only.
20542 The ciphers are sorted by security margin.
20543 </p>
20544 <p>&quot;SECURE128&quot; means all &quot;secure&quot; ciphersuites of security level 128-bit
20545 or more.
20546 </p>
20547 <p>&quot;SECURE192&quot; means all &quot;secure&quot; ciphersuites of security level 192-bit
20548 or more.
20549 </p>
20550 <p>&quot;SUITEB128&quot; means all the NSA SuiteB ciphersuites with security level
20551 of 128.
20552 </p>
20553 <p>&quot;SUITEB192&quot; means all the NSA SuiteB ciphersuites with security level
20554 of 192.
20555 </p>
20556 <p>&quot;EXPORT&quot; means all ciphersuites are enabled, including the
20557 low-security 40 bit ciphers.
20558 </p>
20559 <p>&quot;NONE&quot; means nothing is enabled.  This disables even protocols and
20560 compression methods.
20561 </p>
20562 <p>&quot; <code>KEYWORD</code> &quot; The system administrator imposed settings. The provided keywords
20563 will be expanded from a configuration-time provided file - default is:
20564 /etc/gnutls/default-priorities. Any keywords that follow it, will
20565 be appended to the expanded string. If there is no system string,
20566 then the function will fail. The system file should be formatted
20567 as &quot;KEYWORD=VALUE&quot;, e.g., &quot;SYSTEM=NORMAL:-ARCFOUR-128&quot;.
20568 </p>
20569 <p>Special keywords are &quot;!&quot;, &quot;-&quot; and &quot;+&quot;.
20570 &quot;!&quot; or &quot;-&quot; appended with an algorithm will remove this algorithm.
20571 &quot;+&quot; appended with an algorithm will add this algorithm.
20572 </p>
20573 <p>Check the GnuTLS manual section &quot;Priority strings&quot; for detailed
20574 information.
20575 </p>
20576 <p><strong>Examples:</strong>
20577 &quot;NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL&quot;
20578 </p>
20579 <p>&quot;NORMAL:-ARCFOUR-128&quot; means normal ciphers except for ARCFOUR-128.
20580 </p>
20581 <p>&quot;SECURE128:-VERS-SSL3.0:+COMP-DEFLATE&quot; means that only secure ciphers are
20582 enabled, SSL3.0 is disabled, and libz compression enabled.
20583 </p>
20584 <p>&quot;NONE:+VERS-TLS-ALL:+AES-128-CBC:+RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1&quot;,
20585 </p>
20586 <p>&quot;NONE:+VERS-TLS-ALL:+AES-128-CBC:+ECDHE-RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1:+CURVE-SECP256R1&quot;,
20587 </p>
20588 <p>&quot;SECURE256:+SECURE128&quot;,
20589 </p>
20590 <p>Note that &quot;NORMAL:<code>COMPAT</code> &quot; is the most compatible mode.
20591 </p>
20592 <p>A <code>NULL</code>   <code>priorities</code> string indicates the default priorities to be
20593 used (this is available since GnuTLS 3.3.0).
20594 </p>
20595 <p><strong>Returns:</strong> On syntax error <code>GNUTLS_E_INVALID_REQUEST</code>  is returned,
20596 <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
20597 </p></dd></dl>
20598
20599 <a name="gnutls_005fpriority_005fkx_005flist-1"></a>
20600 <h4 class="subheading">gnutls_priority_kx_list</h4>
20601 <a name="gnutls_005fpriority_005fkx_005flist"></a><dl>
20602 <dt><a name="index-gnutls_005fpriority_005fkx_005flist"></a>Function: <em>int</em> <strong>gnutls_priority_kx_list</strong> <em>(gnutls_priority_t <var>pcache</var>, const unsigned int ** <var>list</var>)</em></dt>
20603 <dd><p><var>pcache</var>: is a <code>gnutls_prioritity_t</code>  structure.
20604 </p>
20605 <p><var>list</var>: will point to an integer list
20606 </p>
20607 <p>Get a list of available key exchange methods in the priority
20608 structure.
20609 </p>
20610 <p><strong>Returns:</strong> the number of curves, or an error code.
20611 </p>
20612 <p><strong>Since:</strong> 3.2.3
20613 </p></dd></dl>
20614
20615 <a name="gnutls_005fpriority_005fmac_005flist-1"></a>
20616 <h4 class="subheading">gnutls_priority_mac_list</h4>
20617 <a name="gnutls_005fpriority_005fmac_005flist"></a><dl>
20618 <dt><a name="index-gnutls_005fpriority_005fmac_005flist"></a>Function: <em>int</em> <strong>gnutls_priority_mac_list</strong> <em>(gnutls_priority_t <var>pcache</var>, const unsigned int ** <var>list</var>)</em></dt>
20619 <dd><p><var>pcache</var>: is a <code>gnutls_prioritity_t</code>  structure.
20620 </p>
20621 <p><var>list</var>: will point to an integer list
20622 </p>
20623 <p>Get a list of available MAC algorithms in the priority
20624 structure.
20625 </p>
20626 <p><strong>Returns:</strong> the number of curves, or an error code.
20627 </p>
20628 <p><strong>Since:</strong> 3.2.3
20629 </p></dd></dl>
20630
20631 <a name="gnutls_005fpriority_005fprotocol_005flist-1"></a>
20632 <h4 class="subheading">gnutls_priority_protocol_list</h4>
20633 <a name="gnutls_005fpriority_005fprotocol_005flist"></a><dl>
20634 <dt><a name="index-gnutls_005fpriority_005fprotocol_005flist"></a>Function: <em>int</em> <strong>gnutls_priority_protocol_list</strong> <em>(gnutls_priority_t <var>pcache</var>, const unsigned int ** <var>list</var>)</em></dt>
20635 <dd><p><var>pcache</var>: is a <code>gnutls_prioritity_t</code>  structure.
20636 </p>
20637 <p><var>list</var>: will point to an integer list
20638 </p>
20639 <p>Get a list of available TLS version numbers in the priority
20640 structure.
20641 </p>
20642 <p><strong>Returns:</strong> the number of protocols, or an error code.
20643 </p>
20644 <p><strong>Since:</strong> 3.0
20645 </p></dd></dl>
20646
20647 <a name="gnutls_005fpriority_005fset-1"></a>
20648 <h4 class="subheading">gnutls_priority_set</h4>
20649 <a name="gnutls_005fpriority_005fset"></a><dl>
20650 <dt><a name="index-gnutls_005fpriority_005fset"></a>Function: <em>int</em> <strong>gnutls_priority_set</strong> <em>(gnutls_session_t <var>session</var>, gnutls_priority_t <var>priority</var>)</em></dt>
20651 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
20652 </p>
20653 <p><var>priority</var>: is a <code>gnutls_priority_t</code>  structure.
20654 </p>
20655 <p>Sets the priorities to use on the ciphers, key exchange methods,
20656 macs and compression methods.
20657 </p>
20658 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
20659 </p></dd></dl>
20660
20661 <a name="gnutls_005fpriority_005fset_005fdirect-1"></a>
20662 <h4 class="subheading">gnutls_priority_set_direct</h4>
20663 <a name="gnutls_005fpriority_005fset_005fdirect"></a><dl>
20664 <dt><a name="index-gnutls_005fpriority_005fset_005fdirect"></a>Function: <em>int</em> <strong>gnutls_priority_set_direct</strong> <em>(gnutls_session_t <var>session</var>, const char * <var>priorities</var>, const char ** <var>err_pos</var>)</em></dt>
20665 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
20666 </p>
20667 <p><var>priorities</var>: is a string describing priorities
20668 </p>
20669 <p><var>err_pos</var>: In case of an error this will have the position in the string the error occured
20670 </p>
20671 <p>Sets the priorities to use on the ciphers, key exchange methods,
20672 macs and compression methods.  This function avoids keeping a
20673 priority cache and is used to directly set string priorities to a
20674 TLS session.  For documentation check the <code>gnutls_priority_init()</code> .
20675 </p>
20676 <p>To simply use a reasonable default, consider using <code>gnutls_set_default_priority()</code> .
20677 </p>
20678 <p><strong>Returns:</strong> On syntax error <code>GNUTLS_E_INVALID_REQUEST</code>  is returned,
20679 <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
20680 </p></dd></dl>
20681
20682 <a name="gnutls_005fpriority_005fsign_005flist-1"></a>
20683 <h4 class="subheading">gnutls_priority_sign_list</h4>
20684 <a name="gnutls_005fpriority_005fsign_005flist"></a><dl>
20685 <dt><a name="index-gnutls_005fpriority_005fsign_005flist"></a>Function: <em>int</em> <strong>gnutls_priority_sign_list</strong> <em>(gnutls_priority_t <var>pcache</var>, const unsigned int ** <var>list</var>)</em></dt>
20686 <dd><p><var>pcache</var>: is a <code>gnutls_prioritity_t</code>  structure.
20687 </p>
20688 <p><var>list</var>: will point to an integer list
20689 </p>
20690 <p>Get a list of available signature algorithms in the priority
20691 structure.
20692 </p>
20693 <p><strong>Returns:</strong> the number of algorithms, or an error code.
20694 </p>
20695 <p><strong>Since:</strong> 3.0
20696 </p></dd></dl>
20697
20698 <a name="gnutls_005fprotocol_005fget_005fid-1"></a>
20699 <h4 class="subheading">gnutls_protocol_get_id</h4>
20700 <a name="gnutls_005fprotocol_005fget_005fid"></a><dl>
20701 <dt><a name="index-gnutls_005fprotocol_005fget_005fid"></a>Function: <em>gnutls_protocol_t</em> <strong>gnutls_protocol_get_id</strong> <em>(const char * <var>name</var>)</em></dt>
20702 <dd><p><var>name</var>: is a protocol name
20703 </p>
20704 <p>The names are compared in a case insensitive way.
20705 </p>
20706 <p><strong>Returns:</strong> an id of the specified protocol, or
20707 <code>GNUTLS_VERSION_UNKNOWN</code>  on error.
20708 </p></dd></dl>
20709
20710 <a name="gnutls_005fprotocol_005fget_005fname-1"></a>
20711 <h4 class="subheading">gnutls_protocol_get_name</h4>
20712 <a name="gnutls_005fprotocol_005fget_005fname"></a><dl>
20713 <dt><a name="index-gnutls_005fprotocol_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_protocol_get_name</strong> <em>(gnutls_protocol_t <var>version</var>)</em></dt>
20714 <dd><p><var>version</var>: is a (gnutls) version number
20715 </p>
20716 <p>Convert a <code>gnutls_protocol_t</code>  value to a string.
20717 </p>
20718 <p><strong>Returns:</strong> a string that contains the name of the specified TLS
20719 version (e.g., &quot;TLS1.0&quot;), or <code>NULL</code> .
20720 </p></dd></dl>
20721
20722 <a name="gnutls_005fprotocol_005fget_005fversion-1"></a>
20723 <h4 class="subheading">gnutls_protocol_get_version</h4>
20724 <a name="gnutls_005fprotocol_005fget_005fversion"></a><dl>
20725 <dt><a name="index-gnutls_005fprotocol_005fget_005fversion"></a>Function: <em>gnutls_protocol_t</em> <strong>gnutls_protocol_get_version</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
20726 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
20727 </p>
20728 <p>Get TLS version, a <code>gnutls_protocol_t</code>  value.
20729 </p>
20730 <p><strong>Returns:</strong> The version of the currently used protocol.
20731 </p></dd></dl>
20732
20733 <a name="gnutls_005fprotocol_005flist-1"></a>
20734 <h4 class="subheading">gnutls_protocol_list</h4>
20735 <a name="gnutls_005fprotocol_005flist"></a><dl>
20736 <dt><a name="index-gnutls_005fprotocol_005flist"></a>Function: <em>const gnutls_protocol_t *</em> <strong>gnutls_protocol_list</strong> <em>( <var>void</var>)</em></dt>
20737 <dd>
20738 <p>Get a list of supported protocols, e.g. SSL 3.0, TLS 1.0 etc.
20739 </p>
20740 <p>This function is not thread safe.
20741 </p>
20742 <p><strong>Returns:</strong> a (0)-terminated list of <code>gnutls_protocol_t</code>  integers
20743 indicating the available protocols.
20744 </p></dd></dl>
20745
20746 <a name="gnutls_005fpsk_005fallocate_005fclient_005fcredentials-1"></a>
20747 <h4 class="subheading">gnutls_psk_allocate_client_credentials</h4>
20748 <a name="gnutls_005fpsk_005fallocate_005fclient_005fcredentials"></a><dl>
20749 <dt><a name="index-gnutls_005fpsk_005fallocate_005fclient_005fcredentials"></a>Function: <em>int</em> <strong>gnutls_psk_allocate_client_credentials</strong> <em>(gnutls_psk_client_credentials_t *            <var>sc</var>)</em></dt>
20750 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_psk_server_credentials_t</code>  structure.
20751 </p>
20752 <p>This structure is complex enough to manipulate directly thus this
20753 helper function is provided in order to allocate it.
20754 </p>
20755 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
20756 an error code is returned.
20757 </p></dd></dl>
20758
20759 <a name="gnutls_005fpsk_005fallocate_005fserver_005fcredentials-1"></a>
20760 <h4 class="subheading">gnutls_psk_allocate_server_credentials</h4>
20761 <a name="gnutls_005fpsk_005fallocate_005fserver_005fcredentials"></a><dl>
20762 <dt><a name="index-gnutls_005fpsk_005fallocate_005fserver_005fcredentials"></a>Function: <em>int</em> <strong>gnutls_psk_allocate_server_credentials</strong> <em>(gnutls_psk_server_credentials_t *            <var>sc</var>)</em></dt>
20763 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_psk_server_credentials_t</code>  structure.
20764 </p>
20765 <p>This structure is complex enough to manipulate directly thus this
20766 helper function is provided in order to allocate it.
20767 </p>
20768 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
20769 an error code is returned.
20770 </p></dd></dl>
20771
20772 <a name="gnutls_005fpsk_005fclient_005fget_005fhint-1"></a>
20773 <h4 class="subheading">gnutls_psk_client_get_hint</h4>
20774 <a name="gnutls_005fpsk_005fclient_005fget_005fhint"></a><dl>
20775 <dt><a name="index-gnutls_005fpsk_005fclient_005fget_005fhint"></a>Function: <em>const char *</em> <strong>gnutls_psk_client_get_hint</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
20776 <dd><p><var>session</var>: is a gnutls session
20777 </p>
20778 <p>The PSK identity hint may give the client help in deciding which
20779 username to use.  This should only be called in case of PSK
20780 authentication and in case of a client.
20781 </p>
20782 <p><strong>Returns:</strong> the identity hint of the peer, or <code>NULL</code>  in case of an error.
20783 </p>
20784 <p><strong>Since:</strong> 2.4.0
20785 </p></dd></dl>
20786
20787 <a name="gnutls_005fpsk_005ffree_005fclient_005fcredentials-1"></a>
20788 <h4 class="subheading">gnutls_psk_free_client_credentials</h4>
20789 <a name="gnutls_005fpsk_005ffree_005fclient_005fcredentials"></a><dl>
20790 <dt><a name="index-gnutls_005fpsk_005ffree_005fclient_005fcredentials"></a>Function: <em>void</em> <strong>gnutls_psk_free_client_credentials</strong> <em>(gnutls_psk_client_credentials_t <var>sc</var>)</em></dt>
20791 <dd><p><var>sc</var>: is a <code>gnutls_psk_client_credentials_t</code>  structure.
20792 </p>
20793 <p>This structure is complex enough to manipulate directly thus this
20794 helper function is provided in order to free (deallocate) it.
20795 </p></dd></dl>
20796
20797 <a name="gnutls_005fpsk_005ffree_005fserver_005fcredentials-1"></a>
20798 <h4 class="subheading">gnutls_psk_free_server_credentials</h4>
20799 <a name="gnutls_005fpsk_005ffree_005fserver_005fcredentials"></a><dl>
20800 <dt><a name="index-gnutls_005fpsk_005ffree_005fserver_005fcredentials"></a>Function: <em>void</em> <strong>gnutls_psk_free_server_credentials</strong> <em>(gnutls_psk_server_credentials_t <var>sc</var>)</em></dt>
20801 <dd><p><var>sc</var>: is a <code>gnutls_psk_server_credentials_t</code>  structure.
20802 </p>
20803 <p>This structure is complex enough to manipulate directly thus this
20804 helper function is provided in order to free (deallocate) it.
20805 </p></dd></dl>
20806
20807 <a name="gnutls_005fpsk_005fserver_005fget_005fusername-1"></a>
20808 <h4 class="subheading">gnutls_psk_server_get_username</h4>
20809 <a name="gnutls_005fpsk_005fserver_005fget_005fusername"></a><dl>
20810 <dt><a name="index-gnutls_005fpsk_005fserver_005fget_005fusername"></a>Function: <em>const char *</em> <strong>gnutls_psk_server_get_username</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
20811 <dd><p><var>session</var>: is a gnutls session
20812 </p>
20813 <p>This should only be called in case of PSK authentication and in
20814 case of a server.
20815 </p>
20816 <p><strong>Returns:</strong> the username of the peer, or <code>NULL</code>  in case of an error.
20817 </p></dd></dl>
20818
20819 <a name="gnutls_005fpsk_005fset_005fclient_005fcredentials-1"></a>
20820 <h4 class="subheading">gnutls_psk_set_client_credentials</h4>
20821 <a name="gnutls_005fpsk_005fset_005fclient_005fcredentials"></a><dl>
20822 <dt><a name="index-gnutls_005fpsk_005fset_005fclient_005fcredentials"></a>Function: <em>int</em> <strong>gnutls_psk_set_client_credentials</strong> <em>(gnutls_psk_client_credentials_t <var>res</var>, const char * <var>username</var>, const gnutls_datum_t * <var>key</var>, gnutls_psk_key_flags <var>flags</var>)</em></dt>
20823 <dd><p><var>res</var>: is a <code>gnutls_psk_client_credentials_t</code>  structure.
20824 </p>
20825 <p><var>username</var>: is the user&rsquo;s zero-terminated userid
20826 </p>
20827 <p><var>key</var>: is the user&rsquo;s key
20828 </p>
20829 <p><var>flags</var>: indicate the format of the key, either
20830 <code>GNUTLS_PSK_KEY_RAW</code>  or <code>GNUTLS_PSK_KEY_HEX</code> .
20831 </p>
20832 <p>This function sets the username and password, in a
20833 gnutls_psk_client_credentials_t structure.  Those will be used in
20834 PSK authentication.   <code>username</code> should be an ASCII string or UTF-8
20835 strings prepared using the &quot;SASLprep&quot; profile of &quot;stringprep&quot;.  The
20836 key can be either in raw byte format or in Hex format (without the
20837 0x prefix).
20838 </p>
20839 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
20840 an error code is returned.
20841 </p></dd></dl>
20842
20843 <a name="gnutls_005fpsk_005fset_005fclient_005fcredentials_005ffunction-1"></a>
20844 <h4 class="subheading">gnutls_psk_set_client_credentials_function</h4>
20845 <a name="gnutls_005fpsk_005fset_005fclient_005fcredentials_005ffunction"></a><dl>
20846 <dt><a name="index-gnutls_005fpsk_005fset_005fclient_005fcredentials_005ffunction-1"></a>Function: <em>void</em> <strong>gnutls_psk_set_client_credentials_function</strong> <em>(gnutls_psk_client_credentials_t         <var>cred</var>, gnutls_psk_client_credentials_function         * <var>func</var>)</em></dt>
20847 <dd><p><var>cred</var>: is a <code>gnutls_psk_server_credentials_t</code>  structure.
20848 </p>
20849 <p><var>func</var>: is the callback function
20850 </p>
20851 <p>This function can be used to set a callback to retrieve the username and
20852 password for client PSK authentication.
20853 The callback&rsquo;s function form is:
20854 int (*callback)(gnutls_session_t, char** username,
20855 gnutls_datum_t* key);
20856 </p>
20857 <p>The  <code>username</code> and  <code>key</code> -&gt;data must be allocated using <code>gnutls_malloc()</code> .
20858  <code>username</code> should be ASCII strings or UTF-8 strings prepared using
20859 the &quot;SASLprep&quot; profile of &quot;stringprep&quot;.
20860 </p>
20861 <p>The callback function will be called once per handshake.
20862 </p>
20863 <p>The callback function should return 0 on success.
20864 -1 indicates an error.
20865 </p></dd></dl>
20866
20867 <a name="gnutls_005fpsk_005fset_005fparams_005ffunction-1"></a>
20868 <h4 class="subheading">gnutls_psk_set_params_function</h4>
20869 <a name="gnutls_005fpsk_005fset_005fparams_005ffunction"></a><dl>
20870 <dt><a name="index-gnutls_005fpsk_005fset_005fparams_005ffunction"></a>Function: <em>void</em> <strong>gnutls_psk_set_params_function</strong> <em>(gnutls_psk_server_credentials_t <var>res</var>, gnutls_params_function * <var>func</var>)</em></dt>
20871 <dd><p><var>res</var>: is a gnutls_psk_server_credentials_t structure
20872 </p>
20873 <p><var>func</var>: is the function to be called
20874 </p>
20875 <p>This function will set a callback in order for the server to get
20876 the Diffie-Hellman or RSA parameters for PSK authentication.  The
20877 callback should return <code>GNUTLS_E_SUCCESS</code>  (0) on success.
20878 </p></dd></dl>
20879
20880 <a name="gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffile-1"></a>
20881 <h4 class="subheading">gnutls_psk_set_server_credentials_file</h4>
20882 <a name="gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffile"></a><dl>
20883 <dt><a name="index-gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffile-1"></a>Function: <em>int</em> <strong>gnutls_psk_set_server_credentials_file</strong> <em>(gnutls_psk_server_credentials_t            <var>res</var>, const char * <var>password_file</var>)</em></dt>
20884 <dd><p><var>res</var>: is a <code>gnutls_psk_server_credentials_t</code>  structure.
20885 </p>
20886 <p><var>password_file</var>: is the PSK password file (passwd.psk)
20887 </p>
20888 <p>This function sets the password file, in a
20889 <code>gnutls_psk_server_credentials_t</code>  structure.  This password file
20890 holds usernames and keys and will be used for PSK authentication.
20891 </p>
20892 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
20893 an error code is returned.
20894 </p></dd></dl>
20895
20896 <a name="gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffunction-1"></a>
20897 <h4 class="subheading">gnutls_psk_set_server_credentials_function</h4>
20898 <a name="gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffunction"></a><dl>
20899 <dt><a name="index-gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffunction"></a>Function: <em>void</em> <strong>gnutls_psk_set_server_credentials_function</strong> <em>(gnutls_psk_server_credentials_t         <var>cred</var>, gnutls_psk_server_credentials_function         * <var>func</var>)</em></dt>
20900 <dd><p><var>cred</var>: is a <code>gnutls_psk_server_credentials_t</code>  structure.
20901 </p>
20902 <p><var>func</var>: is the callback function
20903 </p>
20904 <p>This function can be used to set a callback to retrieve the user&rsquo;s PSK credentials.
20905 The callback&rsquo;s function form is:
20906 int (*callback)(gnutls_session_t, const char* username,
20907 gnutls_datum_t* key);
20908 </p>
20909 <p><code>username</code> contains the actual username.
20910 The  <code>key</code> must be filled in using the <code>gnutls_malloc()</code> .
20911 </p>
20912 <p>In case the callback returned a negative number then gnutls will
20913 assume that the username does not exist.
20914 </p>
20915 <p>The callback function will only be called once per handshake.  The
20916 callback function should return 0 on success, while -1 indicates
20917 an error.
20918 </p></dd></dl>
20919
20920 <a name="gnutls_005fpsk_005fset_005fserver_005fcredentials_005fhint-1"></a>
20921 <h4 class="subheading">gnutls_psk_set_server_credentials_hint</h4>
20922 <a name="gnutls_005fpsk_005fset_005fserver_005fcredentials_005fhint"></a><dl>
20923 <dt><a name="index-gnutls_005fpsk_005fset_005fserver_005fcredentials_005fhint"></a>Function: <em>int</em> <strong>gnutls_psk_set_server_credentials_hint</strong> <em>(gnutls_psk_server_credentials_t <var>res</var>, const char * <var>hint</var>)</em></dt>
20924 <dd><p><var>res</var>: is a <code>gnutls_psk_server_credentials_t</code>  structure.
20925 </p>
20926 <p><var>hint</var>: is the PSK identity hint string
20927 </p>
20928 <p>This function sets the identity hint, in a
20929 <code>gnutls_psk_server_credentials_t</code>  structure.  This hint is sent to
20930 the client to help it chose a good PSK credential (i.e., username
20931 and password).
20932 </p>
20933 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
20934 an error code is returned.
20935 </p>
20936 <p><strong>Since:</strong> 2.4.0
20937 </p></dd></dl>
20938
20939 <a name="gnutls_005fpsk_005fset_005fserver_005fdh_005fparams-1"></a>
20940 <h4 class="subheading">gnutls_psk_set_server_dh_params</h4>
20941 <a name="gnutls_005fpsk_005fset_005fserver_005fdh_005fparams"></a><dl>
20942 <dt><a name="index-gnutls_005fpsk_005fset_005fserver_005fdh_005fparams"></a>Function: <em>void</em> <strong>gnutls_psk_set_server_dh_params</strong> <em>(gnutls_psk_server_credentials_t <var>res</var>, gnutls_dh_params_t <var>dh_params</var>)</em></dt>
20943 <dd><p><var>res</var>: is a gnutls_psk_server_credentials_t structure
20944 </p>
20945 <p><var>dh_params</var>: is a structure that holds Diffie-Hellman parameters.
20946 </p>
20947 <p>This function will set the Diffie-Hellman parameters for an
20948 anonymous server to use. These parameters will be used in
20949 Diffie-Hellman exchange with PSK cipher suites.
20950 </p></dd></dl>
20951
20952 <a name="gnutls_005fpsk_005fset_005fserver_005fparams_005ffunction-1"></a>
20953 <h4 class="subheading">gnutls_psk_set_server_params_function</h4>
20954 <a name="gnutls_005fpsk_005fset_005fserver_005fparams_005ffunction"></a><dl>
20955 <dt><a name="index-gnutls_005fpsk_005fset_005fserver_005fparams_005ffunction"></a>Function: <em>void</em> <strong>gnutls_psk_set_server_params_function</strong> <em>(gnutls_psk_server_credentials_t <var>res</var>, gnutls_params_function * <var>func</var>)</em></dt>
20956 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure
20957 </p>
20958 <p><var>func</var>: is the function to be called
20959 </p>
20960 <p>This function will set a callback in order for the server to get
20961 the Diffie-Hellman parameters for PSK authentication.  The callback
20962 should return <code>GNUTLS_E_SUCCESS</code>  (0) on success.
20963 </p></dd></dl>
20964
20965 <a name="gnutls_005frandom_005fart-1"></a>
20966 <h4 class="subheading">gnutls_random_art</h4>
20967 <a name="gnutls_005frandom_005fart"></a><dl>
20968 <dt><a name="index-gnutls_005frandom_005fart"></a>Function: <em>int</em> <strong>gnutls_random_art</strong> <em>(gnutls_random_art_t <var>type</var>, const char * <var>key_type</var>, unsigned int <var>key_size</var>, void * <var>fpr</var>, size_t <var>fpr_size</var>, gnutls_datum_t * <var>art</var>)</em></dt>
20969 <dd><p><var>type</var>: The type of the random art (for now only <code>GNUTLS_RANDOM_ART_OPENSSH</code>  is supported)
20970 </p>
20971 <p><var>key_type</var>: The type of the key (RSA, DSA etc.)
20972 </p>
20973 <p><var>key_size</var>: The size of the key in bits
20974 </p>
20975 <p><var>fpr</var>: The fingerprint of the key
20976 </p>
20977 <p><var>fpr_size</var>: The size of the fingerprint
20978 </p>
20979 <p><var>art</var>: The returned random art
20980 </p>
20981 <p>This function will convert a given fingerprint to an &quot;artistic&quot;
20982 image. The returned image is allocated using <code>gnutls_malloc()</code> .
20983 </p>
20984 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
20985 an error code is returned.
20986 </p></dd></dl>
20987
20988 <a name="gnutls_005frange_005fsplit-1"></a>
20989 <h4 class="subheading">gnutls_range_split</h4>
20990 <a name="gnutls_005frange_005fsplit"></a><dl>
20991 <dt><a name="index-gnutls_005frange_005fsplit"></a>Function: <em>int</em> <strong>gnutls_range_split</strong> <em>(gnutls_session_t <var>session</var>, const gnutls_range_st * <var>orig</var>, gnutls_range_st * <var>next</var>, gnutls_range_st * <var>remainder</var>)</em></dt>
20992 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure
20993 </p>
20994 <p><var>orig</var>: is the original range provided by the user
20995 </p>
20996 <p><var>next</var>: is the returned range that can be conveyed in a TLS record
20997 </p>
20998 <p><var>remainder</var>: is the returned remaining range
20999 </p>
21000 <p>This function should be used when it is required to hide the length
21001 of very long data that cannot be directly provided to <code>gnutls_record_send_range()</code> .
21002 In that case this function should be called with the desired length
21003 hiding range in  <code>orig</code> . The returned  <code>next</code> value should then be used in
21004 the next call to <code>gnutls_record_send_range()</code>  with the partial data.
21005 That process should be repeated until  <code>remainder</code> is (0,0).
21006 </p>
21007 <p><strong>Returns:</strong> 0 in case splitting succeeds, non zero in case of error.
21008 Note that  <code>orig</code> is not changed, while the values of  <code>next</code> and  <code>remainder</code> are modified to store the resulting values.
21009 </p></dd></dl>
21010
21011 <a name="gnutls_005frecord_005fcan_005fuse_005flength_005fhiding-1"></a>
21012 <h4 class="subheading">gnutls_record_can_use_length_hiding</h4>
21013 <a name="gnutls_005frecord_005fcan_005fuse_005flength_005fhiding"></a><dl>
21014 <dt><a name="index-gnutls_005frecord_005fcan_005fuse_005flength_005fhiding"></a>Function: <em>int</em> <strong>gnutls_record_can_use_length_hiding</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21015 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21016 </p>
21017 <p>If the session supports length-hiding padding, you can
21018 invoke <code>gnutls_range_send_message()</code>  to send a message whose
21019 length is hidden in the given range. If the session does not
21020 support length hiding padding, you can use the standard
21021 <code>gnutls_record_send()</code>  function, or <code>gnutls_range_send_message()</code>
21022 making sure that the range is the same as the length of the
21023 message you are trying to send.
21024 </p>
21025 <p><strong>Returns:</strong> true (1) if the current session supports length-hiding
21026 padding, false (0) if the current session does not.
21027 </p></dd></dl>
21028
21029 <a name="gnutls_005frecord_005fcheck_005fcorked-1"></a>
21030 <h4 class="subheading">gnutls_record_check_corked</h4>
21031 <a name="gnutls_005frecord_005fcheck_005fcorked"></a><dl>
21032 <dt><a name="index-gnutls_005frecord_005fcheck_005fcorked"></a>Function: <em>size_t</em> <strong>gnutls_record_check_corked</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21033 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21034 </p>
21035 <p>This function checks if there pending corked
21036 data in the gnutls buffers &ndash;see <code>gnutls_record_cork()</code> .
21037 </p>
21038 <p><strong>Returns:</strong> Returns the size of the corked data or zero.
21039 </p>
21040 <p><strong>Since:</strong> 3.2.8
21041 </p></dd></dl>
21042
21043 <a name="gnutls_005frecord_005fcheck_005fpending-1"></a>
21044 <h4 class="subheading">gnutls_record_check_pending</h4>
21045 <a name="gnutls_005frecord_005fcheck_005fpending"></a><dl>
21046 <dt><a name="index-gnutls_005frecord_005fcheck_005fpending-1"></a>Function: <em>size_t</em> <strong>gnutls_record_check_pending</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21047 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21048 </p>
21049 <p>This function checks if there are unread data
21050 in the gnutls buffers. If the return value is
21051 non-zero the next call to <code>gnutls_record_recv()</code>
21052 is guaranteed not to block.
21053 </p>
21054 <p><strong>Returns:</strong> Returns the size of the data or zero.
21055 </p></dd></dl>
21056
21057 <a name="gnutls_005frecord_005fcork-1"></a>
21058 <h4 class="subheading">gnutls_record_cork</h4>
21059 <a name="gnutls_005frecord_005fcork"></a><dl>
21060 <dt><a name="index-gnutls_005frecord_005fcork-1"></a>Function: <em>void</em> <strong>gnutls_record_cork</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21061 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21062 </p>
21063 <p>If called, <code>gnutls_record_send()</code>  will no longer send any records.
21064 Any sent records will be cached until <code>gnutls_record_uncork()</code>  is called.
21065 </p>
21066 <p>This function is safe to use with DTLS after GnuTLS 3.3.0.
21067 </p>
21068 <p><strong>Since:</strong> 3.1.9
21069 </p></dd></dl>
21070
21071 <a name="gnutls_005frecord_005fdisable_005fpadding-1"></a>
21072 <h4 class="subheading">gnutls_record_disable_padding</h4>
21073 <a name="gnutls_005frecord_005fdisable_005fpadding"></a><dl>
21074 <dt><a name="index-gnutls_005frecord_005fdisable_005fpadding"></a>Function: <em>void</em> <strong>gnutls_record_disable_padding</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21075 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21076 </p>
21077 <p>Used to disabled padding in TLS 1.0 and above.  Normally you do not
21078 need to use this function, but there are buggy clients that
21079 complain if a server pads the encrypted data.  This of course will
21080 disable protection against statistical attacks on the data.
21081 </p>
21082 <p>This functions is defunt since 3.1.7. Random padding is disabled
21083 by default unless requested using <code>gnutls_range_send_message()</code> .
21084 </p></dd></dl>
21085
21086 <a name="gnutls_005frecord_005fget_005fdirection-1"></a>
21087 <h4 class="subheading">gnutls_record_get_direction</h4>
21088 <a name="gnutls_005frecord_005fget_005fdirection"></a><dl>
21089 <dt><a name="index-gnutls_005frecord_005fget_005fdirection-1"></a>Function: <em>int</em> <strong>gnutls_record_get_direction</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21090 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21091 </p>
21092 <p>This function provides information about the internals of the
21093 record protocol and is only useful if a prior gnutls function call
21094 (e.g.  <code>gnutls_handshake()</code> ) was interrupted for some reason, that
21095 is, if a function returned <code>GNUTLS_E_INTERRUPTED</code>  or
21096 <code>GNUTLS_E_AGAIN</code> .  In such a case, you might want to call <code>select()</code>
21097 or <code>poll()</code>  before calling the interrupted gnutls function again.  To
21098 tell you whether a file descriptor should be selected for either
21099 reading or writing, <code>gnutls_record_get_direction()</code>  returns 0 if the
21100 interrupted function was trying to read data, and 1 if it was
21101 trying to write data.
21102 </p>
21103 <p>This function&rsquo;s output is unreliable if you are using the
21104  <code>session</code> in different threads, for sending and receiving.
21105 </p>
21106 <p><strong>Returns:</strong> 0 if trying to read data, 1 if trying to write data.
21107 </p></dd></dl>
21108
21109 <a name="gnutls_005frecord_005fget_005fmax_005fsize-1"></a>
21110 <h4 class="subheading">gnutls_record_get_max_size</h4>
21111 <a name="gnutls_005frecord_005fget_005fmax_005fsize"></a><dl>
21112 <dt><a name="index-gnutls_005frecord_005fget_005fmax_005fsize"></a>Function: <em>size_t</em> <strong>gnutls_record_get_max_size</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21113 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21114 </p>
21115 <p>Get the record size.  The maximum record size is negotiated by the
21116 client after the first handshake message.
21117 </p>
21118 <p><strong>Returns:</strong> The maximum record packet size in this connection.
21119 </p></dd></dl>
21120
21121 <a name="gnutls_005frecord_005foverhead_005fsize-1"></a>
21122 <h4 class="subheading">gnutls_record_overhead_size</h4>
21123 <a name="gnutls_005frecord_005foverhead_005fsize"></a><dl>
21124 <dt><a name="index-gnutls_005frecord_005foverhead_005fsize"></a>Function: <em>size_t</em> <strong>gnutls_record_overhead_size</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21125 <dd><p><var>session</var>: is <code>gnutls_session_t</code>
21126 </p>
21127 <p>This function will return the set size in bytes of the overhead
21128 due to TLS (or DTLS) per record.
21129 </p>
21130 <p><strong>Since:</strong> 3.2.2
21131 </p></dd></dl>
21132
21133 <a name="gnutls_005frecord_005frecv-1"></a>
21134 <h4 class="subheading">gnutls_record_recv</h4>
21135 <a name="gnutls_005frecord_005frecv"></a><dl>
21136 <dt><a name="index-gnutls_005frecord_005frecv-1"></a>Function: <em>ssize_t</em> <strong>gnutls_record_recv</strong> <em>(gnutls_session_t <var>session</var>, void * <var>data</var>, size_t <var>data_size</var>)</em></dt>
21137 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21138 </p>
21139 <p><var>data</var>: the buffer that the data will be read into
21140 </p>
21141 <p><var>data_size</var>: the number of requested bytes
21142 </p>
21143 <p>This function has the similar semantics with <code>recv()</code> .  The only
21144 difference is that it accepts a GnuTLS session, and uses different
21145 error codes.
21146 In the special case that a server requests a renegotiation, the
21147 client may receive an error code of <code>GNUTLS_E_REHANDSHAKE</code> .  This
21148 message may be simply ignored, replied with an alert
21149 <code>GNUTLS_A_NO_RENEGOTIATION</code> , or replied with a new handshake,
21150 depending on the client&rsquo;s will.
21151 If <code>EINTR</code>  is returned by the internal push function (the default
21152 is <code>recv()</code> ) then <code>GNUTLS_E_INTERRUPTED</code>  will be returned.  If
21153 <code>GNUTLS_E_INTERRUPTED</code>  or <code>GNUTLS_E_AGAIN</code>  is returned, you must
21154 call this function again to get the data.  See also
21155 <code>gnutls_record_get_direction()</code> .
21156 A server may also receive <code>GNUTLS_E_REHANDSHAKE</code>  when a client has
21157 initiated a handshake. In that case the server can only initiate a
21158 handshake or terminate the connection.
21159 </p>
21160 <p><strong>Returns:</strong> The number of bytes received and zero on EOF (for stream
21161 connections).  A negative error code is returned in case of an error.
21162 The number of bytes received might be less than the requested  <code>data_size</code> .
21163 </p></dd></dl>
21164
21165 <a name="gnutls_005frecord_005frecv_005fpacket-1"></a>
21166 <h4 class="subheading">gnutls_record_recv_packet</h4>
21167 <a name="gnutls_005frecord_005frecv_005fpacket"></a><dl>
21168 <dt><a name="index-gnutls_005frecord_005frecv_005fpacket"></a>Function: <em>ssize_t</em> <strong>gnutls_record_recv_packet</strong> <em>(gnutls_session_t <var>session</var>, gnutls_packet_t * <var>packet</var>)</em></dt>
21169 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21170 </p>
21171 <p><var>packet</var>: the structure that will hold the packet data
21172 </p>
21173 <p>This is a lower-level function thatn <code>gnutls_record_recv()</code>  and allows
21174 to directly receive the whole decrypted packet. That avoids a
21175 memory copy, and is mostly applicable to applications seeking high
21176 performance.
21177 </p>
21178 <p>The received packet is accessed using <code>gnutls_packet_get()</code>  and
21179 must be deinitialized using <code>gnutls_packet_deinit()</code> . The returned
21180 packet will be <code>NULL</code>  if the return value is zero (EOF).
21181 </p>
21182 <p><strong>Returns:</strong> The number of bytes received and zero on EOF (for stream
21183 connections).  A negative error code is returned in case of an error.
21184 </p>
21185 <p><strong>Since:</strong> 3.3.5
21186 </p></dd></dl>
21187
21188 <a name="gnutls_005frecord_005frecv_005fseq-1"></a>
21189 <h4 class="subheading">gnutls_record_recv_seq</h4>
21190 <a name="gnutls_005frecord_005frecv_005fseq"></a><dl>
21191 <dt><a name="index-gnutls_005frecord_005frecv_005fseq-1"></a>Function: <em>ssize_t</em> <strong>gnutls_record_recv_seq</strong> <em>(gnutls_session_t <var>session</var>, void * <var>data</var>, size_t <var>data_size</var>, unsigned char * <var>seq</var>)</em></dt>
21192 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21193 </p>
21194 <p><var>data</var>: the buffer that the data will be read into
21195 </p>
21196 <p><var>data_size</var>: the number of requested bytes
21197 </p>
21198 <p><var>seq</var>: is the packet&rsquo;s 64-bit sequence number. Should have space for 8 bytes.
21199 </p>
21200 <p>This function is the same as <code>gnutls_record_recv()</code> , except that
21201 it returns in addition to data, the sequence number of the data.
21202 This is useful in DTLS where record packets might be received
21203 out-of-order. The returned 8-byte sequence number is an
21204 integer in big-endian format and should be
21205 treated as a unique message identification.
21206 </p>
21207 <p><strong>Returns:</strong> The number of bytes received and zero on EOF.  A negative
21208 error code is returned in case of an error.  The number of bytes
21209 received might be less than  <code>data_size</code> .
21210 </p>
21211 <p><strong>Since:</strong> 3.0
21212 </p></dd></dl>
21213
21214 <a name="gnutls_005frecord_005fsend-1"></a>
21215 <h4 class="subheading">gnutls_record_send</h4>
21216 <a name="gnutls_005frecord_005fsend"></a><dl>
21217 <dt><a name="index-gnutls_005frecord_005fsend-1"></a>Function: <em>ssize_t</em> <strong>gnutls_record_send</strong> <em>(gnutls_session_t <var>session</var>, const void * <var>data</var>, size_t <var>data_size</var>)</em></dt>
21218 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21219 </p>
21220 <p><var>data</var>: contains the data to send
21221 </p>
21222 <p><var>data_size</var>: is the length of the data
21223 </p>
21224 <p>This function has the similar semantics with <code>send()</code> .  The only
21225 difference is that it accepts a GnuTLS session, and uses different
21226 error codes.
21227 Note that if the send buffer is full, <code>send()</code>  will block this
21228 function.  See the <code>send()</code>  documentation for more information.
21229 </p>
21230 <p>You can replace the default push function which is <code>send()</code> , by using
21231 <code>gnutls_transport_set_push_function()</code> .
21232 </p>
21233 <p>If the EINTR is returned by the internal push function
21234 then <code>GNUTLS_E_INTERRUPTED</code>  will be returned. If
21235 <code>GNUTLS_E_INTERRUPTED</code>  or <code>GNUTLS_E_AGAIN</code>  is returned, you must
21236 call this function again, with the exact same parameters; alternatively
21237 you could provide a <code>NULL</code>  pointer for data, and 0 for
21238 size. cf. <code>gnutls_record_get_direction()</code> .
21239 </p>
21240 <p>Note that in DTLS this function will return the <code>GNUTLS_E_LARGE_PACKET</code>
21241 error code if the send data exceed the data MTU value - as returned
21242 by <code>gnutls_dtls_get_data_mtu()</code> . The errno value EMSGSIZE
21243 also maps to <code>GNUTLS_E_LARGE_PACKET</code> .
21244 Note that since 3.2.13 this function can be called under cork in DTLS
21245 mode, and will refuse to send data over the MTU size by returning
21246 <code>GNUTLS_E_LARGE_PACKET</code> .
21247 </p>
21248 <p><strong>Returns:</strong> The number of bytes sent, or a negative error code.  The
21249 number of bytes sent might be less than  <code>data_size</code> .  The maximum
21250 number of bytes this function can send in a single call depends
21251 on the negotiated maximum record size.
21252 </p></dd></dl>
21253
21254 <a name="gnutls_005frecord_005fsend_005frange-1"></a>
21255 <h4 class="subheading">gnutls_record_send_range</h4>
21256 <a name="gnutls_005frecord_005fsend_005frange"></a><dl>
21257 <dt><a name="index-gnutls_005frecord_005fsend_005frange"></a>Function: <em>ssize_t</em> <strong>gnutls_record_send_range</strong> <em>(gnutls_session_t <var>session</var>, const void * <var>data</var>, size_t <var>data_size</var>, const gnutls_range_st * <var>range</var>)</em></dt>
21258 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21259 </p>
21260 <p><var>data</var>: contains the data to send.
21261 </p>
21262 <p><var>data_size</var>: is the length of the data.
21263 </p>
21264 <p><var>range</var>: is the range of lengths in which the real data length must be hidden.
21265 </p>
21266 <p>This function operates like <code>gnutls_record_send()</code>  but, while
21267 <code>gnutls_record_send()</code>  adds minimal padding to each TLS record,
21268 this function uses the TLS extra-padding feature to conceal the real
21269 data size within the range of lengths provided.
21270 Some TLS sessions do not support extra padding (e.g. stream ciphers in standard
21271 TLS or SSL3 sessions). To know whether the current session supports extra
21272 padding, and hence length hiding, use the <code>gnutls_record_can_use_length_hiding()</code>
21273 function.
21274 </p>
21275 <p><strong>Note:</strong> This function currently is only limited to blocking sockets.
21276 </p>
21277 <p><strong>Returns:</strong> The number of bytes sent (that is data_size in a successful invocation),
21278 or a negative error code.
21279 </p></dd></dl>
21280
21281 <a name="gnutls_005frecord_005fset_005fmax_005fempty_005frecords-1"></a>
21282 <h4 class="subheading">gnutls_record_set_max_empty_records</h4>
21283 <a name="gnutls_005frecord_005fset_005fmax_005fempty_005frecords"></a><dl>
21284 <dt><a name="index-gnutls_005frecord_005fset_005fmax_005fempty_005frecords"></a>Function: <em>void</em> <strong>gnutls_record_set_max_empty_records</strong> <em>(gnutls_session_t <var>session</var>, const unsigned int <var>i</var>)</em></dt>
21285 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21286 </p>
21287 <p><var>i</var>: is the desired value of maximum empty records that can be accepted in a row.
21288 </p>
21289 <p>Used to set the maximum number of empty fragments that can be accepted
21290 in a row. Accepting many empty fragments is useful for receiving length-hidden
21291 content, where empty fragments filled with pad are sent to hide the real
21292 length of a message. However, a malicious peer could send empty fragments to
21293 mount a DoS attack, so as a safety measure, a maximum number of empty fragments
21294 is accepted by default. If you know your application must accept a given number
21295 of empty fragments in a row, you can use this function to set the desired value.
21296 </p></dd></dl>
21297
21298 <a name="gnutls_005frecord_005fset_005fmax_005fsize-1"></a>
21299 <h4 class="subheading">gnutls_record_set_max_size</h4>
21300 <a name="gnutls_005frecord_005fset_005fmax_005fsize"></a><dl>
21301 <dt><a name="index-gnutls_005frecord_005fset_005fmax_005fsize"></a>Function: <em>ssize_t</em> <strong>gnutls_record_set_max_size</strong> <em>(gnutls_session_t <var>session</var>, size_t <var>size</var>)</em></dt>
21302 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21303 </p>
21304 <p><var>size</var>: is the new size
21305 </p>
21306 <p>This function sets the maximum record packet size in this
21307 connection.  This property can only be set to clients.  The server
21308 may choose not to accept the requested size.
21309 </p>
21310 <p>Acceptable values are 512(=2^9), 1024(=2^10), 2048(=2^11) and
21311 4096(=2^12).  The requested record size does get in effect
21312 immediately only while sending data. The receive part will take
21313 effect after a successful handshake.
21314 </p>
21315 <p>This function uses a TLS extension called &rsquo;max record size&rsquo;.  Not
21316 all TLS implementations use or even understand this extension.
21317 </p>
21318 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
21319 otherwise a negative error code is returned.
21320 </p></dd></dl>
21321
21322 <a name="gnutls_005frecord_005fset_005ftimeout-1"></a>
21323 <h4 class="subheading">gnutls_record_set_timeout</h4>
21324 <a name="gnutls_005frecord_005fset_005ftimeout"></a><dl>
21325 <dt><a name="index-gnutls_005frecord_005fset_005ftimeout"></a>Function: <em>void</em> <strong>gnutls_record_set_timeout</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>ms</var>)</em></dt>
21326 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21327 </p>
21328 <p><var>ms</var>: is a timeout value in milliseconds
21329 </p>
21330 <p>This function sets the receive timeout for the record layer
21331 to the provided value. Use an  <code>ms</code> value of zero to disable
21332 timeout (the default).
21333 </p>
21334 <p><strong>Since:</strong> 3.1.7
21335 </p></dd></dl>
21336
21337 <a name="gnutls_005frecord_005funcork-1"></a>
21338 <h4 class="subheading">gnutls_record_uncork</h4>
21339 <a name="gnutls_005frecord_005funcork"></a><dl>
21340 <dt><a name="index-gnutls_005frecord_005funcork-1"></a>Function: <em>int</em> <strong>gnutls_record_uncork</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>flags</var>)</em></dt>
21341 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21342 </p>
21343 <p><var>flags</var>: Could be zero or <code>GNUTLS_RECORD_WAIT</code>
21344 </p>
21345 <p>This resets the effect of <code>gnutls_record_cork()</code> , and flushes any pending
21346 data. If the <code>GNUTLS_RECORD_WAIT</code>  flag is specified then this
21347 function will block until the data is sent or a fatal error
21348 occurs (i.e., the function will retry on <code>GNUTLS_E_AGAIN</code>  and
21349 <code>GNUTLS_E_INTERRUPTED</code> ).
21350 </p>
21351 <p>If the flag <code>GNUTLS_RECORD_WAIT</code>  is not specified and the function
21352 is interrupted then the <code>GNUTLS_E_AGAIN</code>  or <code>GNUTLS_E_INTERRUPTED</code>
21353 errors will be returned. To obtain the data left in the corked
21354 buffer use <code>gnutls_record_check_corked()</code> .
21355 </p>
21356 <p><strong>Returns:</strong> On success the number of transmitted data is returned, or
21357 otherwise a negative error code.
21358 </p>
21359 <p><strong>Since:</strong> 3.1.9
21360 </p></dd></dl>
21361
21362 <a name="gnutls_005frehandshake-1"></a>
21363 <h4 class="subheading">gnutls_rehandshake</h4>
21364 <a name="gnutls_005frehandshake"></a><dl>
21365 <dt><a name="index-gnutls_005frehandshake"></a>Function: <em>int</em> <strong>gnutls_rehandshake</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21366 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21367 </p>
21368 <p>This function will renegotiate security parameters with the
21369 client.  This should only be called in case of a server.
21370 </p>
21371 <p>This message informs the peer that we want to renegotiate
21372 parameters (perform a handshake).
21373 </p>
21374 <p>If this function succeeds (returns 0), you must call the
21375 <code>gnutls_handshake()</code>  function in order to negotiate the new
21376 parameters.
21377 </p>
21378 <p>Since TLS is full duplex some application data might have been
21379 sent during peer&rsquo;s processing of this message. In that case
21380 one should call <code>gnutls_record_recv()</code>  until GNUTLS_E_REHANDSHAKE
21381 is returned to clear any pending data. Care must be taken if
21382 rehandshake is mandatory to terminate if it does not start after
21383 some threshold.
21384 </p>
21385 <p>If the client does not wish to renegotiate parameters he
21386 should reply with an alert message, thus the return code will be
21387 <code>GNUTLS_E_WARNING_ALERT_RECEIVED</code>  and the alert will be
21388 <code>GNUTLS_A_NO_RENEGOTIATION</code> .  A client may also choose to ignore
21389 this message.
21390 </p>
21391 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
21392 </p></dd></dl>
21393
21394 <a name="gnutls_005fsafe_005frenegotiation_005fstatus-1"></a>
21395 <h4 class="subheading">gnutls_safe_renegotiation_status</h4>
21396 <a name="gnutls_005fsafe_005frenegotiation_005fstatus"></a><dl>
21397 <dt><a name="index-gnutls_005fsafe_005frenegotiation_005fstatus"></a>Function: <em>int</em> <strong>gnutls_safe_renegotiation_status</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21398 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21399 </p>
21400 <p>Can be used to check whether safe renegotiation is being used
21401 in the current session.
21402 </p>
21403 <p><strong>Returns:</strong> 0 when safe renegotiation is not used and non (0) when
21404 safe renegotiation is used.
21405 </p>
21406 <p><strong>Since:</strong> 2.10.0
21407 </p></dd></dl>
21408
21409 <a name="gnutls_005fsec_005fparam_005fget_005fname-1"></a>
21410 <h4 class="subheading">gnutls_sec_param_get_name</h4>
21411 <a name="gnutls_005fsec_005fparam_005fget_005fname"></a><dl>
21412 <dt><a name="index-gnutls_005fsec_005fparam_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_sec_param_get_name</strong> <em>(gnutls_sec_param_t <var>param</var>)</em></dt>
21413 <dd><p><var>param</var>: is a security parameter
21414 </p>
21415 <p>Convert a <code>gnutls_sec_param_t</code>  value to a string.
21416 </p>
21417 <p><strong>Returns:</strong> a pointer to a string that contains the name of the
21418 specified security level, or <code>NULL</code> .
21419 </p>
21420 <p><strong>Since:</strong> 2.12.0
21421 </p></dd></dl>
21422
21423 <a name="gnutls_005fsec_005fparam_005fto_005fpk_005fbits-1"></a>
21424 <h4 class="subheading">gnutls_sec_param_to_pk_bits</h4>
21425 <a name="gnutls_005fsec_005fparam_005fto_005fpk_005fbits"></a><dl>
21426 <dt><a name="index-gnutls_005fsec_005fparam_005fto_005fpk_005fbits-1"></a>Function: <em>unsigned int</em> <strong>gnutls_sec_param_to_pk_bits</strong> <em>(gnutls_pk_algorithm_t <var>algo</var>, gnutls_sec_param_t <var>param</var>)</em></dt>
21427 <dd><p><var>algo</var>: is a public key algorithm
21428 </p>
21429 <p><var>param</var>: is a security parameter
21430 </p>
21431 <p>When generating private and public key pairs a difficult question
21432 is which size of &quot;bits&quot; the modulus will be in RSA and the group size
21433 in DSA. The easy answer is 1024, which is also wrong. This function
21434 will convert a human understandable security parameter to an
21435 appropriate size for the specific algorithm.
21436 </p>
21437 <p><strong>Returns:</strong> The number of bits, or (0).
21438 </p>
21439 <p><strong>Since:</strong> 2.12.0
21440 </p></dd></dl>
21441
21442 <a name="gnutls_005fsec_005fparam_005fto_005fsymmetric_005fbits-1"></a>
21443 <h4 class="subheading">gnutls_sec_param_to_symmetric_bits</h4>
21444 <a name="gnutls_005fsec_005fparam_005fto_005fsymmetric_005fbits"></a><dl>
21445 <dt><a name="index-gnutls_005fsec_005fparam_005fto_005fsymmetric_005fbits"></a>Function: <em>unsigned int</em> <strong>gnutls_sec_param_to_symmetric_bits</strong> <em>(gnutls_sec_param_t <var>param</var>)</em></dt>
21446 <dd><p><var>param</var>: is a security parameter
21447 </p>
21448 <p>This function will return the number of bits that correspond to
21449 symmetric cipher strength for the given security parameter.
21450 </p>
21451 <p><strong>Returns:</strong> The number of bits, or (0).
21452 </p>
21453 <p><strong>Since:</strong> 3.3.0
21454 </p></dd></dl>
21455
21456 <a name="gnutls_005fserver_005fname_005fget-1"></a>
21457 <h4 class="subheading">gnutls_server_name_get</h4>
21458 <a name="gnutls_005fserver_005fname_005fget"></a><dl>
21459 <dt><a name="index-gnutls_005fserver_005fname_005fget"></a>Function: <em>int</em> <strong>gnutls_server_name_get</strong> <em>(gnutls_session_t <var>session</var>, void * <var>data</var>, size_t * <var>data_length</var>, unsigned int * <var>type</var>, unsigned int <var>indx</var>)</em></dt>
21460 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21461 </p>
21462 <p><var>data</var>: will hold the data
21463 </p>
21464 <p><var>data_length</var>: will hold the data length. Must hold the maximum size of data.
21465 </p>
21466 <p><var>type</var>: will hold the server name indicator type
21467 </p>
21468 <p><var>indx</var>: is the index of the server_name
21469 </p>
21470 <p>This function will allow you to get the name indication (if any), a
21471 client has sent.  The name indication may be any of the enumeration
21472 gnutls_server_name_type_t.
21473 </p>
21474 <p>If  <code>type</code> is GNUTLS_NAME_DNS, then this function is to be used by
21475 servers that support virtual hosting, and the data will be a null
21476 terminated UTF-8 string.
21477 </p>
21478 <p>If  <code>data</code> has not enough size to hold the server name
21479 GNUTLS_E_SHORT_MEMORY_BUFFER is returned, and  <code>data_length</code> will
21480 hold the required size.
21481 </p>
21482 <p><code>index</code> is used to retrieve more than one server names (if sent by
21483 the client).  The first server name has an index of 0, the second 1
21484 and so on.  If no name with the given index exists
21485 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE is returned.
21486 </p>
21487 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
21488 otherwise a negative error code is returned.
21489 </p></dd></dl>
21490
21491 <a name="gnutls_005fserver_005fname_005fset-1"></a>
21492 <h4 class="subheading">gnutls_server_name_set</h4>
21493 <a name="gnutls_005fserver_005fname_005fset"></a><dl>
21494 <dt><a name="index-gnutls_005fserver_005fname_005fset"></a>Function: <em>int</em> <strong>gnutls_server_name_set</strong> <em>(gnutls_session_t <var>session</var>, gnutls_server_name_type_t <var>type</var>, const void * <var>name</var>, size_t <var>name_length</var>)</em></dt>
21495 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21496 </p>
21497 <p><var>type</var>: specifies the indicator type
21498 </p>
21499 <p><var>name</var>: is a string that contains the server name.
21500 </p>
21501 <p><var>name_length</var>: holds the length of name
21502 </p>
21503 <p>This function is to be used by clients that want to inform (via a
21504 TLS extension mechanism) the server of the name they connected to.
21505 This should be used by clients that connect to servers that do
21506 virtual hosting.
21507 </p>
21508 <p>The value of  <code>name</code> depends on the  <code>type</code> type.  In case of
21509 <code>GNUTLS_NAME_DNS</code> , an ASCII (0)-terminated domain name string,
21510 without the trailing dot, is expected.  IPv4 or IPv6 addresses are
21511 not permitted.
21512 </p>
21513 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
21514 otherwise a negative error code is returned.
21515 </p></dd></dl>
21516
21517 <a name="gnutls_005fsession_005fchannel_005fbinding-1"></a>
21518 <h4 class="subheading">gnutls_session_channel_binding</h4>
21519 <a name="gnutls_005fsession_005fchannel_005fbinding"></a><dl>
21520 <dt><a name="index-gnutls_005fsession_005fchannel_005fbinding"></a>Function: <em>int</em> <strong>gnutls_session_channel_binding</strong> <em>(gnutls_session_t <var>session</var>, gnutls_channel_binding_t <var>cbtype</var>, gnutls_datum_t * <var>cb</var>)</em></dt>
21521 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21522 </p>
21523 <p><var>cbtype</var>: an <code>gnutls_channel_binding_t</code>  enumeration type
21524 </p>
21525 <p><var>cb</var>: output buffer array with data
21526 </p>
21527 <p>Extract given channel binding data of the  <code>cbtype</code> (e.g.,
21528 <code>GNUTLS_CB_TLS_UNIQUE</code> ) type.
21529 </p>
21530 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success,
21531 <code>GNUTLS_E_UNIMPLEMENTED_FEATURE</code>  if the  <code>cbtype</code> is unsupported,
21532 <code>GNUTLS_E_CHANNEL_BINDING_NOT_AVAILABLE</code>  if the data is not
21533 currently available, or an error code.
21534 </p>
21535 <p><strong>Since:</strong> 2.12.0
21536 </p></dd></dl>
21537
21538 <a name="gnutls_005fsession_005fenable_005fcompatibility_005fmode-1"></a>
21539 <h4 class="subheading">gnutls_session_enable_compatibility_mode</h4>
21540 <a name="gnutls_005fsession_005fenable_005fcompatibility_005fmode"></a><dl>
21541 <dt><a name="index-gnutls_005fsession_005fenable_005fcompatibility_005fmode"></a>Function: <em>void</em> <strong>gnutls_session_enable_compatibility_mode</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21542 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21543 </p>
21544 <p>This function can be used to disable certain (security) features in
21545 TLS in order to maintain maximum compatibility with buggy
21546 clients. Because several trade-offs with security are enabled,
21547 if required they will be reported through the audit subsystem.
21548 </p>
21549 <p>Normally only servers that require maximum compatibility with
21550 everything out there, need to call this function.
21551 </p>
21552 <p>Note that this function must be called after any call to gnutls_priority
21553 functions.
21554 </p></dd></dl>
21555
21556 <a name="gnutls_005fsession_005fforce_005fvalid-1"></a>
21557 <h4 class="subheading">gnutls_session_force_valid</h4>
21558 <a name="gnutls_005fsession_005fforce_005fvalid"></a><dl>
21559 <dt><a name="index-gnutls_005fsession_005fforce_005fvalid"></a>Function: <em>void</em> <strong>gnutls_session_force_valid</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21560 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21561 </p>
21562 <p>Clears the invalid flag in a session. That means
21563 that sessions were corrupt or invalid data were received
21564 can be re-used. Use only when debugging or experimenting
21565 with the TLS protocol. Should not be used in typical
21566 applications.
21567 </p></dd></dl>
21568
21569 <a name="gnutls_005fsession_005fget_005fdata-1"></a>
21570 <h4 class="subheading">gnutls_session_get_data</h4>
21571 <a name="gnutls_005fsession_005fget_005fdata"></a><dl>
21572 <dt><a name="index-gnutls_005fsession_005fget_005fdata"></a>Function: <em>int</em> <strong>gnutls_session_get_data</strong> <em>(gnutls_session_t <var>session</var>, void * <var>session_data</var>, size_t * <var>session_data_size</var>)</em></dt>
21573 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21574 </p>
21575 <p><var>session_data</var>: is a pointer to space to hold the session.
21576 </p>
21577 <p><var>session_data_size</var>: is the session_data&rsquo;s size, or it will be set by the function.
21578 </p>
21579 <p>Returns all session parameters needed to be stored to support resumption.
21580 The client should call this, and store the returned session data. A session
21581 may be resumed later by calling <code>gnutls_session_set_data()</code> .
21582 This function must be called after a successful (full) handshake. It should
21583 not be used in resumed sessions &ndash;see <code>gnutls_session_is_resumed()</code> .
21584 </p>
21585 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
21586 an error code is returned.
21587 </p></dd></dl>
21588
21589 <a name="gnutls_005fsession_005fget_005fdata2-1"></a>
21590 <h4 class="subheading">gnutls_session_get_data2</h4>
21591 <a name="gnutls_005fsession_005fget_005fdata2"></a><dl>
21592 <dt><a name="index-gnutls_005fsession_005fget_005fdata2"></a>Function: <em>int</em> <strong>gnutls_session_get_data2</strong> <em>(gnutls_session_t <var>session</var>, gnutls_datum_t * <var>data</var>)</em></dt>
21593 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21594 </p>
21595 <p><var>data</var>: is a pointer to a datum that will hold the session.
21596 </p>
21597 <p>Returns all session parameters needed to be stored to support resumption.
21598 The client should call this, and store the returned session data. A session
21599 may be resumed later by calling <code>gnutls_session_set_data()</code> .
21600 This function must be called after a successful (full) handshake. It should
21601 not be used in resumed sessions &ndash;see <code>gnutls_session_is_resumed()</code> .
21602 </p>
21603 <p>The returned  <code>data</code> are allocated and must be released using <code>gnutls_free()</code> .
21604 </p>
21605 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
21606 an error code is returned.
21607 </p></dd></dl>
21608
21609 <a name="gnutls_005fsession_005fget_005fdesc-1"></a>
21610 <h4 class="subheading">gnutls_session_get_desc</h4>
21611 <a name="gnutls_005fsession_005fget_005fdesc"></a><dl>
21612 <dt><a name="index-gnutls_005fsession_005fget_005fdesc"></a>Function: <em>char *</em> <strong>gnutls_session_get_desc</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21613 <dd><p><var>session</var>: is a gnutls session
21614 </p>
21615 <p>This function returns a string describing the current session.
21616 The string is null terminated and allocated using <code>gnutls_malloc()</code> .
21617 </p>
21618 <p><strong>Returns:</strong> a description of the protocols and algorithms in the current session.
21619 </p>
21620 <p><strong>Since:</strong> 3.1.10
21621 </p></dd></dl>
21622
21623 <a name="gnutls_005fsession_005fget_005fid-1"></a>
21624 <h4 class="subheading">gnutls_session_get_id</h4>
21625 <a name="gnutls_005fsession_005fget_005fid"></a><dl>
21626 <dt><a name="index-gnutls_005fsession_005fget_005fid"></a>Function: <em>int</em> <strong>gnutls_session_get_id</strong> <em>(gnutls_session_t <var>session</var>, void * <var>session_id</var>, size_t * <var>session_id_size</var>)</em></dt>
21627 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21628 </p>
21629 <p><var>session_id</var>: is a pointer to space to hold the session id.
21630 </p>
21631 <p><var>session_id_size</var>: initially should contain the maximum  <code>session_id</code> size and will be updated.
21632 </p>
21633 <p>Returns the current session ID. This can be used if you want to
21634 check if the next session you tried to resume was actually
21635 resumed.  That is because resumed sessions share the same session ID
21636 with the original session.
21637 </p>
21638 <p>The session ID is selected by the server, that identify the
21639 current session.  In TLS 1.0 and SSL 3.0 session id is always less
21640 than 32 bytes.
21641 </p>
21642 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
21643 an error code is returned.
21644 </p></dd></dl>
21645
21646 <a name="gnutls_005fsession_005fget_005fid2-1"></a>
21647 <h4 class="subheading">gnutls_session_get_id2</h4>
21648 <a name="gnutls_005fsession_005fget_005fid2"></a><dl>
21649 <dt><a name="index-gnutls_005fsession_005fget_005fid2"></a>Function: <em>int</em> <strong>gnutls_session_get_id2</strong> <em>(gnutls_session_t <var>session</var>, gnutls_datum_t * <var>session_id</var>)</em></dt>
21650 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21651 </p>
21652 <p><var>session_id</var>: will point to the session ID.
21653 </p>
21654 <p>Returns the current session ID. The returned data should be
21655 treated as constant.
21656 </p>
21657 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
21658 an error code is returned.
21659 </p>
21660 <p><strong>Since:</strong> 3.1.4
21661 </p></dd></dl>
21662
21663 <a name="gnutls_005fsession_005fget_005fptr-1"></a>
21664 <h4 class="subheading">gnutls_session_get_ptr</h4>
21665 <a name="gnutls_005fsession_005fget_005fptr"></a><dl>
21666 <dt><a name="index-gnutls_005fsession_005fget_005fptr"></a>Function: <em>void *</em> <strong>gnutls_session_get_ptr</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21667 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21668 </p>
21669 <p>Get user pointer for session.  Useful in callbacks.  This is the
21670 pointer set with <code>gnutls_session_set_ptr()</code> .
21671 </p>
21672 <p><strong>Returns:</strong> the user given pointer from the session structure, or
21673 <code>NULL</code>  if it was never set.
21674 </p></dd></dl>
21675
21676 <a name="gnutls_005fsession_005fget_005frandom-1"></a>
21677 <h4 class="subheading">gnutls_session_get_random</h4>
21678 <a name="gnutls_005fsession_005fget_005frandom"></a><dl>
21679 <dt><a name="index-gnutls_005fsession_005fget_005frandom"></a>Function: <em>void</em> <strong>gnutls_session_get_random</strong> <em>(gnutls_session_t <var>session</var>, gnutls_datum_t * <var>client</var>, gnutls_datum_t * <var>server</var>)</em></dt>
21680 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21681 </p>
21682 <p><var>client</var>: the client part of the random
21683 </p>
21684 <p><var>server</var>: the server part of the random
21685 </p>
21686 <p>This function returns pointers to the client and server
21687 random fields used in the TLS handshake. The pointers are
21688 not to be modified or deallocated.
21689 </p>
21690 <p>If a client random value has not yet been established, the output
21691 will be garbage.
21692 </p>
21693 <p><strong>Since:</strong> 3.0
21694 </p></dd></dl>
21695
21696 <a name="gnutls_005fsession_005fis_005fresumed-1"></a>
21697 <h4 class="subheading">gnutls_session_is_resumed</h4>
21698 <a name="gnutls_005fsession_005fis_005fresumed"></a><dl>
21699 <dt><a name="index-gnutls_005fsession_005fis_005fresumed-1"></a>Function: <em>int</em> <strong>gnutls_session_is_resumed</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21700 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21701 </p>
21702 <p>Check whether session is resumed or not.
21703 </p>
21704 <p><strong>Returns:</strong> non zero if this session is resumed, or a zero if this is
21705 a new session.
21706 </p></dd></dl>
21707
21708 <a name="gnutls_005fsession_005fresumption_005frequested-1"></a>
21709 <h4 class="subheading">gnutls_session_resumption_requested</h4>
21710 <a name="gnutls_005fsession_005fresumption_005frequested"></a><dl>
21711 <dt><a name="index-gnutls_005fsession_005fresumption_005frequested-1"></a>Function: <em>int</em> <strong>gnutls_session_resumption_requested</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21712 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21713 </p>
21714 <p>Check whether the client has asked for session resumption.
21715 This function is valid only on server side.
21716 </p>
21717 <p><strong>Returns:</strong> non zero if session resumption was asked, or a zero if not.
21718 </p></dd></dl>
21719
21720 <a name="gnutls_005fsession_005fset_005fdata-1"></a>
21721 <h4 class="subheading">gnutls_session_set_data</h4>
21722 <a name="gnutls_005fsession_005fset_005fdata"></a><dl>
21723 <dt><a name="index-gnutls_005fsession_005fset_005fdata"></a>Function: <em>int</em> <strong>gnutls_session_set_data</strong> <em>(gnutls_session_t <var>session</var>, const void * <var>session_data</var>, size_t <var>session_data_size</var>)</em></dt>
21724 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21725 </p>
21726 <p><var>session_data</var>: is a pointer to space to hold the session.
21727 </p>
21728 <p><var>session_data_size</var>: is the session&rsquo;s size
21729 </p>
21730 <p>Sets all session parameters, in order to resume a previously
21731 established session.  The session data given must be the one
21732 returned by <code>gnutls_session_get_data()</code> .  This function should be
21733 called before <code>gnutls_handshake()</code> .
21734 </p>
21735 <p>Keep in mind that session resuming is advisory. The server may
21736 choose not to resume the session, thus a full handshake will be
21737 performed.
21738 </p>
21739 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
21740 an error code is returned.
21741 </p></dd></dl>
21742
21743 <a name="gnutls_005fsession_005fset_005fid-1"></a>
21744 <h4 class="subheading">gnutls_session_set_id</h4>
21745 <a name="gnutls_005fsession_005fset_005fid"></a><dl>
21746 <dt><a name="index-gnutls_005fsession_005fset_005fid"></a>Function: <em>int</em> <strong>gnutls_session_set_id</strong> <em>(gnutls_session_t <var>session</var>, const gnutls_datum_t * <var>sid</var>)</em></dt>
21747 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21748 </p>
21749 <p><var>sid</var>: the session identifier
21750 </p>
21751 <p>This function sets the session ID to be used in a client hello.
21752 This is a function intended for exceptional uses. Do not use this
21753 function unless you are implementing a custom protocol.
21754 </p>
21755 <p>To set session resumption parameters use <code>gnutls_session_set_data()</code>  instead.
21756 </p>
21757 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
21758 an error code is returned.
21759 </p></dd></dl>
21760
21761 <a name="gnutls_005fsession_005fset_005fpremaster-1"></a>
21762 <h4 class="subheading">gnutls_session_set_premaster</h4>
21763 <a name="gnutls_005fsession_005fset_005fpremaster"></a><dl>
21764 <dt><a name="index-gnutls_005fsession_005fset_005fpremaster"></a>Function: <em>int</em> <strong>gnutls_session_set_premaster</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>entity</var>, gnutls_protocol_t <var>version</var>, gnutls_kx_algorithm_t <var>kx</var>, gnutls_cipher_algorithm_t <var>cipher</var>, gnutls_mac_algorithm_t <var>mac</var>, gnutls_compression_method_t <var>comp</var>, const gnutls_datum_t * <var>master</var>, const gnutls_datum_t * <var>session_id</var>)</em></dt>
21765 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21766 </p>
21767 <p><var>entity</var>: GNUTLS_SERVER or GNUTLS_CLIENT
21768 </p>
21769 <p><var>version</var>: the TLS protocol version
21770 </p>
21771 <p><var>kx</var>: the key exchange method
21772 </p>
21773 <p><var>cipher</var>: the cipher
21774 </p>
21775 <p><var>mac</var>: the MAC algorithm
21776 </p>
21777 <p><var>comp</var>: the compression method
21778 </p>
21779 <p><var>master</var>: the master key to use
21780 </p>
21781 <p><var>session_id</var>: the session identifier
21782 </p>
21783 <p>This function sets the premaster secret in a session. This is
21784 a function intended for exceptional uses. Do not use this
21785 function unless you are implementing a legacy protocol.
21786 Use <code>gnutls_session_set_data()</code>  instead.
21787 </p>
21788 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
21789 an error code is returned.
21790 </p></dd></dl>
21791
21792 <a name="gnutls_005fsession_005fset_005fptr-1"></a>
21793 <h4 class="subheading">gnutls_session_set_ptr</h4>
21794 <a name="gnutls_005fsession_005fset_005fptr"></a><dl>
21795 <dt><a name="index-gnutls_005fsession_005fset_005fptr"></a>Function: <em>void</em> <strong>gnutls_session_set_ptr</strong> <em>(gnutls_session_t <var>session</var>, void * <var>ptr</var>)</em></dt>
21796 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21797 </p>
21798 <p><var>ptr</var>: is the user pointer
21799 </p>
21800 <p>This function will set (associate) the user given pointer  <code>ptr</code> to
21801 the session structure.  This pointer can be accessed with
21802 <code>gnutls_session_get_ptr()</code> .
21803 </p></dd></dl>
21804
21805 <a name="gnutls_005fsession_005fticket_005fenable_005fclient-1"></a>
21806 <h4 class="subheading">gnutls_session_ticket_enable_client</h4>
21807 <a name="gnutls_005fsession_005fticket_005fenable_005fclient"></a><dl>
21808 <dt><a name="index-gnutls_005fsession_005fticket_005fenable_005fclient"></a>Function: <em>int</em> <strong>gnutls_session_ticket_enable_client</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21809 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21810 </p>
21811 <p>Request that the client should attempt session resumption using
21812 SessionTicket.
21813 </p>
21814 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or an
21815 error code.
21816 </p>
21817 <p><strong>Since:</strong> 2.10.0
21818 </p></dd></dl>
21819
21820 <a name="gnutls_005fsession_005fticket_005fenable_005fserver-1"></a>
21821 <h4 class="subheading">gnutls_session_ticket_enable_server</h4>
21822 <a name="gnutls_005fsession_005fticket_005fenable_005fserver"></a><dl>
21823 <dt><a name="index-gnutls_005fsession_005fticket_005fenable_005fserver-1"></a>Function: <em>int</em> <strong>gnutls_session_ticket_enable_server</strong> <em>(gnutls_session_t <var>session</var>, const gnutls_datum_t * <var>key</var>)</em></dt>
21824 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21825 </p>
21826 <p><var>key</var>: key to encrypt session parameters.
21827 </p>
21828 <p>Request that the server should attempt session resumption using
21829 SessionTicket.   <code>key</code> must be initialized with
21830 <code>gnutls_session_ticket_key_generate()</code> .
21831 </p>
21832 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or an
21833 error code.
21834 </p>
21835 <p><strong>Since:</strong> 2.10.0
21836 </p></dd></dl>
21837
21838 <a name="gnutls_005fsession_005fticket_005fkey_005fgenerate-1"></a>
21839 <h4 class="subheading">gnutls_session_ticket_key_generate</h4>
21840 <a name="gnutls_005fsession_005fticket_005fkey_005fgenerate"></a><dl>
21841 <dt><a name="index-gnutls_005fsession_005fticket_005fkey_005fgenerate-1"></a>Function: <em>int</em> <strong>gnutls_session_ticket_key_generate</strong> <em>(gnutls_datum_t * <var>key</var>)</em></dt>
21842 <dd><p><var>key</var>: is a pointer to a <code>gnutls_datum_t</code>  which will contain a newly
21843 created key.
21844 </p>
21845 <p>Generate a random key to encrypt security parameters within
21846 SessionTicket.
21847 </p>
21848 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or an
21849 error code.
21850 </p>
21851 <p><strong>Since:</strong> 2.10.0
21852 </p></dd></dl>
21853
21854 <a name="gnutls_005fset_005fdefault_005fpriority-1"></a>
21855 <h4 class="subheading">gnutls_set_default_priority</h4>
21856 <a name="gnutls_005fset_005fdefault_005fpriority"></a><dl>
21857 <dt><a name="index-gnutls_005fset_005fdefault_005fpriority"></a>Function: <em>int</em> <strong>gnutls_set_default_priority</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21858 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21859 </p>
21860 <p>Sets the default priority on the ciphers, key exchange methods,
21861 macs and compression methods. For more fine-tuning you could
21862 use <code>gnutls_priority_set_direct()</code>  or <code>gnutls_priority_set()</code>  instead.
21863 </p>
21864 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
21865 </p></dd></dl>
21866
21867 <a name="gnutls_005fsign_005falgorithm_005fget-1"></a>
21868 <h4 class="subheading">gnutls_sign_algorithm_get</h4>
21869 <a name="gnutls_005fsign_005falgorithm_005fget"></a><dl>
21870 <dt><a name="index-gnutls_005fsign_005falgorithm_005fget"></a>Function: <em>int</em> <strong>gnutls_sign_algorithm_get</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21871 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21872 </p>
21873 <p>Returns the signature algorithm that is (or will be) used in this
21874 session by the server to sign data.
21875 </p>
21876 <p><strong>Returns:</strong> The sign algorithm or <code>GNUTLS_SIGN_UNKNOWN</code> .
21877 </p>
21878 <p><strong>Since:</strong> 3.1.1
21879 </p></dd></dl>
21880
21881 <a name="gnutls_005fsign_005falgorithm_005fget_005fclient-1"></a>
21882 <h4 class="subheading">gnutls_sign_algorithm_get_client</h4>
21883 <a name="gnutls_005fsign_005falgorithm_005fget_005fclient"></a><dl>
21884 <dt><a name="index-gnutls_005fsign_005falgorithm_005fget_005fclient"></a>Function: <em>int</em> <strong>gnutls_sign_algorithm_get_client</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
21885 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21886 </p>
21887 <p>Returns the signature algorithm that is (or will be) used in this
21888 session by the client to sign data.
21889 </p>
21890 <p><strong>Returns:</strong> The sign algorithm or <code>GNUTLS_SIGN_UNKNOWN</code> .
21891 </p>
21892 <p><strong>Since:</strong> 3.1.11
21893 </p></dd></dl>
21894
21895 <a name="gnutls_005fsign_005falgorithm_005fget_005frequested-1"></a>
21896 <h4 class="subheading">gnutls_sign_algorithm_get_requested</h4>
21897 <a name="gnutls_005fsign_005falgorithm_005fget_005frequested"></a><dl>
21898 <dt><a name="index-gnutls_005fsign_005falgorithm_005fget_005frequested"></a>Function: <em>int</em> <strong>gnutls_sign_algorithm_get_requested</strong> <em>(gnutls_session_t <var>session</var>, size_t <var>indx</var>, gnutls_sign_algorithm_t * <var>algo</var>)</em></dt>
21899 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
21900 </p>
21901 <p><var>indx</var>: is an index of the signature algorithm to return
21902 </p>
21903 <p><var>algo</var>: the returned certificate type will be stored there
21904 </p>
21905 <p>Returns the signature algorithm specified by index that was
21906 requested by the peer. If the specified index has no data available
21907 this function returns <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> .  If
21908 the negotiated TLS version does not support signature algorithms
21909 then <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be returned even
21910 for the first index.  The first index is 0.
21911 </p>
21912 <p>This function is useful in the certificate callback functions
21913 to assist in selecting the correct certificate.
21914 </p>
21915 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
21916 an error code is returned.
21917 </p>
21918 <p><strong>Since:</strong> 2.10.0
21919 </p></dd></dl>
21920
21921 <a name="gnutls_005fsign_005fget_005fhash_005falgorithm-1"></a>
21922 <h4 class="subheading">gnutls_sign_get_hash_algorithm</h4>
21923 <a name="gnutls_005fsign_005fget_005fhash_005falgorithm"></a><dl>
21924 <dt><a name="index-gnutls_005fsign_005fget_005fhash_005falgorithm"></a>Function: <em>gnutls_digest_algorithm_t</em> <strong>gnutls_sign_get_hash_algorithm</strong> <em>(gnutls_sign_algorithm_t <var>sign</var>)</em></dt>
21925 <dd><p><var>sign</var>: is a signature algorithm
21926 </p>
21927 <p>This function returns the digest algorithm corresponding to
21928 the given signature algorithms.
21929 </p>
21930 <p><strong>Since:</strong> 3.1.1
21931 </p>
21932 <p><strong>Returns:</strong> return a <code>gnutls_digest_algorithm_t</code>  value, or <code>GNUTLS_DIG_UNKNOWN</code>  on error.
21933 </p></dd></dl>
21934
21935 <a name="gnutls_005fsign_005fget_005fid-1"></a>
21936 <h4 class="subheading">gnutls_sign_get_id</h4>
21937 <a name="gnutls_005fsign_005fget_005fid"></a><dl>
21938 <dt><a name="index-gnutls_005fsign_005fget_005fid"></a>Function: <em>gnutls_sign_algorithm_t</em> <strong>gnutls_sign_get_id</strong> <em>(const char * <var>name</var>)</em></dt>
21939 <dd><p><var>name</var>: is a sign algorithm name
21940 </p>
21941 <p>The names are compared in a case insensitive way.
21942 </p>
21943 <p><strong>Returns:</strong> return a <code>gnutls_sign_algorithm_t</code>  value corresponding to
21944 the specified algorithm, or <code>GNUTLS_SIGN_UNKNOWN</code>  on error.
21945 </p></dd></dl>
21946
21947 <a name="gnutls_005fsign_005fget_005fname-1"></a>
21948 <h4 class="subheading">gnutls_sign_get_name</h4>
21949 <a name="gnutls_005fsign_005fget_005fname"></a><dl>
21950 <dt><a name="index-gnutls_005fsign_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_sign_get_name</strong> <em>(gnutls_sign_algorithm_t <var>algorithm</var>)</em></dt>
21951 <dd><p><var>algorithm</var>: is a sign algorithm
21952 </p>
21953 <p>Convert a <code>gnutls_sign_algorithm_t</code>  value to a string.
21954 </p>
21955 <p><strong>Returns:</strong> a string that contains the name of the specified sign
21956 algorithm, or <code>NULL</code> .
21957 </p></dd></dl>
21958
21959 <a name="gnutls_005fsign_005fget_005fpk_005falgorithm-1"></a>
21960 <h4 class="subheading">gnutls_sign_get_pk_algorithm</h4>
21961 <a name="gnutls_005fsign_005fget_005fpk_005falgorithm"></a><dl>
21962 <dt><a name="index-gnutls_005fsign_005fget_005fpk_005falgorithm"></a>Function: <em>gnutls_pk_algorithm_t</em> <strong>gnutls_sign_get_pk_algorithm</strong> <em>(gnutls_sign_algorithm_t <var>sign</var>)</em></dt>
21963 <dd><p><var>sign</var>: is a signature algorithm
21964 </p>
21965 <p>This function returns the public key algorithm corresponding to
21966 the given signature algorithms.
21967 </p>
21968 <p><strong>Since:</strong> 3.1.1
21969 </p>
21970 <p><strong>Returns:</strong> return a <code>gnutls_pk_algorithm_t</code>  value, or <code>GNUTLS_PK_UNKNOWN</code>  on error.
21971 </p></dd></dl>
21972
21973 <a name="gnutls_005fsign_005fis_005fsecure-1"></a>
21974 <h4 class="subheading">gnutls_sign_is_secure</h4>
21975 <a name="gnutls_005fsign_005fis_005fsecure"></a><dl>
21976 <dt><a name="index-gnutls_005fsign_005fis_005fsecure"></a>Function: <em>int</em> <strong>gnutls_sign_is_secure</strong> <em>(gnutls_sign_algorithm_t <var>algorithm</var>)</em></dt>
21977 <dd><p><var>algorithm</var>: is a sign algorithm
21978 </p>
21979
21980 <p><strong>Returns:</strong> Non-zero if the provided signature algorithm is considered to be secure.
21981 </p></dd></dl>
21982
21983 <a name="gnutls_005fsign_005flist-1"></a>
21984 <h4 class="subheading">gnutls_sign_list</h4>
21985 <a name="gnutls_005fsign_005flist"></a><dl>
21986 <dt><a name="index-gnutls_005fsign_005flist"></a>Function: <em>const gnutls_sign_algorithm_t *</em> <strong>gnutls_sign_list</strong> <em>( <var>void</var>)</em></dt>
21987 <dd>
21988 <p>Get a list of supported public key signature algorithms.
21989 </p>
21990 <p><strong>Returns:</strong> a (0)-terminated list of <code>gnutls_sign_algorithm_t</code>
21991 integers indicating the available ciphers.
21992 </p></dd></dl>
21993
21994 <a name="gnutls_005fsrp_005fallocate_005fclient_005fcredentials-1"></a>
21995 <h4 class="subheading">gnutls_srp_allocate_client_credentials</h4>
21996 <a name="gnutls_005fsrp_005fallocate_005fclient_005fcredentials"></a><dl>
21997 <dt><a name="index-gnutls_005fsrp_005fallocate_005fclient_005fcredentials"></a>Function: <em>int</em> <strong>gnutls_srp_allocate_client_credentials</strong> <em>(gnutls_srp_client_credentials_t *            <var>sc</var>)</em></dt>
21998 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_srp_server_credentials_t</code>  structure.
21999 </p>
22000 <p>This structure is complex enough to manipulate directly thus
22001 this helper function is provided in order to allocate it.
22002 </p>
22003 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or an
22004 error code.
22005 </p></dd></dl>
22006
22007 <a name="gnutls_005fsrp_005fallocate_005fserver_005fcredentials-1"></a>
22008 <h4 class="subheading">gnutls_srp_allocate_server_credentials</h4>
22009 <a name="gnutls_005fsrp_005fallocate_005fserver_005fcredentials"></a><dl>
22010 <dt><a name="index-gnutls_005fsrp_005fallocate_005fserver_005fcredentials"></a>Function: <em>int</em> <strong>gnutls_srp_allocate_server_credentials</strong> <em>(gnutls_srp_server_credentials_t *            <var>sc</var>)</em></dt>
22011 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_srp_server_credentials_t</code>  structure.
22012 </p>
22013 <p>This structure is complex enough to manipulate directly thus this
22014 helper function is provided in order to allocate it.
22015 </p>
22016 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or an
22017 error code.
22018 </p></dd></dl>
22019
22020 <a name="gnutls_005fsrp_005fbase64_005fdecode-1"></a>
22021 <h4 class="subheading">gnutls_srp_base64_decode</h4>
22022 <a name="gnutls_005fsrp_005fbase64_005fdecode"></a><dl>
22023 <dt><a name="index-gnutls_005fsrp_005fbase64_005fdecode"></a>Function: <em>int</em> <strong>gnutls_srp_base64_decode</strong> <em>(const gnutls_datum_t * <var>b64_data</var>, char * <var>result</var>, size_t * <var>result_size</var>)</em></dt>
22024 <dd><p><var>b64_data</var>: contain the encoded data
22025 </p>
22026 <p><var>result</var>: the place where decoded data will be copied
22027 </p>
22028 <p><var>result_size</var>: holds the size of the result
22029 </p>
22030 <p>This function will decode the given encoded data, using the base64
22031 encoding found in libsrp.
22032 </p>
22033 <p>Note that  <code>b64_data</code> should be null terminated.
22034 </p>
22035 <p>Warning!  This base64 encoding is not the &quot;standard&quot; encoding, so
22036 do not use it for non-SRP purposes.
22037 </p>
22038 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the buffer given is not
22039 long enough, or 0 on success.
22040 </p></dd></dl>
22041
22042 <a name="gnutls_005fsrp_005fbase64_005fdecode_005falloc-1"></a>
22043 <h4 class="subheading">gnutls_srp_base64_decode_alloc</h4>
22044 <a name="gnutls_005fsrp_005fbase64_005fdecode_005falloc"></a><dl>
22045 <dt><a name="index-gnutls_005fsrp_005fbase64_005fdecode_005falloc"></a>Function: <em>int</em> <strong>gnutls_srp_base64_decode_alloc</strong> <em>(const gnutls_datum_t * <var>b64_data</var>, gnutls_datum_t * <var>result</var>)</em></dt>
22046 <dd><p><var>b64_data</var>: contains the encoded data
22047 </p>
22048 <p><var>result</var>: the place where decoded data lie
22049 </p>
22050 <p>This function will decode the given encoded data. The decoded data
22051 will be allocated, and stored into result.  It will decode using
22052 the base64 algorithm as used in libsrp.
22053 </p>
22054 <p>You should use <code>gnutls_free()</code>  to free the returned data.
22055 </p>
22056 <p>Warning!  This base64 encoding is not the &quot;standard&quot; encoding, so
22057 do not use it for non-SRP purposes.
22058 </p>
22059 <p><strong>Returns:</strong> 0 on success, or an error code.
22060 </p></dd></dl>
22061
22062 <a name="gnutls_005fsrp_005fbase64_005fencode-1"></a>
22063 <h4 class="subheading">gnutls_srp_base64_encode</h4>
22064 <a name="gnutls_005fsrp_005fbase64_005fencode"></a><dl>
22065 <dt><a name="index-gnutls_005fsrp_005fbase64_005fencode"></a>Function: <em>int</em> <strong>gnutls_srp_base64_encode</strong> <em>(const gnutls_datum_t * <var>data</var>, char * <var>result</var>, size_t * <var>result_size</var>)</em></dt>
22066 <dd><p><var>data</var>: contain the raw data
22067 </p>
22068 <p><var>result</var>: the place where base64 data will be copied
22069 </p>
22070 <p><var>result_size</var>: holds the size of the result
22071 </p>
22072 <p>This function will convert the given data to printable data, using
22073 the base64 encoding, as used in the libsrp.  This is the encoding
22074 used in SRP password files.  If the provided buffer is not long
22075 enough GNUTLS_E_SHORT_MEMORY_BUFFER is returned.
22076 </p>
22077 <p>Warning!  This base64 encoding is not the &quot;standard&quot; encoding, so
22078 do not use it for non-SRP purposes.
22079 </p>
22080 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the buffer given is not
22081 long enough, or 0 on success.
22082 </p></dd></dl>
22083
22084 <a name="gnutls_005fsrp_005fbase64_005fencode_005falloc-1"></a>
22085 <h4 class="subheading">gnutls_srp_base64_encode_alloc</h4>
22086 <a name="gnutls_005fsrp_005fbase64_005fencode_005falloc"></a><dl>
22087 <dt><a name="index-gnutls_005fsrp_005fbase64_005fencode_005falloc"></a>Function: <em>int</em> <strong>gnutls_srp_base64_encode_alloc</strong> <em>(const gnutls_datum_t * <var>data</var>, gnutls_datum_t * <var>result</var>)</em></dt>
22088 <dd><p><var>data</var>: contains the raw data
22089 </p>
22090 <p><var>result</var>: will hold the newly allocated encoded data
22091 </p>
22092 <p>This function will convert the given data to printable data, using
22093 the base64 encoding.  This is the encoding used in SRP password
22094 files.  This function will allocate the required memory to hold
22095 the encoded data.
22096 </p>
22097 <p>You should use <code>gnutls_free()</code>  to free the returned data.
22098 </p>
22099 <p>Warning!  This base64 encoding is not the &quot;standard&quot; encoding, so
22100 do not use it for non-SRP purposes.
22101 </p>
22102 <p><strong>Returns:</strong> 0 on success, or an error code.
22103 </p></dd></dl>
22104
22105 <a name="gnutls_005fsrp_005ffree_005fclient_005fcredentials-1"></a>
22106 <h4 class="subheading">gnutls_srp_free_client_credentials</h4>
22107 <a name="gnutls_005fsrp_005ffree_005fclient_005fcredentials"></a><dl>
22108 <dt><a name="index-gnutls_005fsrp_005ffree_005fclient_005fcredentials"></a>Function: <em>void</em> <strong>gnutls_srp_free_client_credentials</strong> <em>(gnutls_srp_client_credentials_t <var>sc</var>)</em></dt>
22109 <dd><p><var>sc</var>: is a <code>gnutls_srp_client_credentials_t</code>  structure.
22110 </p>
22111 <p>This structure is complex enough to manipulate directly thus
22112 this helper function is provided in order to free (deallocate) it.
22113 </p></dd></dl>
22114
22115 <a name="gnutls_005fsrp_005ffree_005fserver_005fcredentials-1"></a>
22116 <h4 class="subheading">gnutls_srp_free_server_credentials</h4>
22117 <a name="gnutls_005fsrp_005ffree_005fserver_005fcredentials"></a><dl>
22118 <dt><a name="index-gnutls_005fsrp_005ffree_005fserver_005fcredentials"></a>Function: <em>void</em> <strong>gnutls_srp_free_server_credentials</strong> <em>(gnutls_srp_server_credentials_t <var>sc</var>)</em></dt>
22119 <dd><p><var>sc</var>: is a <code>gnutls_srp_server_credentials_t</code>  structure.
22120 </p>
22121 <p>This structure is complex enough to manipulate directly thus
22122 this helper function is provided in order to free (deallocate) it.
22123 </p></dd></dl>
22124
22125 <a name="gnutls_005fsrp_005fserver_005fget_005fusername-1"></a>
22126 <h4 class="subheading">gnutls_srp_server_get_username</h4>
22127 <a name="gnutls_005fsrp_005fserver_005fget_005fusername"></a><dl>
22128 <dt><a name="index-gnutls_005fsrp_005fserver_005fget_005fusername"></a>Function: <em>const char *</em> <strong>gnutls_srp_server_get_username</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
22129 <dd><p><var>session</var>: is a gnutls session
22130 </p>
22131 <p>This function will return the username of the peer.  This should
22132 only be called in case of SRP authentication and in case of a
22133 server.  Returns NULL in case of an error.
22134 </p>
22135 <p><strong>Returns:</strong> SRP username of the peer, or NULL in case of error.
22136 </p></dd></dl>
22137
22138 <a name="gnutls_005fsrp_005fset_005fclient_005fcredentials-1"></a>
22139 <h4 class="subheading">gnutls_srp_set_client_credentials</h4>
22140 <a name="gnutls_005fsrp_005fset_005fclient_005fcredentials"></a><dl>
22141 <dt><a name="index-gnutls_005fsrp_005fset_005fclient_005fcredentials"></a>Function: <em>int</em> <strong>gnutls_srp_set_client_credentials</strong> <em>(gnutls_srp_client_credentials_t <var>res</var>, const char * <var>username</var>, const char * <var>password</var>)</em></dt>
22142 <dd><p><var>res</var>: is a <code>gnutls_srp_client_credentials_t</code>  structure.
22143 </p>
22144 <p><var>username</var>: is the user&rsquo;s userid
22145 </p>
22146 <p><var>password</var>: is the user&rsquo;s password
22147 </p>
22148 <p>This function sets the username and password, in a
22149 <code>gnutls_srp_client_credentials_t</code>  structure.  Those will be used in
22150 SRP authentication.   <code>username</code> and  <code>password</code> should be ASCII
22151 strings or UTF-8 strings prepared using the &quot;SASLprep&quot; profile of
22152 &quot;stringprep&quot;.
22153 </p>
22154 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or an
22155 error code.
22156 </p></dd></dl>
22157
22158 <a name="gnutls_005fsrp_005fset_005fclient_005fcredentials_005ffunction-1"></a>
22159 <h4 class="subheading">gnutls_srp_set_client_credentials_function</h4>
22160 <a name="gnutls_005fsrp_005fset_005fclient_005fcredentials_005ffunction"></a><dl>
22161 <dt><a name="index-gnutls_005fsrp_005fset_005fclient_005fcredentials_005ffunction-1"></a>Function: <em>void</em> <strong>gnutls_srp_set_client_credentials_function</strong> <em>(gnutls_srp_client_credentials_t         <var>cred</var>, gnutls_srp_client_credentials_function         * <var>func</var>)</em></dt>
22162 <dd><p><var>cred</var>: is a <code>gnutls_srp_server_credentials_t</code>  structure.
22163 </p>
22164 <p><var>func</var>: is the callback function
22165 </p>
22166 <p>This function can be used to set a callback to retrieve the
22167 username and password for client SRP authentication.  The
22168 callback&rsquo;s function form is:
22169 </p>
22170 <p>int (*callback)(gnutls_session_t, char** username, char**password);
22171 </p>
22172 <p>The  <code>username</code> and  <code>password</code> must be allocated using
22173 <code>gnutls_malloc()</code> .   <code>username</code> and  <code>password</code> should be ASCII strings
22174 or UTF-8 strings prepared using the &quot;SASLprep&quot; profile of
22175 &quot;stringprep&quot;.
22176 </p>
22177 <p>The callback function will be called once per handshake before the
22178 initial hello message is sent.
22179 </p>
22180 <p>The callback should not return a negative error code the second
22181 time called, since the handshake procedure will be aborted.
22182 </p>
22183 <p>The callback function should return 0 on success.
22184 -1 indicates an error.
22185 </p></dd></dl>
22186
22187 <a name="gnutls_005fsrp_005fset_005fprime_005fbits-1"></a>
22188 <h4 class="subheading">gnutls_srp_set_prime_bits</h4>
22189 <a name="gnutls_005fsrp_005fset_005fprime_005fbits"></a><dl>
22190 <dt><a name="index-gnutls_005fsrp_005fset_005fprime_005fbits"></a>Function: <em>void</em> <strong>gnutls_srp_set_prime_bits</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>bits</var>)</em></dt>
22191 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22192 </p>
22193 <p><var>bits</var>: is the number of bits
22194 </p>
22195 <p>This function sets the minimum accepted number of bits, for use in
22196 an SRP key exchange.  If zero, the default 2048 bits will be used.
22197 </p>
22198 <p>In the client side it sets the minimum accepted number of bits.  If
22199 a server sends a prime with less bits than that
22200 <code>GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER</code>  will be returned by the
22201 handshake.
22202 </p>
22203 <p>This function has no effect in server side.
22204 </p>
22205 <p><strong>Since:</strong> 2.6.0
22206 </p></dd></dl>
22207
22208 <a name="gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffile-1"></a>
22209 <h4 class="subheading">gnutls_srp_set_server_credentials_file</h4>
22210 <a name="gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffile"></a><dl>
22211 <dt><a name="index-gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffile-1"></a>Function: <em>int</em> <strong>gnutls_srp_set_server_credentials_file</strong> <em>(gnutls_srp_server_credentials_t <var>res</var>, const char * <var>password_file</var>, const char * <var>password_conf_file</var>)</em></dt>
22212 <dd><p><var>res</var>: is a <code>gnutls_srp_server_credentials_t</code>  structure.
22213 </p>
22214 <p><var>password_file</var>: is the SRP password file (tpasswd)
22215 </p>
22216 <p><var>password_conf_file</var>: is the SRP password conf file (tpasswd.conf)
22217 </p>
22218 <p>This function sets the password files, in a
22219 <code>gnutls_srp_server_credentials_t</code>  structure.  Those password files
22220 hold usernames and verifiers and will be used for SRP
22221 authentication.
22222 </p>
22223 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or an
22224 error code.
22225 </p></dd></dl>
22226
22227 <a name="gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffunction-1"></a>
22228 <h4 class="subheading">gnutls_srp_set_server_credentials_function</h4>
22229 <a name="gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffunction"></a><dl>
22230 <dt><a name="index-gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffunction-1"></a>Function: <em>void</em> <strong>gnutls_srp_set_server_credentials_function</strong> <em>(gnutls_srp_server_credentials_t         <var>cred</var>, gnutls_srp_server_credentials_function         * <var>func</var>)</em></dt>
22231 <dd><p><var>cred</var>: is a <code>gnutls_srp_server_credentials_t</code>  structure.
22232 </p>
22233 <p><var>func</var>: is the callback function
22234 </p>
22235 <p>This function can be used to set a callback to retrieve the user&rsquo;s
22236 SRP credentials.  The callback&rsquo;s function form is:
22237 </p>
22238 <p>int (*callback)(gnutls_session_t, const char* username,
22239 gnutls_datum_t *salt, gnutls_datum_t *verifier, gnutls_datum_t *generator,
22240 gnutls_datum_t *prime);
22241 </p>
22242 <p><code>username</code> contains the actual username.
22243 The  <code>salt</code> ,  <code>verifier</code> ,  <code>generator</code> and  <code>prime</code> must be filled
22244 in using the <code>gnutls_malloc()</code> . For convenience  <code>prime</code> and  <code>generator</code> may also be one of the static parameters defined in gnutls.h.
22245 </p>
22246 <p>Initially, the data field is NULL in every <code>gnutls_datum_t</code>
22247 structure that the callback has to fill in. When the
22248 callback is done GnuTLS deallocates all of those buffers
22249 which are non-NULL, regardless of the return value.
22250 </p>
22251 <p>In order to prevent attackers from guessing valid usernames,
22252 if a user does not exist, g and n values should be filled in
22253 using a random user&rsquo;s parameters. In that case the callback must
22254 return the special value (1).
22255 See <code>gnutls_srp_set_server_fake_salt_seed</code>  too.
22256 If this is not required for your application, return a negative
22257 number from the callback to abort the handshake.
22258 </p>
22259 <p>The callback function will only be called once per handshake.
22260 The callback function should return 0 on success, while
22261 -1 indicates an error.
22262 </p></dd></dl>
22263
22264 <a name="gnutls_005fsrp_005fset_005fserver_005ffake_005fsalt_005fseed-1"></a>
22265 <h4 class="subheading">gnutls_srp_set_server_fake_salt_seed</h4>
22266 <a name="gnutls_005fsrp_005fset_005fserver_005ffake_005fsalt_005fseed"></a><dl>
22267 <dt><a name="index-gnutls_005fsrp_005fset_005fserver_005ffake_005fsalt_005fseed"></a>Function: <em>void</em> <strong>gnutls_srp_set_server_fake_salt_seed</strong> <em>(gnutls_srp_server_credentials_t <var>cred</var>, const gnutls_datum_t * <var>seed</var>, unsigned int <var>salt_length</var>)</em></dt>
22268 <dd><p><var>cred</var>: is a <code>gnutls_srp_server_credentials_t</code>  structure
22269 </p>
22270 <p><var>seed</var>: is the seed data, only needs to be valid until the function
22271 returns; size of the seed must be greater than zero
22272 </p>
22273 <p><var>salt_length</var>: is the length of the generated fake salts
22274 </p>
22275 <p>This function sets the seed that is used to generate salts for
22276 invalid (non-existent) usernames.
22277 </p>
22278 <p>In order to prevent attackers from guessing valid usernames,
22279 when a user does not exist gnutls generates a salt and a verifier
22280 and proceeds with the protocol as usual.
22281 The authentication will ultimately fail, but the client cannot tell
22282 whether the username is valid (exists) or invalid.
22283 </p>
22284 <p>If an attacker learns the seed, given a salt (which is part of the
22285 handshake) which was generated when the seed was in use, it can tell
22286 whether or not the authentication failed because of an unknown username.
22287 This seed cannot be used to reveal application data or passwords.
22288 </p>
22289 <p><code>salt_length</code> should represent the salt length your application uses.
22290 Generating fake salts longer than 20 bytes is not supported.
22291 </p>
22292 <p>By default the seed is a random value, different each time a
22293 <code>gnutls_srp_server_credentials_t</code>  is allocated and fake salts are
22294 16 bytes long.
22295 </p>
22296 <p><strong>Since:</strong> 3.3.0
22297 </p></dd></dl>
22298
22299 <a name="gnutls_005fsrp_005fverifier-1"></a>
22300 <h4 class="subheading">gnutls_srp_verifier</h4>
22301 <a name="gnutls_005fsrp_005fverifier"></a><dl>
22302 <dt><a name="index-gnutls_005fsrp_005fverifier-1"></a>Function: <em>int</em> <strong>gnutls_srp_verifier</strong> <em>(const char * <var>username</var>, const char * <var>password</var>, const gnutls_datum_t * <var>salt</var>, const gnutls_datum_t * <var>generator</var>, const gnutls_datum_t * <var>prime</var>, gnutls_datum_t * <var>res</var>)</em></dt>
22303 <dd><p><var>username</var>: is the user&rsquo;s name
22304 </p>
22305 <p><var>password</var>: is the user&rsquo;s password
22306 </p>
22307 <p><var>salt</var>: should be some randomly generated bytes
22308 </p>
22309 <p><var>generator</var>: is the generator of the group
22310 </p>
22311 <p><var>prime</var>: is the group&rsquo;s prime
22312 </p>
22313 <p><var>res</var>: where the verifier will be stored.
22314 </p>
22315 <p>This function will create an SRP verifier, as specified in
22316 RFC2945.  The  <code>prime</code> and  <code>generator</code> should be one of the static
22317 parameters defined in gnutls/gnutls.h or may be generated.
22318 </p>
22319 <p>The verifier will be allocated with  <code>gnutls_malloc</code> () and will be stored in
22320  <code>res</code> using binary format.
22321 </p>
22322 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or an
22323 error code.
22324 </p></dd></dl>
22325
22326 <a name="gnutls_005fsrtp_005fget_005fkeys-1"></a>
22327 <h4 class="subheading">gnutls_srtp_get_keys</h4>
22328 <a name="gnutls_005fsrtp_005fget_005fkeys"></a><dl>
22329 <dt><a name="index-gnutls_005fsrtp_005fget_005fkeys-1"></a>Function: <em>int</em> <strong>gnutls_srtp_get_keys</strong> <em>(gnutls_session_t <var>session</var>, void * <var>key_material</var>, unsigned int <var>key_material_size</var>, gnutls_datum_t * <var>client_key</var>, gnutls_datum_t * <var>client_salt</var>, gnutls_datum_t * <var>server_key</var>, gnutls_datum_t * <var>server_salt</var>)</em></dt>
22330 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22331 </p>
22332 <p><var>key_material</var>: Space to hold the generated key material
22333 </p>
22334 <p><var>key_material_size</var>: The maximum size of the key material
22335 </p>
22336 <p><var>client_key</var>: The master client write key, pointing inside the key material
22337 </p>
22338 <p><var>client_salt</var>: The master client write salt, pointing inside the key material
22339 </p>
22340 <p><var>server_key</var>: The master server write key, pointing inside the key material
22341 </p>
22342 <p><var>server_salt</var>: The master server write salt, pointing inside the key material
22343 </p>
22344 <p>This is a helper function to generate the keying material for SRTP.
22345 It requires the space of the key material to be pre-allocated (should be at least
22346 2x the maximum key size and salt size). The  <code>client_key</code> ,  <code>client_salt</code> ,  <code>server_key</code> and  <code>server_salt</code> are convenience datums that point inside the key material. They may
22347 be <code>NULL</code> .
22348 </p>
22349 <p><strong>Returns:</strong> On success the size of the key material is returned,
22350 otherwise, <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the buffer given is not
22351 sufficient, or a negative error code.
22352 </p>
22353 <p>Since 3.1.4
22354 </p></dd></dl>
22355
22356 <a name="gnutls_005fsrtp_005fget_005fmki-1"></a>
22357 <h4 class="subheading">gnutls_srtp_get_mki</h4>
22358 <a name="gnutls_005fsrtp_005fget_005fmki"></a><dl>
22359 <dt><a name="index-gnutls_005fsrtp_005fget_005fmki"></a>Function: <em>int</em> <strong>gnutls_srtp_get_mki</strong> <em>(gnutls_session_t <var>session</var>, gnutls_datum_t * <var>mki</var>)</em></dt>
22360 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22361 </p>
22362 <p><var>mki</var>: will hold the MKI
22363 </p>
22364 <p>This function exports the negotiated Master Key Identifier,
22365 received by the peer if any. The returned value in  <code>mki</code> should be
22366 treated as constant and valid only during the session&rsquo;s lifetime.
22367 </p>
22368 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
22369 otherwise a negative error code is returned.
22370 </p>
22371 <p>Since 3.1.4
22372 </p></dd></dl>
22373
22374 <a name="gnutls_005fsrtp_005fget_005fprofile_005fid-1"></a>
22375 <h4 class="subheading">gnutls_srtp_get_profile_id</h4>
22376 <a name="gnutls_005fsrtp_005fget_005fprofile_005fid"></a><dl>
22377 <dt><a name="index-gnutls_005fsrtp_005fget_005fprofile_005fid"></a>Function: <em>int</em> <strong>gnutls_srtp_get_profile_id</strong> <em>(const char * <var>name</var>, gnutls_srtp_profile_t * <var>profile</var>)</em></dt>
22378 <dd><p><var>name</var>: The name of the profile to look up
22379 </p>
22380 <p><var>profile</var>: Will hold the profile id
22381 </p>
22382 <p>This function allows you to look up a profile based on a string.
22383 </p>
22384 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
22385 otherwise a negative error code is returned.
22386 </p>
22387 <p>Since 3.1.4
22388 </p></dd></dl>
22389
22390 <a name="gnutls_005fsrtp_005fget_005fprofile_005fname-1"></a>
22391 <h4 class="subheading">gnutls_srtp_get_profile_name</h4>
22392 <a name="gnutls_005fsrtp_005fget_005fprofile_005fname"></a><dl>
22393 <dt><a name="index-gnutls_005fsrtp_005fget_005fprofile_005fname"></a>Function: <em>const char *</em> <strong>gnutls_srtp_get_profile_name</strong> <em>(gnutls_srtp_profile_t <var>profile</var>)</em></dt>
22394 <dd><p><var>profile</var>: The profile to look up a string for
22395 </p>
22396 <p>This function allows you to get the corresponding name for a
22397 SRTP protection profile.
22398 </p>
22399 <p><strong>Returns:</strong> On success, the name of a SRTP profile as a string,
22400 otherwise NULL.
22401 </p>
22402 <p>Since 3.1.4
22403 </p></dd></dl>
22404
22405 <a name="gnutls_005fsrtp_005fget_005fselected_005fprofile-1"></a>
22406 <h4 class="subheading">gnutls_srtp_get_selected_profile</h4>
22407 <a name="gnutls_005fsrtp_005fget_005fselected_005fprofile"></a><dl>
22408 <dt><a name="index-gnutls_005fsrtp_005fget_005fselected_005fprofile"></a>Function: <em>int</em> <strong>gnutls_srtp_get_selected_profile</strong> <em>(gnutls_session_t <var>session</var>, gnutls_srtp_profile_t * <var>profile</var>)</em></dt>
22409 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22410 </p>
22411 <p><var>profile</var>: will hold the profile
22412 </p>
22413 <p>This function allows you to get the negotiated SRTP profile.
22414 </p>
22415 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
22416 otherwise a negative error code is returned.
22417 </p>
22418 <p>Since 3.1.4
22419 </p></dd></dl>
22420
22421 <a name="gnutls_005fsrtp_005fset_005fmki-1"></a>
22422 <h4 class="subheading">gnutls_srtp_set_mki</h4>
22423 <a name="gnutls_005fsrtp_005fset_005fmki"></a><dl>
22424 <dt><a name="index-gnutls_005fsrtp_005fset_005fmki"></a>Function: <em>int</em> <strong>gnutls_srtp_set_mki</strong> <em>(gnutls_session_t <var>session</var>, const gnutls_datum_t * <var>mki</var>)</em></dt>
22425 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22426 </p>
22427 <p><var>mki</var>: holds the MKI
22428 </p>
22429 <p>This function sets the Master Key Identifier, to be
22430 used by this session (if any).
22431 </p>
22432 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
22433 otherwise a negative error code is returned.
22434 </p>
22435 <p>Since 3.1.4
22436 </p></dd></dl>
22437
22438 <a name="gnutls_005fsrtp_005fset_005fprofile-1"></a>
22439 <h4 class="subheading">gnutls_srtp_set_profile</h4>
22440 <a name="gnutls_005fsrtp_005fset_005fprofile"></a><dl>
22441 <dt><a name="index-gnutls_005fsrtp_005fset_005fprofile"></a>Function: <em>int</em> <strong>gnutls_srtp_set_profile</strong> <em>(gnutls_session_t <var>session</var>, gnutls_srtp_profile_t <var>profile</var>)</em></dt>
22442 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22443 </p>
22444 <p><var>profile</var>: is the profile id to add.
22445 </p>
22446 <p>This function is to be used by both clients and servers, to declare
22447 what SRTP profiles they support, to negotiate with the peer.
22448 </p>
22449 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
22450 otherwise a negative error code is returned.
22451 </p>
22452 <p>Since 3.1.4
22453 </p></dd></dl>
22454
22455 <a name="gnutls_005fsrtp_005fset_005fprofile_005fdirect-1"></a>
22456 <h4 class="subheading">gnutls_srtp_set_profile_direct</h4>
22457 <a name="gnutls_005fsrtp_005fset_005fprofile_005fdirect"></a><dl>
22458 <dt><a name="index-gnutls_005fsrtp_005fset_005fprofile_005fdirect"></a>Function: <em>int</em> <strong>gnutls_srtp_set_profile_direct</strong> <em>(gnutls_session_t <var>session</var>, const char * <var>profiles</var>, const char ** <var>err_pos</var>)</em></dt>
22459 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22460 </p>
22461 <p><var>profiles</var>: is a string that contains the supported SRTP profiles,
22462 separated by colons.
22463 </p>
22464 <p><var>err_pos</var>: In case of an error this will have the position in the string the error occured, may be NULL.
22465 </p>
22466 <p>This function is to be used by both clients and servers, to declare
22467 what SRTP profiles they support, to negotiate with the peer.
22468 </p>
22469 <p><strong>Returns:</strong> On syntax error <code>GNUTLS_E_INVALID_REQUEST</code>  is returned,
22470 <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
22471 </p>
22472 <p>Since 3.1.4
22473 </p></dd></dl>
22474
22475 <a name="gnutls_005fstore_005fcommitment-1"></a>
22476 <h4 class="subheading">gnutls_store_commitment</h4>
22477 <a name="gnutls_005fstore_005fcommitment"></a><dl>
22478 <dt><a name="index-gnutls_005fstore_005fcommitment-1"></a>Function: <em>int</em> <strong>gnutls_store_commitment</strong> <em>(const char * <var>db_name</var>, gnutls_tdb_t <var>tdb</var>, const char * <var>host</var>, const char * <var>service</var>, gnutls_digest_algorithm_t <var>hash_algo</var>, const gnutls_datum_t * <var>hash</var>, time_t <var>expiration</var>, unsigned int <var>flags</var>)</em></dt>
22479 <dd><p><var>db_name</var>: A file specifying the stored keys (use NULL for the default)
22480 </p>
22481 <p><var>tdb</var>: A storage structure or NULL to use the default
22482 </p>
22483 <p><var>host</var>: The peer&rsquo;s name
22484 </p>
22485 <p><var>service</var>: non-NULL if this key is specific to a service (e.g. http)
22486 </p>
22487 <p><var>hash_algo</var>: The hash algorithm type
22488 </p>
22489 <p><var>hash</var>: The raw hash
22490 </p>
22491 <p><var>expiration</var>: The expiration time (use 0 to disable expiration)
22492 </p>
22493 <p><var>flags</var>: should be 0.
22494 </p>
22495 <p>This function will store the provided hash commitment to
22496 the list of stored public keys. The key with the given
22497 hash will be considered valid until the provided expiration time.
22498 </p>
22499 <p>The  <code>store</code> variable if non-null specifies a custom backend for
22500 the storage of entries. If it is NULL then the
22501 default file backend will be used.
22502 </p>
22503 <p>Note that this function is not thread safe with the default backend.
22504 </p>
22505 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
22506 negative error value.
22507 </p>
22508 <p><strong>Since:</strong> 3.0
22509 </p></dd></dl>
22510
22511 <a name="gnutls_005fstore_005fpubkey-1"></a>
22512 <h4 class="subheading">gnutls_store_pubkey</h4>
22513 <a name="gnutls_005fstore_005fpubkey"></a><dl>
22514 <dt><a name="index-gnutls_005fstore_005fpubkey-1"></a>Function: <em>int</em> <strong>gnutls_store_pubkey</strong> <em>(const char * <var>db_name</var>, gnutls_tdb_t <var>tdb</var>, const char * <var>host</var>, const char * <var>service</var>, gnutls_certificate_type_t <var>cert_type</var>, const gnutls_datum_t * <var>cert</var>, time_t <var>expiration</var>, unsigned int <var>flags</var>)</em></dt>
22515 <dd><p><var>db_name</var>: A file specifying the stored keys (use NULL for the default)
22516 </p>
22517 <p><var>tdb</var>: A storage structure or NULL to use the default
22518 </p>
22519 <p><var>host</var>: The peer&rsquo;s name
22520 </p>
22521 <p><var>service</var>: non-NULL if this key is specific to a service (e.g. http)
22522 </p>
22523 <p><var>cert_type</var>: The type of the certificate
22524 </p>
22525 <p><var>cert</var>: The data of the certificate
22526 </p>
22527 <p><var>expiration</var>: The expiration time (use 0 to disable expiration)
22528 </p>
22529 <p><var>flags</var>: should be 0.
22530 </p>
22531 <p>This function will store the provided (raw or DER-encoded) certificate to
22532 the list of stored public keys. The key will be considered valid until
22533 the provided expiration time.
22534 </p>
22535 <p>The  <code>store</code> variable if non-null specifies a custom backend for
22536 the storage of entries. If it is NULL then the
22537 default file backend will be used.
22538 </p>
22539 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
22540 negative error value.
22541 </p>
22542 <p><strong>Since:</strong> 3.0.13
22543 </p></dd></dl>
22544
22545 <a name="gnutls_005fstrerror-1"></a>
22546 <h4 class="subheading">gnutls_strerror</h4>
22547 <a name="gnutls_005fstrerror"></a><dl>
22548 <dt><a name="index-gnutls_005fstrerror"></a>Function: <em>const char *</em> <strong>gnutls_strerror</strong> <em>(int <var>error</var>)</em></dt>
22549 <dd><p><var>error</var>: is a GnuTLS error code, a negative error code
22550 </p>
22551 <p>This function is similar to strerror.  The difference is that it
22552 accepts an error number returned by a gnutls function; In case of
22553 an unknown error a descriptive string is sent instead of <code>NULL</code> .
22554 </p>
22555 <p>Error codes are always a negative error code.
22556 </p>
22557 <p><strong>Returns:</strong> A string explaining the GnuTLS error message.
22558 </p></dd></dl>
22559
22560 <a name="gnutls_005fstrerror_005fname-1"></a>
22561 <h4 class="subheading">gnutls_strerror_name</h4>
22562 <a name="gnutls_005fstrerror_005fname"></a><dl>
22563 <dt><a name="index-gnutls_005fstrerror_005fname"></a>Function: <em>const char *</em> <strong>gnutls_strerror_name</strong> <em>(int <var>error</var>)</em></dt>
22564 <dd><p><var>error</var>: is an error returned by a gnutls function.
22565 </p>
22566 <p>Return the GnuTLS error code define as a string.  For example,
22567 gnutls_strerror_name (GNUTLS_E_DH_PRIME_UNACCEPTABLE) will return
22568 the string &quot;GNUTLS_E_DH_PRIME_UNACCEPTABLE&quot;.
22569 </p>
22570 <p><strong>Returns:</strong> A string corresponding to the symbol name of the error
22571 code.
22572 </p>
22573 <p><strong>Since:</strong> 2.6.0
22574 </p></dd></dl>
22575
22576 <a name="gnutls_005fsupplemental_005fget_005fname-1"></a>
22577 <h4 class="subheading">gnutls_supplemental_get_name</h4>
22578 <a name="gnutls_005fsupplemental_005fget_005fname"></a><dl>
22579 <dt><a name="index-gnutls_005fsupplemental_005fget_005fname"></a>Function: <em>const char     *</em> <strong>gnutls_supplemental_get_name</strong> <em>(gnutls_supplemental_data_format_type_t       <var>type</var>)</em></dt>
22580 <dd><p><var>type</var>: is a supplemental data format type
22581 </p>
22582 <p>Convert a <code>gnutls_supplemental_data_format_type_t</code>  value to a
22583 string.
22584 </p>
22585 <p><strong>Returns:</strong> a string that contains the name of the specified
22586 supplemental data format type, or <code>NULL</code>  for unknown types.
22587 </p></dd></dl>
22588
22589 <a name="gnutls_005ftdb_005fdeinit-1"></a>
22590 <h4 class="subheading">gnutls_tdb_deinit</h4>
22591 <a name="gnutls_005ftdb_005fdeinit"></a><dl>
22592 <dt><a name="index-gnutls_005ftdb_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_tdb_deinit</strong> <em>(gnutls_tdb_t <var>tdb</var>)</em></dt>
22593 <dd><p><var>tdb</var>: The structure to be deinitialized
22594 </p>
22595 <p>This function will deinitialize a public key trust storage structure.
22596 </p></dd></dl>
22597
22598 <a name="gnutls_005ftdb_005finit-1"></a>
22599 <h4 class="subheading">gnutls_tdb_init</h4>
22600 <a name="gnutls_005ftdb_005finit"></a><dl>
22601 <dt><a name="index-gnutls_005ftdb_005finit"></a>Function: <em>int</em> <strong>gnutls_tdb_init</strong> <em>(gnutls_tdb_t * <var>tdb</var>)</em></dt>
22602 <dd><p><var>tdb</var>: The structure to be initialized
22603 </p>
22604 <p>This function will initialize a public key trust storage structure.
22605 </p>
22606 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
22607 negative error value.
22608 </p></dd></dl>
22609
22610 <a name="gnutls_005ftdb_005fset_005fstore_005fcommitment_005ffunc-1"></a>
22611 <h4 class="subheading">gnutls_tdb_set_store_commitment_func</h4>
22612 <a name="gnutls_005ftdb_005fset_005fstore_005fcommitment_005ffunc"></a><dl>
22613 <dt><a name="index-gnutls_005ftdb_005fset_005fstore_005fcommitment_005ffunc"></a>Function: <em>void</em> <strong>gnutls_tdb_set_store_commitment_func</strong> <em>(gnutls_tdb_t <var>tdb</var>, gnutls_tdb_store_commitment_func        <var>cstore</var>)</em></dt>
22614 <dd><p><var>tdb</var>: The trust storage
22615 </p>
22616 <p><var>cstore</var>: The commitment storage function
22617 </p>
22618 <p>This function will associate a commitment (hash) storage function with the
22619 trust storage structure. The function is of the following form.
22620 </p>
22621 <p>int gnutls_tdb_store_commitment_func(const char* db_name, const char* host,
22622 const char* service, time_t expiration,
22623 gnutls_digest_algorithm_t, const gnutls_datum_t* hash);
22624 </p>
22625 <p>The  <code>db_name</code> should be used to pass any private data to this function.
22626 </p></dd></dl>
22627
22628 <a name="gnutls_005ftdb_005fset_005fstore_005ffunc-1"></a>
22629 <h4 class="subheading">gnutls_tdb_set_store_func</h4>
22630 <a name="gnutls_005ftdb_005fset_005fstore_005ffunc"></a><dl>
22631 <dt><a name="index-gnutls_005ftdb_005fset_005fstore_005ffunc"></a>Function: <em>void</em> <strong>gnutls_tdb_set_store_func</strong> <em>(gnutls_tdb_t <var>tdb</var>, gnutls_tdb_store_func <var>store</var>)</em></dt>
22632 <dd><p><var>tdb</var>: The trust storage
22633 </p>
22634 <p><var>store</var>: The storage function
22635 </p>
22636 <p>This function will associate a storage function with the
22637 trust storage structure. The function is of the following form.
22638 </p>
22639 <p>int gnutls_tdb_store_func(const char* db_name, const char* host,
22640 const char* service, time_t expiration,
22641 const gnutls_datum_t* pubkey);
22642 </p>
22643 <p>The  <code>db_name</code> should be used to pass any private data to this function.
22644 </p></dd></dl>
22645
22646 <a name="gnutls_005ftdb_005fset_005fverify_005ffunc-1"></a>
22647 <h4 class="subheading">gnutls_tdb_set_verify_func</h4>
22648 <a name="gnutls_005ftdb_005fset_005fverify_005ffunc"></a><dl>
22649 <dt><a name="index-gnutls_005ftdb_005fset_005fverify_005ffunc"></a>Function: <em>void</em> <strong>gnutls_tdb_set_verify_func</strong> <em>(gnutls_tdb_t <var>tdb</var>, gnutls_tdb_verify_func <var>verify</var>)</em></dt>
22650 <dd><p><var>tdb</var>: The trust storage
22651 </p>
22652 <p><var>verify</var>: The verification function
22653 </p>
22654 <p>This function will associate a retrieval function with the
22655 trust storage structure. The function is of the following form.
22656 </p>
22657 <p>int gnutls_tdb_verify_func(const char* db_name, const char* host,
22658 const char* service, const gnutls_datum_t* pubkey);
22659 </p>
22660 <p>The verify function should return zero on a match, <code>GNUTLS_E_CERTIFICATE_KEY_MISMATCH</code>
22661 if there is a mismatch and any other negative error code otherwise.
22662 </p>
22663 <p>The  <code>db_name</code> should be used to pass any private data to this function.
22664 </p></dd></dl>
22665
22666 <a name="gnutls_005ftransport_005fget_005fint-1"></a>
22667 <h4 class="subheading">gnutls_transport_get_int</h4>
22668 <a name="gnutls_005ftransport_005fget_005fint"></a><dl>
22669 <dt><a name="index-gnutls_005ftransport_005fget_005fint"></a>Function: <em>int</em> <strong>gnutls_transport_get_int</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
22670 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22671 </p>
22672 <p>Used to get the first argument of the transport function (like
22673 PUSH and PULL).  This must have been set using
22674 <code>gnutls_transport_set_int()</code> .
22675 </p>
22676 <p><strong>Returns:</strong> The first argument of the transport function.
22677 </p>
22678 <p><strong>Since:</strong> 3.1.9
22679 </p></dd></dl>
22680
22681 <a name="gnutls_005ftransport_005fget_005fint2-1"></a>
22682 <h4 class="subheading">gnutls_transport_get_int2</h4>
22683 <a name="gnutls_005ftransport_005fget_005fint2"></a><dl>
22684 <dt><a name="index-gnutls_005ftransport_005fget_005fint2"></a>Function: <em>void</em> <strong>gnutls_transport_get_int2</strong> <em>(gnutls_session_t <var>session</var>, int * <var>recv_int</var>, int * <var>send_int</var>)</em></dt>
22685 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22686 </p>
22687 <p><var>recv_int</var>: will hold the value for the pull function
22688 </p>
22689 <p><var>send_int</var>: will hold the value for the push function
22690 </p>
22691 <p>Used to get the arguments of the transport functions (like PUSH
22692 and PULL).  These should have been set using
22693 <code>gnutls_transport_set_int2()</code> .
22694 </p>
22695 <p><strong>Since:</strong> 3.1.9
22696 </p></dd></dl>
22697
22698 <a name="gnutls_005ftransport_005fget_005fptr-1"></a>
22699 <h4 class="subheading">gnutls_transport_get_ptr</h4>
22700 <a name="gnutls_005ftransport_005fget_005fptr"></a><dl>
22701 <dt><a name="index-gnutls_005ftransport_005fget_005fptr"></a>Function: <em>gnutls_transport_ptr_t</em> <strong>gnutls_transport_get_ptr</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
22702 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22703 </p>
22704 <p>Used to get the first argument of the transport function (like
22705 PUSH and PULL).  This must have been set using
22706 <code>gnutls_transport_set_ptr()</code> .
22707 </p>
22708 <p><strong>Returns:</strong> The first argument of the transport function.
22709 </p></dd></dl>
22710
22711 <a name="gnutls_005ftransport_005fget_005fptr2-1"></a>
22712 <h4 class="subheading">gnutls_transport_get_ptr2</h4>
22713 <a name="gnutls_005ftransport_005fget_005fptr2"></a><dl>
22714 <dt><a name="index-gnutls_005ftransport_005fget_005fptr2"></a>Function: <em>void</em> <strong>gnutls_transport_get_ptr2</strong> <em>(gnutls_session_t <var>session</var>, gnutls_transport_ptr_t * <var>recv_ptr</var>, gnutls_transport_ptr_t * <var>send_ptr</var>)</em></dt>
22715 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22716 </p>
22717 <p><var>recv_ptr</var>: will hold the value for the pull function
22718 </p>
22719 <p><var>send_ptr</var>: will hold the value for the push function
22720 </p>
22721 <p>Used to get the arguments of the transport functions (like PUSH
22722 and PULL).  These should have been set using
22723 <code>gnutls_transport_set_ptr2()</code> .
22724 </p></dd></dl>
22725
22726 <a name="gnutls_005ftransport_005fset_005ferrno-1"></a>
22727 <h4 class="subheading">gnutls_transport_set_errno</h4>
22728 <a name="gnutls_005ftransport_005fset_005ferrno"></a><dl>
22729 <dt><a name="index-gnutls_005ftransport_005fset_005ferrno-1"></a>Function: <em>void</em> <strong>gnutls_transport_set_errno</strong> <em>(gnutls_session_t <var>session</var>, int <var>err</var>)</em></dt>
22730 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22731 </p>
22732 <p><var>err</var>: error value to store in session-specific errno variable.
22733 </p>
22734 <p>Store  <code>err</code> in the session-specific errno variable.  Useful values
22735 for  <code>err</code> are EINTR, EAGAIN and EMSGSIZE, other values are treated will be
22736 treated as real errors in the push/pull function.
22737 </p>
22738 <p>This function is useful in replacement push and pull functions set by
22739 <code>gnutls_transport_set_push_function()</code>  and
22740 <code>gnutls_transport_set_pull_function()</code>  under Windows, where the
22741 replacements may not have access to the same  <code>errno</code> variable that is used by GnuTLS (e.g., the application is linked to
22742 msvcr71.dll and gnutls is linked to msvcrt.dll).
22743 </p></dd></dl>
22744
22745 <a name="gnutls_005ftransport_005fset_005ferrno_005ffunction-1"></a>
22746 <h4 class="subheading">gnutls_transport_set_errno_function</h4>
22747 <a name="gnutls_005ftransport_005fset_005ferrno_005ffunction"></a><dl>
22748 <dt><a name="index-gnutls_005ftransport_005fset_005ferrno_005ffunction"></a>Function: <em>void</em> <strong>gnutls_transport_set_errno_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_errno_func <var>errno_func</var>)</em></dt>
22749 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22750 </p>
22751 <p><var>errno_func</var>: a callback function similar to <code>write()</code>
22752 </p>
22753 <p>This is the function where you set a function to retrieve errno
22754 after a failed push or pull operation.
22755 </p>
22756 <p><code>errno_func</code> is of the form,
22757 int (*gnutls_errno_func)(gnutls_transport_ptr_t);
22758 and should return the errno.
22759 </p>
22760 <p><strong>Since:</strong> 2.12.0
22761 </p></dd></dl>
22762
22763 <a name="gnutls_005ftransport_005fset_005fint-1"></a>
22764 <h4 class="subheading">gnutls_transport_set_int</h4>
22765 <a name="gnutls_005ftransport_005fset_005fint"></a><dl>
22766 <dt><a name="index-gnutls_005ftransport_005fset_005fint"></a>Function: <em>void</em> <strong>gnutls_transport_set_int</strong> <em>(gnutls_session_t <var>session</var>, int <var>i</var>)</em></dt>
22767 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22768 </p>
22769 <p><var>i</var>: is the value.
22770 </p>
22771 <p>Used to set the first argument of the transport function (for push
22772 and pull callbacks) for berkeley style sockets.
22773 </p>
22774 <p><strong>Since:</strong> 3.1.9
22775 </p></dd></dl>
22776
22777 <a name="gnutls_005ftransport_005fset_005fint2-1"></a>
22778 <h4 class="subheading">gnutls_transport_set_int2</h4>
22779 <a name="gnutls_005ftransport_005fset_005fint2"></a><dl>
22780 <dt><a name="index-gnutls_005ftransport_005fset_005fint2"></a>Function: <em>void</em> <strong>gnutls_transport_set_int2</strong> <em>(gnutls_session_t <var>session</var>, int <var>recv_int</var>, int <var>send_int</var>)</em></dt>
22781 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22782 </p>
22783 <p><var>recv_int</var>: is the value for the pull function
22784 </p>
22785 <p><var>send_int</var>: is the value for the push function
22786 </p>
22787 <p>Used to set the first argument of the transport function (for push
22788 and pull callbacks), when using the berkeley style sockets.
22789 With this function you can set two different
22790 pointers for receiving and sending.
22791 </p>
22792 <p><strong>Since:</strong> 3.1.9
22793 </p></dd></dl>
22794
22795 <a name="gnutls_005ftransport_005fset_005fptr-1"></a>
22796 <h4 class="subheading">gnutls_transport_set_ptr</h4>
22797 <a name="gnutls_005ftransport_005fset_005fptr"></a><dl>
22798 <dt><a name="index-gnutls_005ftransport_005fset_005fptr"></a>Function: <em>void</em> <strong>gnutls_transport_set_ptr</strong> <em>(gnutls_session_t <var>session</var>, gnutls_transport_ptr_t <var>ptr</var>)</em></dt>
22799 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22800 </p>
22801 <p><var>ptr</var>: is the value.
22802 </p>
22803 <p>Used to set the first argument of the transport function (for push
22804 and pull callbacks). In berkeley style sockets this function will set the
22805 connection descriptor.
22806 </p></dd></dl>
22807
22808 <a name="gnutls_005ftransport_005fset_005fptr2-1"></a>
22809 <h4 class="subheading">gnutls_transport_set_ptr2</h4>
22810 <a name="gnutls_005ftransport_005fset_005fptr2"></a><dl>
22811 <dt><a name="index-gnutls_005ftransport_005fset_005fptr2"></a>Function: <em>void</em> <strong>gnutls_transport_set_ptr2</strong> <em>(gnutls_session_t <var>session</var>, gnutls_transport_ptr_t <var>recv_ptr</var>, gnutls_transport_ptr_t <var>send_ptr</var>)</em></dt>
22812 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22813 </p>
22814 <p><var>recv_ptr</var>: is the value for the pull function
22815 </p>
22816 <p><var>send_ptr</var>: is the value for the push function
22817 </p>
22818 <p>Used to set the first argument of the transport function (for push
22819 and pull callbacks). In berkeley style sockets this function will set the
22820 connection descriptor.  With this function you can use two different
22821 pointers for receiving and sending.
22822 </p></dd></dl>
22823
22824 <a name="gnutls_005ftransport_005fset_005fpull_005ffunction-1"></a>
22825 <h4 class="subheading">gnutls_transport_set_pull_function</h4>
22826 <a name="gnutls_005ftransport_005fset_005fpull_005ffunction"></a><dl>
22827 <dt><a name="index-gnutls_005ftransport_005fset_005fpull_005ffunction-1"></a>Function: <em>void</em> <strong>gnutls_transport_set_pull_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_pull_func <var>pull_func</var>)</em></dt>
22828 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22829 </p>
22830 <p><var>pull_func</var>: a callback function similar to <code>read()</code>
22831 </p>
22832 <p>This is the function where you set a function for gnutls to receive
22833 data.  Normally, if you use berkeley style sockets, do not need to
22834 use this function since the default recv(2) will probably be ok.
22835 The callback should return 0 on connection termination, a positive
22836 number indicating the number of bytes received, and -1 on error.
22837 </p>
22838 <p><code>gnutls_pull_func</code> is of the form,
22839 ssize_t (*gnutls_pull_func)(gnutls_transport_ptr_t, void*, size_t);
22840 </p></dd></dl>
22841
22842 <a name="gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction-1"></a>
22843 <h4 class="subheading">gnutls_transport_set_pull_timeout_function</h4>
22844 <a name="gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction"></a><dl>
22845 <dt><a name="index-gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction-2"></a>Function: <em>void</em> <strong>gnutls_transport_set_pull_timeout_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_pull_timeout_func <var>func</var>)</em></dt>
22846 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22847 </p>
22848 <p><var>func</var>: a callback function
22849 </p>
22850 <p>This is the function where you set a function for gnutls to know
22851 whether data are ready to be received. It should wait for data a
22852 given time frame in milliseconds. The callback should return 0 on
22853 timeout, a positive number if data can be received, and -1 on error.
22854 You&rsquo;ll need to override this function if <code>select()</code>  is not suitable
22855 for the provided transport calls.
22856 </p>
22857 <p>As with <code>select()</code> , if the timeout value is zero the callback should return
22858 zero if no data are immediately available.
22859 </p>
22860 <p><code>gnutls_pull_timeout_func</code> is of the form,
22861 int (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int ms);
22862 </p>
22863 <p><strong>Since:</strong> 3.0
22864 </p></dd></dl>
22865
22866 <a name="gnutls_005ftransport_005fset_005fpush_005ffunction-1"></a>
22867 <h4 class="subheading">gnutls_transport_set_push_function</h4>
22868 <a name="gnutls_005ftransport_005fset_005fpush_005ffunction"></a><dl>
22869 <dt><a name="index-gnutls_005ftransport_005fset_005fpush_005ffunction-1"></a>Function: <em>void</em> <strong>gnutls_transport_set_push_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_push_func <var>push_func</var>)</em></dt>
22870 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22871 </p>
22872 <p><var>push_func</var>: a callback function similar to <code>write()</code>
22873 </p>
22874 <p>This is the function where you set a push function for gnutls to
22875 use in order to send data.  If you are going to use berkeley style
22876 sockets, you do not need to use this function since the default
22877 send(2) will probably be ok.  Otherwise you should specify this
22878 function for gnutls to be able to send data.
22879 The callback should return a positive number indicating the
22880 bytes sent, and -1 on error.
22881 </p>
22882 <p><code>push_func</code> is of the form,
22883 ssize_t (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t);
22884 </p></dd></dl>
22885
22886 <a name="gnutls_005ftransport_005fset_005fvec_005fpush_005ffunction-1"></a>
22887 <h4 class="subheading">gnutls_transport_set_vec_push_function</h4>
22888 <a name="gnutls_005ftransport_005fset_005fvec_005fpush_005ffunction"></a><dl>
22889 <dt><a name="index-gnutls_005ftransport_005fset_005fvec_005fpush_005ffunction-1"></a>Function: <em>void</em> <strong>gnutls_transport_set_vec_push_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_vec_push_func <var>vec_func</var>)</em></dt>
22890 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
22891 </p>
22892 <p><var>vec_func</var>: a callback function similar to <code>writev()</code>
22893 </p>
22894 <p>Using this function you can override the default writev(2)
22895 function for gnutls to send data. Setting this callback
22896 instead of <code>gnutls_transport_set_push_function()</code>  is recommended
22897 since it introduces less overhead in the TLS handshake process.
22898 </p>
22899 <p><code>vec_func</code> is of the form,
22900 ssize_t (*gnutls_vec_push_func) (gnutls_transport_ptr_t, const giovec_t * iov, int iovcnt);
22901 </p>
22902 <p><strong>Since:</strong> 2.12.0
22903 </p></dd></dl>
22904
22905 <a name="gnutls_005furl_005fis_005fsupported-1"></a>
22906 <h4 class="subheading">gnutls_url_is_supported</h4>
22907 <a name="gnutls_005furl_005fis_005fsupported"></a><dl>
22908 <dt><a name="index-gnutls_005furl_005fis_005fsupported-1"></a>Function: <em>int</em> <strong>gnutls_url_is_supported</strong> <em>(const char * <var>url</var>)</em></dt>
22909 <dd><p><var>url</var>: A PKCS 11 url
22910 </p>
22911 <p>Check whether url is supported.  Depending on the system libraries
22912 GnuTLS may support pkcs11 or tpmkey URLs.
22913 </p>
22914 <p><strong>Returns:</strong> return non-zero if the given URL is supported, and zero if
22915 it is not known.
22916 </p>
22917 <p><strong>Since:</strong> 3.1.0
22918 </p></dd></dl>
22919
22920 <a name="gnutls_005fverify_005fstored_005fpubkey-1"></a>
22921 <h4 class="subheading">gnutls_verify_stored_pubkey</h4>
22922 <a name="gnutls_005fverify_005fstored_005fpubkey"></a><dl>
22923 <dt><a name="index-gnutls_005fverify_005fstored_005fpubkey-1"></a>Function: <em>int</em> <strong>gnutls_verify_stored_pubkey</strong> <em>(const char * <var>db_name</var>, gnutls_tdb_t <var>tdb</var>, const char * <var>host</var>, const char * <var>service</var>, gnutls_certificate_type_t <var>cert_type</var>, const gnutls_datum_t * <var>cert</var>, unsigned int <var>flags</var>)</em></dt>
22924 <dd><p><var>db_name</var>: A file specifying the stored keys (use NULL for the default)
22925 </p>
22926 <p><var>tdb</var>: A storage structure or NULL to use the default
22927 </p>
22928 <p><var>host</var>: The peer&rsquo;s name
22929 </p>
22930 <p><var>service</var>: non-NULL if this key is specific to a service (e.g. http)
22931 </p>
22932 <p><var>cert_type</var>: The type of the certificate
22933 </p>
22934 <p><var>cert</var>: The raw (der) data of the certificate
22935 </p>
22936 <p><var>flags</var>: should be 0.
22937 </p>
22938 <p>This function will try to verify the provided (raw or DER-encoded) certificate
22939 using a list of stored public keys.  The  <code>service</code> field if non-NULL should
22940 be a port number.
22941 </p>
22942 <p>The  <code>retrieve</code> variable if non-null specifies a custom backend for
22943 the retrieval of entries. If it is NULL then the
22944 default file backend will be used. In POSIX-like systems the
22945 file backend uses the $HOME/.gnutls/known_hosts file.
22946 </p>
22947 <p>Note that if the custom storage backend is provided the
22948 retrieval function should return <code>GNUTLS_E_CERTIFICATE_KEY_MISMATCH</code>
22949 if the host/service pair is found but key doesn&rsquo;t match,
22950 <code>GNUTLS_E_NO_CERTIFICATE_FOUND</code>  if no such host/service with
22951 the given key is found, and 0 if it was found. The storage
22952 function should return 0 on success.
22953 </p>
22954 <p><strong>Returns:</strong> If no associated public key is found
22955 then <code>GNUTLS_E_NO_CERTIFICATE_FOUND</code>  will be returned. If a key
22956 is found but does not match <code>GNUTLS_E_CERTIFICATE_KEY_MISMATCH</code>
22957 is returned. On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
22958 or a negative error value on other errors.
22959 </p>
22960 <p><strong>Since:</strong> 3.0.13
22961 </p></dd></dl>
22962
22963
22964 <hr>
22965 <a name="Datagram-TLS-API"></a>
22966 <div class="header">
22967 <p>
22968 Next: <a href="#X509-certificate-API" accesskey="n" rel="next">X509 certificate API</a>, Previous: <a href="#Core-TLS-API" accesskey="p" rel="prev">Core TLS API</a>, Up: <a href="#API-reference" accesskey="u" rel="up">API reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
22969 </div>
22970 <a name="Datagram-TLS-API-1"></a>
22971 <h3 class="section">E.2 Datagram TLS API</h3>
22972
22973 <p>The prototypes for the following functions lie in
22974 <samp>gnutls/dtls.h</samp>.
22975 </p>
22976
22977 <a name="gnutls_005fdtls_005fcookie_005fsend-1"></a>
22978 <h4 class="subheading">gnutls_dtls_cookie_send</h4>
22979 <a name="gnutls_005fdtls_005fcookie_005fsend"></a><dl>
22980 <dt><a name="index-gnutls_005fdtls_005fcookie_005fsend"></a>Function: <em>int</em> <strong>gnutls_dtls_cookie_send</strong> <em>(gnutls_datum_t * <var>key</var>, void * <var>client_data</var>, size_t <var>client_data_size</var>, gnutls_dtls_prestate_st * <var>prestate</var>, gnutls_transport_ptr_t <var>ptr</var>, gnutls_push_func <var>push_func</var>)</em></dt>
22981 <dd><p><var>key</var>: is a random key to be used at cookie generation
22982 </p>
22983 <p><var>client_data</var>: contains data identifying the client (i.e. address)
22984 </p>
22985 <p><var>client_data_size</var>: The size of client&rsquo;s data
22986 </p>
22987 <p><var>prestate</var>: The previous cookie returned by <code>gnutls_dtls_cookie_verify()</code>
22988 </p>
22989 <p><var>ptr</var>: A transport pointer to be used by  <code>push_func</code>
22990 </p>
22991 <p><var>push_func</var>: A function that will be used to reply
22992 </p>
22993 <p>This function can be used to prevent denial of service
22994 attacks to a DTLS server by requiring the client to
22995 reply using a cookie sent by this function. That way
22996 it can be ensured that a client we allocated resources
22997 for (i.e. <code>gnutls_session_t</code> ) is the one that the
22998 original incoming packet was originated from.
22999 </p>
23000 <p>This function must be called at the first incoming packet,
23001 prior to allocating any resources and must be succeeded
23002 by <code>gnutls_dtls_cookie_verify()</code> .
23003 </p>
23004 <p><strong>Returns:</strong> the number of bytes sent, or a negative error code.
23005 </p>
23006 <p><strong>Since:</strong> 3.0
23007 </p></dd></dl>
23008
23009 <a name="gnutls_005fdtls_005fcookie_005fverify-1"></a>
23010 <h4 class="subheading">gnutls_dtls_cookie_verify</h4>
23011 <a name="gnutls_005fdtls_005fcookie_005fverify"></a><dl>
23012 <dt><a name="index-gnutls_005fdtls_005fcookie_005fverify"></a>Function: <em>int</em> <strong>gnutls_dtls_cookie_verify</strong> <em>(gnutls_datum_t * <var>key</var>, void * <var>client_data</var>, size_t <var>client_data_size</var>, void * <var>_msg</var>, size_t <var>msg_size</var>, gnutls_dtls_prestate_st * <var>prestate</var>)</em></dt>
23013 <dd><p><var>key</var>: is a random key to be used at cookie generation
23014 </p>
23015 <p><var>client_data</var>: contains data identifying the client (i.e. address)
23016 </p>
23017 <p><var>client_data_size</var>: The size of client&rsquo;s data
23018 </p>
23019 <p><var>_msg</var>: An incoming message that initiates a connection.
23020 </p>
23021 <p><var>msg_size</var>: The size of the message.
23022 </p>
23023 <p><var>prestate</var>: The cookie of this client.
23024 </p>
23025 <p>This function will verify the received message for
23026 a valid cookie. If a valid cookie is returned then
23027 it should be associated with the session using
23028 <code>gnutls_dtls_prestate_set()</code> ;
23029 </p>
23030 <p>This function must be called after <code>gnutls_dtls_cookie_send()</code> .
23031 </p>
23032 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success, or a negative error code.
23033 </p>
23034 <p><strong>Since:</strong> 3.0
23035 </p></dd></dl>
23036
23037 <a name="gnutls_005fdtls_005fget_005fdata_005fmtu-1"></a>
23038 <h4 class="subheading">gnutls_dtls_get_data_mtu</h4>
23039 <a name="gnutls_005fdtls_005fget_005fdata_005fmtu"></a><dl>
23040 <dt><a name="index-gnutls_005fdtls_005fget_005fdata_005fmtu"></a>Function: <em>unsigned int</em> <strong>gnutls_dtls_get_data_mtu</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
23041 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
23042 </p>
23043 <p>This function will return the actual maximum transfer unit for
23044 application data. I.e. DTLS headers are subtracted from the
23045 actual MTU which is set using <code>gnutls_dtls_set_mtu()</code> .
23046 </p>
23047 <p><strong>Returns:</strong> the maximum allowed transfer unit.
23048 </p>
23049 <p><strong>Since:</strong> 3.0
23050 </p></dd></dl>
23051
23052 <a name="gnutls_005fdtls_005fget_005fmtu-1"></a>
23053 <h4 class="subheading">gnutls_dtls_get_mtu</h4>
23054 <a name="gnutls_005fdtls_005fget_005fmtu"></a><dl>
23055 <dt><a name="index-gnutls_005fdtls_005fget_005fmtu"></a>Function: <em>unsigned int</em> <strong>gnutls_dtls_get_mtu</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
23056 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
23057 </p>
23058 <p>This function will return the MTU size as set with
23059 <code>gnutls_dtls_set_mtu()</code> . This is not the actual MTU
23060 of data you can transmit. Use <code>gnutls_dtls_get_data_mtu()</code>
23061 for that reason.
23062 </p>
23063 <p><strong>Returns:</strong> the set maximum transfer unit.
23064 </p>
23065 <p><strong>Since:</strong> 3.0
23066 </p></dd></dl>
23067
23068 <a name="gnutls_005fdtls_005fget_005ftimeout-1"></a>
23069 <h4 class="subheading">gnutls_dtls_get_timeout</h4>
23070 <a name="gnutls_005fdtls_005fget_005ftimeout"></a><dl>
23071 <dt><a name="index-gnutls_005fdtls_005fget_005ftimeout-1"></a>Function: <em>unsigned int</em> <strong>gnutls_dtls_get_timeout</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
23072 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
23073 </p>
23074 <p>This function will return the milliseconds remaining
23075 for a retransmission of the previously sent handshake
23076 message. This function is useful when DTLS is used in
23077 non-blocking mode, to estimate when to call <code>gnutls_handshake()</code>
23078 if no packets have been received.
23079 </p>
23080 <p><strong>Returns:</strong> the remaining time in milliseconds.
23081 </p>
23082 <p><strong>Since:</strong> 3.0
23083 </p></dd></dl>
23084
23085 <a name="gnutls_005fdtls_005fprestate_005fset-1"></a>
23086 <h4 class="subheading">gnutls_dtls_prestate_set</h4>
23087 <a name="gnutls_005fdtls_005fprestate_005fset"></a><dl>
23088 <dt><a name="index-gnutls_005fdtls_005fprestate_005fset"></a>Function: <em>void</em> <strong>gnutls_dtls_prestate_set</strong> <em>(gnutls_session_t <var>session</var>, gnutls_dtls_prestate_st * <var>prestate</var>)</em></dt>
23089 <dd><p><var>session</var>: a new session
23090 </p>
23091 <p><var>prestate</var>: contains the client&rsquo;s prestate
23092 </p>
23093 <p>This function will associate the prestate acquired by
23094 the cookie authentication with the client, with the newly
23095 established session.
23096 </p>
23097 <p>This functions must be called after a successful <code>gnutls_dtls_cookie_verify()</code>
23098 and should be succeeded by the actual DTLS handshake using <code>gnutls_handshake()</code> .
23099 </p>
23100 <p><strong>Since:</strong> 3.0
23101 </p></dd></dl>
23102
23103 <a name="gnutls_005fdtls_005fset_005fdata_005fmtu-1"></a>
23104 <h4 class="subheading">gnutls_dtls_set_data_mtu</h4>
23105 <a name="gnutls_005fdtls_005fset_005fdata_005fmtu"></a><dl>
23106 <dt><a name="index-gnutls_005fdtls_005fset_005fdata_005fmtu"></a>Function: <em>int</em> <strong>gnutls_dtls_set_data_mtu</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>mtu</var>)</em></dt>
23107 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
23108 </p>
23109 <p><var>mtu</var>: The maximum unencrypted transfer unit of the session
23110 </p>
23111 <p>This function will set the maximum size of the *unencrypted* records
23112 which will be sent over a DTLS session. It is equivalent to calculating
23113 the DTLS packet overhead with the current encryption parameters, and
23114 calling <code>gnutls_dtls_set_mtu()</code>  with that value. In particular, this means
23115 that you may need to call this function again after any negotiation or
23116 renegotiation, in order to ensure that the MTU is still sufficient to
23117 account for the new protocol overhead.
23118 </p>
23119 <p>In most cases you only need to call <code>gnutls_dtls_set_mtu()</code>  with
23120 the maximum MTU of your transport layer.
23121 </p>
23122 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success, or a negative error code.
23123 </p>
23124 <p><strong>Since:</strong> 3.1
23125 </p></dd></dl>
23126
23127 <a name="gnutls_005fdtls_005fset_005fmtu-1"></a>
23128 <h4 class="subheading">gnutls_dtls_set_mtu</h4>
23129 <a name="gnutls_005fdtls_005fset_005fmtu"></a><dl>
23130 <dt><a name="index-gnutls_005fdtls_005fset_005fmtu"></a>Function: <em>void</em> <strong>gnutls_dtls_set_mtu</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>mtu</var>)</em></dt>
23131 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
23132 </p>
23133 <p><var>mtu</var>: The maximum transfer unit of the transport
23134 </p>
23135 <p>This function will set the maximum transfer unit of the transport
23136 that DTLS packets are sent over. Note that this should exclude
23137 the IP (or IPv6) and UDP headers. So for DTLS over IPv6 on an
23138 Ethenet device with MTU 1500, the DTLS MTU set with this function
23139 would be 1500 - 40 (IPV6 header) - 8 (UDP header) = 1452.
23140 </p>
23141 <p><strong>Since:</strong> 3.0
23142 </p></dd></dl>
23143
23144 <a name="gnutls_005fdtls_005fset_005ftimeouts-1"></a>
23145 <h4 class="subheading">gnutls_dtls_set_timeouts</h4>
23146 <a name="gnutls_005fdtls_005fset_005ftimeouts"></a><dl>
23147 <dt><a name="index-gnutls_005fdtls_005fset_005ftimeouts"></a>Function: <em>void</em> <strong>gnutls_dtls_set_timeouts</strong> <em>(gnutls_session_t <var>session</var>, unsigned int <var>retrans_timeout</var>, unsigned int <var>total_timeout</var>)</em></dt>
23148 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
23149 </p>
23150 <p><var>retrans_timeout</var>: The time at which a retransmission will occur in milliseconds
23151 </p>
23152 <p><var>total_timeout</var>: The time at which the connection will be aborted, in milliseconds.
23153 </p>
23154 <p>This function will set the timeouts required for the DTLS handshake
23155 protocol. The retransmission timeout is the time after which a
23156 message from the peer is not received, the previous messages will
23157 be retransmitted. The total timeout is the time after which the
23158 handshake will be aborted with <code>GNUTLS_E_TIMEDOUT</code> .
23159 </p>
23160 <p>The DTLS protocol recommends the values of 1 sec and 60 seconds
23161 respectively.
23162 </p>
23163 <p>To disable retransmissions set a  <code>retrans_timeout</code> larger than the  <code>total_timeout</code> .
23164 </p>
23165 <p><strong>Since:</strong> 3.0
23166 </p></dd></dl>
23167
23168 <a name="gnutls_005frecord_005fget_005fdiscarded-1"></a>
23169 <h4 class="subheading">gnutls_record_get_discarded</h4>
23170 <a name="gnutls_005frecord_005fget_005fdiscarded"></a><dl>
23171 <dt><a name="index-gnutls_005frecord_005fget_005fdiscarded"></a>Function: <em>unsigned int</em> <strong>gnutls_record_get_discarded</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
23172 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
23173 </p>
23174 <p>Returns the number of discarded packets in a
23175 DTLS connection.
23176 </p>
23177 <p><strong>Returns:</strong> The number of discarded packets.
23178 </p>
23179 <p><strong>Since:</strong> 3.0
23180 </p></dd></dl>
23181
23182
23183 <hr>
23184 <a name="X509-certificate-API"></a>
23185 <div class="header">
23186 <p>
23187 Next: <a href="#OCSP-API" accesskey="n" rel="next">OCSP API</a>, Previous: <a href="#Datagram-TLS-API" accesskey="p" rel="prev">Datagram TLS API</a>, Up: <a href="#API-reference" accesskey="u" rel="up">API reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
23188 </div>
23189 <a name="X_002e509-certificate-API"></a>
23190 <h3 class="section">E.3 <acronym>X.509</acronym> certificate API</h3>
23191 <a name="index-X_002e509-Functions"></a>
23192
23193 <p>The following functions are to be used for <acronym>X.509</acronym> certificate handling.
23194 Their prototypes lie in <samp>gnutls/x509.h</samp>.
23195 </p>
23196
23197 <a name="gnutls_005fcertificate_005fset_005ftrust_005flist-1"></a>
23198 <h4 class="subheading">gnutls_certificate_set_trust_list</h4>
23199 <a name="gnutls_005fcertificate_005fset_005ftrust_005flist"></a><dl>
23200 <dt><a name="index-gnutls_005fcertificate_005fset_005ftrust_005flist"></a>Function: <em>void</em> <strong>gnutls_certificate_set_trust_list</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, gnutls_x509_trust_list_t <var>tlist</var>, unsigned <var>flags</var>)</em></dt>
23201 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
23202 </p>
23203 <p><var>tlist</var>: is a <code>gnutls_x509_trust_list_t</code>  structure
23204 </p>
23205 <p><var>flags</var>: must be zero
23206 </p>
23207 <p>This function sets a trust list in the gnutls_certificate_credentials_t structure.
23208 </p>
23209 <p>Note that the  <code>tlist</code> will become part of the credentials
23210 structure and must not be deallocated. It will be automatically deallocated
23211 when the  <code>res</code> structure is deinitialized.
23212 </p>
23213 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success, or a negative error code.
23214 </p>
23215 <p><strong>Since:</strong> 3.2.2
23216 </p></dd></dl>
23217
23218 <a name="gnutls_005fpkcs7_005fdeinit-1"></a>
23219 <h4 class="subheading">gnutls_pkcs7_deinit</h4>
23220 <a name="gnutls_005fpkcs7_005fdeinit"></a><dl>
23221 <dt><a name="index-gnutls_005fpkcs7_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_pkcs7_deinit</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>)</em></dt>
23222 <dd><p><var>pkcs7</var>: The structure to be initialized
23223 </p>
23224 <p>This function will deinitialize a PKCS7 structure.
23225 </p></dd></dl>
23226
23227 <a name="gnutls_005fpkcs7_005fdelete_005fcrl-1"></a>
23228 <h4 class="subheading">gnutls_pkcs7_delete_crl</h4>
23229 <a name="gnutls_005fpkcs7_005fdelete_005fcrl"></a><dl>
23230 <dt><a name="index-gnutls_005fpkcs7_005fdelete_005fcrl"></a>Function: <em>int</em> <strong>gnutls_pkcs7_delete_crl</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>, int <var>indx</var>)</em></dt>
23231 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code>  structure
23232 </p>
23233 <p><var>indx</var>: the index of the crl to delete
23234 </p>
23235 <p>This function will delete a crl from a PKCS7 or RFC2630 crl set.
23236 Index starts from 0. Returns 0 on success.
23237 </p>
23238 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23239 negative error value.
23240 </p></dd></dl>
23241
23242 <a name="gnutls_005fpkcs7_005fdelete_005fcrt-1"></a>
23243 <h4 class="subheading">gnutls_pkcs7_delete_crt</h4>
23244 <a name="gnutls_005fpkcs7_005fdelete_005fcrt"></a><dl>
23245 <dt><a name="index-gnutls_005fpkcs7_005fdelete_005fcrt"></a>Function: <em>int</em> <strong>gnutls_pkcs7_delete_crt</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>, int <var>indx</var>)</em></dt>
23246 <dd><p><var>pkcs7</var>: should contain a gnutls_pkcs7_t structure
23247 </p>
23248 <p><var>indx</var>: the index of the certificate to delete
23249 </p>
23250 <p>This function will delete a certificate from a PKCS7 or RFC2630
23251 certificate set.  Index starts from 0. Returns 0 on success.
23252 </p>
23253 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23254 negative error value.
23255 </p></dd></dl>
23256
23257 <a name="gnutls_005fpkcs7_005fexport-1"></a>
23258 <h4 class="subheading">gnutls_pkcs7_export</h4>
23259 <a name="gnutls_005fpkcs7_005fexport"></a><dl>
23260 <dt><a name="index-gnutls_005fpkcs7_005fexport"></a>Function: <em>int</em> <strong>gnutls_pkcs7_export</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>, gnutls_x509_crt_fmt_t <var>format</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
23261 <dd><p><var>pkcs7</var>: Holds the pkcs7 structure
23262 </p>
23263 <p><var>format</var>: the format of output params. One of PEM or DER.
23264 </p>
23265 <p><var>output_data</var>: will contain a structure PEM or DER encoded
23266 </p>
23267 <p><var>output_data_size</var>: holds the size of output_data (and will be
23268 replaced by the actual size of parameters)
23269 </p>
23270 <p>This function will export the pkcs7 structure to DER or PEM format.
23271 </p>
23272 <p>If the buffer provided is not long enough to hold the output, then
23273 * <code>output_data_size</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>
23274 will be returned.
23275 </p>
23276 <p>If the structure is PEM encoded, it will have a header
23277 of &quot;BEGIN PKCS7&quot;.
23278 </p>
23279 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23280 negative error value.
23281 </p></dd></dl>
23282
23283 <a name="gnutls_005fpkcs7_005fexport2-1"></a>
23284 <h4 class="subheading">gnutls_pkcs7_export2</h4>
23285 <a name="gnutls_005fpkcs7_005fexport2"></a><dl>
23286 <dt><a name="index-gnutls_005fpkcs7_005fexport2"></a>Function: <em>int</em> <strong>gnutls_pkcs7_export2</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>, gnutls_x509_crt_fmt_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
23287 <dd><p><var>pkcs7</var>: Holds the pkcs7 structure
23288 </p>
23289 <p><var>format</var>: the format of output params. One of PEM or DER.
23290 </p>
23291 <p><var>out</var>: will contain a structure PEM or DER encoded
23292 </p>
23293 <p>This function will export the pkcs7 structure to DER or PEM format.
23294 </p>
23295 <p>The output buffer is allocated using <code>gnutls_malloc()</code> .
23296 </p>
23297 <p>If the structure is PEM encoded, it will have a header
23298 of &quot;BEGIN PKCS7&quot;.
23299 </p>
23300 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23301 negative error value.
23302 </p>
23303 <p><strong>Since:</strong> 3.1.3
23304 </p></dd></dl>
23305
23306 <a name="gnutls_005fpkcs7_005fget_005fcrl_005fcount-1"></a>
23307 <h4 class="subheading">gnutls_pkcs7_get_crl_count</h4>
23308 <a name="gnutls_005fpkcs7_005fget_005fcrl_005fcount"></a><dl>
23309 <dt><a name="index-gnutls_005fpkcs7_005fget_005fcrl_005fcount"></a>Function: <em>int</em> <strong>gnutls_pkcs7_get_crl_count</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>)</em></dt>
23310 <dd><p><var>pkcs7</var>: should contain a gnutls_pkcs7_t structure
23311 </p>
23312 <p>This function will return the number of certifcates in the PKCS7
23313 or RFC2630 crl set.
23314 </p>
23315 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23316 negative error value.
23317 </p></dd></dl>
23318
23319 <a name="gnutls_005fpkcs7_005fget_005fcrl_005fraw-1"></a>
23320 <h4 class="subheading">gnutls_pkcs7_get_crl_raw</h4>
23321 <a name="gnutls_005fpkcs7_005fget_005fcrl_005fraw"></a><dl>
23322 <dt><a name="index-gnutls_005fpkcs7_005fget_005fcrl_005fraw"></a>Function: <em>int</em> <strong>gnutls_pkcs7_get_crl_raw</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>, int <var>indx</var>, void * <var>crl</var>, size_t * <var>crl_size</var>)</em></dt>
23323 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code>  structure
23324 </p>
23325 <p><var>indx</var>: contains the index of the crl to extract
23326 </p>
23327 <p><var>crl</var>: the contents of the crl will be copied there (may be null)
23328 </p>
23329 <p><var>crl_size</var>: should hold the size of the crl
23330 </p>
23331 <p>This function will return a crl of the PKCS7 or RFC2630 crl set.
23332 </p>
23333 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23334 negative error value.  If the provided buffer is not long enough,
23335 then  <code>crl_size</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  is
23336 returned.  After the last crl has been read
23337 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be returned.
23338 </p></dd></dl>
23339
23340 <a name="gnutls_005fpkcs7_005fget_005fcrt_005fcount-1"></a>
23341 <h4 class="subheading">gnutls_pkcs7_get_crt_count</h4>
23342 <a name="gnutls_005fpkcs7_005fget_005fcrt_005fcount"></a><dl>
23343 <dt><a name="index-gnutls_005fpkcs7_005fget_005fcrt_005fcount"></a>Function: <em>int</em> <strong>gnutls_pkcs7_get_crt_count</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>)</em></dt>
23344 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code>  structure
23345 </p>
23346 <p>This function will return the number of certifcates in the PKCS7
23347 or RFC2630 certificate set.
23348 </p>
23349 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23350 negative error value.
23351 </p></dd></dl>
23352
23353 <a name="gnutls_005fpkcs7_005fget_005fcrt_005fraw-1"></a>
23354 <h4 class="subheading">gnutls_pkcs7_get_crt_raw</h4>
23355 <a name="gnutls_005fpkcs7_005fget_005fcrt_005fraw"></a><dl>
23356 <dt><a name="index-gnutls_005fpkcs7_005fget_005fcrt_005fraw"></a>Function: <em>int</em> <strong>gnutls_pkcs7_get_crt_raw</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>, int <var>indx</var>, void * <var>certificate</var>, size_t * <var>certificate_size</var>)</em></dt>
23357 <dd><p><var>pkcs7</var>: should contain a gnutls_pkcs7_t structure
23358 </p>
23359 <p><var>indx</var>: contains the index of the certificate to extract
23360 </p>
23361 <p><var>certificate</var>: the contents of the certificate will be copied
23362 there (may be null)
23363 </p>
23364 <p><var>certificate_size</var>: should hold the size of the certificate
23365 </p>
23366 <p>This function will return a certificate of the PKCS7 or RFC2630
23367 certificate set.
23368 </p>
23369 <p>After the last certificate has been read
23370 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be returned.
23371 </p>
23372 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23373 negative error value.  If the provided buffer is not long enough,
23374 then  <code>certificate_size</code> is updated and
23375 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  is returned.
23376 </p></dd></dl>
23377
23378 <a name="gnutls_005fpkcs7_005fimport-1"></a>
23379 <h4 class="subheading">gnutls_pkcs7_import</h4>
23380 <a name="gnutls_005fpkcs7_005fimport"></a><dl>
23381 <dt><a name="index-gnutls_005fpkcs7_005fimport"></a>Function: <em>int</em> <strong>gnutls_pkcs7_import</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>)</em></dt>
23382 <dd><p><var>pkcs7</var>: The structure to store the parsed PKCS7.
23383 </p>
23384 <p><var>data</var>: The DER or PEM encoded PKCS7.
23385 </p>
23386 <p><var>format</var>: One of DER or PEM
23387 </p>
23388 <p>This function will convert the given DER or PEM encoded PKCS7 to
23389 the native <code>gnutls_pkcs7_t</code>  format.  The output will be stored in
23390  <code>pkcs7</code> .
23391 </p>
23392 <p>If the PKCS7 is PEM encoded it should have a header of &quot;PKCS7&quot;.
23393 </p>
23394 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23395 negative error value.
23396 </p></dd></dl>
23397
23398 <a name="gnutls_005fpkcs7_005finit-1"></a>
23399 <h4 class="subheading">gnutls_pkcs7_init</h4>
23400 <a name="gnutls_005fpkcs7_005finit"></a><dl>
23401 <dt><a name="index-gnutls_005fpkcs7_005finit"></a>Function: <em>int</em> <strong>gnutls_pkcs7_init</strong> <em>(gnutls_pkcs7_t * <var>pkcs7</var>)</em></dt>
23402 <dd><p><var>pkcs7</var>: The structure to be initialized
23403 </p>
23404 <p>This function will initialize a PKCS7 structure. PKCS7 structures
23405 usually contain lists of X.509 Certificates and X.509 Certificate
23406 revocation lists.
23407 </p>
23408 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23409 negative error value.
23410 </p></dd></dl>
23411
23412 <a name="gnutls_005fpkcs7_005fset_005fcrl-1"></a>
23413 <h4 class="subheading">gnutls_pkcs7_set_crl</h4>
23414 <a name="gnutls_005fpkcs7_005fset_005fcrl"></a><dl>
23415 <dt><a name="index-gnutls_005fpkcs7_005fset_005fcrl"></a>Function: <em>int</em> <strong>gnutls_pkcs7_set_crl</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>, gnutls_x509_crl_t <var>crl</var>)</em></dt>
23416 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code>  structure
23417 </p>
23418 <p><var>crl</var>: the DER encoded crl to be added
23419 </p>
23420 <p>This function will add a parsed CRL to the PKCS7 or RFC2630 crl
23421 set.
23422 </p>
23423 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23424 negative error value.
23425 </p></dd></dl>
23426
23427 <a name="gnutls_005fpkcs7_005fset_005fcrl_005fraw-1"></a>
23428 <h4 class="subheading">gnutls_pkcs7_set_crl_raw</h4>
23429 <a name="gnutls_005fpkcs7_005fset_005fcrl_005fraw"></a><dl>
23430 <dt><a name="index-gnutls_005fpkcs7_005fset_005fcrl_005fraw"></a>Function: <em>int</em> <strong>gnutls_pkcs7_set_crl_raw</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>, const gnutls_datum_t * <var>crl</var>)</em></dt>
23431 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code>  structure
23432 </p>
23433 <p><var>crl</var>: the DER encoded crl to be added
23434 </p>
23435 <p>This function will add a crl to the PKCS7 or RFC2630 crl set.
23436 </p>
23437 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23438 negative error value.
23439 </p></dd></dl>
23440
23441 <a name="gnutls_005fpkcs7_005fset_005fcrt-1"></a>
23442 <h4 class="subheading">gnutls_pkcs7_set_crt</h4>
23443 <a name="gnutls_005fpkcs7_005fset_005fcrt"></a><dl>
23444 <dt><a name="index-gnutls_005fpkcs7_005fset_005fcrt"></a>Function: <em>int</em> <strong>gnutls_pkcs7_set_crt</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>, gnutls_x509_crt_t <var>crt</var>)</em></dt>
23445 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code>  structure
23446 </p>
23447 <p><var>crt</var>: the certificate to be copied.
23448 </p>
23449 <p>This function will add a parsed certificate to the PKCS7 or
23450 RFC2630 certificate set.  This is a wrapper function over
23451 <code>gnutls_pkcs7_set_crt_raw()</code>  .
23452 </p>
23453 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23454 negative error value.
23455 </p></dd></dl>
23456
23457 <a name="gnutls_005fpkcs7_005fset_005fcrt_005fraw-1"></a>
23458 <h4 class="subheading">gnutls_pkcs7_set_crt_raw</h4>
23459 <a name="gnutls_005fpkcs7_005fset_005fcrt_005fraw"></a><dl>
23460 <dt><a name="index-gnutls_005fpkcs7_005fset_005fcrt_005fraw"></a>Function: <em>int</em> <strong>gnutls_pkcs7_set_crt_raw</strong> <em>(gnutls_pkcs7_t <var>pkcs7</var>, const gnutls_datum_t * <var>crt</var>)</em></dt>
23461 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code>  structure
23462 </p>
23463 <p><var>crt</var>: the DER encoded certificate to be added
23464 </p>
23465 <p>This function will add a certificate to the PKCS7 or RFC2630
23466 certificate set.
23467 </p>
23468 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23469 negative error value.
23470 </p></dd></dl>
23471
23472 <a name="gnutls_005fsubject_005falt_005fnames_005fdeinit-1"></a>
23473 <h4 class="subheading">gnutls_subject_alt_names_deinit</h4>
23474 <a name="gnutls_005fsubject_005falt_005fnames_005fdeinit"></a><dl>
23475 <dt><a name="index-gnutls_005fsubject_005falt_005fnames_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_subject_alt_names_deinit</strong> <em>(gnutls_subject_alt_names_t <var>sans</var>)</em></dt>
23476 <dd><p><var>sans</var>: The alternative names structure
23477 </p>
23478 <p>This function will deinitialize an alternative names structure.
23479 </p>
23480 <p><strong>Since:</strong> 3.3.0
23481 </p></dd></dl>
23482
23483 <a name="gnutls_005fsubject_005falt_005fnames_005fget-1"></a>
23484 <h4 class="subheading">gnutls_subject_alt_names_get</h4>
23485 <a name="gnutls_005fsubject_005falt_005fnames_005fget"></a><dl>
23486 <dt><a name="index-gnutls_005fsubject_005falt_005fnames_005fget"></a>Function: <em>int</em> <strong>gnutls_subject_alt_names_get</strong> <em>(gnutls_subject_alt_names_t <var>sans</var>, unsigned int <var>seq</var>, unsigned int * <var>san_type</var>, gnutls_datum_t * <var>san</var>, gnutls_datum_t * <var>othername_oid</var>)</em></dt>
23487 <dd><p><var>sans</var>: The alternative names structure
23488 </p>
23489 <p><var>seq</var>: The index of the name to get
23490 </p>
23491 <p><var>san_type</var>: Will hold the type of the name (of <code>gnutls_subject_alt_names_t</code> )
23492 </p>
23493 <p><var>san</var>: The alternative name data (should be treated as constant)
23494 </p>
23495 <p><var>othername_oid</var>: The object identifier if  <code>san_type</code> is <code>GNUTLS_SAN_OTHERNAME</code>  (should be treated as constant)
23496 </p>
23497 <p>This function will return a specific alternative name as stored in
23498 the  <code>sans</code> structure. The returned values should be treated as constant
23499 and valid for the lifetime of  <code>sans</code> .
23500 </p>
23501 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
23502 if the index is out of bounds, otherwise a negative error value.
23503 </p>
23504 <p><strong>Since:</strong> 3.3.0
23505 </p></dd></dl>
23506
23507 <a name="gnutls_005fsubject_005falt_005fnames_005finit-1"></a>
23508 <h4 class="subheading">gnutls_subject_alt_names_init</h4>
23509 <a name="gnutls_005fsubject_005falt_005fnames_005finit"></a><dl>
23510 <dt><a name="index-gnutls_005fsubject_005falt_005fnames_005finit"></a>Function: <em>int</em> <strong>gnutls_subject_alt_names_init</strong> <em>(gnutls_subject_alt_names_t * <var>sans</var>)</em></dt>
23511 <dd><p><var>sans</var>: The alternative names structure
23512 </p>
23513 <p>This function will initialize an alternative names structure.
23514 </p>
23515 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
23516 </p>
23517 <p><strong>Since:</strong> 3.3.0
23518 </p></dd></dl>
23519
23520 <a name="gnutls_005fsubject_005falt_005fnames_005fset-1"></a>
23521 <h4 class="subheading">gnutls_subject_alt_names_set</h4>
23522 <a name="gnutls_005fsubject_005falt_005fnames_005fset"></a><dl>
23523 <dt><a name="index-gnutls_005fsubject_005falt_005fnames_005fset"></a>Function: <em>int</em> <strong>gnutls_subject_alt_names_set</strong> <em>(gnutls_subject_alt_names_t <var>sans</var>, unsigned int <var>san_type</var>, const gnutls_datum_t * <var>san</var>, const char * <var>othername_oid</var>)</em></dt>
23524 <dd><p><var>sans</var>: The alternative names structure
23525 </p>
23526 <p><var>san_type</var>: The type of the name (of <code>gnutls_subject_alt_names_t</code> )
23527 </p>
23528 <p><var>san</var>: The alternative name data
23529 </p>
23530 <p><var>othername_oid</var>: The object identifier if  <code>san_type</code> is <code>GNUTLS_SAN_OTHERNAME</code>
23531 </p>
23532 <p>This function will store the specified alternative name in
23533 the  <code>sans</code> structure.
23534 </p>
23535 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0), otherwise a negative error value.
23536 </p>
23537 <p><strong>Since:</strong> 3.3.0
23538 </p></dd></dl>
23539
23540 <a name="gnutls_005fx509_005faia_005fdeinit-1"></a>
23541 <h4 class="subheading">gnutls_x509_aia_deinit</h4>
23542 <a name="gnutls_005fx509_005faia_005fdeinit"></a><dl>
23543 <dt><a name="index-gnutls_005fx509_005faia_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_aia_deinit</strong> <em>(gnutls_x509_aia_t <var>aia</var>)</em></dt>
23544 <dd><p><var>aia</var>: The authority info access structure
23545 </p>
23546 <p>This function will deinitialize a CRL distribution points structure.
23547 </p>
23548 <p><strong>Since:</strong> 3.3.0
23549 </p></dd></dl>
23550
23551 <a name="gnutls_005fx509_005faia_005fget-1"></a>
23552 <h4 class="subheading">gnutls_x509_aia_get</h4>
23553 <a name="gnutls_005fx509_005faia_005fget"></a><dl>
23554 <dt><a name="index-gnutls_005fx509_005faia_005fget"></a>Function: <em>int</em> <strong>gnutls_x509_aia_get</strong> <em>(gnutls_x509_aia_t <var>aia</var>, unsigned int <var>seq</var>, gnutls_datum_t * <var>oid</var>, unsigned * <var>san_type</var>, gnutls_datum_t * <var>san</var>)</em></dt>
23555 <dd><p><var>aia</var>: The authority info access structure
23556 </p>
23557 <p><var>seq</var>: specifies the sequence number of the access descriptor (0 for the first one, 1 for the second etc.)
23558 </p>
23559 <p><var>oid</var>: the type of available data; to be treated as constant.
23560 </p>
23561 <p><var>san_type</var>: Will hold the type of the name of <code>gnutls_subject_alt_names_t</code>  (may be null).
23562 </p>
23563 <p><var>san</var>: the access location name; to be treated as constant (may be null).
23564 </p>
23565 <p>This function reads from the Authority Information Access structure.
23566 </p>
23567 <p>The  <code>seq</code> input parameter is used to indicate which member of the
23568 sequence the caller is interested in.  The first member is 0, the
23569 second member 1 and so on.  When the  <code>seq</code> value is out of bounds,
23570 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is returned.
23571 </p>
23572 <p>Typically  <code>oid</code> is <code>GNUTLS_OID_AD_CAISSUERS</code>  or <code>GNUTLS_OID_AD_OCSP</code> .
23573 </p>
23574 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
23575 </p>
23576 <p><strong>Since:</strong> 3.3.0
23577 </p></dd></dl>
23578
23579 <a name="gnutls_005fx509_005faia_005finit-1"></a>
23580 <h4 class="subheading">gnutls_x509_aia_init</h4>
23581 <a name="gnutls_005fx509_005faia_005finit"></a><dl>
23582 <dt><a name="index-gnutls_005fx509_005faia_005finit"></a>Function: <em>int</em> <strong>gnutls_x509_aia_init</strong> <em>(gnutls_x509_aia_t * <var>aia</var>)</em></dt>
23583 <dd><p><var>aia</var>: The authority info access structure
23584 </p>
23585 <p>This function will initialize a CRL distribution points structure.
23586 </p>
23587 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
23588 </p>
23589 <p><strong>Since:</strong> 3.3.0
23590 </p></dd></dl>
23591
23592 <a name="gnutls_005fx509_005faia_005fset-1"></a>
23593 <h4 class="subheading">gnutls_x509_aia_set</h4>
23594 <a name="gnutls_005fx509_005faia_005fset"></a><dl>
23595 <dt><a name="index-gnutls_005fx509_005faia_005fset"></a>Function: <em>int</em> <strong>gnutls_x509_aia_set</strong> <em>(gnutls_x509_aia_t <var>aia</var>, const char * <var>oid</var>, unsigned <var>san_type</var>, const gnutls_datum_t * <var>san</var>)</em></dt>
23596 <dd><p><var>aia</var>: The authority info access structure
23597 </p>
23598 <p><var>oid</var>: the type of data.
23599 </p>
23600 <p><var>san_type</var>: The type of the name (of <code>gnutls_subject_alt_names_t</code> )
23601 </p>
23602 <p><var>san</var>: The alternative name data
23603 </p>
23604 <p>This function will store the specified alternative name in
23605 the  <code>aia</code> structure.
23606 </p>
23607 <p>Typically the value for  <code>oid</code> should be <code>GNUTLS_OID_AD_OCSP</code> , or
23608 <code>GNUTLS_OID_AD_CAISSUERS</code> .
23609 </p>
23610 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0), otherwise a negative error value.
23611 </p>
23612 <p><strong>Since:</strong> 3.3.0
23613 </p></dd></dl>
23614
23615 <a name="gnutls_005fx509_005faki_005fdeinit-1"></a>
23616 <h4 class="subheading">gnutls_x509_aki_deinit</h4>
23617 <a name="gnutls_005fx509_005faki_005fdeinit"></a><dl>
23618 <dt><a name="index-gnutls_005fx509_005faki_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_aki_deinit</strong> <em>(gnutls_x509_aki_t <var>aki</var>)</em></dt>
23619 <dd><p><var>aki</var>: The authority key identifier structure
23620 </p>
23621 <p>This function will deinitialize an authority key identifier structure.
23622 </p>
23623 <p><strong>Since:</strong> 3.3.0
23624 </p></dd></dl>
23625
23626 <a name="gnutls_005fx509_005faki_005fget_005fcert_005fissuer-1"></a>
23627 <h4 class="subheading">gnutls_x509_aki_get_cert_issuer</h4>
23628 <a name="gnutls_005fx509_005faki_005fget_005fcert_005fissuer"></a><dl>
23629 <dt><a name="index-gnutls_005fx509_005faki_005fget_005fcert_005fissuer"></a>Function: <em>int</em> <strong>gnutls_x509_aki_get_cert_issuer</strong> <em>(gnutls_x509_aki_t <var>aki</var>, unsigned int <var>seq</var>, unsigned int * <var>san_type</var>, gnutls_datum_t * <var>san</var>, gnutls_datum_t * <var>othername_oid</var>, gnutls_datum_t * <var>serial</var>)</em></dt>
23630 <dd><p><var>aki</var>: The authority key ID structure
23631 </p>
23632 <p><var>seq</var>: The index of the name to get
23633 </p>
23634 <p><var>san_type</var>: Will hold the type of the name (of <code>gnutls_subject_alt_names_t</code> )
23635 </p>
23636 <p><var>san</var>: The alternative name data
23637 </p>
23638 <p><var>othername_oid</var>: The object identifier if  <code>san_type</code> is <code>GNUTLS_SAN_OTHERNAME</code>
23639 </p>
23640 <p><var>serial</var>: The authorityCertSerialNumber number
23641 </p>
23642 <p>This function will return a specific authorityCertIssuer name as stored in
23643 the  <code>aki</code> structure, as well as the authorityCertSerialNumber. All the returned
23644 values should be treated as constant, and may be set to <code>NULL</code>  when are not required.
23645 </p>
23646 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
23647 if the index is out of bounds, otherwise a negative error value.
23648 </p>
23649 <p><strong>Since:</strong> 3.3.0
23650 </p></dd></dl>
23651
23652 <a name="gnutls_005fx509_005faki_005fget_005fid-1"></a>
23653 <h4 class="subheading">gnutls_x509_aki_get_id</h4>
23654 <a name="gnutls_005fx509_005faki_005fget_005fid"></a><dl>
23655 <dt><a name="index-gnutls_005fx509_005faki_005fget_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_aki_get_id</strong> <em>(gnutls_x509_aki_t <var>aki</var>, gnutls_datum_t * <var>id</var>)</em></dt>
23656 <dd><p><var>aki</var>: The authority key ID structure
23657 </p>
23658 <p><var>id</var>: Will hold the identifier
23659 </p>
23660 <p>This function will return the key identifier as stored in
23661 the  <code>aki</code> structure. The identifier should be treated as constant.
23662 </p>
23663 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
23664 if the index is out of bounds, otherwise a negative error value.
23665 </p>
23666 <p><strong>Since:</strong> 3.3.0
23667 </p></dd></dl>
23668
23669 <a name="gnutls_005fx509_005faki_005finit-1"></a>
23670 <h4 class="subheading">gnutls_x509_aki_init</h4>
23671 <a name="gnutls_005fx509_005faki_005finit"></a><dl>
23672 <dt><a name="index-gnutls_005fx509_005faki_005finit"></a>Function: <em>int</em> <strong>gnutls_x509_aki_init</strong> <em>(gnutls_x509_aki_t * <var>aki</var>)</em></dt>
23673 <dd><p><var>aki</var>: The authority key ID structure
23674 </p>
23675 <p>This function will initialize an authority key ID structure.
23676 </p>
23677 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
23678 </p>
23679 <p><strong>Since:</strong> 3.3.0
23680 </p></dd></dl>
23681
23682 <a name="gnutls_005fx509_005faki_005fset_005fcert_005fissuer-1"></a>
23683 <h4 class="subheading">gnutls_x509_aki_set_cert_issuer</h4>
23684 <a name="gnutls_005fx509_005faki_005fset_005fcert_005fissuer"></a><dl>
23685 <dt><a name="index-gnutls_005fx509_005faki_005fset_005fcert_005fissuer"></a>Function: <em>int</em> <strong>gnutls_x509_aki_set_cert_issuer</strong> <em>(gnutls_x509_aki_t <var>aki</var>, unsigned int <var>san_type</var>, const gnutls_datum_t * <var>san</var>, const char * <var>othername_oid</var>, const gnutls_datum_t * <var>serial</var>)</em></dt>
23686 <dd><p><var>aki</var>: The authority key ID structure
23687 </p>
23688 <p><var>san_type</var>: the type of the name (of <code>gnutls_subject_alt_names_t</code> ), may be null
23689 </p>
23690 <p><var>san</var>: The alternative name data
23691 </p>
23692 <p><var>othername_oid</var>: The object identifier if  <code>san_type</code> is <code>GNUTLS_SAN_OTHERNAME</code>
23693 </p>
23694 <p><var>serial</var>: The authorityCertSerialNumber number (may be null)
23695 </p>
23696 <p>This function will set the authorityCertIssuer name and the authorityCertSerialNumber
23697 to be stored in the  <code>aki</code> structure. When storing multiple names, the serial
23698 should be set on the first call, and subsequent calls should use a <code>NULL</code>  serial.
23699 </p>
23700 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
23701 </p>
23702 <p><strong>Since:</strong> 3.3.0
23703 </p></dd></dl>
23704
23705 <a name="gnutls_005fx509_005faki_005fset_005fid-1"></a>
23706 <h4 class="subheading">gnutls_x509_aki_set_id</h4>
23707 <a name="gnutls_005fx509_005faki_005fset_005fid"></a><dl>
23708 <dt><a name="index-gnutls_005fx509_005faki_005fset_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_aki_set_id</strong> <em>(gnutls_x509_aki_t <var>aki</var>, const gnutls_datum_t * <var>id</var>)</em></dt>
23709 <dd><p><var>aki</var>: The authority key ID structure
23710 </p>
23711 <p><var>id</var>: the key identifier
23712 </p>
23713 <p>This function will set the keyIdentifier to be stored in the  <code>aki</code> structure.
23714 </p>
23715 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
23716 </p>
23717 <p><strong>Since:</strong> 3.3.0
23718 </p></dd></dl>
23719
23720 <a name="gnutls_005fx509_005fcrl_005fcheck_005fissuer-1"></a>
23721 <h4 class="subheading">gnutls_x509_crl_check_issuer</h4>
23722 <a name="gnutls_005fx509_005fcrl_005fcheck_005fissuer"></a><dl>
23723 <dt><a name="index-gnutls_005fx509_005fcrl_005fcheck_005fissuer"></a>Function: <em>int</em> <strong>gnutls_x509_crl_check_issuer</strong> <em>(gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crt_t <var>issuer</var>)</em></dt>
23724 <dd><p><var>crl</var>: is the CRL to be checked
23725 </p>
23726 <p><var>issuer</var>: is the certificate of a possible issuer
23727 </p>
23728 <p>This function will check if the given CRL was issued by the given
23729 issuer certificate.
23730 </p>
23731 <p><strong>Returns:</strong> true (1) if the given CRL was issued by the given issuer,
23732 and false (0) if not.
23733 </p></dd></dl>
23734
23735 <a name="gnutls_005fx509_005fcrl_005fdeinit-1"></a>
23736 <h4 class="subheading">gnutls_x509_crl_deinit</h4>
23737 <a name="gnutls_005fx509_005fcrl_005fdeinit"></a><dl>
23738 <dt><a name="index-gnutls_005fx509_005fcrl_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_crl_deinit</strong> <em>(gnutls_x509_crl_t <var>crl</var>)</em></dt>
23739 <dd><p><var>crl</var>: The structure to be deinitialized
23740 </p>
23741 <p>This function will deinitialize a CRL structure.
23742 </p></dd></dl>
23743
23744 <a name="gnutls_005fx509_005fcrl_005fdist_005fpoints_005fdeinit-1"></a>
23745 <h4 class="subheading">gnutls_x509_crl_dist_points_deinit</h4>
23746 <a name="gnutls_005fx509_005fcrl_005fdist_005fpoints_005fdeinit"></a><dl>
23747 <dt><a name="index-gnutls_005fx509_005fcrl_005fdist_005fpoints_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_crl_dist_points_deinit</strong> <em>(gnutls_x509_crl_dist_points_t <var>cdp</var>)</em></dt>
23748 <dd><p><var>cdp</var>: The CRL distribution points structure
23749 </p>
23750 <p>This function will deinitialize a CRL distribution points structure.
23751 </p>
23752 <p><strong>Since:</strong> 3.3.0
23753 </p></dd></dl>
23754
23755 <a name="gnutls_005fx509_005fcrl_005fdist_005fpoints_005fget-1"></a>
23756 <h4 class="subheading">gnutls_x509_crl_dist_points_get</h4>
23757 <a name="gnutls_005fx509_005fcrl_005fdist_005fpoints_005fget"></a><dl>
23758 <dt><a name="index-gnutls_005fx509_005fcrl_005fdist_005fpoints_005fget"></a>Function: <em>int</em> <strong>gnutls_x509_crl_dist_points_get</strong> <em>(gnutls_x509_crl_dist_points_t <var>cdp</var>, unsigned int <var>seq</var>, unsigned int * <var>type</var>, gnutls_datum_t * <var>san</var>, unsigned int * <var>reasons</var>)</em></dt>
23759 <dd><p><var>cdp</var>: The CRL distribution points structure
23760 </p>
23761 <p><var>seq</var>: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.)
23762 </p>
23763 <p><var>type</var>: The name type of the corresponding name (gnutls_x509_subject_alt_name_t)
23764 </p>
23765 <p><var>san</var>: The distribution point names (to be treated as constant)
23766 </p>
23767 <p><var>reasons</var>: Revocation reasons. An ORed sequence of flags from <code>gnutls_x509_crl_reason_flags_t</code> .
23768 </p>
23769 <p>This function retrieves the individual CRL distribution points (2.5.29.31),
23770 contained in provided structure.
23771 </p>
23772 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
23773 if the index is out of bounds, otherwise a negative error value.
23774 </p></dd></dl>
23775
23776 <a name="gnutls_005fx509_005fcrl_005fdist_005fpoints_005finit-1"></a>
23777 <h4 class="subheading">gnutls_x509_crl_dist_points_init</h4>
23778 <a name="gnutls_005fx509_005fcrl_005fdist_005fpoints_005finit"></a><dl>
23779 <dt><a name="index-gnutls_005fx509_005fcrl_005fdist_005fpoints_005finit"></a>Function: <em>int</em> <strong>gnutls_x509_crl_dist_points_init</strong> <em>(gnutls_x509_crl_dist_points_t * <var>cdp</var>)</em></dt>
23780 <dd><p><var>cdp</var>: The CRL distribution points structure
23781 </p>
23782 <p>This function will initialize a CRL distribution points structure.
23783 </p>
23784 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
23785 </p>
23786 <p><strong>Since:</strong> 3.3.0
23787 </p></dd></dl>
23788
23789 <a name="gnutls_005fx509_005fcrl_005fdist_005fpoints_005fset-1"></a>
23790 <h4 class="subheading">gnutls_x509_crl_dist_points_set</h4>
23791 <a name="gnutls_005fx509_005fcrl_005fdist_005fpoints_005fset"></a><dl>
23792 <dt><a name="index-gnutls_005fx509_005fcrl_005fdist_005fpoints_005fset"></a>Function: <em>int</em> <strong>gnutls_x509_crl_dist_points_set</strong> <em>(gnutls_x509_crl_dist_points_t <var>cdp</var>, gnutls_x509_subject_alt_name_t <var>type</var>, const gnutls_datum_t * <var>san</var>, unsigned int <var>reasons</var>)</em></dt>
23793 <dd><p><var>cdp</var>: The CRL distribution points structure
23794 </p>
23795 <p><var>type</var>: The type of the name (of <code>gnutls_subject_alt_names_t</code> )
23796 </p>
23797 <p><var>san</var>: The point name data
23798 </p>
23799 <p><var>reasons</var>: Revocation reasons. An ORed sequence of flags from <code>gnutls_x509_crl_reason_flags_t</code> .
23800 </p>
23801 <p>This function will store the specified CRL distibution point value
23802 the  <code>cdp</code> structure.
23803 </p>
23804 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0), otherwise a negative error value.
23805 </p>
23806 <p><strong>Since:</strong> 3.3.0
23807 </p></dd></dl>
23808
23809 <a name="gnutls_005fx509_005fcrl_005fexport-1"></a>
23810 <h4 class="subheading">gnutls_x509_crl_export</h4>
23811 <a name="gnutls_005fx509_005fcrl_005fexport"></a><dl>
23812 <dt><a name="index-gnutls_005fx509_005fcrl_005fexport"></a>Function: <em>int</em> <strong>gnutls_x509_crl_export</strong> <em>(gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crt_fmt_t <var>format</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
23813 <dd><p><var>crl</var>: Holds the revocation list
23814 </p>
23815 <p><var>format</var>: the format of output params. One of PEM or DER.
23816 </p>
23817 <p><var>output_data</var>: will contain a private key PEM or DER encoded
23818 </p>
23819 <p><var>output_data_size</var>: holds the size of output_data (and will
23820 be replaced by the actual size of parameters)
23821 </p>
23822 <p>This function will export the revocation list to DER or PEM format.
23823 </p>
23824 <p>If the buffer provided is not long enough to hold the output, then
23825 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  will be returned.
23826 </p>
23827 <p>If the structure is PEM encoded, it will have a header
23828 of &quot;BEGIN X509 CRL&quot;.
23829 </p>
23830 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23831 negative error value.
23832 </p></dd></dl>
23833
23834 <a name="gnutls_005fx509_005fcrl_005fexport2-1"></a>
23835 <h4 class="subheading">gnutls_x509_crl_export2</h4>
23836 <a name="gnutls_005fx509_005fcrl_005fexport2"></a><dl>
23837 <dt><a name="index-gnutls_005fx509_005fcrl_005fexport2"></a>Function: <em>int</em> <strong>gnutls_x509_crl_export2</strong> <em>(gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crt_fmt_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
23838 <dd><p><var>crl</var>: Holds the revocation list
23839 </p>
23840 <p><var>format</var>: the format of output params. One of PEM or DER.
23841 </p>
23842 <p><var>out</var>: will contain a private key PEM or DER encoded
23843 </p>
23844 <p>This function will export the revocation list to DER or PEM format.
23845 </p>
23846 <p>The output buffer is allocated using <code>gnutls_malloc()</code> .
23847 </p>
23848 <p>If the structure is PEM encoded, it will have a header
23849 of &quot;BEGIN X509 CRL&quot;.
23850 </p>
23851 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23852 negative error value.
23853 </p>
23854 <p>Since 3.1.3
23855 </p></dd></dl>
23856
23857 <a name="gnutls_005fx509_005fcrl_005fget_005fauthority_005fkey_005fgn_005fserial-1"></a>
23858 <h4 class="subheading">gnutls_x509_crl_get_authority_key_gn_serial</h4>
23859 <a name="gnutls_005fx509_005fcrl_005fget_005fauthority_005fkey_005fgn_005fserial"></a><dl>
23860 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fauthority_005fkey_005fgn_005fserial"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_authority_key_gn_serial</strong> <em>(gnutls_x509_crl_t <var>crl</var>, unsigned int <var>seq</var>, void * <var>alt</var>, size_t * <var>alt_size</var>, unsigned int * <var>alt_type</var>, void * <var>serial</var>, size_t * <var>serial_size</var>, unsigned int * <var>critical</var>)</em></dt>
23861 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
23862 </p>
23863 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
23864 </p>
23865 <p><var>alt</var>: is the place where the alternative name will be copied to
23866 </p>
23867 <p><var>alt_size</var>: holds the size of alt.
23868 </p>
23869 <p><var>alt_type</var>: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
23870 </p>
23871 <p><var>serial</var>: buffer to store the serial number (may be null)
23872 </p>
23873 <p><var>serial_size</var>: Holds the size of the serial field (may be null)
23874 </p>
23875 <p><var>critical</var>: will be non-zero if the extension is marked as critical (may be null)
23876 </p>
23877 <p>This function will return the X.509 authority key
23878 identifier when stored as a general name (authorityCertIssuer)
23879 and serial number.
23880 </p>
23881 <p>Because more than one general names might be stored
23882  <code>seq</code> can be used as a counter to request them all until
23883 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is returned.
23884 </p>
23885 <p><strong>Returns:</strong> Returns 0 on success, or an error code.
23886 </p>
23887 <p><strong>Since:</strong> 3.0
23888 </p></dd></dl>
23889
23890 <a name="gnutls_005fx509_005fcrl_005fget_005fauthority_005fkey_005fid-1"></a>
23891 <h4 class="subheading">gnutls_x509_crl_get_authority_key_id</h4>
23892 <a name="gnutls_005fx509_005fcrl_005fget_005fauthority_005fkey_005fid"></a><dl>
23893 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fauthority_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_authority_key_id</strong> <em>(gnutls_x509_crl_t <var>crl</var>, void * <var>id</var>, size_t * <var>id_size</var>, unsigned int * <var>critical</var>)</em></dt>
23894 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
23895 </p>
23896 <p><var>id</var>: The place where the identifier will be copied
23897 </p>
23898 <p><var>id_size</var>: Holds the size of the result field.
23899 </p>
23900 <p><var>critical</var>: will be non-zero if the extension is marked as critical
23901 (may be null)
23902 </p>
23903 <p>This function will return the CRL authority&rsquo;s key identifier.  This
23904 is obtained by the X.509 Authority Key identifier extension field
23905 (2.5.29.35).  Note that this function
23906 only returns the keyIdentifier field of the extension and
23907 <code>GNUTLS_E_X509_UNSUPPORTED_EXTENSION</code> , if the extension contains
23908 the name and serial number of the certificate. In that case
23909 <code>gnutls_x509_crl_get_authority_key_gn_serial()</code>  may be used.
23910 </p>
23911 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23912 negative error code in case of an error.
23913 </p>
23914 <p><strong>Since:</strong> 2.8.0
23915 </p></dd></dl>
23916
23917 <a name="gnutls_005fx509_005fcrl_005fget_005fcrt_005fcount-1"></a>
23918 <h4 class="subheading">gnutls_x509_crl_get_crt_count</h4>
23919 <a name="gnutls_005fx509_005fcrl_005fget_005fcrt_005fcount"></a><dl>
23920 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fcrt_005fcount"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_crt_count</strong> <em>(gnutls_x509_crl_t <var>crl</var>)</em></dt>
23921 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
23922 </p>
23923 <p>This function will return the number of revoked certificates in the
23924 given CRL.
23925 </p>
23926 <p><strong>Returns:</strong> number of certificates, a negative error code on failure.
23927 </p></dd></dl>
23928
23929 <a name="gnutls_005fx509_005fcrl_005fget_005fcrt_005fserial-1"></a>
23930 <h4 class="subheading">gnutls_x509_crl_get_crt_serial</h4>
23931 <a name="gnutls_005fx509_005fcrl_005fget_005fcrt_005fserial"></a><dl>
23932 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fcrt_005fserial-1"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_crt_serial</strong> <em>(gnutls_x509_crl_t <var>crl</var>, int <var>indx</var>, unsigned char * <var>serial</var>, size_t * <var>serial_size</var>, time_t * <var>t</var>)</em></dt>
23933 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
23934 </p>
23935 <p><var>indx</var>: the index of the certificate to extract (starting from 0)
23936 </p>
23937 <p><var>serial</var>: where the serial number will be copied
23938 </p>
23939 <p><var>serial_size</var>: initially holds the size of serial
23940 </p>
23941 <p><var>t</var>: if non null, will hold the time this certificate was revoked
23942 </p>
23943 <p>This function will retrieve the serial number of the specified, by
23944 the index, revoked certificate.
23945 </p>
23946 <p>Note that this function will have performance issues in large sequences
23947 of revoked certificates. In that case use <code>gnutls_x509_crl_iter_crt_serial()</code> .
23948 </p>
23949 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23950 negative error value.
23951 </p></dd></dl>
23952
23953 <a name="gnutls_005fx509_005fcrl_005fget_005fdn_005foid-1"></a>
23954 <h4 class="subheading">gnutls_x509_crl_get_dn_oid</h4>
23955 <a name="gnutls_005fx509_005fcrl_005fget_005fdn_005foid"></a><dl>
23956 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fdn_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_dn_oid</strong> <em>(gnutls_x509_crl_t <var>crl</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>sizeof_oid</var>)</em></dt>
23957 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
23958 </p>
23959 <p><var>indx</var>: Specifies which DN OID to send. Use (0) to get the first one.
23960 </p>
23961 <p><var>oid</var>: a pointer to a structure to hold the name (may be null)
23962 </p>
23963 <p><var>sizeof_oid</var>: initially holds the size of &rsquo;oid&rsquo;
23964 </p>
23965 <p>This function will extract the requested OID of the name of the CRL
23966 issuer, specified by the given index.
23967 </p>
23968 <p>If oid is null then only the size will be filled.
23969 </p>
23970 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is
23971 not long enough, and in that case the sizeof_oid will be updated
23972 with the required size.  On success 0 is returned.
23973 </p></dd></dl>
23974
23975 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005fdata-1"></a>
23976 <h4 class="subheading">gnutls_x509_crl_get_extension_data</h4>
23977 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005fdata"></a><dl>
23978 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fextension_005fdata"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_extension_data</strong> <em>(gnutls_x509_crl_t <var>crl</var>, int <var>indx</var>, void * <var>data</var>, size_t * <var>sizeof_data</var>)</em></dt>
23979 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
23980 </p>
23981 <p><var>indx</var>: Specifies which extension OID to send. Use (0) to get the first one.
23982 </p>
23983 <p><var>data</var>: a pointer to a structure to hold the data (may be null)
23984 </p>
23985 <p><var>sizeof_data</var>: initially holds the size of  <code>oid</code>
23986 </p>
23987 <p>This function will return the requested extension data in the CRL.
23988 The extension data will be stored as a string in the provided
23989 buffer.
23990 </p>
23991 <p>Use <code>gnutls_x509_crl_get_extension_info()</code>  to extract the OID and
23992 critical flag.  Use <code>gnutls_x509_crl_get_extension_info()</code>  instead,
23993 if you want to get data indexed by the extension OID rather than
23994 sequence.
23995 </p>
23996 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
23997 negative error code in case of an error.  If your have reached the
23998 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
23999 will be returned.
24000 </p>
24001 <p><strong>Since:</strong> 2.8.0
24002 </p></dd></dl>
24003
24004 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005fdata2-1"></a>
24005 <h4 class="subheading">gnutls_x509_crl_get_extension_data2</h4>
24006 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005fdata2"></a><dl>
24007 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fextension_005fdata2"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_extension_data2</strong> <em>(gnutls_x509_crl_t <var>crl</var>, unsigned <var>indx</var>, gnutls_datum_t * <var>data</var>)</em></dt>
24008 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
24009 </p>
24010 <p><var>indx</var>: Specifies which extension OID to read. Use (0) to get the first one.
24011 </p>
24012 <p><var>data</var>: will contain the extension DER-encoded data
24013 </p>
24014 <p>This function will return the requested by the index extension data in the
24015 certificate revocation list.  The extension data will be allocated using
24016 <code>gnutls_malloc()</code> .
24017 </p>
24018 <p>Use <code>gnutls_x509_crt_get_extension_info()</code>  to extract the OID.
24019 </p>
24020 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
24021 otherwise a negative error code is returned.  If you have reached the
24022 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
24023 will be returned.
24024 </p></dd></dl>
24025
24026 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005finfo-1"></a>
24027 <h4 class="subheading">gnutls_x509_crl_get_extension_info</h4>
24028 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005finfo"></a><dl>
24029 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fextension_005finfo"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_extension_info</strong> <em>(gnutls_x509_crl_t <var>crl</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>sizeof_oid</var>, unsigned int * <var>critical</var>)</em></dt>
24030 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
24031 </p>
24032 <p><var>indx</var>: Specifies which extension OID to send, use (0) to get the first one.
24033 </p>
24034 <p><var>oid</var>: a pointer to a structure to hold the OID
24035 </p>
24036 <p><var>sizeof_oid</var>: initially holds the maximum size of  <code>oid</code> , on return
24037 holds actual size of  <code>oid</code> .
24038 </p>
24039 <p><var>critical</var>: output variable with critical flag, may be NULL.
24040 </p>
24041 <p>This function will return the requested extension OID in the CRL,
24042 and the critical flag for it.  The extension OID will be stored as
24043 a string in the provided buffer.  Use
24044 <code>gnutls_x509_crl_get_extension_data()</code>  to extract the data.
24045 </p>
24046 <p>If the buffer provided is not long enough to hold the output, then
24047 * <code>sizeof_oid</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  will be
24048 returned.
24049 </p>
24050 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24051 negative error code in case of an error.  If your have reached the
24052 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
24053 will be returned.
24054 </p>
24055 <p><strong>Since:</strong> 2.8.0
24056 </p></dd></dl>
24057
24058 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005foid-1"></a>
24059 <h4 class="subheading">gnutls_x509_crl_get_extension_oid</h4>
24060 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005foid"></a><dl>
24061 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fextension_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_extension_oid</strong> <em>(gnutls_x509_crl_t <var>crl</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>sizeof_oid</var>)</em></dt>
24062 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
24063 </p>
24064 <p><var>indx</var>: Specifies which extension OID to send, use (0) to get the first one.
24065 </p>
24066 <p><var>oid</var>: a pointer to a structure to hold the OID (may be null)
24067 </p>
24068 <p><var>sizeof_oid</var>: initially holds the size of  <code>oid</code>
24069 </p>
24070 <p>This function will return the requested extension OID in the CRL.
24071 The extension OID will be stored as a string in the provided
24072 buffer.
24073 </p>
24074 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24075 negative error code in case of an error.  If your have reached the
24076 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
24077 will be returned.
24078 </p>
24079 <p><strong>Since:</strong> 2.8.0
24080 </p></dd></dl>
24081
24082 <a name="gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn-1"></a>
24083 <h4 class="subheading">gnutls_x509_crl_get_issuer_dn</h4>
24084 <a name="gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn"></a><dl>
24085 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_issuer_dn</strong> <em>(const gnutls_x509_crl_t <var>crl</var>, char * <var>buf</var>, size_t * <var>sizeof_buf</var>)</em></dt>
24086 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
24087 </p>
24088 <p><var>buf</var>: a pointer to a structure to hold the peer&rsquo;s name (may be null)
24089 </p>
24090 <p><var>sizeof_buf</var>: initially holds the size of  <code>buf</code>
24091 </p>
24092 <p>This function will copy the name of the CRL issuer in the provided
24093 buffer. The name will be in the form &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as
24094 described in RFC4514. The output string will be ASCII or UTF-8
24095 encoded, depending on the certificate data.
24096 </p>
24097 <p>If buf is <code>NULL</code>  then only the size will be filled.
24098 </p>
24099 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is
24100 not long enough, and in that case the sizeof_buf will be updated
24101 with the required size, and 0 on success.
24102 </p></dd></dl>
24103
24104 <a name="gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn2-1"></a>
24105 <h4 class="subheading">gnutls_x509_crl_get_issuer_dn2</h4>
24106 <a name="gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn2"></a><dl>
24107 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn2"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_issuer_dn2</strong> <em>(gnutls_x509_crl_t <var>crl</var>, gnutls_datum_t * <var>dn</var>)</em></dt>
24108 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
24109 </p>
24110 <p><var>dn</var>: a pointer to a structure to hold the name
24111 </p>
24112 <p>This function will allocate buffer and copy the name of the CRL issuer.
24113 The name will be in the form &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as
24114 described in RFC4514. The output string will be ASCII or UTF-8
24115 encoded, depending on the certificate data.
24116 </p>
24117 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24118 negative error value.
24119 </p>
24120 <p><strong>Since:</strong> 3.1.10
24121 </p></dd></dl>
24122
24123 <a name="gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn_005fby_005foid-1"></a>
24124 <h4 class="subheading">gnutls_x509_crl_get_issuer_dn_by_oid</h4>
24125 <a name="gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn_005fby_005foid"></a><dl>
24126 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn_005fby_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_issuer_dn_by_oid</strong> <em>(gnutls_x509_crl_t <var>crl</var>, const char * <var>oid</var>, int <var>indx</var>, unsigned int <var>raw_flag</var>, void * <var>buf</var>, size_t * <var>sizeof_buf</var>)</em></dt>
24127 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
24128 </p>
24129 <p><var>oid</var>: holds an Object Identified in null terminated string
24130 </p>
24131 <p><var>indx</var>: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
24132 </p>
24133 <p><var>raw_flag</var>: If non-zero returns the raw DER data of the DN part.
24134 </p>
24135 <p><var>buf</var>: a pointer to a structure to hold the peer&rsquo;s name (may be null)
24136 </p>
24137 <p><var>sizeof_buf</var>: initially holds the size of  <code>buf</code>
24138 </p>
24139 <p>This function will extract the part of the name of the CRL issuer
24140 specified by the given OID. The output will be encoded as described
24141 in RFC4514. The output string will be ASCII or UTF-8 encoded,
24142 depending on the certificate data.
24143 </p>
24144 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
24145 If raw flag is (0), this function will only return known OIDs as
24146 text. Other OIDs will be DER encoded, as described in RFC4514 &ndash; in
24147 hex format with a &rsquo;#&rsquo; prefix.  You can check about known OIDs
24148 using <code>gnutls_x509_dn_oid_known()</code> .
24149 </p>
24150 <p>If buf is null then only the size will be filled.
24151 </p>
24152 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is
24153 not long enough, and in that case the sizeof_buf will be updated
24154 with the required size, and 0 on success.
24155 </p></dd></dl>
24156
24157 <a name="gnutls_005fx509_005fcrl_005fget_005fnext_005fupdate-1"></a>
24158 <h4 class="subheading">gnutls_x509_crl_get_next_update</h4>
24159 <a name="gnutls_005fx509_005fcrl_005fget_005fnext_005fupdate"></a><dl>
24160 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fnext_005fupdate"></a>Function: <em>time_t</em> <strong>gnutls_x509_crl_get_next_update</strong> <em>(gnutls_x509_crl_t <var>crl</var>)</em></dt>
24161 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
24162 </p>
24163 <p>This function will return the time the next CRL will be issued.
24164 This field is optional in a CRL so it might be normal to get an
24165 error instead.
24166 </p>
24167 <p><strong>Returns:</strong> when the next CRL will be issued, or (time_t)-1 on error.
24168 </p></dd></dl>
24169
24170 <a name="gnutls_005fx509_005fcrl_005fget_005fnumber-1"></a>
24171 <h4 class="subheading">gnutls_x509_crl_get_number</h4>
24172 <a name="gnutls_005fx509_005fcrl_005fget_005fnumber"></a><dl>
24173 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fnumber"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_number</strong> <em>(gnutls_x509_crl_t <var>crl</var>, void * <var>ret</var>, size_t * <var>ret_size</var>, unsigned int * <var>critical</var>)</em></dt>
24174 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
24175 </p>
24176 <p><var>ret</var>: The place where the number will be copied
24177 </p>
24178 <p><var>ret_size</var>: Holds the size of the result field.
24179 </p>
24180 <p><var>critical</var>: will be non-zero if the extension is marked as critical
24181 (may be null)
24182 </p>
24183 <p>This function will return the CRL number extension.  This is
24184 obtained by the CRL Number extension field (2.5.29.20).
24185 </p>
24186 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24187 negative error code in case of an error.
24188 </p>
24189 <p><strong>Since:</strong> 2.8.0
24190 </p></dd></dl>
24191
24192 <a name="gnutls_005fx509_005fcrl_005fget_005fraw_005fissuer_005fdn-1"></a>
24193 <h4 class="subheading">gnutls_x509_crl_get_raw_issuer_dn</h4>
24194 <a name="gnutls_005fx509_005fcrl_005fget_005fraw_005fissuer_005fdn"></a><dl>
24195 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fraw_005fissuer_005fdn"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_raw_issuer_dn</strong> <em>(gnutls_x509_crl_t <var>crl</var>, gnutls_datum_t * <var>dn</var>)</em></dt>
24196 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
24197 </p>
24198 <p><var>dn</var>: will hold the starting point of the DN
24199 </p>
24200 <p>This function will return a pointer to the DER encoded DN structure
24201 and the length.
24202 </p>
24203 <p><strong>Returns:</strong> a negative error code on error, and (0) on success.
24204 </p>
24205 <p><strong>Since:</strong> 2.12.0
24206 </p></dd></dl>
24207
24208 <a name="gnutls_005fx509_005fcrl_005fget_005fsignature-1"></a>
24209 <h4 class="subheading">gnutls_x509_crl_get_signature</h4>
24210 <a name="gnutls_005fx509_005fcrl_005fget_005fsignature"></a><dl>
24211 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fsignature"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_signature</strong> <em>(gnutls_x509_crl_t <var>crl</var>, char * <var>sig</var>, size_t * <var>sizeof_sig</var>)</em></dt>
24212 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
24213 </p>
24214 <p><var>sig</var>: a pointer where the signature part will be copied (may be null).
24215 </p>
24216 <p><var>sizeof_sig</var>: initially holds the size of  <code>sig</code>
24217 </p>
24218 <p>This function will extract the signature field of a CRL.
24219 </p>
24220 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24221 negative error value.
24222 </p></dd></dl>
24223
24224 <a name="gnutls_005fx509_005fcrl_005fget_005fsignature_005falgorithm-1"></a>
24225 <h4 class="subheading">gnutls_x509_crl_get_signature_algorithm</h4>
24226 <a name="gnutls_005fx509_005fcrl_005fget_005fsignature_005falgorithm"></a><dl>
24227 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fsignature_005falgorithm"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_signature_algorithm</strong> <em>(gnutls_x509_crl_t <var>crl</var>)</em></dt>
24228 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
24229 </p>
24230 <p>This function will return a value of the <code>gnutls_sign_algorithm_t</code>
24231 enumeration that is the signature algorithm.
24232 </p>
24233 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24234 negative error value.
24235 </p></dd></dl>
24236
24237 <a name="gnutls_005fx509_005fcrl_005fget_005fthis_005fupdate-1"></a>
24238 <h4 class="subheading">gnutls_x509_crl_get_this_update</h4>
24239 <a name="gnutls_005fx509_005fcrl_005fget_005fthis_005fupdate"></a><dl>
24240 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fthis_005fupdate"></a>Function: <em>time_t</em> <strong>gnutls_x509_crl_get_this_update</strong> <em>(gnutls_x509_crl_t <var>crl</var>)</em></dt>
24241 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
24242 </p>
24243 <p>This function will return the time this CRL was issued.
24244 </p>
24245 <p><strong>Returns:</strong> when the CRL was issued, or (time_t)-1 on error.
24246 </p></dd></dl>
24247
24248 <a name="gnutls_005fx509_005fcrl_005fget_005fversion-1"></a>
24249 <h4 class="subheading">gnutls_x509_crl_get_version</h4>
24250 <a name="gnutls_005fx509_005fcrl_005fget_005fversion"></a><dl>
24251 <dt><a name="index-gnutls_005fx509_005fcrl_005fget_005fversion"></a>Function: <em>int</em> <strong>gnutls_x509_crl_get_version</strong> <em>(gnutls_x509_crl_t <var>crl</var>)</em></dt>
24252 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
24253 </p>
24254 <p>This function will return the version of the specified CRL.
24255 </p>
24256 <p><strong>Returns:</strong> The version number, or a negative error code on error.
24257 </p></dd></dl>
24258
24259 <a name="gnutls_005fx509_005fcrl_005fimport-1"></a>
24260 <h4 class="subheading">gnutls_x509_crl_import</h4>
24261 <a name="gnutls_005fx509_005fcrl_005fimport"></a><dl>
24262 <dt><a name="index-gnutls_005fx509_005fcrl_005fimport"></a>Function: <em>int</em> <strong>gnutls_x509_crl_import</strong> <em>(gnutls_x509_crl_t <var>crl</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>)</em></dt>
24263 <dd><p><var>crl</var>: The structure to store the parsed CRL.
24264 </p>
24265 <p><var>data</var>: The DER or PEM encoded CRL.
24266 </p>
24267 <p><var>format</var>: One of DER or PEM
24268 </p>
24269 <p>This function will convert the given DER or PEM encoded CRL
24270 to the native <code>gnutls_x509_crl_t</code>  format. The output will be stored in &rsquo;crl&rsquo;.
24271 </p>
24272 <p>If the CRL is PEM encoded it should have a header of &quot;X509 CRL&quot;.
24273 </p>
24274 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24275 negative error value.
24276 </p></dd></dl>
24277
24278 <a name="gnutls_005fx509_005fcrl_005finit-1"></a>
24279 <h4 class="subheading">gnutls_x509_crl_init</h4>
24280 <a name="gnutls_005fx509_005fcrl_005finit"></a><dl>
24281 <dt><a name="index-gnutls_005fx509_005fcrl_005finit"></a>Function: <em>int</em> <strong>gnutls_x509_crl_init</strong> <em>(gnutls_x509_crl_t * <var>crl</var>)</em></dt>
24282 <dd><p><var>crl</var>: The structure to be initialized
24283 </p>
24284 <p>This function will initialize a CRL structure. CRL stands for
24285 Certificate Revocation List. A revocation list usually contains
24286 lists of certificate serial numbers that have been revoked by an
24287 Authority. The revocation lists are always signed with the
24288 authority&rsquo;s private key.
24289 </p>
24290 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24291 negative error value.
24292 </p></dd></dl>
24293
24294 <a name="gnutls_005fx509_005fcrl_005fiter_005fcrt_005fserial-1"></a>
24295 <h4 class="subheading">gnutls_x509_crl_iter_crt_serial</h4>
24296 <a name="gnutls_005fx509_005fcrl_005fiter_005fcrt_005fserial"></a><dl>
24297 <dt><a name="index-gnutls_005fx509_005fcrl_005fiter_005fcrt_005fserial"></a>Function: <em>int</em> <strong>gnutls_x509_crl_iter_crt_serial</strong> <em>(gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crl_iter_t * <var>iter</var>, unsigned char * <var>serial</var>, size_t * <var>serial_size</var>, time_t * <var>t</var>)</em></dt>
24298 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code>  structure
24299 </p>
24300 <p><var>iter</var>: A pointer to an iterator (initially the iterator should be <code>NULL</code> )
24301 </p>
24302 <p><var>serial</var>: where the serial number will be copied
24303 </p>
24304 <p><var>serial_size</var>: initially holds the size of serial
24305 </p>
24306 <p><var>t</var>: if non null, will hold the time this certificate was revoked
24307 </p>
24308 <p>This function performs the same as <code>gnutls_x509_crl_get_crt_serial()</code> ,
24309 but reads sequentially and keeps state in the iterator
24310 between calls. That allows it to provide better performance in sequences
24311 with many elements (50000+).
24312 </p>
24313 <p>When past the last element is accessed <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
24314 is returned and the iterator is reset.
24315 </p>
24316 <p>After use, the iterator must be deinitialized using <code>gnutls_x509_crl_iter_deinit()</code> .
24317 </p>
24318 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24319 negative error value.
24320 </p></dd></dl>
24321
24322 <a name="gnutls_005fx509_005fcrl_005fiter_005fdeinit-1"></a>
24323 <h4 class="subheading">gnutls_x509_crl_iter_deinit</h4>
24324 <a name="gnutls_005fx509_005fcrl_005fiter_005fdeinit"></a><dl>
24325 <dt><a name="index-gnutls_005fx509_005fcrl_005fiter_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_crl_iter_deinit</strong> <em>(gnutls_x509_crl_iter_t <var>iter</var>)</em></dt>
24326 <dd><p><var>iter</var>: The iterator structure to be deinitialized
24327 </p>
24328 <p>This function will deinitialize an iterator structure.
24329 </p></dd></dl>
24330
24331 <a name="gnutls_005fx509_005fcrl_005flist_005fimport-1"></a>
24332 <h4 class="subheading">gnutls_x509_crl_list_import</h4>
24333 <a name="gnutls_005fx509_005fcrl_005flist_005fimport"></a><dl>
24334 <dt><a name="index-gnutls_005fx509_005fcrl_005flist_005fimport"></a>Function: <em>int</em> <strong>gnutls_x509_crl_list_import</strong> <em>(gnutls_x509_crl_t * <var>crls</var>, unsigned int * <var>crl_max</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned int <var>flags</var>)</em></dt>
24335 <dd><p><var>crls</var>: The structures to store the parsed CRLs. Must not be initialized.
24336 </p>
24337 <p><var>crl_max</var>: Initially must hold the maximum number of crls. It will be updated with the number of crls available.
24338 </p>
24339 <p><var>data</var>: The PEM encoded CRLs
24340 </p>
24341 <p><var>format</var>: One of DER or PEM.
24342 </p>
24343 <p><var>flags</var>: must be (0) or an OR&rsquo;d sequence of gnutls_certificate_import_flags.
24344 </p>
24345 <p>This function will convert the given PEM encoded CRL list
24346 to the native gnutls_x509_crl_t format. The output will be stored
24347 in  <code>crls</code> .  They will be automatically initialized.
24348 </p>
24349 <p>If the Certificate is PEM encoded it should have a header of &quot;X509 CRL&quot;.
24350 </p>
24351 <p><strong>Returns:</strong> the number of certificates read or a negative error value.
24352 </p>
24353 <p><strong>Since:</strong> 3.0
24354 </p></dd></dl>
24355
24356 <a name="gnutls_005fx509_005fcrl_005flist_005fimport2-1"></a>
24357 <h4 class="subheading">gnutls_x509_crl_list_import2</h4>
24358 <a name="gnutls_005fx509_005fcrl_005flist_005fimport2"></a><dl>
24359 <dt><a name="index-gnutls_005fx509_005fcrl_005flist_005fimport2"></a>Function: <em>int</em> <strong>gnutls_x509_crl_list_import2</strong> <em>(gnutls_x509_crl_t ** <var>crls</var>, unsigned int * <var>size</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned int <var>flags</var>)</em></dt>
24360 <dd><p><var>crls</var>: The structures to store the parsed crl list. Must not be initialized.
24361 </p>
24362 <p><var>size</var>: It will contain the size of the list.
24363 </p>
24364 <p><var>data</var>: The PEM encoded CRL.
24365 </p>
24366 <p><var>format</var>: One of DER or PEM.
24367 </p>
24368 <p><var>flags</var>: must be (0) or an OR&rsquo;d sequence of gnutls_certificate_import_flags.
24369 </p>
24370 <p>This function will convert the given PEM encoded CRL list
24371 to the native gnutls_x509_crl_t format. The output will be stored
24372 in  <code>crls</code> .  They will be automatically initialized.
24373 </p>
24374 <p>If the Certificate is PEM encoded it should have a header of &quot;X509
24375 CRL&quot;.
24376 </p>
24377 <p><strong>Returns:</strong> the number of certificates read or a negative error value.
24378 </p>
24379 <p><strong>Since:</strong> 3.0
24380 </p></dd></dl>
24381
24382 <a name="gnutls_005fx509_005fcrl_005fprint-1"></a>
24383 <h4 class="subheading">gnutls_x509_crl_print</h4>
24384 <a name="gnutls_005fx509_005fcrl_005fprint"></a><dl>
24385 <dt><a name="index-gnutls_005fx509_005fcrl_005fprint"></a>Function: <em>int</em> <strong>gnutls_x509_crl_print</strong> <em>(gnutls_x509_crl_t <var>crl</var>, gnutls_certificate_print_formats_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
24386 <dd><p><var>crl</var>: The structure to be printed
24387 </p>
24388 <p><var>format</var>: Indicate the format to use
24389 </p>
24390 <p><var>out</var>: Newly allocated datum with null terminated string.
24391 </p>
24392 <p>This function will pretty print a X.509 certificate revocation
24393 list, suitable for display to a human.
24394 </p>
24395 <p>The output  <code>out</code> needs to be deallocated using <code>gnutls_free()</code> .
24396 </p>
24397 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24398 negative error value.
24399 </p></dd></dl>
24400
24401 <a name="gnutls_005fx509_005fcrl_005fset_005fauthority_005fkey_005fid-1"></a>
24402 <h4 class="subheading">gnutls_x509_crl_set_authority_key_id</h4>
24403 <a name="gnutls_005fx509_005fcrl_005fset_005fauthority_005fkey_005fid"></a><dl>
24404 <dt><a name="index-gnutls_005fx509_005fcrl_005fset_005fauthority_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_crl_set_authority_key_id</strong> <em>(gnutls_x509_crl_t <var>crl</var>, const void * <var>id</var>, size_t <var>id_size</var>)</em></dt>
24405 <dd><p><var>crl</var>: a CRL of type <code>gnutls_x509_crl_t</code>
24406 </p>
24407 <p><var>id</var>: The key ID
24408 </p>
24409 <p><var>id_size</var>: Holds the size of the serial field.
24410 </p>
24411 <p>This function will set the CRL&rsquo;s authority key ID extension.  Only
24412 the keyIdentifier field can be set with this function. This may
24413 be used by an authority that holds multiple private keys, to distinguish
24414 the used key.
24415 </p>
24416 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24417 negative error value.
24418 </p>
24419 <p><strong>Since:</strong> 2.8.0
24420 </p></dd></dl>
24421
24422 <a name="gnutls_005fx509_005fcrl_005fset_005fcrt-1"></a>
24423 <h4 class="subheading">gnutls_x509_crl_set_crt</h4>
24424 <a name="gnutls_005fx509_005fcrl_005fset_005fcrt"></a><dl>
24425 <dt><a name="index-gnutls_005fx509_005fcrl_005fset_005fcrt"></a>Function: <em>int</em> <strong>gnutls_x509_crl_set_crt</strong> <em>(gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crt_t <var>crt</var>, time_t <var>revocation_time</var>)</em></dt>
24426 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
24427 </p>
24428 <p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>  with the revoked certificate
24429 </p>
24430 <p><var>revocation_time</var>: The time this certificate was revoked
24431 </p>
24432 <p>This function will set a revoked certificate&rsquo;s serial number to the CRL.
24433 </p>
24434 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24435 negative error value.
24436 </p></dd></dl>
24437
24438 <a name="gnutls_005fx509_005fcrl_005fset_005fcrt_005fserial-1"></a>
24439 <h4 class="subheading">gnutls_x509_crl_set_crt_serial</h4>
24440 <a name="gnutls_005fx509_005fcrl_005fset_005fcrt_005fserial"></a><dl>
24441 <dt><a name="index-gnutls_005fx509_005fcrl_005fset_005fcrt_005fserial"></a>Function: <em>int</em> <strong>gnutls_x509_crl_set_crt_serial</strong> <em>(gnutls_x509_crl_t <var>crl</var>, const void * <var>serial</var>, size_t <var>serial_size</var>, time_t <var>revocation_time</var>)</em></dt>
24442 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
24443 </p>
24444 <p><var>serial</var>: The revoked certificate&rsquo;s serial number
24445 </p>
24446 <p><var>serial_size</var>: Holds the size of the serial field.
24447 </p>
24448 <p><var>revocation_time</var>: The time this certificate was revoked
24449 </p>
24450 <p>This function will set a revoked certificate&rsquo;s serial number to the CRL.
24451 </p>
24452 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24453 negative error value.
24454 </p></dd></dl>
24455
24456 <a name="gnutls_005fx509_005fcrl_005fset_005fnext_005fupdate-1"></a>
24457 <h4 class="subheading">gnutls_x509_crl_set_next_update</h4>
24458 <a name="gnutls_005fx509_005fcrl_005fset_005fnext_005fupdate"></a><dl>
24459 <dt><a name="index-gnutls_005fx509_005fcrl_005fset_005fnext_005fupdate"></a>Function: <em>int</em> <strong>gnutls_x509_crl_set_next_update</strong> <em>(gnutls_x509_crl_t <var>crl</var>, time_t <var>exp_time</var>)</em></dt>
24460 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
24461 </p>
24462 <p><var>exp_time</var>: The actual time
24463 </p>
24464 <p>This function will set the time this CRL will be updated.
24465 </p>
24466 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24467 negative error value.
24468 </p></dd></dl>
24469
24470 <a name="gnutls_005fx509_005fcrl_005fset_005fnumber-1"></a>
24471 <h4 class="subheading">gnutls_x509_crl_set_number</h4>
24472 <a name="gnutls_005fx509_005fcrl_005fset_005fnumber"></a><dl>
24473 <dt><a name="index-gnutls_005fx509_005fcrl_005fset_005fnumber"></a>Function: <em>int</em> <strong>gnutls_x509_crl_set_number</strong> <em>(gnutls_x509_crl_t <var>crl</var>, const void * <var>nr</var>, size_t <var>nr_size</var>)</em></dt>
24474 <dd><p><var>crl</var>: a CRL of type <code>gnutls_x509_crl_t</code>
24475 </p>
24476 <p><var>nr</var>: The CRL number
24477 </p>
24478 <p><var>nr_size</var>: Holds the size of the nr field.
24479 </p>
24480 <p>This function will set the CRL&rsquo;s number extension. This
24481 is to be used as a unique and monotonic number assigned to
24482 the CRL by the authority.
24483 </p>
24484 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24485 negative error value.
24486 </p>
24487 <p><strong>Since:</strong> 2.8.0
24488 </p></dd></dl>
24489
24490 <a name="gnutls_005fx509_005fcrl_005fset_005fthis_005fupdate-1"></a>
24491 <h4 class="subheading">gnutls_x509_crl_set_this_update</h4>
24492 <a name="gnutls_005fx509_005fcrl_005fset_005fthis_005fupdate"></a><dl>
24493 <dt><a name="index-gnutls_005fx509_005fcrl_005fset_005fthis_005fupdate"></a>Function: <em>int</em> <strong>gnutls_x509_crl_set_this_update</strong> <em>(gnutls_x509_crl_t <var>crl</var>, time_t <var>act_time</var>)</em></dt>
24494 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
24495 </p>
24496 <p><var>act_time</var>: The actual time
24497 </p>
24498 <p>This function will set the time this CRL was issued.
24499 </p>
24500 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24501 negative error value.
24502 </p></dd></dl>
24503
24504 <a name="gnutls_005fx509_005fcrl_005fset_005fversion-1"></a>
24505 <h4 class="subheading">gnutls_x509_crl_set_version</h4>
24506 <a name="gnutls_005fx509_005fcrl_005fset_005fversion"></a><dl>
24507 <dt><a name="index-gnutls_005fx509_005fcrl_005fset_005fversion"></a>Function: <em>int</em> <strong>gnutls_x509_crl_set_version</strong> <em>(gnutls_x509_crl_t <var>crl</var>, unsigned int <var>version</var>)</em></dt>
24508 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
24509 </p>
24510 <p><var>version</var>: holds the version number. For CRLv1 crls must be 1.
24511 </p>
24512 <p>This function will set the version of the CRL. This
24513 must be one for CRL version 1, and so on. The CRLs generated
24514 by gnutls should have a version number of 2.
24515 </p>
24516 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24517 negative error value.
24518 </p></dd></dl>
24519
24520 <a name="gnutls_005fx509_005fcrl_005fsign2-1"></a>
24521 <h4 class="subheading">gnutls_x509_crl_sign2</h4>
24522 <a name="gnutls_005fx509_005fcrl_005fsign2"></a><dl>
24523 <dt><a name="index-gnutls_005fx509_005fcrl_005fsign2-1"></a>Function: <em>int</em> <strong>gnutls_x509_crl_sign2</strong> <em>(gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crt_t <var>issuer</var>, gnutls_x509_privkey_t <var>issuer_key</var>, gnutls_digest_algorithm_t <var>dig</var>, unsigned int <var>flags</var>)</em></dt>
24524 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
24525 </p>
24526 <p><var>issuer</var>: is the certificate of the certificate issuer
24527 </p>
24528 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
24529 </p>
24530 <p><var>dig</var>: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you&rsquo;re doing.
24531 </p>
24532 <p><var>flags</var>: must be 0
24533 </p>
24534 <p>This function will sign the CRL with the issuer&rsquo;s private key, and
24535 will copy the issuer&rsquo;s information into the CRL.
24536 </p>
24537 <p>This must be the last step in a certificate CRL since all
24538 the previously set parameters are now signed.
24539 </p>
24540 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24541 negative error value.
24542 </p></dd></dl>
24543
24544 <a name="gnutls_005fx509_005fcrl_005fverify-1"></a>
24545 <h4 class="subheading">gnutls_x509_crl_verify</h4>
24546 <a name="gnutls_005fx509_005fcrl_005fverify"></a><dl>
24547 <dt><a name="index-gnutls_005fx509_005fcrl_005fverify"></a>Function: <em>int</em> <strong>gnutls_x509_crl_verify</strong> <em>(gnutls_x509_crl_t <var>crl</var>, const gnutls_x509_crt_t * <var>trusted_cas</var>, int <var>tcas_size</var>, unsigned int <var>flags</var>, unsigned int * <var>verify</var>)</em></dt>
24548 <dd><p><var>crl</var>: is the crl to be verified
24549 </p>
24550 <p><var>trusted_cas</var>: is a certificate list that is considered to be trusted one
24551 </p>
24552 <p><var>tcas_size</var>: holds the number of CA certificates in CA_list
24553 </p>
24554 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
24555 </p>
24556 <p><var>verify</var>: will hold the crl verification output.
24557 </p>
24558 <p>This function will try to verify the given crl and return its verification status.
24559 See <code>gnutls_x509_crt_list_verify()</code>  for a detailed description of
24560 return values. Note that since GnuTLS 3.1.4 this function includes
24561 the time checks.
24562 </p>
24563 <p>Note that value in  <code>verify</code> is set only when the return value of this
24564 function is success (i.e, failure to trust a CRL a certificate does not imply
24565 a negative return value).
24566 </p>
24567 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24568 negative error value.
24569 </p></dd></dl>
24570
24571 <a name="gnutls_005fx509_005fcrq_005fdeinit-1"></a>
24572 <h4 class="subheading">gnutls_x509_crq_deinit</h4>
24573 <a name="gnutls_005fx509_005fcrq_005fdeinit"></a><dl>
24574 <dt><a name="index-gnutls_005fx509_005fcrq_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_crq_deinit</strong> <em>(gnutls_x509_crq_t <var>crq</var>)</em></dt>
24575 <dd><p><var>crq</var>: The structure to be initialized
24576 </p>
24577 <p>This function will deinitialize a PKCS<code>10</code>  certificate request
24578 structure.
24579 </p></dd></dl>
24580
24581 <a name="gnutls_005fx509_005fcrq_005fexport-1"></a>
24582 <h4 class="subheading">gnutls_x509_crq_export</h4>
24583 <a name="gnutls_005fx509_005fcrq_005fexport"></a><dl>
24584 <dt><a name="index-gnutls_005fx509_005fcrq_005fexport"></a>Function: <em>int</em> <strong>gnutls_x509_crq_export</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_x509_crt_fmt_t <var>format</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
24585 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24586 </p>
24587 <p><var>format</var>: the format of output params. One of PEM or DER.
24588 </p>
24589 <p><var>output_data</var>: will contain a certificate request PEM or DER encoded
24590 </p>
24591 <p><var>output_data_size</var>: holds the size of output_data (and will be
24592 replaced by the actual size of parameters)
24593 </p>
24594 <p>This function will export the certificate request to a PEM or DER
24595 encoded PKCS10 structure.
24596 </p>
24597 <p>If the buffer provided is not long enough to hold the output, then
24598 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  will be returned and
24599 * <code>output_data_size</code> will be updated.
24600 </p>
24601 <p>If the structure is PEM encoded, it will have a header of &quot;BEGIN
24602 NEW CERTIFICATE REQUEST&quot;.
24603 </p>
24604 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24605 negative error value.
24606 </p></dd></dl>
24607
24608 <a name="gnutls_005fx509_005fcrq_005fexport2-1"></a>
24609 <h4 class="subheading">gnutls_x509_crq_export2</h4>
24610 <a name="gnutls_005fx509_005fcrq_005fexport2"></a><dl>
24611 <dt><a name="index-gnutls_005fx509_005fcrq_005fexport2"></a>Function: <em>int</em> <strong>gnutls_x509_crq_export2</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_x509_crt_fmt_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
24612 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24613 </p>
24614 <p><var>format</var>: the format of output params. One of PEM or DER.
24615 </p>
24616 <p><var>out</var>: will contain a certificate request PEM or DER encoded
24617 </p>
24618 <p>This function will export the certificate request to a PEM or DER
24619 encoded PKCS10 structure.
24620 </p>
24621 <p>The output buffer is allocated using <code>gnutls_malloc()</code> .
24622 </p>
24623 <p>If the structure is PEM encoded, it will have a header of &quot;BEGIN
24624 NEW CERTIFICATE REQUEST&quot;.
24625 </p>
24626 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24627 negative error value.
24628 </p>
24629 <p>Since 3.1.3
24630 </p></dd></dl>
24631
24632 <a name="gnutls_005fx509_005fcrq_005fget_005fattribute_005fby_005foid-1"></a>
24633 <h4 class="subheading">gnutls_x509_crq_get_attribute_by_oid</h4>
24634 <a name="gnutls_005fx509_005fcrq_005fget_005fattribute_005fby_005foid"></a><dl>
24635 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fattribute_005fby_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_attribute_by_oid</strong> <em>(gnutls_x509_crq_t <var>crq</var>, const char * <var>oid</var>, int <var>indx</var>, void * <var>buf</var>, size_t * <var>buf_size</var>)</em></dt>
24636 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24637 </p>
24638 <p><var>oid</var>: holds an Object Identifier in null-terminated string
24639 </p>
24640 <p><var>indx</var>: In case multiple same OIDs exist in the attribute list, this
24641 specifies which to get, use (0) to get the first one
24642 </p>
24643 <p><var>buf</var>: a pointer to a structure to hold the attribute data (may be <code>NULL</code> )
24644 </p>
24645 <p><var>buf_size</var>: initially holds the size of  <code>buf</code>
24646 </p>
24647 <p>This function will return the attribute in the certificate request
24648 specified by the given Object ID.  The attribute will be DER
24649 encoded.
24650 </p>
24651 <p>Attributes in a certificate request is an optional set of data
24652 appended to the request. Their interpretation depends on the CA policy.
24653 </p>
24654 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24655 negative error value.
24656 </p></dd></dl>
24657
24658 <a name="gnutls_005fx509_005fcrq_005fget_005fattribute_005fdata-1"></a>
24659 <h4 class="subheading">gnutls_x509_crq_get_attribute_data</h4>
24660 <a name="gnutls_005fx509_005fcrq_005fget_005fattribute_005fdata"></a><dl>
24661 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fattribute_005fdata"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_attribute_data</strong> <em>(gnutls_x509_crq_t <var>crq</var>, int <var>indx</var>, void * <var>data</var>, size_t * <var>sizeof_data</var>)</em></dt>
24662 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24663 </p>
24664 <p><var>indx</var>: Specifies which attribute number to get. Use (0) to get the first one.
24665 </p>
24666 <p><var>data</var>: a pointer to a structure to hold the data (may be null)
24667 </p>
24668 <p><var>sizeof_data</var>: initially holds the size of  <code>oid</code>
24669 </p>
24670 <p>This function will return the requested attribute data in the
24671 certificate request.  The attribute data will be stored as a string in the
24672 provided buffer.
24673 </p>
24674 <p>Use <code>gnutls_x509_crq_get_attribute_info()</code>  to extract the OID.
24675 Use <code>gnutls_x509_crq_get_attribute_by_oid()</code>  instead,
24676 if you want to get data indexed by the attribute OID rather than
24677 sequence.
24678 </p>
24679 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24680 negative error code in case of an error.  If your have reached the
24681 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
24682 will be returned.
24683 </p>
24684 <p><strong>Since:</strong> 2.8.0
24685 </p></dd></dl>
24686
24687 <a name="gnutls_005fx509_005fcrq_005fget_005fattribute_005finfo-1"></a>
24688 <h4 class="subheading">gnutls_x509_crq_get_attribute_info</h4>
24689 <a name="gnutls_005fx509_005fcrq_005fget_005fattribute_005finfo"></a><dl>
24690 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fattribute_005finfo"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_attribute_info</strong> <em>(gnutls_x509_crq_t <var>crq</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>sizeof_oid</var>)</em></dt>
24691 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24692 </p>
24693 <p><var>indx</var>: Specifies which attribute number to get. Use (0) to get the first one.
24694 </p>
24695 <p><var>oid</var>: a pointer to a structure to hold the OID
24696 </p>
24697 <p><var>sizeof_oid</var>: initially holds the maximum size of  <code>oid</code> , on return
24698 holds actual size of  <code>oid</code> .
24699 </p>
24700 <p>This function will return the requested attribute OID in the
24701 certificate, and the critical flag for it.  The attribute OID will
24702 be stored as a string in the provided buffer.  Use
24703 <code>gnutls_x509_crq_get_attribute_data()</code>  to extract the data.
24704 </p>
24705 <p>If the buffer provided is not long enough to hold the output, then
24706 * <code>sizeof_oid</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  will be
24707 returned.
24708 </p>
24709 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24710 negative error code in case of an error.  If your have reached the
24711 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
24712 will be returned.
24713 </p>
24714 <p><strong>Since:</strong> 2.8.0
24715 </p></dd></dl>
24716
24717 <a name="gnutls_005fx509_005fcrq_005fget_005fbasic_005fconstraints-1"></a>
24718 <h4 class="subheading">gnutls_x509_crq_get_basic_constraints</h4>
24719 <a name="gnutls_005fx509_005fcrq_005fget_005fbasic_005fconstraints"></a><dl>
24720 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fbasic_005fconstraints"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_basic_constraints</strong> <em>(gnutls_x509_crq_t <var>crq</var>, unsigned int * <var>critical</var>, unsigned int * <var>ca</var>, int * <var>pathlen</var>)</em></dt>
24721 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24722 </p>
24723 <p><var>critical</var>: will be non-zero if the extension is marked as critical
24724 </p>
24725 <p><var>ca</var>: pointer to output integer indicating CA status, may be NULL,
24726 value is 1 if the certificate CA flag is set, 0 otherwise.
24727 </p>
24728 <p><var>pathlen</var>: pointer to output integer indicating path length (may be
24729 NULL), non-negative error codes indicate a present pathLenConstraint
24730 field and the actual value, -1 indicate that the field is absent.
24731 </p>
24732 <p>This function will read the certificate&rsquo;s basic constraints, and
24733 return the certificates CA status.  It reads the basicConstraints
24734 X.509 extension (2.5.29.19).
24735 </p>
24736 <p><strong>Returns:</strong> If the certificate is a CA a positive value will be
24737 returned, or (0) if the certificate does not have CA flag set.
24738 A negative error code may be returned in case of errors.  If the
24739 certificate does not contain the basicConstraints extension
24740 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be returned.
24741 </p>
24742 <p><strong>Since:</strong> 2.8.0
24743 </p></dd></dl>
24744
24745 <a name="gnutls_005fx509_005fcrq_005fget_005fchallenge_005fpassword-1"></a>
24746 <h4 class="subheading">gnutls_x509_crq_get_challenge_password</h4>
24747 <a name="gnutls_005fx509_005fcrq_005fget_005fchallenge_005fpassword"></a><dl>
24748 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fchallenge_005fpassword"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_challenge_password</strong> <em>(gnutls_x509_crq_t <var>crq</var>, char * <var>pass</var>, size_t * <var>pass_size</var>)</em></dt>
24749 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24750 </p>
24751 <p><var>pass</var>: will hold a (0)-terminated password string
24752 </p>
24753 <p><var>pass_size</var>: Initially holds the size of  <code>pass</code> .
24754 </p>
24755 <p>This function will return the challenge password in the request.
24756 The challenge password is intended to be used for requesting a
24757 revocation of the certificate.
24758 </p>
24759 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24760 negative error value.
24761 </p></dd></dl>
24762
24763 <a name="gnutls_005fx509_005fcrq_005fget_005fdn-1"></a>
24764 <h4 class="subheading">gnutls_x509_crq_get_dn</h4>
24765 <a name="gnutls_005fx509_005fcrq_005fget_005fdn"></a><dl>
24766 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fdn"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_dn</strong> <em>(gnutls_x509_crq_t <var>crq</var>, char * <var>buf</var>, size_t * <var>buf_size</var>)</em></dt>
24767 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24768 </p>
24769 <p><var>buf</var>: a pointer to a structure to hold the name (may be <code>NULL</code> )
24770 </p>
24771 <p><var>buf_size</var>: initially holds the size of  <code>buf</code>
24772 </p>
24773 <p>This function will copy the name of the Certificate request subject
24774 to the provided buffer.  The name will be in the form
24775 &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as described in RFC 2253. The output string
24776  <code>buf</code> will be ASCII or UTF-8 encoded, depending on the certificate
24777 data.
24778 </p>
24779 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is not
24780 long enough, and in that case the * <code>buf_size</code> will be updated with
24781 the required size.  On success 0 is returned.
24782 </p></dd></dl>
24783
24784 <a name="gnutls_005fx509_005fcrq_005fget_005fdn2-1"></a>
24785 <h4 class="subheading">gnutls_x509_crq_get_dn2</h4>
24786 <a name="gnutls_005fx509_005fcrq_005fget_005fdn2"></a><dl>
24787 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fdn2"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_dn2</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_datum_t * <var>dn</var>)</em></dt>
24788 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24789 </p>
24790 <p><var>dn</var>: a pointer to a structure to hold the name
24791 </p>
24792 <p>This function will allocate buffer and copy the name of the Certificate
24793 request. The name will be in the form &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as
24794 described in RFC4514. The output string will be ASCII or UTF-8
24795 encoded, depending on the certificate data.
24796 </p>
24797 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24798 negative error value. and a negative error code on error.
24799 </p>
24800 <p><strong>Since:</strong> 3.1.10
24801 </p></dd></dl>
24802
24803 <a name="gnutls_005fx509_005fcrq_005fget_005fdn_005fby_005foid-1"></a>
24804 <h4 class="subheading">gnutls_x509_crq_get_dn_by_oid</h4>
24805 <a name="gnutls_005fx509_005fcrq_005fget_005fdn_005fby_005foid"></a><dl>
24806 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fdn_005fby_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_dn_by_oid</strong> <em>(gnutls_x509_crq_t <var>crq</var>, const char * <var>oid</var>, int <var>indx</var>, unsigned int <var>raw_flag</var>, void * <var>buf</var>, size_t * <var>buf_size</var>)</em></dt>
24807 <dd><p><var>crq</var>: should contain a gnutls_x509_crq_t structure
24808 </p>
24809 <p><var>oid</var>: holds an Object Identifier in a null terminated string
24810 </p>
24811 <p><var>indx</var>: In case multiple same OIDs exist in the RDN, this specifies
24812 which to get. Use (0) to get the first one.
24813 </p>
24814 <p><var>raw_flag</var>: If non-zero returns the raw DER data of the DN part.
24815 </p>
24816 <p><var>buf</var>: a pointer to a structure to hold the name (may be <code>NULL</code> )
24817 </p>
24818 <p><var>buf_size</var>: initially holds the size of  <code>buf</code>
24819 </p>
24820 <p>This function will extract the part of the name of the Certificate
24821 request subject, specified by the given OID. The output will be
24822 encoded as described in RFC2253. The output string will be ASCII
24823 or UTF-8 encoded, depending on the certificate data.
24824 </p>
24825 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
24826 If raw flag is (0), this function will only return known OIDs as
24827 text. Other OIDs will be DER encoded, as described in RFC2253 &ndash;
24828 in hex format with a &rsquo;\#&rsquo; prefix.  You can check about known OIDs
24829 using <code>gnutls_x509_dn_oid_known()</code> .
24830 </p>
24831 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is
24832 not long enough, and in that case the * <code>buf_size</code> will be
24833 updated with the required size.  On success 0 is returned.
24834 </p></dd></dl>
24835
24836 <a name="gnutls_005fx509_005fcrq_005fget_005fdn_005foid-1"></a>
24837 <h4 class="subheading">gnutls_x509_crq_get_dn_oid</h4>
24838 <a name="gnutls_005fx509_005fcrq_005fget_005fdn_005foid"></a><dl>
24839 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fdn_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_dn_oid</strong> <em>(gnutls_x509_crq_t <var>crq</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>sizeof_oid</var>)</em></dt>
24840 <dd><p><var>crq</var>: should contain a gnutls_x509_crq_t structure
24841 </p>
24842 <p><var>indx</var>: Specifies which DN OID to get. Use (0) to get the first one.
24843 </p>
24844 <p><var>oid</var>: a pointer to a structure to hold the name (may be <code>NULL</code> )
24845 </p>
24846 <p><var>sizeof_oid</var>: initially holds the size of  <code>oid</code>
24847 </p>
24848 <p>This function will extract the requested OID of the name of the
24849 certificate request subject, specified by the given index.
24850 </p>
24851 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is
24852 not long enough, and in that case the * <code>sizeof_oid</code> will be
24853 updated with the required size.  On success 0 is returned.
24854 </p></dd></dl>
24855
24856 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005fby_005foid-1"></a>
24857 <h4 class="subheading">gnutls_x509_crq_get_extension_by_oid</h4>
24858 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005fby_005foid"></a><dl>
24859 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fextension_005fby_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_extension_by_oid</strong> <em>(gnutls_x509_crq_t <var>crq</var>, const char * <var>oid</var>, int <var>indx</var>, void * <var>buf</var>, size_t * <var>buf_size</var>, unsigned int * <var>critical</var>)</em></dt>
24860 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24861 </p>
24862 <p><var>oid</var>: holds an Object Identifier in a null terminated string
24863 </p>
24864 <p><var>indx</var>: In case multiple same OIDs exist in the extensions, this
24865 specifies which to get. Use (0) to get the first one.
24866 </p>
24867 <p><var>buf</var>: a pointer to a structure to hold the name (may be null)
24868 </p>
24869 <p><var>buf_size</var>: initially holds the size of  <code>buf</code>
24870 </p>
24871 <p><var>critical</var>: will be non-zero if the extension is marked as critical
24872 </p>
24873 <p>This function will return the extension specified by the OID in
24874 the certificate.  The extensions will be returned as binary data
24875 DER encoded, in the provided buffer.
24876 </p>
24877 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24878 negative error code in case of an error.  If the certificate does not
24879 contain the specified extension
24880 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be returned.
24881 </p>
24882 <p><strong>Since:</strong> 2.8.0
24883 </p></dd></dl>
24884
24885 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005fby_005foid2-1"></a>
24886 <h4 class="subheading">gnutls_x509_crq_get_extension_by_oid2</h4>
24887 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005fby_005foid2"></a><dl>
24888 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fextension_005fby_005foid2"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_extension_by_oid2</strong> <em>(gnutls_x509_crq_t <var>crq</var>, const char * <var>oid</var>, int <var>indx</var>, gnutls_datum_t * <var>output</var>, unsigned int * <var>critical</var>)</em></dt>
24889 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24890 </p>
24891 <p><var>oid</var>: holds an Object Identifier in a null terminated string
24892 </p>
24893 <p><var>indx</var>: In case multiple same OIDs exist in the extensions, this
24894 specifies which to get. Use (0) to get the first one.
24895 </p>
24896 <p><var>output</var>: will hold the allocated extension data
24897 </p>
24898 <p><var>critical</var>: will be non-zero if the extension is marked as critical
24899 </p>
24900 <p>This function will return the extension specified by the OID in
24901 the certificate.  The extensions will be returned as binary data
24902 DER encoded, in the provided buffer.
24903 </p>
24904 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24905 negative error code in case of an error.  If the certificate does not
24906 contain the specified extension
24907 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be returned.
24908 </p>
24909 <p><strong>Since:</strong> 3.3.8
24910 </p></dd></dl>
24911
24912 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005fdata-1"></a>
24913 <h4 class="subheading">gnutls_x509_crq_get_extension_data</h4>
24914 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005fdata"></a><dl>
24915 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fextension_005fdata"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_extension_data</strong> <em>(gnutls_x509_crq_t <var>crq</var>, int <var>indx</var>, void * <var>data</var>, size_t * <var>sizeof_data</var>)</em></dt>
24916 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24917 </p>
24918 <p><var>indx</var>: Specifies which extension number to get. Use (0) to get the first one.
24919 </p>
24920 <p><var>data</var>: a pointer to a structure to hold the data (may be null)
24921 </p>
24922 <p><var>sizeof_data</var>: initially holds the size of  <code>oid</code>
24923 </p>
24924 <p>This function will return the requested extension data in the
24925 certificate.  The extension data will be stored as a string in the
24926 provided buffer.
24927 </p>
24928 <p>Use <code>gnutls_x509_crq_get_extension_info()</code>  to extract the OID and
24929 critical flag.  Use <code>gnutls_x509_crq_get_extension_by_oid()</code>  instead,
24930 if you want to get data indexed by the extension OID rather than
24931 sequence.
24932 </p>
24933 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24934 negative error code in case of an error.  If your have reached the
24935 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
24936 will be returned.
24937 </p>
24938 <p><strong>Since:</strong> 2.8.0
24939 </p></dd></dl>
24940
24941 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005fdata2-1"></a>
24942 <h4 class="subheading">gnutls_x509_crq_get_extension_data2</h4>
24943 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005fdata2"></a><dl>
24944 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fextension_005fdata2"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_extension_data2</strong> <em>(gnutls_x509_crq_t <var>crq</var>, unsigned <var>indx</var>, gnutls_datum_t * <var>data</var>)</em></dt>
24945 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24946 </p>
24947 <p><var>indx</var>: Specifies which extension OID to read. Use (0) to get the first one.
24948 </p>
24949 <p><var>data</var>: will contain the extension DER-encoded data
24950 </p>
24951 <p>This function will return the requested extension data in the
24952 certificate request.  The extension data will be allocated using
24953 <code>gnutls_malloc()</code> .
24954 </p>
24955 <p>Use <code>gnutls_x509_crq_get_extension_info()</code>  to extract the OID.
24956 </p>
24957 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
24958 otherwise a negative error code is returned.  If you have reached the
24959 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
24960 will be returned.
24961 </p>
24962 <p><strong>Since:</strong> 3.3.0
24963 </p></dd></dl>
24964
24965 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005finfo-1"></a>
24966 <h4 class="subheading">gnutls_x509_crq_get_extension_info</h4>
24967 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005finfo"></a><dl>
24968 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fextension_005finfo"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_extension_info</strong> <em>(gnutls_x509_crq_t <var>crq</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>sizeof_oid</var>, unsigned int * <var>critical</var>)</em></dt>
24969 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
24970 </p>
24971 <p><var>indx</var>: Specifies which extension number to get. Use (0) to get the first one.
24972 </p>
24973 <p><var>oid</var>: a pointer to a structure to hold the OID
24974 </p>
24975 <p><var>sizeof_oid</var>: initially holds the maximum size of  <code>oid</code> , on return
24976 holds actual size of  <code>oid</code> .
24977 </p>
24978 <p><var>critical</var>: output variable with critical flag, may be NULL.
24979 </p>
24980 <p>This function will return the requested extension OID in the
24981 certificate, and the critical flag for it.  The extension OID will
24982 be stored as a string in the provided buffer.  Use
24983 <code>gnutls_x509_crq_get_extension_data()</code>  to extract the data.
24984 </p>
24985 <p>If the buffer provided is not long enough to hold the output, then
24986 * <code>sizeof_oid</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  will be
24987 returned.
24988 </p>
24989 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
24990 negative error code in case of an error.  If your have reached the
24991 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
24992 will be returned.
24993 </p>
24994 <p><strong>Since:</strong> 2.8.0
24995 </p></dd></dl>
24996
24997 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005fid-1"></a>
24998 <h4 class="subheading">gnutls_x509_crq_get_key_id</h4>
24999 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005fid"></a><dl>
25000 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_key_id</strong> <em>(gnutls_x509_crq_t <var>crq</var>, unsigned int <var>flags</var>, unsigned char * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
25001 <dd><p><var>crq</var>: a certificate of type <code>gnutls_x509_crq_t</code>
25002 </p>
25003 <p><var>flags</var>: should be 0 for now
25004 </p>
25005 <p><var>output_data</var>: will contain the key ID
25006 </p>
25007 <p><var>output_data_size</var>: holds the size of output_data (and will be
25008 replaced by the actual size of parameters)
25009 </p>
25010 <p>This function will return a unique ID that depends on the public key
25011 parameters.  This ID can be used in checking whether a certificate
25012 corresponds to the given private key.
25013 </p>
25014 <p>If the buffer provided is not long enough to hold the output, then
25015 * <code>output_data_size</code> is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
25016 be returned.  The output will normally be a SHA-1 hash output,
25017 which is 20 bytes.
25018 </p>
25019 <p><strong>Returns:</strong> In case of failure a negative error code will be
25020 returned, and 0 on success.
25021 </p>
25022 <p><strong>Since:</strong> 2.8.0
25023 </p></dd></dl>
25024
25025 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005fpurpose_005foid-1"></a>
25026 <h4 class="subheading">gnutls_x509_crq_get_key_purpose_oid</h4>
25027 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005fpurpose_005foid"></a><dl>
25028 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fkey_005fpurpose_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_key_purpose_oid</strong> <em>(gnutls_x509_crq_t <var>crq</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>sizeof_oid</var>, unsigned int * <var>critical</var>)</em></dt>
25029 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25030 </p>
25031 <p><var>indx</var>: This specifies which OID to return, use (0) to get the first one
25032 </p>
25033 <p><var>oid</var>: a pointer to a buffer to hold the OID (may be <code>NULL</code> )
25034 </p>
25035 <p><var>sizeof_oid</var>: initially holds the size of  <code>oid</code>
25036 </p>
25037 <p><var>critical</var>: output variable with critical flag, may be <code>NULL</code> .
25038 </p>
25039 <p>This function will extract the key purpose OIDs of the Certificate
25040 specified by the given index.  These are stored in the Extended Key
25041 Usage extension (2.5.29.37).  See the GNUTLS_KP_* definitions for
25042 human readable names.
25043 </p>
25044 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is
25045 not long enough, and in that case the * <code>sizeof_oid</code> will be
25046 updated with the required size.  On success 0 is returned.
25047 </p>
25048 <p><strong>Since:</strong> 2.8.0
25049 </p></dd></dl>
25050
25051 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005frsa_005fraw-1"></a>
25052 <h4 class="subheading">gnutls_x509_crq_get_key_rsa_raw</h4>
25053 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005frsa_005fraw"></a><dl>
25054 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fkey_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_key_rsa_raw</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>)</em></dt>
25055 <dd><p><var>crq</var>: Holds the certificate
25056 </p>
25057 <p><var>m</var>: will hold the modulus
25058 </p>
25059 <p><var>e</var>: will hold the public exponent
25060 </p>
25061 <p>This function will export the RSA public key&rsquo;s parameters found in
25062 the given structure.  The new parameters will be allocated using
25063 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
25064 </p>
25065 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25066 negative error value.
25067 </p>
25068 <p><strong>Since:</strong> 2.8.0
25069 </p></dd></dl>
25070
25071 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005fusage-1"></a>
25072 <h4 class="subheading">gnutls_x509_crq_get_key_usage</h4>
25073 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005fusage"></a><dl>
25074 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fkey_005fusage"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_key_usage</strong> <em>(gnutls_x509_crq_t <var>crq</var>, unsigned int * <var>key_usage</var>, unsigned int * <var>critical</var>)</em></dt>
25075 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25076 </p>
25077 <p><var>key_usage</var>: where the key usage bits will be stored
25078 </p>
25079 <p><var>critical</var>: will be non-zero if the extension is marked as critical
25080 </p>
25081 <p>This function will return certificate&rsquo;s key usage, by reading the
25082 keyUsage X.509 extension (2.5.29.15).  The key usage value will
25083 ORed values of the: <code>GNUTLS_KEY_DIGITAL_SIGNATURE</code> ,
25084 <code>GNUTLS_KEY_NON_REPUDIATION</code> , <code>GNUTLS_KEY_KEY_ENCIPHERMENT</code> ,
25085 <code>GNUTLS_KEY_DATA_ENCIPHERMENT</code> , <code>GNUTLS_KEY_KEY_AGREEMENT</code> ,
25086 <code>GNUTLS_KEY_KEY_CERT_SIGN</code> , <code>GNUTLS_KEY_CRL_SIGN</code> ,
25087 <code>GNUTLS_KEY_ENCIPHER_ONLY</code> , <code>GNUTLS_KEY_DECIPHER_ONLY</code> .
25088 </p>
25089 <p><strong>Returns:</strong> the certificate key usage, or a negative error code in case of
25090 parsing error.  If the certificate does not contain the keyUsage
25091 extension <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be
25092 returned.
25093 </p>
25094 <p><strong>Since:</strong> 2.8.0
25095 </p></dd></dl>
25096
25097 <a name="gnutls_005fx509_005fcrq_005fget_005fpk_005falgorithm-1"></a>
25098 <h4 class="subheading">gnutls_x509_crq_get_pk_algorithm</h4>
25099 <a name="gnutls_005fx509_005fcrq_005fget_005fpk_005falgorithm"></a><dl>
25100 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fpk_005falgorithm"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_pk_algorithm</strong> <em>(gnutls_x509_crq_t <var>crq</var>, unsigned int * <var>bits</var>)</em></dt>
25101 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25102 </p>
25103 <p><var>bits</var>: if bits is non-<code>NULL</code>  it will hold the size of the parameters&rsquo; in bits
25104 </p>
25105 <p>This function will return the public key algorithm of a PKCS<code>10</code>
25106 certificate request.
25107 </p>
25108 <p>If bits is non-<code>NULL</code> , it should have enough size to hold the
25109 parameters size in bits.  For RSA the bits returned is the modulus.
25110 For DSA the bits returned are of the public exponent.
25111 </p>
25112 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code>  enumeration on
25113 success, or a negative error code on error.
25114 </p></dd></dl>
25115
25116 <a name="gnutls_005fx509_005fcrq_005fget_005fprivate_005fkey_005fusage_005fperiod-1"></a>
25117 <h4 class="subheading">gnutls_x509_crq_get_private_key_usage_period</h4>
25118 <a name="gnutls_005fx509_005fcrq_005fget_005fprivate_005fkey_005fusage_005fperiod"></a><dl>
25119 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fprivate_005fkey_005fusage_005fperiod"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_private_key_usage_period</strong> <em>(gnutls_x509_crq_t <var>crq</var>, time_t * <var>activation</var>, time_t * <var>expiration</var>, unsigned int * <var>critical</var>)</em></dt>
25120 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25121 </p>
25122 <p><var>activation</var>: The activation time
25123 </p>
25124 <p><var>expiration</var>: The expiration time
25125 </p>
25126 <p><var>critical</var>: the extension status
25127 </p>
25128 <p>This function will return the expiration and activation
25129 times of the private key of the certificate.
25130 </p>
25131 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
25132 if the extension is not present, otherwise a negative error value.
25133 </p></dd></dl>
25134
25135 <a name="gnutls_005fx509_005fcrq_005fget_005fsubject_005falt_005fname-1"></a>
25136 <h4 class="subheading">gnutls_x509_crq_get_subject_alt_name</h4>
25137 <a name="gnutls_005fx509_005fcrq_005fget_005fsubject_005falt_005fname"></a><dl>
25138 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fsubject_005falt_005fname"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_subject_alt_name</strong> <em>(gnutls_x509_crq_t <var>crq</var>, unsigned int <var>seq</var>, void * <var>ret</var>, size_t * <var>ret_size</var>, unsigned int * <var>ret_type</var>, unsigned int * <var>critical</var>)</em></dt>
25139 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25140 </p>
25141 <p><var>seq</var>: specifies the sequence number of the alt name, 0 for the
25142 first one, 1 for the second etc.
25143 </p>
25144 <p><var>ret</var>: is the place where the alternative name will be copied to
25145 </p>
25146 <p><var>ret_size</var>: holds the size of ret.
25147 </p>
25148 <p><var>ret_type</var>: holds the <code>gnutls_x509_subject_alt_name_t</code>  name type
25149 </p>
25150 <p><var>critical</var>: will be non-zero if the extension is marked as critical
25151 (may be null)
25152 </p>
25153 <p>This function will return the alternative names, contained in the
25154 given certificate.  It is the same as
25155 <code>gnutls_x509_crq_get_subject_alt_name()</code>  except for the fact that it
25156 will return the type of the alternative name in  <code>ret_type</code> even if
25157 the function fails for some reason (i.e.  the buffer provided is
25158 not enough).
25159 </p>
25160 <p><strong>Returns:</strong> the alternative subject name type on success, one of the
25161 enumerated <code>gnutls_x509_subject_alt_name_t</code> .  It will return
25162 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if  <code>ret_size</code> is not large enough to
25163 hold the value.  In that case  <code>ret_size</code> will be updated with the
25164 required size.  If the certificate request does not have an
25165 Alternative name with the specified sequence number then
25166 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is returned.
25167 </p>
25168 <p><strong>Since:</strong> 2.8.0
25169 </p></dd></dl>
25170
25171 <a name="gnutls_005fx509_005fcrq_005fget_005fsubject_005falt_005fothername_005foid-1"></a>
25172 <h4 class="subheading">gnutls_x509_crq_get_subject_alt_othername_oid</h4>
25173 <a name="gnutls_005fx509_005fcrq_005fget_005fsubject_005falt_005fothername_005foid"></a><dl>
25174 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fsubject_005falt_005fothername_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_subject_alt_othername_oid</strong> <em>(gnutls_x509_crq_t <var>crq</var>, unsigned int <var>seq</var>, void * <var>ret</var>, size_t * <var>ret_size</var>)</em></dt>
25175 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25176 </p>
25177 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
25178 </p>
25179 <p><var>ret</var>: is the place where the otherName OID will be copied to
25180 </p>
25181 <p><var>ret_size</var>: holds the size of ret.
25182 </p>
25183 <p>This function will extract the type OID of an otherName Subject
25184 Alternative Name, contained in the given certificate, and return
25185 the type as an enumerated element.
25186 </p>
25187 <p>This function is only useful if
25188 <code>gnutls_x509_crq_get_subject_alt_name()</code>  returned
25189 <code>GNUTLS_SAN_OTHERNAME</code> .
25190 </p>
25191 <p><strong>Returns:</strong> the alternative subject name type on success, one of the
25192 enumerated gnutls_x509_subject_alt_name_t.  For supported OIDs,
25193 it will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
25194 e.g. <code>GNUTLS_SAN_OTHERNAME_XMPP</code> , and <code>GNUTLS_SAN_OTHERNAME</code>  for
25195 unknown OIDs.  It will return <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if
25196  <code>ret_size</code> is not large enough to hold the value.  In that case
25197  <code>ret_size</code> will be updated with the required size.  If the
25198 certificate does not have an Alternative name with the specified
25199 sequence number and with the otherName type then
25200 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is returned.
25201 </p>
25202 <p><strong>Since:</strong> 2.8.0
25203 </p></dd></dl>
25204
25205 <a name="gnutls_005fx509_005fcrq_005fget_005fversion-1"></a>
25206 <h4 class="subheading">gnutls_x509_crq_get_version</h4>
25207 <a name="gnutls_005fx509_005fcrq_005fget_005fversion"></a><dl>
25208 <dt><a name="index-gnutls_005fx509_005fcrq_005fget_005fversion"></a>Function: <em>int</em> <strong>gnutls_x509_crq_get_version</strong> <em>(gnutls_x509_crq_t <var>crq</var>)</em></dt>
25209 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25210 </p>
25211 <p>This function will return the version of the specified Certificate
25212 request.
25213 </p>
25214 <p><strong>Returns:</strong> version of certificate request, or a negative error code on
25215 error.
25216 </p></dd></dl>
25217
25218 <a name="gnutls_005fx509_005fcrq_005fimport-1"></a>
25219 <h4 class="subheading">gnutls_x509_crq_import</h4>
25220 <a name="gnutls_005fx509_005fcrq_005fimport"></a><dl>
25221 <dt><a name="index-gnutls_005fx509_005fcrq_005fimport"></a>Function: <em>int</em> <strong>gnutls_x509_crq_import</strong> <em>(gnutls_x509_crq_t <var>crq</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>)</em></dt>
25222 <dd><p><var>crq</var>: The structure to store the parsed certificate request.
25223 </p>
25224 <p><var>data</var>: The DER or PEM encoded certificate.
25225 </p>
25226 <p><var>format</var>: One of DER or PEM
25227 </p>
25228 <p>This function will convert the given DER or PEM encoded certificate
25229 request to a <code>gnutls_x509_crq_t</code>  structure.  The output will be
25230 stored in  <code>crq</code> .
25231 </p>
25232 <p>If the Certificate is PEM encoded it should have a header of &quot;NEW
25233 CERTIFICATE REQUEST&quot;.
25234 </p>
25235 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25236 negative error value.
25237 </p></dd></dl>
25238
25239 <a name="gnutls_005fx509_005fcrq_005finit-1"></a>
25240 <h4 class="subheading">gnutls_x509_crq_init</h4>
25241 <a name="gnutls_005fx509_005fcrq_005finit"></a><dl>
25242 <dt><a name="index-gnutls_005fx509_005fcrq_005finit"></a>Function: <em>int</em> <strong>gnutls_x509_crq_init</strong> <em>(gnutls_x509_crq_t * <var>crq</var>)</em></dt>
25243 <dd><p><var>crq</var>: The structure to be initialized
25244 </p>
25245 <p>This function will initialize a PKCS<code>10</code>  certificate request
25246 structure.
25247 </p>
25248 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25249 negative error value.
25250 </p></dd></dl>
25251
25252 <a name="gnutls_005fx509_005fcrq_005fprint-1"></a>
25253 <h4 class="subheading">gnutls_x509_crq_print</h4>
25254 <a name="gnutls_005fx509_005fcrq_005fprint"></a><dl>
25255 <dt><a name="index-gnutls_005fx509_005fcrq_005fprint"></a>Function: <em>int</em> <strong>gnutls_x509_crq_print</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_certificate_print_formats_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
25256 <dd><p><var>crq</var>: The structure to be printed
25257 </p>
25258 <p><var>format</var>: Indicate the format to use
25259 </p>
25260 <p><var>out</var>: Newly allocated datum with null terminated string.
25261 </p>
25262 <p>This function will pretty print a certificate request, suitable for
25263 display to a human.
25264 </p>
25265 <p>The output  <code>out</code> needs to be deallocated using <code>gnutls_free()</code> .
25266 </p>
25267 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25268 negative error value.
25269 </p>
25270 <p><strong>Since:</strong> 2.8.0
25271 </p></dd></dl>
25272
25273 <a name="gnutls_005fx509_005fcrq_005fset_005fattribute_005fby_005foid-1"></a>
25274 <h4 class="subheading">gnutls_x509_crq_set_attribute_by_oid</h4>
25275 <a name="gnutls_005fx509_005fcrq_005fset_005fattribute_005fby_005foid"></a><dl>
25276 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fattribute_005fby_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_attribute_by_oid</strong> <em>(gnutls_x509_crq_t <var>crq</var>, const char * <var>oid</var>, void * <var>buf</var>, size_t <var>buf_size</var>)</em></dt>
25277 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25278 </p>
25279 <p><var>oid</var>: holds an Object Identifier in a null-terminated string
25280 </p>
25281 <p><var>buf</var>: a pointer to a structure that holds the attribute data
25282 </p>
25283 <p><var>buf_size</var>: holds the size of  <code>buf</code>
25284 </p>
25285 <p>This function will set the attribute in the certificate request
25286 specified by the given Object ID. The provided attribute must be be DER
25287 encoded.
25288 </p>
25289 <p>Attributes in a certificate request is an optional set of data
25290 appended to the request. Their interpretation depends on the CA policy.
25291 </p>
25292 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25293 negative error value.
25294 </p></dd></dl>
25295
25296 <a name="gnutls_005fx509_005fcrq_005fset_005fbasic_005fconstraints-1"></a>
25297 <h4 class="subheading">gnutls_x509_crq_set_basic_constraints</h4>
25298 <a name="gnutls_005fx509_005fcrq_005fset_005fbasic_005fconstraints"></a><dl>
25299 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fbasic_005fconstraints"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_basic_constraints</strong> <em>(gnutls_x509_crq_t <var>crq</var>, unsigned int <var>ca</var>, int <var>pathLenConstraint</var>)</em></dt>
25300 <dd><p><var>crq</var>: a certificate request of type <code>gnutls_x509_crq_t</code>
25301 </p>
25302 <p><var>ca</var>: true(1) or false(0) depending on the Certificate authority status.
25303 </p>
25304 <p><var>pathLenConstraint</var>: non-negative error codes indicate maximum length of path,
25305 and negative error codes indicate that the pathLenConstraints field should
25306 not be present.
25307 </p>
25308 <p>This function will set the basicConstraints certificate extension.
25309 </p>
25310 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25311 negative error value.
25312 </p>
25313 <p><strong>Since:</strong> 2.8.0
25314 </p></dd></dl>
25315
25316 <a name="gnutls_005fx509_005fcrq_005fset_005fchallenge_005fpassword-1"></a>
25317 <h4 class="subheading">gnutls_x509_crq_set_challenge_password</h4>
25318 <a name="gnutls_005fx509_005fcrq_005fset_005fchallenge_005fpassword"></a><dl>
25319 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fchallenge_005fpassword"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_challenge_password</strong> <em>(gnutls_x509_crq_t <var>crq</var>, const char * <var>pass</var>)</em></dt>
25320 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25321 </p>
25322 <p><var>pass</var>: holds a (0)-terminated password
25323 </p>
25324 <p>This function will set a challenge password to be used when
25325 revoking the request.
25326 </p>
25327 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25328 negative error value.
25329 </p></dd></dl>
25330
25331 <a name="gnutls_005fx509_005fcrq_005fset_005fdn-1"></a>
25332 <h4 class="subheading">gnutls_x509_crq_set_dn</h4>
25333 <a name="gnutls_005fx509_005fcrq_005fset_005fdn"></a><dl>
25334 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fdn"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_dn</strong> <em>(gnutls_x509_crq_t <var>crq</var>, const char * <var>dn</var>, const char ** <var>err</var>)</em></dt>
25335 <dd><p><var>crq</var>: a certificate of type <code>gnutls_x509_crq_t</code>
25336 </p>
25337 <p><var>dn</var>: a comma separated DN string (RFC4514)
25338 </p>
25339 <p><var>err</var>: indicates the error position (if any)
25340 </p>
25341 <p>This function will set the DN on the provided certificate.
25342 The input string should be plain ASCII or UTF-8 encoded.
25343 </p>
25344 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25345 negative error value.
25346 </p></dd></dl>
25347
25348 <a name="gnutls_005fx509_005fcrq_005fset_005fdn_005fby_005foid-1"></a>
25349 <h4 class="subheading">gnutls_x509_crq_set_dn_by_oid</h4>
25350 <a name="gnutls_005fx509_005fcrq_005fset_005fdn_005fby_005foid"></a><dl>
25351 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fdn_005fby_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_dn_by_oid</strong> <em>(gnutls_x509_crq_t <var>crq</var>, const char * <var>oid</var>, unsigned int <var>raw_flag</var>, const void * <var>data</var>, unsigned int <var>sizeof_data</var>)</em></dt>
25352 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25353 </p>
25354 <p><var>oid</var>: holds an Object Identifier in a (0)-terminated string
25355 </p>
25356 <p><var>raw_flag</var>: must be 0, or 1 if the data are DER encoded
25357 </p>
25358 <p><var>data</var>: a pointer to the input data
25359 </p>
25360 <p><var>sizeof_data</var>: holds the size of  <code>data</code>
25361 </p>
25362 <p>This function will set the part of the name of the Certificate
25363 request subject, specified by the given OID.  The input string
25364 should be ASCII or UTF-8 encoded.
25365 </p>
25366 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
25367 With this function you can only set the known OIDs.  You can test
25368 for known OIDs using <code>gnutls_x509_dn_oid_known()</code> .  For OIDs that are
25369 not known (by gnutls) you should properly DER encode your data, and
25370 call this function with raw_flag set.
25371 </p>
25372 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25373 negative error value.
25374 </p></dd></dl>
25375
25376 <a name="gnutls_005fx509_005fcrq_005fset_005fkey-1"></a>
25377 <h4 class="subheading">gnutls_x509_crq_set_key</h4>
25378 <a name="gnutls_005fx509_005fcrq_005fset_005fkey"></a><dl>
25379 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fkey-1"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_key</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_x509_privkey_t <var>key</var>)</em></dt>
25380 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25381 </p>
25382 <p><var>key</var>: holds a private key
25383 </p>
25384 <p>This function will set the public parameters from the given private
25385 key to the request.
25386 </p>
25387 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25388 negative error value.
25389 </p></dd></dl>
25390
25391 <a name="gnutls_005fx509_005fcrq_005fset_005fkey_005fpurpose_005foid-1"></a>
25392 <h4 class="subheading">gnutls_x509_crq_set_key_purpose_oid</h4>
25393 <a name="gnutls_005fx509_005fcrq_005fset_005fkey_005fpurpose_005foid"></a><dl>
25394 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fkey_005fpurpose_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_key_purpose_oid</strong> <em>(gnutls_x509_crq_t <var>crq</var>, const void * <var>oid</var>, unsigned int <var>critical</var>)</em></dt>
25395 <dd><p><var>crq</var>: a certificate of type <code>gnutls_x509_crq_t</code>
25396 </p>
25397 <p><var>oid</var>: a pointer to a (0)-terminated string that holds the OID
25398 </p>
25399 <p><var>critical</var>: Whether this extension will be critical or not
25400 </p>
25401 <p>This function will set the key purpose OIDs of the Certificate.
25402 These are stored in the Extended Key Usage extension (2.5.29.37)
25403 See the GNUTLS_KP_* definitions for human readable names.
25404 </p>
25405 <p>Subsequent calls to this function will append OIDs to the OID list.
25406 </p>
25407 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25408 negative error value.
25409 </p>
25410 <p><strong>Since:</strong> 2.8.0
25411 </p></dd></dl>
25412
25413 <a name="gnutls_005fx509_005fcrq_005fset_005fkey_005frsa_005fraw-1"></a>
25414 <h4 class="subheading">gnutls_x509_crq_set_key_rsa_raw</h4>
25415 <a name="gnutls_005fx509_005fcrq_005fset_005fkey_005frsa_005fraw"></a><dl>
25416 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fkey_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_key_rsa_raw</strong> <em>(gnutls_x509_crq_t <var>crq</var>, const gnutls_datum_t * <var>m</var>, const gnutls_datum_t * <var>e</var>)</em></dt>
25417 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25418 </p>
25419 <p><var>m</var>: holds the modulus
25420 </p>
25421 <p><var>e</var>: holds the public exponent
25422 </p>
25423 <p>This function will set the public parameters from the given private
25424 key to the request. Only RSA keys are currently supported.
25425 </p>
25426 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25427 negative error value.
25428 </p>
25429 <p><strong>Since:</strong> 2.6.0
25430 </p></dd></dl>
25431
25432 <a name="gnutls_005fx509_005fcrq_005fset_005fkey_005fusage-1"></a>
25433 <h4 class="subheading">gnutls_x509_crq_set_key_usage</h4>
25434 <a name="gnutls_005fx509_005fcrq_005fset_005fkey_005fusage"></a><dl>
25435 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fkey_005fusage"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_key_usage</strong> <em>(gnutls_x509_crq_t <var>crq</var>, unsigned int <var>usage</var>)</em></dt>
25436 <dd><p><var>crq</var>: a certificate request of type <code>gnutls_x509_crq_t</code>
25437 </p>
25438 <p><var>usage</var>: an ORed sequence of the GNUTLS_KEY_* elements.
25439 </p>
25440 <p>This function will set the keyUsage certificate extension.
25441 </p>
25442 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25443 negative error value.
25444 </p>
25445 <p><strong>Since:</strong> 2.8.0
25446 </p></dd></dl>
25447
25448 <a name="gnutls_005fx509_005fcrq_005fset_005fprivate_005fkey_005fusage_005fperiod-1"></a>
25449 <h4 class="subheading">gnutls_x509_crq_set_private_key_usage_period</h4>
25450 <a name="gnutls_005fx509_005fcrq_005fset_005fprivate_005fkey_005fusage_005fperiod"></a><dl>
25451 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fprivate_005fkey_005fusage_005fperiod"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_private_key_usage_period</strong> <em>(gnutls_x509_crq_t <var>crq</var>, time_t <var>activation</var>, time_t <var>expiration</var>)</em></dt>
25452 <dd><p><var>crq</var>: a certificate of type <code>gnutls_x509_crq_t</code>
25453 </p>
25454 <p><var>activation</var>: The activation time
25455 </p>
25456 <p><var>expiration</var>: The expiration time
25457 </p>
25458 <p>This function will set the private key usage period extension (2.5.29.16).
25459 </p>
25460 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25461 negative error value.
25462 </p></dd></dl>
25463
25464 <a name="gnutls_005fx509_005fcrq_005fset_005fsubject_005falt_005fname-1"></a>
25465 <h4 class="subheading">gnutls_x509_crq_set_subject_alt_name</h4>
25466 <a name="gnutls_005fx509_005fcrq_005fset_005fsubject_005falt_005fname"></a><dl>
25467 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fsubject_005falt_005fname"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_subject_alt_name</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_x509_subject_alt_name_t <var>nt</var>, const void * <var>data</var>, unsigned int <var>data_size</var>, unsigned int <var>flags</var>)</em></dt>
25468 <dd><p><var>crq</var>: a certificate request of type <code>gnutls_x509_crq_t</code>
25469 </p>
25470 <p><var>nt</var>: is one of the <code>gnutls_x509_subject_alt_name_t</code>  enumerations
25471 </p>
25472 <p><var>data</var>: The data to be set
25473 </p>
25474 <p><var>data_size</var>: The size of data to be set
25475 </p>
25476 <p><var>flags</var>: <code>GNUTLS_FSAN_SET</code>  to clear previous data or
25477 <code>GNUTLS_FSAN_APPEND</code>  to append.
25478 </p>
25479 <p>This function will set the subject alternative name certificate
25480 extension.  It can set the following types:
25481 </p>
25482 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25483 negative error value.
25484 </p>
25485 <p><strong>Since:</strong> 2.8.0
25486 </p></dd></dl>
25487
25488 <a name="gnutls_005fx509_005fcrq_005fset_005fversion-1"></a>
25489 <h4 class="subheading">gnutls_x509_crq_set_version</h4>
25490 <a name="gnutls_005fx509_005fcrq_005fset_005fversion"></a><dl>
25491 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fversion"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_version</strong> <em>(gnutls_x509_crq_t <var>crq</var>, unsigned int <var>version</var>)</em></dt>
25492 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25493 </p>
25494 <p><var>version</var>: holds the version number, for v1 Requests must be 1
25495 </p>
25496 <p>This function will set the version of the certificate request.  For
25497 version 1 requests this must be one.
25498 </p>
25499 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25500 negative error value.
25501 </p></dd></dl>
25502
25503 <a name="gnutls_005fx509_005fcrq_005fsign2-1"></a>
25504 <h4 class="subheading">gnutls_x509_crq_sign2</h4>
25505 <a name="gnutls_005fx509_005fcrq_005fsign2"></a><dl>
25506 <dt><a name="index-gnutls_005fx509_005fcrq_005fsign2-1"></a>Function: <em>int</em> <strong>gnutls_x509_crq_sign2</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_x509_privkey_t <var>key</var>, gnutls_digest_algorithm_t <var>dig</var>, unsigned int <var>flags</var>)</em></dt>
25507 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
25508 </p>
25509 <p><var>key</var>: holds a private key
25510 </p>
25511 <p><var>dig</var>: The message digest to use, i.e., <code>GNUTLS_DIG_SHA1</code>
25512 </p>
25513 <p><var>flags</var>: must be 0
25514 </p>
25515 <p>This function will sign the certificate request with a private key.
25516 This must be the same key as the one used in
25517 <code>gnutls_x509_crt_set_key()</code>  since a certificate request is self
25518 signed.
25519 </p>
25520 <p>This must be the last step in a certificate request generation
25521 since all the previously set parameters are now signed.
25522 </p>
25523 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
25524 <code>GNUTLS_E_ASN1_VALUE_NOT_FOUND</code>  is returned if you didn&rsquo;t set all
25525 information in the certificate request (e.g., the version using
25526 <code>gnutls_x509_crq_set_version()</code> ).
25527 </p></dd></dl>
25528
25529 <a name="gnutls_005fx509_005fcrq_005fverify-1"></a>
25530 <h4 class="subheading">gnutls_x509_crq_verify</h4>
25531 <a name="gnutls_005fx509_005fcrq_005fverify"></a><dl>
25532 <dt><a name="index-gnutls_005fx509_005fcrq_005fverify"></a>Function: <em>int</em> <strong>gnutls_x509_crq_verify</strong> <em>(gnutls_x509_crq_t <var>crq</var>, unsigned int <var>flags</var>)</em></dt>
25533 <dd><p><var>crq</var>: is the crq to be verified
25534 </p>
25535 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
25536 </p>
25537 <p>This function will verify self signature in the certificate
25538 request and return its status.
25539 </p>
25540 <p><strong>Returns:</strong> In case of a verification failure <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
25541 is returned, and zero or positive code on success.
25542 </p>
25543 <p>Since 2.12.0
25544 </p></dd></dl>
25545
25546 <a name="gnutls_005fx509_005fcrt_005fcheck_005fhostname-1"></a>
25547 <h4 class="subheading">gnutls_x509_crt_check_hostname</h4>
25548 <a name="gnutls_005fx509_005fcrt_005fcheck_005fhostname"></a><dl>
25549 <dt><a name="index-gnutls_005fx509_005fcrt_005fcheck_005fhostname"></a>Function: <em>int</em> <strong>gnutls_x509_crt_check_hostname</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const char * <var>hostname</var>)</em></dt>
25550 <dd><p><var>cert</var>: should contain an gnutls_x509_crt_t structure
25551 </p>
25552 <p><var>hostname</var>: A null terminated string that contains a DNS name
25553 </p>
25554 <p>This function will check if the given certificate&rsquo;s subject matches
25555 the given hostname.  This is a basic implementation of the matching
25556 described in RFC6125, and takes into account wildcards,
25557 and the DNSName/IPAddress subject alternative name PKIX extension.
25558 </p>
25559 <p>For details see also <code>gnutls_x509_crt_check_hostname2()</code> .
25560 </p>
25561 <p><strong>Returns:</strong> non-zero for a successful match, and zero on failure.
25562 </p></dd></dl>
25563
25564 <a name="gnutls_005fx509_005fcrt_005fcheck_005fhostname2-1"></a>
25565 <h4 class="subheading">gnutls_x509_crt_check_hostname2</h4>
25566 <a name="gnutls_005fx509_005fcrt_005fcheck_005fhostname2"></a><dl>
25567 <dt><a name="index-gnutls_005fx509_005fcrt_005fcheck_005fhostname2"></a>Function: <em>int</em> <strong>gnutls_x509_crt_check_hostname2</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const char * <var>hostname</var>, unsigned int <var>flags</var>)</em></dt>
25568 <dd><p><var>cert</var>: should contain an gnutls_x509_crt_t structure
25569 </p>
25570 <p><var>hostname</var>: A null terminated string that contains a DNS name
25571 </p>
25572 <p><var>flags</var>: gnutls_certificate_verify_flags
25573 </p>
25574 <p>This function will check if the given certificate&rsquo;s subject matches
25575 the given hostname.  This is a basic implementation of the matching
25576 described in RFC6125, and takes into account wildcards,
25577 and the DNSName/IPAddress subject alternative name PKIX extension.
25578 </p>
25579 <p>IPv4 addresses are accepted by this function in the dotted-decimal
25580 format (e.g, ddd.ddd.ddd.ddd), and IPv6 addresses in the hexadecimal
25581 x:x:x:x:x:x:x:x format. For them the IPAddress subject alternative
25582 name extension is consulted, as well as the DNSNames in case of a non-match.
25583 The latter fallback exists due to misconfiguration of many servers
25584 which place an IPAddress inside the DNSName extension.
25585 </p>
25586 <p>The comparison of dns names may have false-negatives as it is done byte
25587 by byte in non-ascii names.
25588 </p>
25589 <p>When the flag <code>GNUTLS_VERIFY_DO_NOT_ALLOW_WILDCARDS</code>  is specified no
25590 wildcards are considered. Otherwise they are only considered if the
25591 domain name consists of three components or more, and the wildcard
25592 starts at the leftmost position.
25593 </p>
25594 <p><strong>Returns:</strong> non-zero for a successful match, and zero on failure.
25595 </p></dd></dl>
25596
25597 <a name="gnutls_005fx509_005fcrt_005fcheck_005fissuer-1"></a>
25598 <h4 class="subheading">gnutls_x509_crt_check_issuer</h4>
25599 <a name="gnutls_005fx509_005fcrt_005fcheck_005fissuer"></a><dl>
25600 <dt><a name="index-gnutls_005fx509_005fcrt_005fcheck_005fissuer"></a>Function: <em>int</em> <strong>gnutls_x509_crt_check_issuer</strong> <em>(gnutls_x509_crt_t <var>cert</var>, gnutls_x509_crt_t <var>issuer</var>)</em></dt>
25601 <dd><p><var>cert</var>: is the certificate to be checked
25602 </p>
25603 <p><var>issuer</var>: is the certificate of a possible issuer
25604 </p>
25605 <p>This function will check if the given certificate was issued by the
25606 given issuer. It checks the DN fields and the authority
25607 key identifier and subject key identifier fields match.
25608 </p>
25609 <p>If the same certificate is provided at the  <code>cert</code> and  <code>issuer</code> fields,
25610 it will check whether the certificate is self-signed.
25611 </p>
25612 <p><strong>Returns:</strong> It will return true (1) if the given certificate is issued
25613 by the given issuer, and false (0) if not.
25614 </p></dd></dl>
25615
25616 <a name="gnutls_005fx509_005fcrt_005fcheck_005frevocation-1"></a>
25617 <h4 class="subheading">gnutls_x509_crt_check_revocation</h4>
25618 <a name="gnutls_005fx509_005fcrt_005fcheck_005frevocation"></a><dl>
25619 <dt><a name="index-gnutls_005fx509_005fcrt_005fcheck_005frevocation"></a>Function: <em>int</em> <strong>gnutls_x509_crt_check_revocation</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const gnutls_x509_crl_t * <var>crl_list</var>, int <var>crl_list_length</var>)</em></dt>
25620 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
25621 </p>
25622 <p><var>crl_list</var>: should contain a list of gnutls_x509_crl_t structures
25623 </p>
25624 <p><var>crl_list_length</var>: the length of the crl_list
25625 </p>
25626 <p>This function will return check if the given certificate is
25627 revoked.  It is assumed that the CRLs have been verified before.
25628 </p>
25629 <p><strong>Returns:</strong> 0 if the certificate is NOT revoked, and 1 if it is.  A
25630 negative error code is returned on error.
25631 </p></dd></dl>
25632
25633 <a name="gnutls_005fx509_005fcrt_005fcpy_005fcrl_005fdist_005fpoints-1"></a>
25634 <h4 class="subheading">gnutls_x509_crt_cpy_crl_dist_points</h4>
25635 <a name="gnutls_005fx509_005fcrt_005fcpy_005fcrl_005fdist_005fpoints"></a><dl>
25636 <dt><a name="index-gnutls_005fx509_005fcrt_005fcpy_005fcrl_005fdist_005fpoints"></a>Function: <em>int</em> <strong>gnutls_x509_crt_cpy_crl_dist_points</strong> <em>(gnutls_x509_crt_t <var>dst</var>, gnutls_x509_crt_t <var>src</var>)</em></dt>
25637 <dd><p><var>dst</var>: a certificate of type <code>gnutls_x509_crt_t</code>
25638 </p>
25639 <p><var>src</var>: the certificate where the dist points will be copied from
25640 </p>
25641 <p>This function will copy the CRL distribution points certificate
25642 extension, from the source to the destination certificate.
25643 This may be useful to copy from a CA certificate to issued ones.
25644 </p>
25645 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25646 negative error value.
25647 </p></dd></dl>
25648
25649 <a name="gnutls_005fx509_005fcrt_005fdeinit-1"></a>
25650 <h4 class="subheading">gnutls_x509_crt_deinit</h4>
25651 <a name="gnutls_005fx509_005fcrt_005fdeinit"></a><dl>
25652 <dt><a name="index-gnutls_005fx509_005fcrt_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_crt_deinit</strong> <em>(gnutls_x509_crt_t <var>cert</var>)</em></dt>
25653 <dd><p><var>cert</var>: The structure to be deinitialized
25654 </p>
25655 <p>This function will deinitialize a certificate structure.
25656 </p></dd></dl>
25657
25658 <a name="gnutls_005fx509_005fcrt_005fexport-1"></a>
25659 <h4 class="subheading">gnutls_x509_crt_export</h4>
25660 <a name="gnutls_005fx509_005fcrt_005fexport"></a><dl>
25661 <dt><a name="index-gnutls_005fx509_005fcrt_005fexport"></a>Function: <em>int</em> <strong>gnutls_x509_crt_export</strong> <em>(gnutls_x509_crt_t <var>cert</var>, gnutls_x509_crt_fmt_t <var>format</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
25662 <dd><p><var>cert</var>: Holds the certificate
25663 </p>
25664 <p><var>format</var>: the format of output params. One of PEM or DER.
25665 </p>
25666 <p><var>output_data</var>: will contain a certificate PEM or DER encoded
25667 </p>
25668 <p><var>output_data_size</var>: holds the size of output_data (and will be
25669 replaced by the actual size of parameters)
25670 </p>
25671 <p>This function will export the certificate to DER or PEM format.
25672 </p>
25673 <p>If the buffer provided is not long enough to hold the output, then
25674 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
25675 be returned.
25676 </p>
25677 <p>If the structure is PEM encoded, it will have a header
25678 of &quot;BEGIN CERTIFICATE&quot;.
25679 </p>
25680 <p><strong>Returns:</strong> In case of failure a negative error code will be
25681 returned, and 0 on success.
25682 </p></dd></dl>
25683
25684 <a name="gnutls_005fx509_005fcrt_005fexport2-1"></a>
25685 <h4 class="subheading">gnutls_x509_crt_export2</h4>
25686 <a name="gnutls_005fx509_005fcrt_005fexport2"></a><dl>
25687 <dt><a name="index-gnutls_005fx509_005fcrt_005fexport2"></a>Function: <em>int</em> <strong>gnutls_x509_crt_export2</strong> <em>(gnutls_x509_crt_t <var>cert</var>, gnutls_x509_crt_fmt_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
25688 <dd><p><var>cert</var>: Holds the certificate
25689 </p>
25690 <p><var>format</var>: the format of output params. One of PEM or DER.
25691 </p>
25692 <p><var>out</var>: will contain a certificate PEM or DER encoded
25693 </p>
25694 <p>This function will export the certificate to DER or PEM format.
25695 The output buffer is allocated using <code>gnutls_malloc()</code> .
25696 </p>
25697 <p>If the structure is PEM encoded, it will have a header
25698 of &quot;BEGIN CERTIFICATE&quot;.
25699 </p>
25700 <p><strong>Returns:</strong> In case of failure a negative error code will be
25701 returned, and 0 on success.
25702 </p>
25703 <p><strong>Since:</strong> 3.1.3
25704 </p></dd></dl>
25705
25706 <a name="gnutls_005fx509_005fcrt_005fget_005factivation_005ftime-1"></a>
25707 <h4 class="subheading">gnutls_x509_crt_get_activation_time</h4>
25708 <a name="gnutls_005fx509_005fcrt_005fget_005factivation_005ftime"></a><dl>
25709 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005factivation_005ftime"></a>Function: <em>time_t</em> <strong>gnutls_x509_crt_get_activation_time</strong> <em>(gnutls_x509_crt_t <var>cert</var>)</em></dt>
25710 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
25711 </p>
25712 <p>This function will return the time this Certificate was or will be
25713 activated.
25714 </p>
25715 <p><strong>Returns:</strong> activation time, or (time_t)-1 on error.
25716 </p></dd></dl>
25717
25718 <a name="gnutls_005fx509_005fcrt_005fget_005fauthority_005finfo_005faccess-1"></a>
25719 <h4 class="subheading">gnutls_x509_crt_get_authority_info_access</h4>
25720 <a name="gnutls_005fx509_005fcrt_005fget_005fauthority_005finfo_005faccess"></a><dl>
25721 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fauthority_005finfo_005faccess"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_authority_info_access</strong> <em>(gnutls_x509_crt_t <var>crt</var>, unsigned int <var>seq</var>, int <var>what</var>, gnutls_datum_t * <var>data</var>, unsigned int * <var>critical</var>)</em></dt>
25722 <dd><p><var>crt</var>: Holds the certificate
25723 </p>
25724 <p><var>seq</var>: specifies the sequence number of the access descriptor (0 for the first one, 1 for the second etc.)
25725 </p>
25726 <p><var>what</var>: what data to get, a <code>gnutls_info_access_what_t</code>  type.
25727 </p>
25728 <p><var>data</var>: output data to be freed with <code>gnutls_free()</code> .
25729 </p>
25730 <p><var>critical</var>: pointer to output integer that is set to non-zero if the extension is marked as critical (may be <code>NULL</code> )
25731 </p>
25732 <p>Note that a simpler API to access the authority info data is provided
25733 by <code>gnutls_x509_aia_get()</code>  and <code>gnutls_x509_ext_import_aia()</code> .
25734 </p>
25735 <p>This function extracts the Authority Information Access (AIA)
25736 extension, see RFC 5280 section 4.2.2.1 for more information.  The
25737 AIA extension holds a sequence of AccessDescription (AD) data.
25738 </p>
25739 <p>The  <code>seq</code> input parameter is used to indicate which member of the
25740 sequence the caller is interested in.  The first member is 0, the
25741 second member 1 and so on.  When the  <code>seq</code> value is out of bounds,
25742 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is returned.
25743 </p>
25744 <p>The type of data returned in  <code>data</code> is specified via  <code>what</code> which
25745 should be <code>gnutls_info_access_what_t</code>  values.
25746 </p>
25747 <p>If  <code>what</code> is <code>GNUTLS_IA_ACCESSMETHOD_OID</code>  then  <code>data</code> will hold the
25748 accessMethod OID (e.g., &quot;1.3.6.1.5.5.7.48.1&quot;).
25749 </p>
25750 <p>If  <code>what</code> is <code>GNUTLS_IA_ACCESSLOCATION_GENERALNAME_TYPE</code> ,  <code>data</code> will
25751 hold the accessLocation GeneralName type (e.g.,
25752 &quot;uniformResourceIdentifier&quot;).
25753 </p>
25754 <p>If  <code>what</code> is <code>GNUTLS_IA_URI</code> ,  <code>data</code> will hold the accessLocation URI
25755 data.  Requesting this  <code>what</code> value leads to an error if the
25756 accessLocation is not of the &quot;uniformResourceIdentifier&quot; type.
25757 </p>
25758 <p>If  <code>what</code> is <code>GNUTLS_IA_OCSP_URI</code> ,  <code>data</code> will hold the OCSP URI.
25759 Requesting this  <code>what</code> value leads to an error if the accessMethod
25760 is not 1.3.6.1.5.5.7.48.1 aka OSCP, or if accessLocation is not of
25761 the &quot;uniformResourceIdentifier&quot; type. In that case <code>GNUTLS_E_UNKNOWN_ALGORITHM</code>
25762 will be returned, and  <code>seq</code> should be increased and this function
25763 called again.
25764 </p>
25765 <p>If  <code>what</code> is <code>GNUTLS_IA_CAISSUERS_URI</code> ,  <code>data</code> will hold the caIssuers
25766 URI.  Requesting this  <code>what</code> value leads to an error if the
25767 accessMethod is not 1.3.6.1.5.5.7.48.2 aka caIssuers, or if
25768 accessLocation is not of the &quot;uniformResourceIdentifier&quot; type.
25769 In that case handle as in <code>GNUTLS_IA_OCSP_URI</code> .
25770 </p>
25771 <p>More  <code>what</code> values may be allocated in the future as needed.
25772 </p>
25773 <p>If  <code>data</code> is NULL, the function does the same without storing the
25774 output data, that is, it will set  <code>critical</code> and do error checking
25775 as usual.
25776 </p>
25777 <p>The value of the critical flag is returned in * <code>critical</code> .  Supply a
25778 NULL  <code>critical</code> if you want the function to make sure the extension
25779 is non-critical, as required by RFC 5280.
25780 </p>
25781 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, <code>GNUTLS_E_INVALID_REQUEST</code>  on
25782 invalid  <code>crt</code> , <code>GNUTLS_E_CONSTRAINT_ERROR</code>  if the extension is
25783 incorrectly marked as critical (use a non-NULL  <code>critical</code> to
25784 override), <code>GNUTLS_E_UNKNOWN_ALGORITHM</code>  if the requested OID does
25785 not match (e.g., when using <code>GNUTLS_IA_OCSP_URI</code> ), otherwise a
25786 negative error code.
25787 </p>
25788 <p><strong>Since:</strong> 3.0
25789 </p></dd></dl>
25790
25791 <a name="gnutls_005fx509_005fcrt_005fget_005fauthority_005fkey_005fgn_005fserial-1"></a>
25792 <h4 class="subheading">gnutls_x509_crt_get_authority_key_gn_serial</h4>
25793 <a name="gnutls_005fx509_005fcrt_005fget_005fauthority_005fkey_005fgn_005fserial"></a><dl>
25794 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fauthority_005fkey_005fgn_005fserial"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_authority_key_gn_serial</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned int <var>seq</var>, void * <var>alt</var>, size_t * <var>alt_size</var>, unsigned int * <var>alt_type</var>, void * <var>serial</var>, size_t * <var>serial_size</var>, unsigned int * <var>critical</var>)</em></dt>
25795 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
25796 </p>
25797 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
25798 </p>
25799 <p><var>alt</var>: is the place where the alternative name will be copied to
25800 </p>
25801 <p><var>alt_size</var>: holds the size of alt.
25802 </p>
25803 <p><var>alt_type</var>: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
25804 </p>
25805 <p><var>serial</var>: buffer to store the serial number (may be null)
25806 </p>
25807 <p><var>serial_size</var>: Holds the size of the serial field (may be null)
25808 </p>
25809 <p><var>critical</var>: will be non-zero if the extension is marked as critical (may be null)
25810 </p>
25811 <p>This function will return the X.509 authority key
25812 identifier when stored as a general name (authorityCertIssuer)
25813 and serial number.
25814 </p>
25815 <p>Because more than one general names might be stored
25816  <code>seq</code> can be used as a counter to request them all until
25817 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is returned.
25818 </p>
25819 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
25820 if the extension is not present, otherwise a negative error value.
25821 </p>
25822 <p><strong>Since:</strong> 3.0
25823 </p></dd></dl>
25824
25825 <a name="gnutls_005fx509_005fcrt_005fget_005fauthority_005fkey_005fid-1"></a>
25826 <h4 class="subheading">gnutls_x509_crt_get_authority_key_id</h4>
25827 <a name="gnutls_005fx509_005fcrt_005fget_005fauthority_005fkey_005fid"></a><dl>
25828 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fauthority_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_authority_key_id</strong> <em>(gnutls_x509_crt_t <var>cert</var>, void * <var>id</var>, size_t * <var>id_size</var>, unsigned int * <var>critical</var>)</em></dt>
25829 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
25830 </p>
25831 <p><var>id</var>: The place where the identifier will be copied
25832 </p>
25833 <p><var>id_size</var>: Holds the size of the id field.
25834 </p>
25835 <p><var>critical</var>: will be non-zero if the extension is marked as critical (may be null)
25836 </p>
25837 <p>This function will return the X.509v3 certificate authority&rsquo;s key
25838 identifier.  This is obtained by the X.509 Authority Key
25839 identifier extension field (2.5.29.35). Note that this function
25840 only returns the keyIdentifier field of the extension and
25841 <code>GNUTLS_E_X509_UNSUPPORTED_EXTENSION</code> , if the extension contains
25842 the name and serial number of the certificate. In that case
25843 <code>gnutls_x509_crt_get_authority_key_gn_serial()</code>  may be used.
25844 </p>
25845 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
25846 if the extension is not present, otherwise a negative error value.
25847 </p></dd></dl>
25848
25849 <a name="gnutls_005fx509_005fcrt_005fget_005fbasic_005fconstraints-1"></a>
25850 <h4 class="subheading">gnutls_x509_crt_get_basic_constraints</h4>
25851 <a name="gnutls_005fx509_005fcrt_005fget_005fbasic_005fconstraints"></a><dl>
25852 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fbasic_005fconstraints"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_basic_constraints</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned int * <var>critical</var>, unsigned int * <var>ca</var>, int * <var>pathlen</var>)</em></dt>
25853 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
25854 </p>
25855 <p><var>critical</var>: will be non-zero if the extension is marked as critical
25856 </p>
25857 <p><var>ca</var>: pointer to output integer indicating CA status, may be NULL,
25858 value is 1 if the certificate CA flag is set, 0 otherwise.
25859 </p>
25860 <p><var>pathlen</var>: pointer to output integer indicating path length (may be
25861 NULL), non-negative error codes indicate a present pathLenConstraint
25862 field and the actual value, -1 indicate that the field is absent.
25863 </p>
25864 <p>This function will read the certificate&rsquo;s basic constraints, and
25865 return the certificates CA status.  It reads the basicConstraints
25866 X.509 extension (2.5.29.19).
25867 </p>
25868 <p><strong>Returns:</strong> If the certificate is a CA a positive value will be
25869 returned, or (0) if the certificate does not have CA flag set.  A
25870 negative error code may be returned in case of errors.  If the
25871 certificate does not contain the basicConstraints extension
25872 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
25873 </p></dd></dl>
25874
25875 <a name="gnutls_005fx509_005fcrt_005fget_005fca_005fstatus-1"></a>
25876 <h4 class="subheading">gnutls_x509_crt_get_ca_status</h4>
25877 <a name="gnutls_005fx509_005fcrt_005fget_005fca_005fstatus"></a><dl>
25878 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fca_005fstatus"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_ca_status</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned int * <var>critical</var>)</em></dt>
25879 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
25880 </p>
25881 <p><var>critical</var>: will be non-zero if the extension is marked as critical
25882 </p>
25883 <p>This function will return certificates CA status, by reading the
25884 basicConstraints X.509 extension (2.5.29.19). If the certificate is
25885 a CA a positive value will be returned, or (0) if the certificate
25886 does not have CA flag set.
25887 </p>
25888 <p>Use <code>gnutls_x509_crt_get_basic_constraints()</code>  if you want to read the
25889 pathLenConstraint field too.
25890 </p>
25891 <p><strong>Returns:</strong> If the certificate is a CA a positive value will be
25892 returned, or (0) if the certificate does not have CA flag set.  A
25893 negative error code may be returned in case of errors.  If the
25894 certificate does not contain the basicConstraints extension
25895 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
25896 </p></dd></dl>
25897
25898 <a name="gnutls_005fx509_005fcrt_005fget_005fcrl_005fdist_005fpoints-1"></a>
25899 <h4 class="subheading">gnutls_x509_crt_get_crl_dist_points</h4>
25900 <a name="gnutls_005fx509_005fcrt_005fget_005fcrl_005fdist_005fpoints"></a><dl>
25901 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fcrl_005fdist_005fpoints"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_crl_dist_points</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned int <var>seq</var>, void * <var>san</var>, size_t * <var>san_size</var>, unsigned int * <var>reason_flags</var>, unsigned int * <var>critical</var>)</em></dt>
25902 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
25903 </p>
25904 <p><var>seq</var>: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.)
25905 </p>
25906 <p><var>san</var>: is the place where the distribution point will be copied to
25907 </p>
25908 <p><var>san_size</var>: holds the size of ret.
25909 </p>
25910 <p><var>reason_flags</var>: Revocation reasons. An ORed sequence of flags from <code>gnutls_x509_crl_reason_flags_t</code> .
25911 </p>
25912 <p><var>critical</var>: will be non-zero if the extension is marked as critical (may be null)
25913 </p>
25914 <p>This function retrieves the CRL distribution points (2.5.29.31),
25915 contained in the given certificate in the X509v3 Certificate
25916 Extensions.
25917 </p>
25918 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  and updates  <code>ret_size</code> if
25919  <code>ret_size</code> is not enough to hold the distribution point, or the
25920 type of the distribution point if everything was ok. The type is
25921 one of the enumerated <code>gnutls_x509_subject_alt_name_t</code> .  If the
25922 certificate does not have an Alternative name with the specified
25923 sequence number then <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is
25924 returned.
25925 </p></dd></dl>
25926
25927 <a name="gnutls_005fx509_005fcrt_005fget_005fdn-1"></a>
25928 <h4 class="subheading">gnutls_x509_crt_get_dn</h4>
25929 <a name="gnutls_005fx509_005fcrt_005fget_005fdn"></a><dl>
25930 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fdn"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_dn</strong> <em>(gnutls_x509_crt_t <var>cert</var>, char * <var>buf</var>, size_t * <var>buf_size</var>)</em></dt>
25931 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
25932 </p>
25933 <p><var>buf</var>: a pointer to a structure to hold the name (may be null)
25934 </p>
25935 <p><var>buf_size</var>: initially holds the size of  <code>buf</code>
25936 </p>
25937 <p>This function will copy the name of the Certificate in the provided
25938 buffer. The name will be in the form &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as
25939 described in RFC4514. The output string will be ASCII or UTF-8
25940 encoded, depending on the certificate data.
25941 </p>
25942 <p>If  <code>buf</code> is null then only the size will be filled.
25943 </p>
25944 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is not
25945 long enough, and in that case the  <code>buf_size</code> will be updated
25946 with the required size.  On success 0 is returned.
25947 </p></dd></dl>
25948
25949 <a name="gnutls_005fx509_005fcrt_005fget_005fdn2-1"></a>
25950 <h4 class="subheading">gnutls_x509_crt_get_dn2</h4>
25951 <a name="gnutls_005fx509_005fcrt_005fget_005fdn2"></a><dl>
25952 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fdn2-1"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_dn2</strong> <em>(gnutls_x509_crt_t <var>cert</var>, gnutls_datum_t * <var>dn</var>)</em></dt>
25953 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
25954 </p>
25955 <p><var>dn</var>: a pointer to a structure to hold the name
25956 </p>
25957 <p>This function will allocate buffer and copy the name of the Certificate.
25958 The name will be in the form &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as
25959 described in RFC4514. The output string will be ASCII or UTF-8
25960 encoded, depending on the certificate data.
25961 </p>
25962 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
25963 negative error value. and a negative error code on error.
25964 </p>
25965 <p><strong>Since:</strong> 3.1.10
25966 </p></dd></dl>
25967
25968 <a name="gnutls_005fx509_005fcrt_005fget_005fdn_005fby_005foid-1"></a>
25969 <h4 class="subheading">gnutls_x509_crt_get_dn_by_oid</h4>
25970 <a name="gnutls_005fx509_005fcrt_005fget_005fdn_005fby_005foid"></a><dl>
25971 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fdn_005fby_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_dn_by_oid</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const char * <var>oid</var>, int <var>indx</var>, unsigned int <var>raw_flag</var>, void * <var>buf</var>, size_t * <var>buf_size</var>)</em></dt>
25972 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
25973 </p>
25974 <p><var>oid</var>: holds an Object Identified in null terminated string
25975 </p>
25976 <p><var>indx</var>: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
25977 </p>
25978 <p><var>raw_flag</var>: If non-zero returns the raw DER data of the DN part.
25979 </p>
25980 <p><var>buf</var>: a pointer where the DN part will be copied (may be null).
25981 </p>
25982 <p><var>buf_size</var>: initially holds the size of  <code>buf</code>
25983 </p>
25984 <p>This function will extract the part of the name of the Certificate
25985 subject specified by the given OID. The output, if the raw flag is
25986 not used, will be encoded as described in RFC4514. Thus a string
25987 that is ASCII or UTF-8 encoded, depending on the certificate data.
25988 </p>
25989 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
25990 If raw flag is (0), this function will only return known OIDs as
25991 text. Other OIDs will be DER encoded, as described in RFC4514 &ndash;
25992 in hex format with a &rsquo;#&rsquo; prefix.  You can check about known OIDs
25993 using <code>gnutls_x509_dn_oid_known()</code> .
25994 </p>
25995 <p>If  <code>buf</code> is null then only the size will be filled. If the  <code>raw_flag</code> is not specified the output is always null terminated, although the
25996  <code>buf_size</code> will not include the null character.
25997 </p>
25998 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is not
25999 long enough, and in that case the  <code>buf_size</code> will be updated with
26000 the required size. <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  if there
26001 are no data in the current index. On success 0 is returned.
26002 </p></dd></dl>
26003
26004 <a name="gnutls_005fx509_005fcrt_005fget_005fdn_005foid-1"></a>
26005 <h4 class="subheading">gnutls_x509_crt_get_dn_oid</h4>
26006 <a name="gnutls_005fx509_005fcrt_005fget_005fdn_005foid"></a><dl>
26007 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fdn_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_dn_oid</strong> <em>(gnutls_x509_crt_t <var>cert</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>oid_size</var>)</em></dt>
26008 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26009 </p>
26010 <p><var>indx</var>: This specifies which OID to return. Use (0) to get the first one.
26011 </p>
26012 <p><var>oid</var>: a pointer to a buffer to hold the OID (may be null)
26013 </p>
26014 <p><var>oid_size</var>: initially holds the size of  <code>oid</code>
26015 </p>
26016 <p>This function will extract the OIDs of the name of the Certificate
26017 subject specified by the given index.
26018 </p>
26019 <p>If  <code>oid</code> is null then only the size will be filled. The  <code>oid</code> returned will be null terminated, although  <code>oid_size</code> will not
26020 account for the trailing null.
26021 </p>
26022 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is not
26023 long enough, and in that case the  <code>buf_size</code> will be updated with
26024 the required size. <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  if there
26025 are no data in the current index. On success 0 is returned.
26026 </p></dd></dl>
26027
26028 <a name="gnutls_005fx509_005fcrt_005fget_005fexpiration_005ftime-1"></a>
26029 <h4 class="subheading">gnutls_x509_crt_get_expiration_time</h4>
26030 <a name="gnutls_005fx509_005fcrt_005fget_005fexpiration_005ftime"></a><dl>
26031 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fexpiration_005ftime"></a>Function: <em>time_t</em> <strong>gnutls_x509_crt_get_expiration_time</strong> <em>(gnutls_x509_crt_t <var>cert</var>)</em></dt>
26032 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26033 </p>
26034 <p>This function will return the time this Certificate was or will be
26035 expired.
26036 </p>
26037 <p>The no well defined expiration time can be checked against with the
26038 <code>GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION</code>  macro.
26039 </p>
26040 <p><strong>Returns:</strong> expiration time, or (time_t)-1 on error.
26041 </p></dd></dl>
26042
26043 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005fby_005foid-1"></a>
26044 <h4 class="subheading">gnutls_x509_crt_get_extension_by_oid</h4>
26045 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005fby_005foid"></a><dl>
26046 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fextension_005fby_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_extension_by_oid</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const char * <var>oid</var>, int <var>indx</var>, void * <var>buf</var>, size_t * <var>buf_size</var>, unsigned int * <var>critical</var>)</em></dt>
26047 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26048 </p>
26049 <p><var>oid</var>: holds an Object Identified in null terminated string
26050 </p>
26051 <p><var>indx</var>: In case multiple same OIDs exist in the extensions, this specifies which to send. Use (0) to get the first one.
26052 </p>
26053 <p><var>buf</var>: a pointer to a structure to hold the name (may be null)
26054 </p>
26055 <p><var>buf_size</var>: initially holds the size of  <code>buf</code>
26056 </p>
26057 <p><var>critical</var>: will be non-zero if the extension is marked as critical
26058 </p>
26059 <p>This function will return the extension specified by the OID in the
26060 certificate.  The extensions will be returned as binary data DER
26061 encoded, in the provided buffer.
26062 </p>
26063 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
26064 otherwise a negative error code is returned. If the certificate does not
26065 contain the specified extension
26066 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
26067 </p></dd></dl>
26068
26069 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005fby_005foid2-1"></a>
26070 <h4 class="subheading">gnutls_x509_crt_get_extension_by_oid2</h4>
26071 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005fby_005foid2"></a><dl>
26072 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fextension_005fby_005foid2"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_extension_by_oid2</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const char * <var>oid</var>, int <var>indx</var>, gnutls_datum_t * <var>output</var>, unsigned int * <var>critical</var>)</em></dt>
26073 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26074 </p>
26075 <p><var>oid</var>: holds an Object Identified in null terminated string
26076 </p>
26077 <p><var>indx</var>: In case multiple same OIDs exist in the extensions, this specifies which to send. Use (0) to get the first one.
26078 </p>
26079 <p><var>output</var>: will hold the allocated extension data
26080 </p>
26081 <p><var>critical</var>: will be non-zero if the extension is marked as critical
26082 </p>
26083 <p>This function will return the extension specified by the OID in the
26084 certificate.  The extensions will be returned as binary data DER
26085 encoded, in the provided buffer.
26086 </p>
26087 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
26088 otherwise a negative error code is returned. If the certificate does not
26089 contain the specified extension
26090 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
26091 </p>
26092 <p><strong>Since:</strong> 3.3.8
26093 </p></dd></dl>
26094
26095 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005fdata-1"></a>
26096 <h4 class="subheading">gnutls_x509_crt_get_extension_data</h4>
26097 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005fdata"></a><dl>
26098 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fextension_005fdata"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_extension_data</strong> <em>(gnutls_x509_crt_t <var>cert</var>, int <var>indx</var>, void * <var>data</var>, size_t * <var>sizeof_data</var>)</em></dt>
26099 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26100 </p>
26101 <p><var>indx</var>: Specifies which extension OID to send. Use (0) to get the first one.
26102 </p>
26103 <p><var>data</var>: a pointer to a structure to hold the data (may be null)
26104 </p>
26105 <p><var>sizeof_data</var>: initially holds the size of  <code>data</code>
26106 </p>
26107 <p>This function will return the requested extension data in the
26108 certificate.  The extension data will be stored in the
26109 provided buffer.
26110 </p>
26111 <p>Use <code>gnutls_x509_crt_get_extension_info()</code>  to extract the OID and
26112 critical flag.  Use <code>gnutls_x509_crt_get_extension_by_oid()</code>  instead,
26113 if you want to get data indexed by the extension OID rather than
26114 sequence.
26115 </p>
26116 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
26117 otherwise a negative error code is returned.  If you have reached the
26118 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
26119 will be returned.
26120 </p></dd></dl>
26121
26122 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005fdata2-1"></a>
26123 <h4 class="subheading">gnutls_x509_crt_get_extension_data2</h4>
26124 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005fdata2"></a><dl>
26125 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fextension_005fdata2"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_extension_data2</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned <var>indx</var>, gnutls_datum_t * <var>data</var>)</em></dt>
26126 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26127 </p>
26128 <p><var>indx</var>: Specifies which extension OID to read. Use (0) to get the first one.
26129 </p>
26130 <p><var>data</var>: will contain the extension DER-encoded data
26131 </p>
26132 <p>This function will return the requested by the index extension data in the
26133 certificate.  The extension data will be allocated using
26134 <code>gnutls_malloc()</code> .
26135 </p>
26136 <p>Use <code>gnutls_x509_crt_get_extension_info()</code>  to extract the OID.
26137 </p>
26138 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
26139 otherwise a negative error code is returned.  If you have reached the
26140 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
26141 will be returned.
26142 </p></dd></dl>
26143
26144 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005finfo-1"></a>
26145 <h4 class="subheading">gnutls_x509_crt_get_extension_info</h4>
26146 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005finfo"></a><dl>
26147 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fextension_005finfo"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_extension_info</strong> <em>(gnutls_x509_crt_t <var>cert</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>oid_size</var>, unsigned int * <var>critical</var>)</em></dt>
26148 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26149 </p>
26150 <p><var>indx</var>: Specifies which extension OID to send. Use (0) to get the first one.
26151 </p>
26152 <p><var>oid</var>: a pointer to a structure to hold the OID
26153 </p>
26154 <p><var>oid_size</var>: initially holds the maximum size of  <code>oid</code> , on return
26155 holds actual size of  <code>oid</code> .
26156 </p>
26157 <p><var>critical</var>: output variable with critical flag, may be NULL.
26158 </p>
26159 <p>This function will return the requested extension OID in the
26160 certificate, and the critical flag for it.  The extension OID will
26161 be stored as a string in the provided buffer.  Use
26162 <code>gnutls_x509_crt_get_extension()</code>  to extract the data.
26163 </p>
26164 <p>If the buffer provided is not long enough to hold the output, then
26165  <code>oid_size</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  will be
26166 returned. The  <code>oid</code> returned will be null terminated, although
26167  <code>oid_size</code> will not account for the trailing null.
26168 </p>
26169 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
26170 otherwise a negative error code is returned.  If you have reached the
26171 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
26172 will be returned.
26173 </p></dd></dl>
26174
26175 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005foid-1"></a>
26176 <h4 class="subheading">gnutls_x509_crt_get_extension_oid</h4>
26177 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005foid"></a><dl>
26178 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fextension_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_extension_oid</strong> <em>(gnutls_x509_crt_t <var>cert</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>oid_size</var>)</em></dt>
26179 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26180 </p>
26181 <p><var>indx</var>: Specifies which extension OID to send. Use (0) to get the first one.
26182 </p>
26183 <p><var>oid</var>: a pointer to a structure to hold the OID (may be null)
26184 </p>
26185 <p><var>oid_size</var>: initially holds the size of  <code>oid</code>
26186 </p>
26187 <p>This function will return the requested extension OID in the certificate.
26188 The extension OID will be stored as a string in the provided buffer.
26189 </p>
26190 <p>The  <code>oid</code> returned will be null terminated, although  <code>oid_size</code> will not
26191 account for the trailing null.
26192 </p>
26193 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
26194 otherwise a negative error code is returned.  If you have reached the
26195 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
26196 will be returned.
26197 </p></dd></dl>
26198
26199 <a name="gnutls_005fx509_005fcrt_005fget_005ffingerprint-1"></a>
26200 <h4 class="subheading">gnutls_x509_crt_get_fingerprint</h4>
26201 <a name="gnutls_005fx509_005fcrt_005fget_005ffingerprint"></a><dl>
26202 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005ffingerprint"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_fingerprint</strong> <em>(gnutls_x509_crt_t <var>cert</var>, gnutls_digest_algorithm_t <var>algo</var>, void * <var>buf</var>, size_t * <var>buf_size</var>)</em></dt>
26203 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26204 </p>
26205 <p><var>algo</var>: is a digest algorithm
26206 </p>
26207 <p><var>buf</var>: a pointer to a structure to hold the fingerprint (may be null)
26208 </p>
26209 <p><var>buf_size</var>: initially holds the size of  <code>buf</code>
26210 </p>
26211 <p>This function will calculate and copy the certificate&rsquo;s fingerprint
26212 in the provided buffer. The fingerprint is a hash of the DER-encoded
26213 data of the certificate.
26214 </p>
26215 <p>If the buffer is null then only the size will be filled.
26216 </p>
26217 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is
26218 not long enough, and in that case the *buf_size will be updated
26219 with the required size.  On success 0 is returned.
26220 </p></dd></dl>
26221
26222 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer-1"></a>
26223 <h4 class="subheading">gnutls_x509_crt_get_issuer</h4>
26224 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer"></a><dl>
26225 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fissuer"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_issuer</strong> <em>(gnutls_x509_crt_t <var>cert</var>, gnutls_x509_dn_t * <var>dn</var>)</em></dt>
26226 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26227 </p>
26228 <p><var>dn</var>: output variable with pointer to uint8_t DN
26229 </p>
26230 <p>Return the Certificate&rsquo;s Issuer DN as a <code>gnutls_x509_dn_t</code>  data type,
26231 that can be decoded using <code>gnutls_x509_dn_get_rdn_ava()</code> .
26232 </p>
26233 <p>Note that  <code>dn</code> should be treated as constant. Because it points
26234 into the  <code>cert</code> object, you should not use  <code>dn</code> after  <code>cert</code> is
26235 deallocated.
26236 </p>
26237 <p><strong>Returns:</strong> Returns 0 on success, or an error code.
26238 </p></dd></dl>
26239
26240 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fname-1"></a>
26241 <h4 class="subheading">gnutls_x509_crt_get_issuer_alt_name</h4>
26242 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fname"></a><dl>
26243 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fname"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_issuer_alt_name</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned int <var>seq</var>, void * <var>ian</var>, size_t * <var>ian_size</var>, unsigned int * <var>critical</var>)</em></dt>
26244 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26245 </p>
26246 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
26247 </p>
26248 <p><var>ian</var>: is the place where the alternative name will be copied to
26249 </p>
26250 <p><var>ian_size</var>: holds the size of ian.
26251 </p>
26252 <p><var>critical</var>: will be non-zero if the extension is marked as critical (may be null)
26253 </p>
26254 <p>This function retrieves the Issuer Alternative Name (2.5.29.18),
26255 contained in the given certificate in the X509v3 Certificate
26256 Extensions.
26257 </p>
26258 <p>When the SAN type is otherName, it will extract the data in the
26259 otherName&rsquo;s value field, and <code>GNUTLS_SAN_OTHERNAME</code>  is returned.
26260 You may use <code>gnutls_x509_crt_get_subject_alt_othername_oid()</code>  to get
26261 the corresponding OID and the &quot;virtual&quot; SAN types (e.g.,
26262 <code>GNUTLS_SAN_OTHERNAME_XMPP</code> ).
26263 </p>
26264 <p>If an otherName OID is known, the data will be decoded.  Otherwise
26265 the returned data will be DER encoded, and you will have to decode
26266 it yourself.  Currently, only the RFC 3920 id-on-xmppAddr Issuer
26267 AltName is recognized.
26268 </p>
26269 <p><strong>Returns:</strong> the alternative issuer name type on success, one of the
26270 enumerated <code>gnutls_x509_subject_alt_name_t</code> .  It will return
26271 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if  <code>ian_size</code> is not large enough
26272 to hold the value.  In that case  <code>ian_size</code> will be updated with
26273 the required size.  If the certificate does not have an
26274 Alternative name with the specified sequence number then
26275 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is returned.
26276 </p>
26277 <p><strong>Since:</strong> 2.10.0
26278 </p></dd></dl>
26279
26280 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fname2-1"></a>
26281 <h4 class="subheading">gnutls_x509_crt_get_issuer_alt_name2</h4>
26282 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fname2"></a><dl>
26283 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fname2"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_issuer_alt_name2</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned int <var>seq</var>, void * <var>ian</var>, size_t * <var>ian_size</var>, unsigned int * <var>ian_type</var>, unsigned int * <var>critical</var>)</em></dt>
26284 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26285 </p>
26286 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
26287 </p>
26288 <p><var>ian</var>: is the place where the alternative name will be copied to
26289 </p>
26290 <p><var>ian_size</var>: holds the size of ret.
26291 </p>
26292 <p><var>ian_type</var>: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
26293 </p>
26294 <p><var>critical</var>: will be non-zero if the extension is marked as critical (may be null)
26295 </p>
26296 <p>This function will return the alternative names, contained in the
26297 given certificate. It is the same as
26298 <code>gnutls_x509_crt_get_issuer_alt_name()</code>  except for the fact that it
26299 will return the type of the alternative name in  <code>ian_type</code> even if
26300 the function fails for some reason (i.e.  the buffer provided is
26301 not enough).
26302 </p>
26303 <p><strong>Returns:</strong> the alternative issuer name type on success, one of the
26304 enumerated <code>gnutls_x509_subject_alt_name_t</code> .  It will return
26305 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if  <code>ian_size</code> is not large enough
26306 to hold the value.  In that case  <code>ian_size</code> will be updated with
26307 the required size.  If the certificate does not have an
26308 Alternative name with the specified sequence number then
26309 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is returned.
26310 </p>
26311 <p><strong>Since:</strong> 2.10.0
26312 </p></dd></dl>
26313
26314 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fothername_005foid-1"></a>
26315 <h4 class="subheading">gnutls_x509_crt_get_issuer_alt_othername_oid</h4>
26316 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fothername_005foid"></a><dl>
26317 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fothername_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_issuer_alt_othername_oid</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned int <var>seq</var>, void * <var>ret</var>, size_t * <var>ret_size</var>)</em></dt>
26318 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26319 </p>
26320 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
26321 </p>
26322 <p><var>ret</var>: is the place where the otherName OID will be copied to
26323 </p>
26324 <p><var>ret_size</var>: holds the size of ret.
26325 </p>
26326 <p>This function will extract the type OID of an otherName Subject
26327 Alternative Name, contained in the given certificate, and return
26328 the type as an enumerated element.
26329 </p>
26330 <p>If  <code>oid</code> is null then only the size will be filled. The  <code>oid</code> returned will be null terminated, although  <code>oid_size</code> will not
26331 account for the trailing null.
26332 </p>
26333 <p>This function is only useful if
26334 <code>gnutls_x509_crt_get_issuer_alt_name()</code>  returned
26335 <code>GNUTLS_SAN_OTHERNAME</code> .
26336 </p>
26337 <p><strong>Returns:</strong> the alternative issuer name type on success, one of the
26338 enumerated gnutls_x509_subject_alt_name_t.  For supported OIDs, it
26339 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
26340 e.g. <code>GNUTLS_SAN_OTHERNAME_XMPP</code> , and <code>GNUTLS_SAN_OTHERNAME</code>  for
26341 unknown OIDs.  It will return <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if
26342  <code>ret_size</code> is not large enough to hold the value.  In that case
26343  <code>ret_size</code> will be updated with the required size.  If the
26344 certificate does not have an Alternative name with the specified
26345 sequence number and with the otherName type then
26346 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is returned.
26347 </p>
26348 <p><strong>Since:</strong> 2.10.0
26349 </p></dd></dl>
26350
26351 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn-1"></a>
26352 <h4 class="subheading">gnutls_x509_crt_get_issuer_dn</h4>
26353 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn"></a><dl>
26354 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_issuer_dn</strong> <em>(gnutls_x509_crt_t <var>cert</var>, char * <var>buf</var>, size_t * <var>buf_size</var>)</em></dt>
26355 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26356 </p>
26357 <p><var>buf</var>: a pointer to a structure to hold the name (may be null)
26358 </p>
26359 <p><var>buf_size</var>: initially holds the size of  <code>buf</code>
26360 </p>
26361 <p>This function will copy the name of the Certificate issuer in the
26362 provided buffer. The name will be in the form
26363 &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as described in RFC4514. The output string
26364 will be ASCII or UTF-8 encoded, depending on the certificate data.
26365 </p>
26366 <p>If  <code>buf</code> is null then only the size will be filled.
26367 </p>
26368 <p><strong>Returns:</strong> GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
26369 long enough, and in that case the  <code>buf_size</code> will be updated with
26370 the required size.  On success 0 is returned.
26371 </p></dd></dl>
26372
26373 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn2-1"></a>
26374 <h4 class="subheading">gnutls_x509_crt_get_issuer_dn2</h4>
26375 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn2"></a><dl>
26376 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn2"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_issuer_dn2</strong> <em>(gnutls_x509_crt_t <var>cert</var>, gnutls_datum_t * <var>dn</var>)</em></dt>
26377 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26378 </p>
26379 <p><var>dn</var>: a pointer to a structure to hold the name
26380 </p>
26381 <p>This function will allocate buffer and copy the name of issuer of the Certificate.
26382 The name will be in the form &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as
26383 described in RFC4514. The output string will be ASCII or UTF-8
26384 encoded, depending on the certificate data.
26385 </p>
26386 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
26387 negative error value. and a negative error code on error.
26388 </p>
26389 <p><strong>Since:</strong> 3.1.10
26390 </p></dd></dl>
26391
26392 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005fby_005foid-1"></a>
26393 <h4 class="subheading">gnutls_x509_crt_get_issuer_dn_by_oid</h4>
26394 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005fby_005foid"></a><dl>
26395 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005fby_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_issuer_dn_by_oid</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const char * <var>oid</var>, int <var>indx</var>, unsigned int <var>raw_flag</var>, void * <var>buf</var>, size_t * <var>buf_size</var>)</em></dt>
26396 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26397 </p>
26398 <p><var>oid</var>: holds an Object Identified in null terminated string
26399 </p>
26400 <p><var>indx</var>: In case multiple same OIDs exist in the RDN, this specifies which to send. Use (0) to get the first one.
26401 </p>
26402 <p><var>raw_flag</var>: If non-zero returns the raw DER data of the DN part.
26403 </p>
26404 <p><var>buf</var>: a pointer to a structure to hold the name (may be null)
26405 </p>
26406 <p><var>buf_size</var>: initially holds the size of  <code>buf</code>
26407 </p>
26408 <p>This function will extract the part of the name of the Certificate
26409 issuer specified by the given OID. The output, if the raw flag is not
26410 used, will be encoded as described in RFC4514. Thus a string that is
26411 ASCII or UTF-8 encoded, depending on the certificate data.
26412 </p>
26413 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
26414 If raw flag is (0), this function will only return known OIDs as
26415 text. Other OIDs will be DER encoded, as described in RFC4514 &ndash;
26416 in hex format with a &rsquo;#&rsquo; prefix.  You can check about known OIDs
26417 using <code>gnutls_x509_dn_oid_known()</code> .
26418 </p>
26419 <p>If  <code>buf</code> is null then only the size will be filled. If the  <code>raw_flag</code> is not specified the output is always null terminated, although the
26420  <code>buf_size</code> will not include the null character.
26421 </p>
26422 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is not
26423 long enough, and in that case the  <code>buf_size</code> will be updated with
26424 the required size. <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  if there
26425 are no data in the current index. On success 0 is returned.
26426 </p></dd></dl>
26427
26428 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005foid-1"></a>
26429 <h4 class="subheading">gnutls_x509_crt_get_issuer_dn_oid</h4>
26430 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005foid"></a><dl>
26431 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_issuer_dn_oid</strong> <em>(gnutls_x509_crt_t <var>cert</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>oid_size</var>)</em></dt>
26432 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26433 </p>
26434 <p><var>indx</var>: This specifies which OID to return. Use (0) to get the first one.
26435 </p>
26436 <p><var>oid</var>: a pointer to a buffer to hold the OID (may be null)
26437 </p>
26438 <p><var>oid_size</var>: initially holds the size of  <code>oid</code>
26439 </p>
26440 <p>This function will extract the OIDs of the name of the Certificate
26441 issuer specified by the given index.
26442 </p>
26443 <p>If  <code>oid</code> is null then only the size will be filled. The  <code>oid</code> returned will be null terminated, although  <code>oid_size</code> will not
26444 account for the trailing null.
26445 </p>
26446 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is not
26447 long enough, and in that case the  <code>buf_size</code> will be updated with
26448 the required size. <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  if there
26449 are no data in the current index. On success 0 is returned.
26450 </p></dd></dl>
26451
26452 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005funique_005fid-1"></a>
26453 <h4 class="subheading">gnutls_x509_crt_get_issuer_unique_id</h4>
26454 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005funique_005fid"></a><dl>
26455 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fissuer_005funique_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_issuer_unique_id</strong> <em>(gnutls_x509_crt_t <var>crt</var>, char * <var>buf</var>, size_t * <var>buf_size</var>)</em></dt>
26456 <dd><p><var>crt</var>: Holds the certificate
26457 </p>
26458 <p><var>buf</var>: user allocated memory buffer, will hold the unique id
26459 </p>
26460 <p><var>buf_size</var>: size of user allocated memory buffer (on input), will hold
26461 actual size of the unique ID on return.
26462 </p>
26463 <p>This function will extract the issuerUniqueID value (if present) for
26464 the given certificate.
26465 </p>
26466 <p>If the user allocated memory buffer is not large enough to hold the
26467 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
26468 returned, and buf_size will be set to the actual length.
26469 </p>
26470 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
26471 </p>
26472 <p><strong>Since:</strong> 2.12.0
26473 </p></dd></dl>
26474
26475 <a name="gnutls_005fx509_005fcrt_005fget_005fkey_005fid-1"></a>
26476 <h4 class="subheading">gnutls_x509_crt_get_key_id</h4>
26477 <a name="gnutls_005fx509_005fcrt_005fget_005fkey_005fid"></a><dl>
26478 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fkey_005fid-1"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_key_id</strong> <em>(gnutls_x509_crt_t <var>crt</var>, unsigned int <var>flags</var>, unsigned char * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
26479 <dd><p><var>crt</var>: Holds the certificate
26480 </p>
26481 <p><var>flags</var>: should be 0 for now
26482 </p>
26483 <p><var>output_data</var>: will contain the key ID
26484 </p>
26485 <p><var>output_data_size</var>: holds the size of output_data (and will be
26486 replaced by the actual size of parameters)
26487 </p>
26488 <p>This function will return a unique ID that depends on the public
26489 key parameters. This ID can be used in checking whether a
26490 certificate corresponds to the given private key.
26491 </p>
26492 <p>If the buffer provided is not long enough to hold the output, then
26493 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
26494 be returned.  The output will normally be a SHA-1 hash output,
26495 which is 20 bytes.
26496 </p>
26497 <p><strong>Returns:</strong> In case of failure a negative error code will be
26498 returned, and 0 on success.
26499 </p></dd></dl>
26500
26501 <a name="gnutls_005fx509_005fcrt_005fget_005fkey_005fpurpose_005foid-1"></a>
26502 <h4 class="subheading">gnutls_x509_crt_get_key_purpose_oid</h4>
26503 <a name="gnutls_005fx509_005fcrt_005fget_005fkey_005fpurpose_005foid"></a><dl>
26504 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fkey_005fpurpose_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_key_purpose_oid</strong> <em>(gnutls_x509_crt_t <var>cert</var>, int <var>indx</var>, void * <var>oid</var>, size_t * <var>oid_size</var>, unsigned int * <var>critical</var>)</em></dt>
26505 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26506 </p>
26507 <p><var>indx</var>: This specifies which OID to return. Use (0) to get the first one.
26508 </p>
26509 <p><var>oid</var>: a pointer to a buffer to hold the OID (may be null)
26510 </p>
26511 <p><var>oid_size</var>: initially holds the size of  <code>oid</code>
26512 </p>
26513 <p><var>critical</var>: output flag to indicate criticality of extension
26514 </p>
26515 <p>This function will extract the key purpose OIDs of the Certificate
26516 specified by the given index.  These are stored in the Extended Key
26517 Usage extension (2.5.29.37) See the GNUTLS_KP_* definitions for
26518 human readable names.
26519 </p>
26520 <p>If  <code>oid</code> is null then only the size will be filled. The  <code>oid</code> returned will be null terminated, although  <code>oid_size</code> will not
26521 account for the trailing null.
26522 </p>
26523 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if the provided buffer is
26524 not long enough, and in that case the *oid_size will be updated
26525 with the required size.  On success 0 is returned.
26526 </p></dd></dl>
26527
26528 <a name="gnutls_005fx509_005fcrt_005fget_005fkey_005fusage-1"></a>
26529 <h4 class="subheading">gnutls_x509_crt_get_key_usage</h4>
26530 <a name="gnutls_005fx509_005fcrt_005fget_005fkey_005fusage"></a><dl>
26531 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fkey_005fusage"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_key_usage</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned int * <var>key_usage</var>, unsigned int * <var>critical</var>)</em></dt>
26532 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26533 </p>
26534 <p><var>key_usage</var>: where the key usage bits will be stored
26535 </p>
26536 <p><var>critical</var>: will be non-zero if the extension is marked as critical
26537 </p>
26538 <p>This function will return certificate&rsquo;s key usage, by reading the
26539 keyUsage X.509 extension (2.5.29.15). The key usage value will ORed
26540 values of the: <code>GNUTLS_KEY_DIGITAL_SIGNATURE</code> ,
26541 <code>GNUTLS_KEY_NON_REPUDIATION</code> , <code>GNUTLS_KEY_KEY_ENCIPHERMENT</code> ,
26542 <code>GNUTLS_KEY_DATA_ENCIPHERMENT</code> , <code>GNUTLS_KEY_KEY_AGREEMENT</code> ,
26543 <code>GNUTLS_KEY_KEY_CERT_SIGN</code> , <code>GNUTLS_KEY_CRL_SIGN</code> ,
26544 <code>GNUTLS_KEY_ENCIPHER_ONLY</code> , <code>GNUTLS_KEY_DECIPHER_ONLY</code> .
26545 </p>
26546 <p><strong>Returns:</strong> the certificate key usage, or a negative error code in case of
26547 parsing error.  If the certificate does not contain the keyUsage
26548 extension <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be
26549 returned.
26550 </p></dd></dl>
26551
26552 <a name="gnutls_005fx509_005fcrt_005fget_005fname_005fconstraints-1"></a>
26553 <h4 class="subheading">gnutls_x509_crt_get_name_constraints</h4>
26554 <a name="gnutls_005fx509_005fcrt_005fget_005fname_005fconstraints"></a><dl>
26555 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fname_005fconstraints"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_name_constraints</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_name_constraints_t <var>nc</var>, unsigned int <var>flags</var>, unsigned int * <var>critical</var>)</em></dt>
26556 <dd><p><var>crt</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26557 </p>
26558 <p><var>nc</var>: The nameconstraints intermediate structure
26559 </p>
26560 <p><var>flags</var>: zero or <code>GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND</code>
26561 </p>
26562 <p><var>critical</var>: the extension status
26563 </p>
26564 <p>This function will return an intermediate structure containing
26565 the name constraints of the provided CA certificate. That
26566 structure can be used in combination with <code>gnutls_x509_name_constraints_check()</code>
26567 to verify whether a server&rsquo;s name is in accordance with the constraints.
26568 </p>
26569 <p>When the  <code>flags</code> is set to <code>GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND</code> , then if
26570 the  <code>nc</code> structure is empty
26571 this function will behave identically as if the flag was not set.
26572 Otherwise if there are elements in the  <code>nc</code> structure then only the
26573 excluded constraints will be appended to the constraints.
26574 </p>
26575 <p>Note that  <code>nc</code> must be initialized prior to calling this function.
26576 </p>
26577 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
26578 if the extension is not present, otherwise a negative error value.
26579 </p>
26580 <p><strong>Since:</strong> 3.3.0
26581 </p></dd></dl>
26582
26583 <a name="gnutls_005fx509_005fcrt_005fget_005fpk_005falgorithm-1"></a>
26584 <h4 class="subheading">gnutls_x509_crt_get_pk_algorithm</h4>
26585 <a name="gnutls_005fx509_005fcrt_005fget_005fpk_005falgorithm"></a><dl>
26586 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fpk_005falgorithm"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_pk_algorithm</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned int * <var>bits</var>)</em></dt>
26587 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26588 </p>
26589 <p><var>bits</var>: if bits is non null it will hold the size of the parameters&rsquo; in bits
26590 </p>
26591 <p>This function will return the public key algorithm of an X.509
26592 certificate.
26593 </p>
26594 <p>If bits is non null, it should have enough size to hold the parameters
26595 size in bits. For RSA the bits returned is the modulus.
26596 For DSA the bits returned are of the public
26597 exponent.
26598 </p>
26599 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code>  enumeration on
26600 success, or a negative error code on error.
26601 </p></dd></dl>
26602
26603 <a name="gnutls_005fx509_005fcrt_005fget_005fpk_005fdsa_005fraw-1"></a>
26604 <h4 class="subheading">gnutls_x509_crt_get_pk_dsa_raw</h4>
26605 <a name="gnutls_005fx509_005fcrt_005fget_005fpk_005fdsa_005fraw"></a><dl>
26606 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fpk_005fdsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_pk_dsa_raw</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>g</var>, gnutls_datum_t * <var>y</var>)</em></dt>
26607 <dd><p><var>crt</var>: Holds the certificate
26608 </p>
26609 <p><var>p</var>: will hold the p
26610 </p>
26611 <p><var>q</var>: will hold the q
26612 </p>
26613 <p><var>g</var>: will hold the g
26614 </p>
26615 <p><var>y</var>: will hold the y
26616 </p>
26617 <p>This function will export the DSA public key&rsquo;s parameters found in
26618 the given certificate.  The new parameters will be allocated using
26619 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
26620 </p>
26621 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
26622 </p></dd></dl>
26623
26624 <a name="gnutls_005fx509_005fcrt_005fget_005fpk_005frsa_005fraw-1"></a>
26625 <h4 class="subheading">gnutls_x509_crt_get_pk_rsa_raw</h4>
26626 <a name="gnutls_005fx509_005fcrt_005fget_005fpk_005frsa_005fraw"></a><dl>
26627 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fpk_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_pk_rsa_raw</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>)</em></dt>
26628 <dd><p><var>crt</var>: Holds the certificate
26629 </p>
26630 <p><var>m</var>: will hold the modulus
26631 </p>
26632 <p><var>e</var>: will hold the public exponent
26633 </p>
26634 <p>This function will export the RSA public key&rsquo;s parameters found in
26635 the given structure.  The new parameters will be allocated using
26636 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
26637 </p>
26638 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
26639 </p></dd></dl>
26640
26641 <a name="gnutls_005fx509_005fcrt_005fget_005fpolicy-1"></a>
26642 <h4 class="subheading">gnutls_x509_crt_get_policy</h4>
26643 <a name="gnutls_005fx509_005fcrt_005fget_005fpolicy"></a><dl>
26644 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fpolicy"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_policy</strong> <em>(gnutls_x509_crt_t <var>crt</var>, int <var>indx</var>, struct gnutls_x509_policy_st * <var>policy</var>, unsigned int * <var>critical</var>)</em></dt>
26645 <dd><p><var>crt</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26646 </p>
26647 <p><var>indx</var>: This specifies which policy to return. Use (0) to get the first one.
26648 </p>
26649 <p><var>policy</var>: A pointer to a policy structure.
26650 </p>
26651 <p><var>critical</var>: will be non-zero if the extension is marked as critical
26652 </p>
26653 <p>This function will extract the certificate policy (extension 2.5.29.32)
26654 specified by the given index.
26655 </p>
26656 <p>The policy returned by this function must be deinitialized by using
26657 <code>gnutls_x509_policy_release()</code> .
26658 </p>
26659 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
26660 if the extension is not present, otherwise a negative error value.
26661 </p>
26662 <p><strong>Since:</strong> 3.1.5
26663 </p></dd></dl>
26664
26665 <a name="gnutls_005fx509_005fcrt_005fget_005fprivate_005fkey_005fusage_005fperiod-1"></a>
26666 <h4 class="subheading">gnutls_x509_crt_get_private_key_usage_period</h4>
26667 <a name="gnutls_005fx509_005fcrt_005fget_005fprivate_005fkey_005fusage_005fperiod"></a><dl>
26668 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fprivate_005fkey_005fusage_005fperiod"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_private_key_usage_period</strong> <em>(gnutls_x509_crt_t <var>cert</var>, time_t * <var>activation</var>, time_t * <var>expiration</var>, unsigned int * <var>critical</var>)</em></dt>
26669 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26670 </p>
26671 <p><var>activation</var>: The activation time
26672 </p>
26673 <p><var>expiration</var>: The expiration time
26674 </p>
26675 <p><var>critical</var>: the extension status
26676 </p>
26677 <p>This function will return the expiration and activation
26678 times of the private key of the certificate. It relies on
26679 the PKIX extension 2.5.29.16 being present.
26680 </p>
26681 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
26682 if the extension is not present, otherwise a negative error value.
26683 </p></dd></dl>
26684
26685 <a name="gnutls_005fx509_005fcrt_005fget_005fproxy-1"></a>
26686 <h4 class="subheading">gnutls_x509_crt_get_proxy</h4>
26687 <a name="gnutls_005fx509_005fcrt_005fget_005fproxy"></a><dl>
26688 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fproxy"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_proxy</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned int * <var>critical</var>, int * <var>pathlen</var>, char ** <var>policyLanguage</var>, char ** <var>policy</var>, size_t * <var>sizeof_policy</var>)</em></dt>
26689 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26690 </p>
26691 <p><var>critical</var>: will be non-zero if the extension is marked as critical
26692 </p>
26693 <p><var>pathlen</var>: pointer to output integer indicating path length (may be
26694 NULL), non-negative error codes indicate a present pCPathLenConstraint
26695 field and the actual value, -1 indicate that the field is absent.
26696 </p>
26697 <p><var>policyLanguage</var>: output variable with OID of policy language
26698 </p>
26699 <p><var>policy</var>: output variable with policy data
26700 </p>
26701 <p><var>sizeof_policy</var>: output variable size of policy data
26702 </p>
26703 <p>This function will get information from a proxy certificate.  It
26704 reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14).
26705 </p>
26706 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
26707 otherwise a negative error code is returned.
26708 </p></dd></dl>
26709
26710 <a name="gnutls_005fx509_005fcrt_005fget_005fraw_005fdn-1"></a>
26711 <h4 class="subheading">gnutls_x509_crt_get_raw_dn</h4>
26712 <a name="gnutls_005fx509_005fcrt_005fget_005fraw_005fdn"></a><dl>
26713 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fraw_005fdn"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_raw_dn</strong> <em>(gnutls_x509_crt_t <var>cert</var>, gnutls_datum_t * <var>dn</var>)</em></dt>
26714 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26715 </p>
26716 <p><var>dn</var>: will hold the starting point of the DN
26717 </p>
26718 <p>This function will return a pointer to the DER encoded DN structure and
26719 the length. This points to allocated data that must be free&rsquo;d using <code>gnutls_free()</code> .
26720 </p>
26721 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
26722 negative error value. or a negative error code on error.
26723 </p></dd></dl>
26724
26725 <a name="gnutls_005fx509_005fcrt_005fget_005fraw_005fissuer_005fdn-1"></a>
26726 <h4 class="subheading">gnutls_x509_crt_get_raw_issuer_dn</h4>
26727 <a name="gnutls_005fx509_005fcrt_005fget_005fraw_005fissuer_005fdn"></a><dl>
26728 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fraw_005fissuer_005fdn"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_raw_issuer_dn</strong> <em>(gnutls_x509_crt_t <var>cert</var>, gnutls_datum_t * <var>dn</var>)</em></dt>
26729 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26730 </p>
26731 <p><var>dn</var>: will hold the starting point of the DN
26732 </p>
26733 <p>This function will return a pointer to the DER encoded DN structure
26734 and the length. This points to allocated data that must be free&rsquo;d using <code>gnutls_free()</code> .
26735 </p>
26736 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
26737 negative error value.or a negative error code on error.
26738 </p></dd></dl>
26739
26740 <a name="gnutls_005fx509_005fcrt_005fget_005fserial-1"></a>
26741 <h4 class="subheading">gnutls_x509_crt_get_serial</h4>
26742 <a name="gnutls_005fx509_005fcrt_005fget_005fserial"></a><dl>
26743 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fserial"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_serial</strong> <em>(gnutls_x509_crt_t <var>cert</var>, void * <var>result</var>, size_t * <var>result_size</var>)</em></dt>
26744 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26745 </p>
26746 <p><var>result</var>: The place where the serial number will be copied
26747 </p>
26748 <p><var>result_size</var>: Holds the size of the result field.
26749 </p>
26750 <p>This function will return the X.509 certificate&rsquo;s serial number.
26751 This is obtained by the X509 Certificate serialNumber field. Serial
26752 is not always a 32 or 64bit number. Some CAs use large serial
26753 numbers, thus it may be wise to handle it as something uint8_t.
26754 </p>
26755 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
26756 negative error value.
26757 </p></dd></dl>
26758
26759 <a name="gnutls_005fx509_005fcrt_005fget_005fsignature-1"></a>
26760 <h4 class="subheading">gnutls_x509_crt_get_signature</h4>
26761 <a name="gnutls_005fx509_005fcrt_005fget_005fsignature"></a><dl>
26762 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fsignature"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_signature</strong> <em>(gnutls_x509_crt_t <var>cert</var>, char * <var>sig</var>, size_t * <var>sig_size</var>)</em></dt>
26763 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26764 </p>
26765 <p><var>sig</var>: a pointer where the signature part will be copied (may be null).
26766 </p>
26767 <p><var>sig_size</var>: initially holds the size of  <code>sig</code>
26768 </p>
26769 <p>This function will extract the signature field of a certificate.
26770 </p>
26771 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
26772 negative error value. and a negative error code on error.
26773 </p></dd></dl>
26774
26775 <a name="gnutls_005fx509_005fcrt_005fget_005fsignature_005falgorithm-1"></a>
26776 <h4 class="subheading">gnutls_x509_crt_get_signature_algorithm</h4>
26777 <a name="gnutls_005fx509_005fcrt_005fget_005fsignature_005falgorithm"></a><dl>
26778 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fsignature_005falgorithm"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_signature_algorithm</strong> <em>(gnutls_x509_crt_t <var>cert</var>)</em></dt>
26779 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26780 </p>
26781 <p>This function will return a value of the <code>gnutls_sign_algorithm_t</code>
26782 enumeration that is the signature algorithm that has been used to
26783 sign this certificate.
26784 </p>
26785 <p><strong>Returns:</strong> a <code>gnutls_sign_algorithm_t</code>  value, or a negative error code on
26786 error.
26787 </p></dd></dl>
26788
26789 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject-1"></a>
26790 <h4 class="subheading">gnutls_x509_crt_get_subject</h4>
26791 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject"></a><dl>
26792 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fsubject"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_subject</strong> <em>(gnutls_x509_crt_t <var>cert</var>, gnutls_x509_dn_t * <var>dn</var>)</em></dt>
26793 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26794 </p>
26795 <p><var>dn</var>: output variable with pointer to uint8_t DN.
26796 </p>
26797 <p>Return the Certificate&rsquo;s Subject DN as a <code>gnutls_x509_dn_t</code>  data type,
26798 that can be decoded using <code>gnutls_x509_dn_get_rdn_ava()</code> .
26799 </p>
26800 <p>Note that  <code>dn</code> should be treated as constant. Because it points
26801 into the  <code>cert</code> object, you should not use  <code>dn</code> after  <code>cert</code> is
26802 deallocated.
26803 </p>
26804 <p><strong>Returns:</strong> Returns 0 on success, or an error code.
26805 </p></dd></dl>
26806
26807 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fname-1"></a>
26808 <h4 class="subheading">gnutls_x509_crt_get_subject_alt_name</h4>
26809 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fname"></a><dl>
26810 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fname"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_subject_alt_name</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned int <var>seq</var>, void * <var>san</var>, size_t * <var>san_size</var>, unsigned int * <var>critical</var>)</em></dt>
26811 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26812 </p>
26813 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
26814 </p>
26815 <p><var>san</var>: is the place where the alternative name will be copied to
26816 </p>
26817 <p><var>san_size</var>: holds the size of san.
26818 </p>
26819 <p><var>critical</var>: will be non-zero if the extension is marked as critical (may be null)
26820 </p>
26821 <p>This function retrieves the Alternative Name (2.5.29.17), contained
26822 in the given certificate in the X509v3 Certificate Extensions.
26823 </p>
26824 <p>When the SAN type is otherName, it will extract the data in the
26825 otherName&rsquo;s value field, and <code>GNUTLS_SAN_OTHERNAME</code>  is returned.
26826 You may use <code>gnutls_x509_crt_get_subject_alt_othername_oid()</code>  to get
26827 the corresponding OID and the &quot;virtual&quot; SAN types (e.g.,
26828 <code>GNUTLS_SAN_OTHERNAME_XMPP</code> ).
26829 </p>
26830 <p>If an otherName OID is known, the data will be decoded.  Otherwise
26831 the returned data will be DER encoded, and you will have to decode
26832 it yourself.  Currently, only the RFC 3920 id-on-xmppAddr SAN is
26833 recognized.
26834 </p>
26835 <p><strong>Returns:</strong> the alternative subject name type on success, one of the
26836 enumerated <code>gnutls_x509_subject_alt_name_t</code> .  It will return
26837 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if  <code>san_size</code> is not large enough to
26838 hold the value.  In that case  <code>san_size</code> will be updated with the
26839 required size.  If the certificate does not have an Alternative
26840 name with the specified sequence number then
26841 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is returned.
26842 </p></dd></dl>
26843
26844 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fname2-1"></a>
26845 <h4 class="subheading">gnutls_x509_crt_get_subject_alt_name2</h4>
26846 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fname2"></a><dl>
26847 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fname2"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_subject_alt_name2</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned int <var>seq</var>, void * <var>san</var>, size_t * <var>san_size</var>, unsigned int * <var>san_type</var>, unsigned int * <var>critical</var>)</em></dt>
26848 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26849 </p>
26850 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
26851 </p>
26852 <p><var>san</var>: is the place where the alternative name will be copied to
26853 </p>
26854 <p><var>san_size</var>: holds the size of ret.
26855 </p>
26856 <p><var>san_type</var>: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
26857 </p>
26858 <p><var>critical</var>: will be non-zero if the extension is marked as critical (may be null)
26859 </p>
26860 <p>This function will return the alternative names, contained in the
26861 given certificate. It is the same as
26862 <code>gnutls_x509_crt_get_subject_alt_name()</code>  except for the fact that it
26863 will return the type of the alternative name in  <code>san_type</code> even if
26864 the function fails for some reason (i.e.  the buffer provided is
26865 not enough).
26866 </p>
26867 <p><strong>Returns:</strong> the alternative subject name type on success, one of the
26868 enumerated <code>gnutls_x509_subject_alt_name_t</code> .  It will return
26869 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if  <code>san_size</code> is not large enough
26870 to hold the value.  In that case  <code>san_size</code> will be updated with
26871 the required size.  If the certificate does not have an
26872 Alternative name with the specified sequence number then
26873 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is returned.
26874 </p></dd></dl>
26875
26876 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fothername_005foid-1"></a>
26877 <h4 class="subheading">gnutls_x509_crt_get_subject_alt_othername_oid</h4>
26878 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fothername_005foid"></a><dl>
26879 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fothername_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_subject_alt_othername_oid</strong> <em>(gnutls_x509_crt_t <var>cert</var>, unsigned int <var>seq</var>, void * <var>oid</var>, size_t * <var>oid_size</var>)</em></dt>
26880 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26881 </p>
26882 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
26883 </p>
26884 <p><var>oid</var>: is the place where the otherName OID will be copied to
26885 </p>
26886 <p><var>oid_size</var>: holds the size of ret.
26887 </p>
26888 <p>This function will extract the type OID of an otherName Subject
26889 Alternative Name, contained in the given certificate, and return
26890 the type as an enumerated element.
26891 </p>
26892 <p>This function is only useful if
26893 <code>gnutls_x509_crt_get_subject_alt_name()</code>  returned
26894 <code>GNUTLS_SAN_OTHERNAME</code> .
26895 </p>
26896 <p>If  <code>oid</code> is null then only the size will be filled. The  <code>oid</code> returned will be null terminated, although  <code>oid_size</code> will not
26897 account for the trailing null.
26898 </p>
26899 <p><strong>Returns:</strong> the alternative subject name type on success, one of the
26900 enumerated gnutls_x509_subject_alt_name_t.  For supported OIDs, it
26901 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
26902 e.g. <code>GNUTLS_SAN_OTHERNAME_XMPP</code> , and <code>GNUTLS_SAN_OTHERNAME</code>  for
26903 unknown OIDs.  It will return <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  if
26904  <code>ian_size</code> is not large enough to hold the value.  In that case
26905  <code>ian_size</code> will be updated with the required size.  If the
26906 certificate does not have an Alternative name with the specified
26907 sequence number and with the otherName type then
26908 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  is returned.
26909 </p></dd></dl>
26910
26911 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005fkey_005fid-1"></a>
26912 <h4 class="subheading">gnutls_x509_crt_get_subject_key_id</h4>
26913 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005fkey_005fid"></a><dl>
26914 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fsubject_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_subject_key_id</strong> <em>(gnutls_x509_crt_t <var>cert</var>, void * <var>ret</var>, size_t * <var>ret_size</var>, unsigned int * <var>critical</var>)</em></dt>
26915 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26916 </p>
26917 <p><var>ret</var>: The place where the identifier will be copied
26918 </p>
26919 <p><var>ret_size</var>: Holds the size of the result field.
26920 </p>
26921 <p><var>critical</var>: will be non-zero if the extension is marked as critical (may be null)
26922 </p>
26923 <p>This function will return the X.509v3 certificate&rsquo;s subject key
26924 identifier.  This is obtained by the X.509 Subject Key identifier
26925 extension field (2.5.29.14).
26926 </p>
26927 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
26928 if the extension is not present, otherwise a negative error value.
26929 </p></dd></dl>
26930
26931 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005funique_005fid-1"></a>
26932 <h4 class="subheading">gnutls_x509_crt_get_subject_unique_id</h4>
26933 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005funique_005fid"></a><dl>
26934 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fsubject_005funique_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_subject_unique_id</strong> <em>(gnutls_x509_crt_t <var>crt</var>, char * <var>buf</var>, size_t * <var>buf_size</var>)</em></dt>
26935 <dd><p><var>crt</var>: Holds the certificate
26936 </p>
26937 <p><var>buf</var>: user allocated memory buffer, will hold the unique id
26938 </p>
26939 <p><var>buf_size</var>: size of user allocated memory buffer (on input), will hold
26940 actual size of the unique ID on return.
26941 </p>
26942 <p>This function will extract the subjectUniqueID value (if present) for
26943 the given certificate.
26944 </p>
26945 <p>If the user allocated memory buffer is not large enough to hold the
26946 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
26947 returned, and buf_size will be set to the actual length.
26948 </p>
26949 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
26950 </p></dd></dl>
26951
26952 <a name="gnutls_005fx509_005fcrt_005fget_005fversion-1"></a>
26953 <h4 class="subheading">gnutls_x509_crt_get_version</h4>
26954 <a name="gnutls_005fx509_005fcrt_005fget_005fversion"></a><dl>
26955 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fversion"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_version</strong> <em>(gnutls_x509_crt_t <var>cert</var>)</em></dt>
26956 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
26957 </p>
26958 <p>This function will return the version of the specified Certificate.
26959 </p>
26960 <p><strong>Returns:</strong> version of certificate, or a negative error code on error.
26961 </p></dd></dl>
26962
26963 <a name="gnutls_005fx509_005fcrt_005fimport-1"></a>
26964 <h4 class="subheading">gnutls_x509_crt_import</h4>
26965 <a name="gnutls_005fx509_005fcrt_005fimport"></a><dl>
26966 <dt><a name="index-gnutls_005fx509_005fcrt_005fimport"></a>Function: <em>int</em> <strong>gnutls_x509_crt_import</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>)</em></dt>
26967 <dd><p><var>cert</var>: The structure to store the parsed certificate.
26968 </p>
26969 <p><var>data</var>: The DER or PEM encoded certificate.
26970 </p>
26971 <p><var>format</var>: One of DER or PEM
26972 </p>
26973 <p>This function will convert the given DER or PEM encoded Certificate
26974 to the native gnutls_x509_crt_t format. The output will be stored
26975 in  <code>cert</code> .
26976 </p>
26977 <p>If the Certificate is PEM encoded it should have a header of &quot;X509
26978 CERTIFICATE&quot;, or &quot;CERTIFICATE&quot;.
26979 </p>
26980 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
26981 negative error value.
26982 </p></dd></dl>
26983
26984 <a name="gnutls_005fx509_005fcrt_005finit-1"></a>
26985 <h4 class="subheading">gnutls_x509_crt_init</h4>
26986 <a name="gnutls_005fx509_005fcrt_005finit"></a><dl>
26987 <dt><a name="index-gnutls_005fx509_005fcrt_005finit"></a>Function: <em>int</em> <strong>gnutls_x509_crt_init</strong> <em>(gnutls_x509_crt_t * <var>cert</var>)</em></dt>
26988 <dd><p><var>cert</var>: The structure to be initialized
26989 </p>
26990 <p>This function will initialize an X.509 certificate structure.
26991 </p>
26992 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
26993 negative error value.
26994 </p></dd></dl>
26995
26996 <a name="gnutls_005fx509_005fcrt_005flist_005fimport-1"></a>
26997 <h4 class="subheading">gnutls_x509_crt_list_import</h4>
26998 <a name="gnutls_005fx509_005fcrt_005flist_005fimport"></a><dl>
26999 <dt><a name="index-gnutls_005fx509_005fcrt_005flist_005fimport"></a>Function: <em>int</em> <strong>gnutls_x509_crt_list_import</strong> <em>(gnutls_x509_crt_t * <var>certs</var>, unsigned int * <var>cert_max</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned int <var>flags</var>)</em></dt>
27000 <dd><p><var>certs</var>: The structures to store the parsed certificate. Must not be initialized.
27001 </p>
27002 <p><var>cert_max</var>: Initially must hold the maximum number of certs. It will be updated with the number of certs available.
27003 </p>
27004 <p><var>data</var>: The PEM encoded certificate.
27005 </p>
27006 <p><var>format</var>: One of DER or PEM.
27007 </p>
27008 <p><var>flags</var>: must be (0) or an OR&rsquo;d sequence of gnutls_certificate_import_flags.
27009 </p>
27010 <p>This function will convert the given PEM encoded certificate list
27011 to the native gnutls_x509_crt_t format. The output will be stored
27012 in  <code>certs</code> .  They will be automatically initialized.
27013 </p>
27014 <p>The flag <code>GNUTLS_X509_CRT_LIST_IMPORT_FAIL_IF_EXCEED</code>  will cause
27015 import to fail if the certificates in the provided buffer are more
27016 than the available structures. The <code>GNUTLS_X509_CRT_LIST_FAIL_IF_UNSORTED</code>
27017 flag will cause the function to fail if the provided list is not
27018 sorted from subject to issuer.
27019 </p>
27020 <p>If the Certificate is PEM encoded it should have a header of &quot;X509
27021 CERTIFICATE&quot;, or &quot;CERTIFICATE&quot;.
27022 </p>
27023 <p><strong>Returns:</strong> the number of certificates read or a negative error value.
27024 </p></dd></dl>
27025
27026 <a name="gnutls_005fx509_005fcrt_005flist_005fimport2-1"></a>
27027 <h4 class="subheading">gnutls_x509_crt_list_import2</h4>
27028 <a name="gnutls_005fx509_005fcrt_005flist_005fimport2"></a><dl>
27029 <dt><a name="index-gnutls_005fx509_005fcrt_005flist_005fimport2"></a>Function: <em>int</em> <strong>gnutls_x509_crt_list_import2</strong> <em>(gnutls_x509_crt_t ** <var>certs</var>, unsigned int * <var>size</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned int <var>flags</var>)</em></dt>
27030 <dd><p><var>certs</var>: The structures to store the parsed certificate. Must not be initialized.
27031 </p>
27032 <p><var>size</var>: It will contain the size of the list.
27033 </p>
27034 <p><var>data</var>: The PEM encoded certificate.
27035 </p>
27036 <p><var>format</var>: One of DER or PEM.
27037 </p>
27038 <p><var>flags</var>: must be (0) or an OR&rsquo;d sequence of gnutls_certificate_import_flags.
27039 </p>
27040 <p>This function will convert the given PEM encoded certificate list
27041 to the native gnutls_x509_crt_t format. The output will be stored
27042 in  <code>certs</code> which will allocated and initialized.
27043 </p>
27044 <p>If the Certificate is PEM encoded it should have a header of &quot;X509
27045 CERTIFICATE&quot;, or &quot;CERTIFICATE&quot;.
27046 </p>
27047 <p>To deinitialize  <code>certs</code> , you need to deinitialize each crt structure
27048 independently, and use <code>gnutls_free()</code>  at
27049 </p>
27050 <p><strong>Returns:</strong> the number of certificates read or a negative error value.
27051 </p>
27052 <p><strong>Since:</strong> 3.0
27053 </p></dd></dl>
27054
27055 <a name="gnutls_005fx509_005fcrt_005flist_005fverify-1"></a>
27056 <h4 class="subheading">gnutls_x509_crt_list_verify</h4>
27057 <a name="gnutls_005fx509_005fcrt_005flist_005fverify"></a><dl>
27058 <dt><a name="index-gnutls_005fx509_005fcrt_005flist_005fverify"></a>Function: <em>int</em> <strong>gnutls_x509_crt_list_verify</strong> <em>(const gnutls_x509_crt_t * <var>cert_list</var>, int <var>cert_list_length</var>, const gnutls_x509_crt_t * <var>CA_list</var>, int <var>CA_list_length</var>, const gnutls_x509_crl_t * <var>CRL_list</var>, int <var>CRL_list_length</var>, unsigned int <var>flags</var>, unsigned int * <var>verify</var>)</em></dt>
27059 <dd><p><var>cert_list</var>: is the certificate list to be verified
27060 </p>
27061 <p><var>cert_list_length</var>: holds the number of certificate in cert_list
27062 </p>
27063 <p><var>CA_list</var>: is the CA list which will be used in verification
27064 </p>
27065 <p><var>CA_list_length</var>: holds the number of CA certificate in CA_list
27066 </p>
27067 <p><var>CRL_list</var>: holds a list of CRLs.
27068 </p>
27069 <p><var>CRL_list_length</var>: the length of CRL list.
27070 </p>
27071 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
27072 </p>
27073 <p><var>verify</var>: will hold the certificate verification output.
27074 </p>
27075 <p>This function will try to verify the given certificate list and
27076 return its status.  If no flags are specified (0), this function
27077 will use the basicConstraints (2.5.29.19) PKIX extension. This
27078 means that only a certificate authority is allowed to sign a
27079 certificate.
27080 </p>
27081 <p>You must also check the peer&rsquo;s name in order to check if the verified
27082 certificate belongs to the actual peer.
27083 </p>
27084 <p>The certificate verification output will be put in  <code>verify</code> and will
27085 be one or more of the gnutls_certificate_status_t enumerated
27086 elements bitwise or&rsquo;d.  For a more detailed verification status use
27087 <code>gnutls_x509_crt_verify()</code>  per list element.
27088 </p>
27089 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27090 negative error value.
27091 </p></dd></dl>
27092
27093 <a name="gnutls_005fx509_005fcrt_005fprint-1"></a>
27094 <h4 class="subheading">gnutls_x509_crt_print</h4>
27095 <a name="gnutls_005fx509_005fcrt_005fprint"></a><dl>
27096 <dt><a name="index-gnutls_005fx509_005fcrt_005fprint"></a>Function: <em>int</em> <strong>gnutls_x509_crt_print</strong> <em>(gnutls_x509_crt_t <var>cert</var>, gnutls_certificate_print_formats_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
27097 <dd><p><var>cert</var>: The structure to be printed
27098 </p>
27099 <p><var>format</var>: Indicate the format to use
27100 </p>
27101 <p><var>out</var>: Newly allocated datum with null terminated string.
27102 </p>
27103 <p>This function will pretty print a X.509 certificate, suitable for
27104 display to a human.
27105 </p>
27106 <p>If the format is <code>GNUTLS_CRT_PRINT_FULL</code>  then all fields of the
27107 certificate will be output, on multiple lines.  The
27108 <code>GNUTLS_CRT_PRINT_ONELINE</code>  format will generate one line with some
27109 selected fields, which is useful for logging purposes.
27110 </p>
27111 <p>The output  <code>out</code> needs to be deallocated using <code>gnutls_free()</code> .
27112 </p>
27113 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27114 negative error value.
27115 </p></dd></dl>
27116
27117 <a name="gnutls_005fx509_005fcrt_005fset_005factivation_005ftime-1"></a>
27118 <h4 class="subheading">gnutls_x509_crt_set_activation_time</h4>
27119 <a name="gnutls_005fx509_005fcrt_005fset_005factivation_005ftime"></a><dl>
27120 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005factivation_005ftime"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_activation_time</strong> <em>(gnutls_x509_crt_t <var>cert</var>, time_t <var>act_time</var>)</em></dt>
27121 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27122 </p>
27123 <p><var>act_time</var>: The actual time
27124 </p>
27125 <p>This function will set the time this Certificate was or will be
27126 activated.
27127 </p>
27128 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27129 negative error value.
27130 </p></dd></dl>
27131
27132 <a name="gnutls_005fx509_005fcrt_005fset_005fauthority_005finfo_005faccess-1"></a>
27133 <h4 class="subheading">gnutls_x509_crt_set_authority_info_access</h4>
27134 <a name="gnutls_005fx509_005fcrt_005fset_005fauthority_005finfo_005faccess"></a><dl>
27135 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fauthority_005finfo_005faccess"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_authority_info_access</strong> <em>(gnutls_x509_crt_t <var>crt</var>, int <var>what</var>, gnutls_datum_t * <var>data</var>)</em></dt>
27136 <dd><p><var>crt</var>: Holds the certificate
27137 </p>
27138 <p><var>what</var>: what data to get, a <code>gnutls_info_access_what_t</code>  type.
27139 </p>
27140 <p><var>data</var>: output data to be freed with <code>gnutls_free()</code> .
27141 </p>
27142 <p>This function sets the Authority Information Access (AIA)
27143 extension, see RFC 5280 section 4.2.2.1 for more information.
27144 </p>
27145 <p>The type of data stored in  <code>data</code> is specified via  <code>what</code> which
27146 should be <code>gnutls_info_access_what_t</code>  values.
27147 </p>
27148 <p>If  <code>what</code> is <code>GNUTLS_IA_OCSP_URI</code> ,  <code>data</code> will hold the OCSP URI.
27149 If  <code>what</code> is <code>GNUTLS_IA_CAISSUERS_URI</code> ,  <code>data</code> will hold the caIssuers
27150 URI.
27151 </p>
27152 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27153 negative error value.
27154 </p>
27155 <p><strong>Since:</strong> 3.0
27156 </p></dd></dl>
27157
27158 <a name="gnutls_005fx509_005fcrt_005fset_005fauthority_005fkey_005fid-1"></a>
27159 <h4 class="subheading">gnutls_x509_crt_set_authority_key_id</h4>
27160 <a name="gnutls_005fx509_005fcrt_005fset_005fauthority_005fkey_005fid"></a><dl>
27161 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fauthority_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_authority_key_id</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const void * <var>id</var>, size_t <var>id_size</var>)</em></dt>
27162 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27163 </p>
27164 <p><var>id</var>: The key ID
27165 </p>
27166 <p><var>id_size</var>: Holds the size of the key ID field.
27167 </p>
27168 <p>This function will set the X.509 certificate&rsquo;s authority key ID extension.
27169 Only the keyIdentifier field can be set with this function.
27170 </p>
27171 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27172 negative error value.
27173 </p></dd></dl>
27174
27175 <a name="gnutls_005fx509_005fcrt_005fset_005fbasic_005fconstraints-1"></a>
27176 <h4 class="subheading">gnutls_x509_crt_set_basic_constraints</h4>
27177 <a name="gnutls_005fx509_005fcrt_005fset_005fbasic_005fconstraints"></a><dl>
27178 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fbasic_005fconstraints"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_basic_constraints</strong> <em>(gnutls_x509_crt_t <var>crt</var>, unsigned int <var>ca</var>, int <var>pathLenConstraint</var>)</em></dt>
27179 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27180 </p>
27181 <p><var>ca</var>: true(1) or false(0). Depending on the Certificate authority status.
27182 </p>
27183 <p><var>pathLenConstraint</var>: non-negative error codes indicate maximum length of path,
27184 and negative error codes indicate that the pathLenConstraints field should
27185 not be present.
27186 </p>
27187 <p>This function will set the basicConstraints certificate extension.
27188 </p>
27189 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27190 negative error value.
27191 </p></dd></dl>
27192
27193 <a name="gnutls_005fx509_005fcrt_005fset_005fca_005fstatus-1"></a>
27194 <h4 class="subheading">gnutls_x509_crt_set_ca_status</h4>
27195 <a name="gnutls_005fx509_005fcrt_005fset_005fca_005fstatus"></a><dl>
27196 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fca_005fstatus"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_ca_status</strong> <em>(gnutls_x509_crt_t <var>crt</var>, unsigned int <var>ca</var>)</em></dt>
27197 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27198 </p>
27199 <p><var>ca</var>: true(1) or false(0). Depending on the Certificate authority status.
27200 </p>
27201 <p>This function will set the basicConstraints certificate extension.
27202 Use <code>gnutls_x509_crt_set_basic_constraints()</code>  if you want to control
27203 the pathLenConstraint field too.
27204 </p>
27205 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27206 negative error value.
27207 </p></dd></dl>
27208
27209 <a name="gnutls_005fx509_005fcrt_005fset_005fcrl_005fdist_005fpoints-1"></a>
27210 <h4 class="subheading">gnutls_x509_crt_set_crl_dist_points</h4>
27211 <a name="gnutls_005fx509_005fcrt_005fset_005fcrl_005fdist_005fpoints"></a><dl>
27212 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fcrl_005fdist_005fpoints"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_crl_dist_points</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_subject_alt_name_t <var>type</var>, const void * <var>data_string</var>, unsigned int <var>reason_flags</var>)</em></dt>
27213 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27214 </p>
27215 <p><var>type</var>: is one of the gnutls_x509_subject_alt_name_t enumerations
27216 </p>
27217 <p><var>data_string</var>: The data to be set
27218 </p>
27219 <p><var>reason_flags</var>: revocation reasons
27220 </p>
27221 <p>This function will set the CRL distribution points certificate extension.
27222 </p>
27223 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27224 negative error value.
27225 </p></dd></dl>
27226
27227 <a name="gnutls_005fx509_005fcrt_005fset_005fcrl_005fdist_005fpoints2-1"></a>
27228 <h4 class="subheading">gnutls_x509_crt_set_crl_dist_points2</h4>
27229 <a name="gnutls_005fx509_005fcrt_005fset_005fcrl_005fdist_005fpoints2"></a><dl>
27230 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fcrl_005fdist_005fpoints2"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_crl_dist_points2</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_subject_alt_name_t <var>type</var>, const void * <var>data</var>, unsigned int <var>data_size</var>, unsigned int <var>reason_flags</var>)</em></dt>
27231 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27232 </p>
27233 <p><var>type</var>: is one of the gnutls_x509_subject_alt_name_t enumerations
27234 </p>
27235 <p><var>data</var>: The data to be set
27236 </p>
27237 <p><var>data_size</var>: The data size
27238 </p>
27239 <p><var>reason_flags</var>: revocation reasons
27240 </p>
27241 <p>This function will set the CRL distribution points certificate extension.
27242 </p>
27243 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27244 negative error value.
27245 </p>
27246 <p><strong>Since:</strong> 2.6.0
27247 </p></dd></dl>
27248
27249 <a name="gnutls_005fx509_005fcrt_005fset_005fcrq-1"></a>
27250 <h4 class="subheading">gnutls_x509_crt_set_crq</h4>
27251 <a name="gnutls_005fx509_005fcrt_005fset_005fcrq"></a><dl>
27252 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fcrq"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_crq</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_crq_t <var>crq</var>)</em></dt>
27253 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27254 </p>
27255 <p><var>crq</var>: holds a certificate request
27256 </p>
27257 <p>This function will set the name and public parameters as well as
27258 the extensions from the given certificate request to the certificate.
27259 Only RSA keys are currently supported.
27260 </p>
27261 <p>Note that this function will only set the  <code>crq</code> if it is self
27262 signed and the signature is correct. See <code>gnutls_x509_crq_sign2()</code> .
27263 </p>
27264 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27265 negative error value.
27266 </p></dd></dl>
27267
27268 <a name="gnutls_005fx509_005fcrt_005fset_005fcrq_005fextensions-1"></a>
27269 <h4 class="subheading">gnutls_x509_crt_set_crq_extensions</h4>
27270 <a name="gnutls_005fx509_005fcrt_005fset_005fcrq_005fextensions"></a><dl>
27271 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fcrq_005fextensions"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_crq_extensions</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_crq_t <var>crq</var>)</em></dt>
27272 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27273 </p>
27274 <p><var>crq</var>: holds a certificate request
27275 </p>
27276 <p>This function will set extensions from the given request to the
27277 certificate.
27278 </p>
27279 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27280 negative error value.
27281 </p>
27282 <p><strong>Since:</strong> 2.8.0
27283 </p></dd></dl>
27284
27285 <a name="gnutls_005fx509_005fcrt_005fset_005fdn-1"></a>
27286 <h4 class="subheading">gnutls_x509_crt_set_dn</h4>
27287 <a name="gnutls_005fx509_005fcrt_005fset_005fdn"></a><dl>
27288 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fdn"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_dn</strong> <em>(gnutls_x509_crt_t <var>crt</var>, const char * <var>dn</var>, const char ** <var>err</var>)</em></dt>
27289 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27290 </p>
27291 <p><var>dn</var>: a comma separated DN string (RFC4514)
27292 </p>
27293 <p><var>err</var>: indicates the error position (if any)
27294 </p>
27295 <p>This function will set the DN on the provided certificate.
27296 The input string should be plain ASCII or UTF-8 encoded.
27297 </p>
27298 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27299 negative error value.
27300 </p></dd></dl>
27301
27302 <a name="gnutls_005fx509_005fcrt_005fset_005fdn_005fby_005foid-1"></a>
27303 <h4 class="subheading">gnutls_x509_crt_set_dn_by_oid</h4>
27304 <a name="gnutls_005fx509_005fcrt_005fset_005fdn_005fby_005foid"></a><dl>
27305 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fdn_005fby_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_dn_by_oid</strong> <em>(gnutls_x509_crt_t <var>crt</var>, const char * <var>oid</var>, unsigned int <var>raw_flag</var>, const void * <var>name</var>, unsigned int <var>sizeof_name</var>)</em></dt>
27306 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27307 </p>
27308 <p><var>oid</var>: holds an Object Identifier in a null terminated string
27309 </p>
27310 <p><var>raw_flag</var>: must be 0, or 1 if the data are DER encoded
27311 </p>
27312 <p><var>name</var>: a pointer to the name
27313 </p>
27314 <p><var>sizeof_name</var>: holds the size of  <code>name</code>
27315 </p>
27316 <p>This function will set the part of the name of the Certificate
27317 subject, specified by the given OID. The input string should be
27318 ASCII or UTF-8 encoded.
27319 </p>
27320 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
27321 With this function you can only set the known OIDs. You can test
27322 for known OIDs using <code>gnutls_x509_dn_oid_known()</code> . For OIDs that are
27323 not known (by gnutls) you should properly DER encode your data,
27324 and call this function with  <code>raw_flag</code> set.
27325 </p>
27326 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27327 negative error value.
27328 </p></dd></dl>
27329
27330 <a name="gnutls_005fx509_005fcrt_005fset_005fexpiration_005ftime-1"></a>
27331 <h4 class="subheading">gnutls_x509_crt_set_expiration_time</h4>
27332 <a name="gnutls_005fx509_005fcrt_005fset_005fexpiration_005ftime"></a><dl>
27333 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fexpiration_005ftime"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_expiration_time</strong> <em>(gnutls_x509_crt_t <var>cert</var>, time_t <var>exp_time</var>)</em></dt>
27334 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27335 </p>
27336 <p><var>exp_time</var>: The actual time
27337 </p>
27338 <p>This function will set the time this Certificate will expire.
27339 Setting an expiration time to (time_t)-1 or to <code>GNUTLS_X509_NO_WELL_DEFINED_EXPIRATION</code>
27340 will set to the no well-defined expiration date value.
27341 </p>
27342 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27343 negative error value.
27344 </p></dd></dl>
27345
27346 <a name="gnutls_005fx509_005fcrt_005fset_005fextension_005fby_005foid-1"></a>
27347 <h4 class="subheading">gnutls_x509_crt_set_extension_by_oid</h4>
27348 <a name="gnutls_005fx509_005fcrt_005fset_005fextension_005fby_005foid"></a><dl>
27349 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fextension_005fby_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_extension_by_oid</strong> <em>(gnutls_x509_crt_t <var>crt</var>, const char * <var>oid</var>, const void * <var>buf</var>, size_t <var>sizeof_buf</var>, unsigned int <var>critical</var>)</em></dt>
27350 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27351 </p>
27352 <p><var>oid</var>: holds an Object Identified in null terminated string
27353 </p>
27354 <p><var>buf</var>: a pointer to a DER encoded data
27355 </p>
27356 <p><var>sizeof_buf</var>: holds the size of  <code>buf</code>
27357 </p>
27358 <p><var>critical</var>: should be non-zero if the extension is to be marked as critical
27359 </p>
27360 <p>This function will set an the extension, by the specified OID, in
27361 the certificate.  The extension data should be binary data DER
27362 encoded.
27363 </p>
27364 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27365 negative error value.
27366 </p></dd></dl>
27367
27368 <a name="gnutls_005fx509_005fcrt_005fset_005fissuer_005falt_005fname-1"></a>
27369 <h4 class="subheading">gnutls_x509_crt_set_issuer_alt_name</h4>
27370 <a name="gnutls_005fx509_005fcrt_005fset_005fissuer_005falt_005fname"></a><dl>
27371 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fissuer_005falt_005fname"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_issuer_alt_name</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_subject_alt_name_t <var>type</var>, const void * <var>data</var>, unsigned int <var>data_size</var>, unsigned int <var>flags</var>)</em></dt>
27372 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27373 </p>
27374 <p><var>type</var>: is one of the gnutls_x509_subject_alt_name_t enumerations
27375 </p>
27376 <p><var>data</var>: The data to be set
27377 </p>
27378 <p><var>data_size</var>: The size of data to be set
27379 </p>
27380 <p><var>flags</var>: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append.
27381 </p>
27382 <p>This function will set the issuer alternative name certificate
27383 extension. It can set the same types as <code>gnutls_x509_crt_set_subject_alt_name()</code> .
27384 </p>
27385 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27386 negative error value.
27387 </p>
27388 <p><strong>Since:</strong> 3.3.0
27389 </p></dd></dl>
27390
27391 <a name="gnutls_005fx509_005fcrt_005fset_005fissuer_005fdn-1"></a>
27392 <h4 class="subheading">gnutls_x509_crt_set_issuer_dn</h4>
27393 <a name="gnutls_005fx509_005fcrt_005fset_005fissuer_005fdn"></a><dl>
27394 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fissuer_005fdn"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_issuer_dn</strong> <em>(gnutls_x509_crt_t <var>crt</var>, const char * <var>dn</var>, const char ** <var>err</var>)</em></dt>
27395 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27396 </p>
27397 <p><var>dn</var>: a comma separated DN string (RFC4514)
27398 </p>
27399 <p><var>err</var>: indicates the error position (if any)
27400 </p>
27401 <p>This function will set the DN on the provided certificate.
27402 The input string should be plain ASCII or UTF-8 encoded.
27403 </p>
27404 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27405 negative error value.
27406 </p></dd></dl>
27407
27408 <a name="gnutls_005fx509_005fcrt_005fset_005fissuer_005fdn_005fby_005foid-1"></a>
27409 <h4 class="subheading">gnutls_x509_crt_set_issuer_dn_by_oid</h4>
27410 <a name="gnutls_005fx509_005fcrt_005fset_005fissuer_005fdn_005fby_005foid"></a><dl>
27411 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fissuer_005fdn_005fby_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_issuer_dn_by_oid</strong> <em>(gnutls_x509_crt_t <var>crt</var>, const char * <var>oid</var>, unsigned int <var>raw_flag</var>, const void * <var>name</var>, unsigned int <var>sizeof_name</var>)</em></dt>
27412 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27413 </p>
27414 <p><var>oid</var>: holds an Object Identifier in a null terminated string
27415 </p>
27416 <p><var>raw_flag</var>: must be 0, or 1 if the data are DER encoded
27417 </p>
27418 <p><var>name</var>: a pointer to the name
27419 </p>
27420 <p><var>sizeof_name</var>: holds the size of  <code>name</code>
27421 </p>
27422 <p>This function will set the part of the name of the Certificate
27423 issuer, specified by the given OID.  The input string should be
27424 ASCII or UTF-8 encoded.
27425 </p>
27426 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
27427 With this function you can only set the known OIDs. You can test
27428 for known OIDs using <code>gnutls_x509_dn_oid_known()</code> . For OIDs that are
27429 not known (by gnutls) you should properly DER encode your data,
27430 and call this function with  <code>raw_flag</code> set.
27431 </p>
27432 <p>Normally you do not need to call this function, since the signing
27433 operation will copy the signer&rsquo;s name as the issuer of the
27434 certificate.
27435 </p>
27436 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27437 negative error value.
27438 </p></dd></dl>
27439
27440 <a name="gnutls_005fx509_005fcrt_005fset_005fissuer_005funique_005fid-1"></a>
27441 <h4 class="subheading">gnutls_x509_crt_set_issuer_unique_id</h4>
27442 <a name="gnutls_005fx509_005fcrt_005fset_005fissuer_005funique_005fid"></a><dl>
27443 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fissuer_005funique_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_issuer_unique_id</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const void * <var>id</var>, size_t <var>id_size</var>)</em></dt>
27444 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27445 </p>
27446 <p><var>id</var>: The unique ID
27447 </p>
27448 <p><var>id_size</var>: Holds the size of the unique ID.
27449 </p>
27450 <p>This function will set the X.509 certificate&rsquo;s issuer unique ID field.
27451 </p>
27452 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27453 negative error value.
27454 </p></dd></dl>
27455
27456 <a name="gnutls_005fx509_005fcrt_005fset_005fkey-1"></a>
27457 <h4 class="subheading">gnutls_x509_crt_set_key</h4>
27458 <a name="gnutls_005fx509_005fcrt_005fset_005fkey"></a><dl>
27459 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fkey"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_key</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_privkey_t <var>key</var>)</em></dt>
27460 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27461 </p>
27462 <p><var>key</var>: holds a private key
27463 </p>
27464 <p>This function will set the public parameters from the given
27465 private key to the certificate. Only RSA keys are currently
27466 supported.
27467 </p>
27468 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27469 negative error value.
27470 </p></dd></dl>
27471
27472 <a name="gnutls_005fx509_005fcrt_005fset_005fkey_005fpurpose_005foid-1"></a>
27473 <h4 class="subheading">gnutls_x509_crt_set_key_purpose_oid</h4>
27474 <a name="gnutls_005fx509_005fcrt_005fset_005fkey_005fpurpose_005foid"></a><dl>
27475 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fkey_005fpurpose_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_key_purpose_oid</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const void * <var>oid</var>, unsigned int <var>critical</var>)</em></dt>
27476 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27477 </p>
27478 <p><var>oid</var>: a pointer to a null terminated string that holds the OID
27479 </p>
27480 <p><var>critical</var>: Whether this extension will be critical or not
27481 </p>
27482 <p>This function will set the key purpose OIDs of the Certificate.
27483 These are stored in the Extended Key Usage extension (2.5.29.37)
27484 See the GNUTLS_KP_* definitions for human readable names.
27485 </p>
27486 <p>Subsequent calls to this function will append OIDs to the OID list.
27487 </p>
27488 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
27489 otherwise a negative error code is returned.
27490 </p></dd></dl>
27491
27492 <a name="gnutls_005fx509_005fcrt_005fset_005fkey_005fusage-1"></a>
27493 <h4 class="subheading">gnutls_x509_crt_set_key_usage</h4>
27494 <a name="gnutls_005fx509_005fcrt_005fset_005fkey_005fusage"></a><dl>
27495 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fkey_005fusage"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_key_usage</strong> <em>(gnutls_x509_crt_t <var>crt</var>, unsigned int <var>usage</var>)</em></dt>
27496 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27497 </p>
27498 <p><var>usage</var>: an ORed sequence of the GNUTLS_KEY_* elements.
27499 </p>
27500 <p>This function will set the keyUsage certificate extension.
27501 </p>
27502 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27503 negative error value.
27504 </p></dd></dl>
27505
27506 <a name="gnutls_005fx509_005fcrt_005fset_005fname_005fconstraints-1"></a>
27507 <h4 class="subheading">gnutls_x509_crt_set_name_constraints</h4>
27508 <a name="gnutls_005fx509_005fcrt_005fset_005fname_005fconstraints"></a><dl>
27509 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fname_005fconstraints"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_name_constraints</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_name_constraints_t <var>nc</var>, unsigned int <var>critical</var>)</em></dt>
27510 <dd><p><var>crt</var>: The certificate structure
27511 </p>
27512 <p><var>nc</var>: The nameconstraints structure
27513 </p>
27514 <p><var>critical</var>: whether this extension will be critical
27515 </p>
27516 <p>This function will set the provided name constraints to
27517 the certificate extension list. This extension is always
27518 marked as critical.
27519 </p>
27520 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
27521 </p>
27522 <p><strong>Since:</strong> 3.3.0
27523 </p></dd></dl>
27524
27525 <a name="gnutls_005fx509_005fcrt_005fset_005fpin_005ffunction-1"></a>
27526 <h4 class="subheading">gnutls_x509_crt_set_pin_function</h4>
27527 <a name="gnutls_005fx509_005fcrt_005fset_005fpin_005ffunction"></a><dl>
27528 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fpin_005ffunction"></a>Function: <em>void</em> <strong>gnutls_x509_crt_set_pin_function</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</em></dt>
27529 <dd><p><var>crt</var>: The certificate structure
27530 </p>
27531 <p><var>fn</var>: the callback
27532 </p>
27533 <p><var>userdata</var>: data associated with the callback
27534 </p>
27535 <p>This function will set a callback function to be used when
27536 it is required to access a protected object. This function overrides
27537 the global function set using <code>gnutls_pkcs11_set_pin_function()</code> .
27538 </p>
27539 <p>Note that this callback is currently used only during the import
27540 of a PKCS <code>11</code>  certificate with <code>gnutls_x509_crt_import_pkcs11_url()</code> .
27541 </p>
27542 <p><strong>Since:</strong> 3.1.0
27543 </p></dd></dl>
27544
27545 <a name="gnutls_005fx509_005fcrt_005fset_005fpolicy-1"></a>
27546 <h4 class="subheading">gnutls_x509_crt_set_policy</h4>
27547 <a name="gnutls_005fx509_005fcrt_005fset_005fpolicy"></a><dl>
27548 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fpolicy"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_policy</strong> <em>(gnutls_x509_crt_t <var>crt</var>, const struct gnutls_x509_policy_st * <var>policy</var>, unsigned int <var>critical</var>)</em></dt>
27549 <dd><p><var>crt</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
27550 </p>
27551 <p><var>policy</var>: A pointer to a policy structure.
27552 </p>
27553 <p><var>critical</var>: use non-zero if the extension is marked as critical
27554 </p>
27555 <p>This function will set the certificate policy extension (2.5.29.32).
27556 Multiple calls to this function append a new policy.
27557 </p>
27558 <p>Note the maximum text size for the qualifier <code>GNUTLS_X509_QUALIFIER_NOTICE</code>
27559 is 200 characters. This function will fail with <code>GNUTLS_E_INVALID_REQUEST</code>
27560 if this is exceeded.
27561 </p>
27562 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27563 negative error value.
27564 </p>
27565 <p><strong>Since:</strong> 3.1.5
27566 </p></dd></dl>
27567
27568 <a name="gnutls_005fx509_005fcrt_005fset_005fprivate_005fkey_005fusage_005fperiod-1"></a>
27569 <h4 class="subheading">gnutls_x509_crt_set_private_key_usage_period</h4>
27570 <a name="gnutls_005fx509_005fcrt_005fset_005fprivate_005fkey_005fusage_005fperiod"></a><dl>
27571 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fprivate_005fkey_005fusage_005fperiod"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_private_key_usage_period</strong> <em>(gnutls_x509_crt_t <var>crt</var>, time_t <var>activation</var>, time_t <var>expiration</var>)</em></dt>
27572 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27573 </p>
27574 <p><var>activation</var>: The activation time
27575 </p>
27576 <p><var>expiration</var>: The expiration time
27577 </p>
27578 <p>This function will set the private key usage period extension (2.5.29.16).
27579 </p>
27580 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27581 negative error value.
27582 </p></dd></dl>
27583
27584 <a name="gnutls_005fx509_005fcrt_005fset_005fproxy-1"></a>
27585 <h4 class="subheading">gnutls_x509_crt_set_proxy</h4>
27586 <a name="gnutls_005fx509_005fcrt_005fset_005fproxy"></a><dl>
27587 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fproxy"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_proxy</strong> <em>(gnutls_x509_crt_t <var>crt</var>, int <var>pathLenConstraint</var>, const char * <var>policyLanguage</var>, const char * <var>policy</var>, size_t <var>sizeof_policy</var>)</em></dt>
27588 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27589 </p>
27590 <p><var>pathLenConstraint</var>: non-negative error codes indicate maximum length of path,
27591 and negative error codes indicate that the pathLenConstraints field should
27592 not be present.
27593 </p>
27594 <p><var>policyLanguage</var>: OID describing the language of  <code>policy</code> .
27595 </p>
27596 <p><var>policy</var>: uint8_t byte array with policy language, can be <code>NULL</code>
27597 </p>
27598 <p><var>sizeof_policy</var>: size of  <code>policy</code> .
27599 </p>
27600 <p>This function will set the proxyCertInfo extension.
27601 </p>
27602 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27603 negative error value.
27604 </p></dd></dl>
27605
27606 <a name="gnutls_005fx509_005fcrt_005fset_005fproxy_005fdn-1"></a>
27607 <h4 class="subheading">gnutls_x509_crt_set_proxy_dn</h4>
27608 <a name="gnutls_005fx509_005fcrt_005fset_005fproxy_005fdn"></a><dl>
27609 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fproxy_005fdn"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_proxy_dn</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_crt_t <var>eecrt</var>, unsigned int <var>raw_flag</var>, const void * <var>name</var>, unsigned int <var>sizeof_name</var>)</em></dt>
27610 <dd><p><var>crt</var>: a gnutls_x509_crt_t structure with the new proxy cert
27611 </p>
27612 <p><var>eecrt</var>: the end entity certificate that will be issuing the proxy
27613 </p>
27614 <p><var>raw_flag</var>: must be 0, or 1 if the CN is DER encoded
27615 </p>
27616 <p><var>name</var>: a pointer to the CN name, may be NULL (but MUST then be added later)
27617 </p>
27618 <p><var>sizeof_name</var>: holds the size of  <code>name</code>
27619 </p>
27620 <p>This function will set the subject in  <code>crt</code> to the end entity&rsquo;s
27621  <code>eecrt</code> subject name, and add a single Common Name component  <code>name</code> of size  <code>sizeof_name</code> .  This corresponds to the required proxy
27622 certificate naming style.  Note that if  <code>name</code> is <code>NULL</code> , you MUST
27623 set it later by using <code>gnutls_x509_crt_set_dn_by_oid()</code>  or similar.
27624 </p>
27625 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27626 negative error value.
27627 </p></dd></dl>
27628
27629 <a name="gnutls_005fx509_005fcrt_005fset_005fserial-1"></a>
27630 <h4 class="subheading">gnutls_x509_crt_set_serial</h4>
27631 <a name="gnutls_005fx509_005fcrt_005fset_005fserial"></a><dl>
27632 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fserial"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_serial</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const void * <var>serial</var>, size_t <var>serial_size</var>)</em></dt>
27633 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27634 </p>
27635 <p><var>serial</var>: The serial number
27636 </p>
27637 <p><var>serial_size</var>: Holds the size of the serial field.
27638 </p>
27639 <p>This function will set the X.509 certificate&rsquo;s serial number.
27640 While the serial number is an integer, it is often handled
27641 as an opaque field by several CAs. For this reason this function
27642 accepts any kind of data as a serial number. To be consistent
27643 with the X.509/PKIX specifications the provided  <code>serial</code> should be
27644 a big-endian positive number (i.e. it&rsquo;s leftmost bit should be zero).
27645 </p>
27646 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27647 negative error value.
27648 </p></dd></dl>
27649
27650 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005falt_005fname-1"></a>
27651 <h4 class="subheading">gnutls_x509_crt_set_subject_alt_name</h4>
27652 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005falt_005fname"></a><dl>
27653 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fsubject_005falt_005fname"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_subject_alt_name</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_subject_alt_name_t <var>type</var>, const void * <var>data</var>, unsigned int <var>data_size</var>, unsigned int <var>flags</var>)</em></dt>
27654 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27655 </p>
27656 <p><var>type</var>: is one of the gnutls_x509_subject_alt_name_t enumerations
27657 </p>
27658 <p><var>data</var>: The data to be set
27659 </p>
27660 <p><var>data_size</var>: The size of data to be set
27661 </p>
27662 <p><var>flags</var>: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append.
27663 </p>
27664 <p>This function will set the subject alternative name certificate
27665 extension. It can set the following types:
27666 </p>
27667 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27668 negative error value.
27669 </p>
27670 <p><strong>Since:</strong> 2.6.0
27671 </p></dd></dl>
27672
27673 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005falternative_005fname-1"></a>
27674 <h4 class="subheading">gnutls_x509_crt_set_subject_alternative_name</h4>
27675 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005falternative_005fname"></a><dl>
27676 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fsubject_005falternative_005fname"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_subject_alternative_name</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_subject_alt_name_t           <var>type</var>, const char * <var>data_string</var>)</em></dt>
27677 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27678 </p>
27679 <p><var>type</var>: is one of the gnutls_x509_subject_alt_name_t enumerations
27680 </p>
27681 <p><var>data_string</var>: The data to be set, a (0) terminated string
27682 </p>
27683 <p>This function will set the subject alternative name certificate
27684 extension. This function assumes that data can be expressed as a null
27685 terminated string.
27686 </p>
27687 <p>The name of the function is unfortunate since it is incosistent with
27688 <code>gnutls_x509_crt_get_subject_alt_name()</code> .
27689 </p>
27690 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27691 negative error value.
27692 </p></dd></dl>
27693
27694 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005fkey_005fid-1"></a>
27695 <h4 class="subheading">gnutls_x509_crt_set_subject_key_id</h4>
27696 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005fkey_005fid"></a><dl>
27697 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fsubject_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_subject_key_id</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const void * <var>id</var>, size_t <var>id_size</var>)</em></dt>
27698 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27699 </p>
27700 <p><var>id</var>: The key ID
27701 </p>
27702 <p><var>id_size</var>: Holds the size of the subject key ID field.
27703 </p>
27704 <p>This function will set the X.509 certificate&rsquo;s subject key ID
27705 extension.
27706 </p>
27707 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27708 negative error value.
27709 </p></dd></dl>
27710
27711 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005funique_005fid-1"></a>
27712 <h4 class="subheading">gnutls_x509_crt_set_subject_unique_id</h4>
27713 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005funique_005fid"></a><dl>
27714 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fsubject_005funique_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_subject_unique_id</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const void * <var>id</var>, size_t <var>id_size</var>)</em></dt>
27715 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27716 </p>
27717 <p><var>id</var>: The unique ID
27718 </p>
27719 <p><var>id_size</var>: Holds the size of the unique ID.
27720 </p>
27721 <p>This function will set the X.509 certificate&rsquo;s subject unique ID field.
27722 </p>
27723 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27724 negative error value.
27725 </p></dd></dl>
27726
27727 <a name="gnutls_005fx509_005fcrt_005fset_005fversion-1"></a>
27728 <h4 class="subheading">gnutls_x509_crt_set_version</h4>
27729 <a name="gnutls_005fx509_005fcrt_005fset_005fversion"></a><dl>
27730 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fversion"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_version</strong> <em>(gnutls_x509_crt_t <var>crt</var>, unsigned int <var>version</var>)</em></dt>
27731 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27732 </p>
27733 <p><var>version</var>: holds the version number. For X.509v1 certificates must be 1.
27734 </p>
27735 <p>This function will set the version of the certificate.  This must
27736 be one for X.509 version 1, and so on.  Plain certificates without
27737 extensions must have version set to one.
27738 </p>
27739 <p>To create well-formed certificates, you must specify version 3 if
27740 you use any certificate extensions.  Extensions are created by
27741 functions such as <code>gnutls_x509_crt_set_subject_alt_name()</code>
27742 or <code>gnutls_x509_crt_set_key_usage()</code> .
27743 </p>
27744 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27745 negative error value.
27746 </p></dd></dl>
27747
27748 <a name="gnutls_005fx509_005fcrt_005fsign-1"></a>
27749 <h4 class="subheading">gnutls_x509_crt_sign</h4>
27750 <a name="gnutls_005fx509_005fcrt_005fsign"></a><dl>
27751 <dt><a name="index-gnutls_005fx509_005fcrt_005fsign"></a>Function: <em>int</em> <strong>gnutls_x509_crt_sign</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_crt_t <var>issuer</var>, gnutls_x509_privkey_t <var>issuer_key</var>)</em></dt>
27752 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27753 </p>
27754 <p><var>issuer</var>: is the certificate of the certificate issuer
27755 </p>
27756 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
27757 </p>
27758 <p>This function is the same a <code>gnutls_x509_crt_sign2()</code>  with no flags,
27759 and SHA1 as the hash algorithm.
27760 </p>
27761 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27762 negative error value.
27763 </p></dd></dl>
27764
27765 <a name="gnutls_005fx509_005fcrt_005fsign2-1"></a>
27766 <h4 class="subheading">gnutls_x509_crt_sign2</h4>
27767 <a name="gnutls_005fx509_005fcrt_005fsign2"></a><dl>
27768 <dt><a name="index-gnutls_005fx509_005fcrt_005fsign2"></a>Function: <em>int</em> <strong>gnutls_x509_crt_sign2</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_crt_t <var>issuer</var>, gnutls_x509_privkey_t <var>issuer_key</var>, gnutls_digest_algorithm_t <var>dig</var>, unsigned int <var>flags</var>)</em></dt>
27769 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
27770 </p>
27771 <p><var>issuer</var>: is the certificate of the certificate issuer
27772 </p>
27773 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
27774 </p>
27775 <p><var>dig</var>: The message digest to use, <code>GNUTLS_DIG_SHA1</code>  is a safe choice
27776 </p>
27777 <p><var>flags</var>: must be 0
27778 </p>
27779 <p>This function will sign the certificate with the issuer&rsquo;s private key, and
27780 will copy the issuer&rsquo;s information into the certificate.
27781 </p>
27782 <p>This must be the last step in a certificate generation since all
27783 the previously set parameters are now signed.
27784 </p>
27785 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27786 negative error value.
27787 </p></dd></dl>
27788
27789 <a name="gnutls_005fx509_005fcrt_005fverify-1"></a>
27790 <h4 class="subheading">gnutls_x509_crt_verify</h4>
27791 <a name="gnutls_005fx509_005fcrt_005fverify"></a><dl>
27792 <dt><a name="index-gnutls_005fx509_005fcrt_005fverify"></a>Function: <em>int</em> <strong>gnutls_x509_crt_verify</strong> <em>(gnutls_x509_crt_t <var>cert</var>, const gnutls_x509_crt_t * <var>CA_list</var>, int <var>CA_list_length</var>, unsigned int <var>flags</var>, unsigned int * <var>verify</var>)</em></dt>
27793 <dd><p><var>cert</var>: is the certificate to be verified
27794 </p>
27795 <p><var>CA_list</var>: is one certificate that is considered to be trusted one
27796 </p>
27797 <p><var>CA_list_length</var>: holds the number of CA certificate in CA_list
27798 </p>
27799 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
27800 </p>
27801 <p><var>verify</var>: will hold the certificate verification output.
27802 </p>
27803 <p>This function will try to verify the given certificate and return
27804 its status. Note that a verification error does not imply a negative
27805 return status. In that case the  <code>verify</code> status is set.
27806 </p>
27807 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27808 negative error value.
27809 </p></dd></dl>
27810
27811 <a name="gnutls_005fx509_005fdn_005fdeinit-1"></a>
27812 <h4 class="subheading">gnutls_x509_dn_deinit</h4>
27813 <a name="gnutls_005fx509_005fdn_005fdeinit"></a><dl>
27814 <dt><a name="index-gnutls_005fx509_005fdn_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_dn_deinit</strong> <em>(gnutls_x509_dn_t <var>dn</var>)</em></dt>
27815 <dd><p><var>dn</var>: a DN uint8_t object pointer.
27816 </p>
27817 <p>This function deallocates the DN object as returned by
27818 <code>gnutls_x509_dn_import()</code> .
27819 </p>
27820 <p><strong>Since:</strong> 2.4.0
27821 </p></dd></dl>
27822
27823 <a name="gnutls_005fx509_005fdn_005fexport-1"></a>
27824 <h4 class="subheading">gnutls_x509_dn_export</h4>
27825 <a name="gnutls_005fx509_005fdn_005fexport"></a><dl>
27826 <dt><a name="index-gnutls_005fx509_005fdn_005fexport"></a>Function: <em>int</em> <strong>gnutls_x509_dn_export</strong> <em>(gnutls_x509_dn_t <var>dn</var>, gnutls_x509_crt_fmt_t <var>format</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
27827 <dd><p><var>dn</var>: Holds the uint8_t DN object
27828 </p>
27829 <p><var>format</var>: the format of output params. One of PEM or DER.
27830 </p>
27831 <p><var>output_data</var>: will contain a DN PEM or DER encoded
27832 </p>
27833 <p><var>output_data_size</var>: holds the size of output_data (and will be
27834 replaced by the actual size of parameters)
27835 </p>
27836 <p>This function will export the DN to DER or PEM format.
27837 </p>
27838 <p>If the buffer provided is not long enough to hold the output, then
27839 * <code>output_data_size</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>
27840 will be returned.
27841 </p>
27842 <p>If the structure is PEM encoded, it will have a header
27843 of &quot;BEGIN NAME&quot;.
27844 </p>
27845 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27846 negative error value.
27847 </p></dd></dl>
27848
27849 <a name="gnutls_005fx509_005fdn_005fexport2-1"></a>
27850 <h4 class="subheading">gnutls_x509_dn_export2</h4>
27851 <a name="gnutls_005fx509_005fdn_005fexport2"></a><dl>
27852 <dt><a name="index-gnutls_005fx509_005fdn_005fexport2"></a>Function: <em>int</em> <strong>gnutls_x509_dn_export2</strong> <em>(gnutls_x509_dn_t <var>dn</var>, gnutls_x509_crt_fmt_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
27853 <dd><p><var>dn</var>: Holds the uint8_t DN object
27854 </p>
27855 <p><var>format</var>: the format of output params. One of PEM or DER.
27856 </p>
27857 <p><var>out</var>: will contain a DN PEM or DER encoded
27858 </p>
27859 <p>This function will export the DN to DER or PEM format.
27860 </p>
27861 <p>The output buffer is allocated using <code>gnutls_malloc()</code> .
27862 </p>
27863 <p>If the structure is PEM encoded, it will have a header
27864 of &quot;BEGIN NAME&quot;.
27865 </p>
27866 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27867 negative error value.
27868 </p>
27869 <p><strong>Since:</strong> 3.1.3
27870 </p></dd></dl>
27871
27872 <a name="gnutls_005fx509_005fdn_005fget_005frdn_005fava-1"></a>
27873 <h4 class="subheading">gnutls_x509_dn_get_rdn_ava</h4>
27874 <a name="gnutls_005fx509_005fdn_005fget_005frdn_005fava"></a><dl>
27875 <dt><a name="index-gnutls_005fx509_005fdn_005fget_005frdn_005fava-1"></a>Function: <em>int</em> <strong>gnutls_x509_dn_get_rdn_ava</strong> <em>(gnutls_x509_dn_t <var>dn</var>, int <var>irdn</var>, int <var>iava</var>, gnutls_x509_ava_st * <var>ava</var>)</em></dt>
27876 <dd><p><var>dn</var>: a pointer to DN
27877 </p>
27878 <p><var>irdn</var>: index of RDN
27879 </p>
27880 <p><var>iava</var>: index of AVA.
27881 </p>
27882 <p><var>ava</var>: Pointer to structure which will hold output information.
27883 </p>
27884 <p>Get pointers to data within the DN. The format of the  <code>ava</code> structure
27885 is shown below.
27886 </p>
27887 <p>struct gnutls_x509_ava_st {
27888 gnutls_datum_t oid;
27889 gnutls_datum_t value;
27890 unsigned long value_tag;
27891 };
27892 </p>
27893 <p>The X.509 distinguished name is a sequence of sequences of strings
27894 and this is what the  <code>irdn</code> and  <code>iava</code> indexes model.
27895 </p>
27896 <p>Note that  <code>ava</code> will contain pointers into the  <code>dn</code> structure which
27897 in turns points to the original certificate. Thus you should not
27898 modify any data or deallocate any of those.
27899 </p>
27900 <p>This is a low-level function that requires the caller to do the
27901 value conversions when necessary (e.g. from UCS-2).
27902 </p>
27903 <p><strong>Returns:</strong> Returns 0 on success, or an error code.
27904 </p></dd></dl>
27905
27906 <a name="gnutls_005fx509_005fdn_005fimport-1"></a>
27907 <h4 class="subheading">gnutls_x509_dn_import</h4>
27908 <a name="gnutls_005fx509_005fdn_005fimport"></a><dl>
27909 <dt><a name="index-gnutls_005fx509_005fdn_005fimport"></a>Function: <em>int</em> <strong>gnutls_x509_dn_import</strong> <em>(gnutls_x509_dn_t <var>dn</var>, const gnutls_datum_t * <var>data</var>)</em></dt>
27910 <dd><p><var>dn</var>: the structure that will hold the imported DN
27911 </p>
27912 <p><var>data</var>: should contain a DER encoded RDN sequence
27913 </p>
27914 <p>This function parses an RDN sequence and stores the result to a
27915 <code>gnutls_x509_dn_t</code>  structure. The structure must have been initialized
27916 with <code>gnutls_x509_dn_init()</code> . You may use <code>gnutls_x509_dn_get_rdn_ava()</code>  to
27917 decode the DN.
27918 </p>
27919 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27920 negative error value.
27921 </p>
27922 <p><strong>Since:</strong> 2.4.0
27923 </p></dd></dl>
27924
27925 <a name="gnutls_005fx509_005fdn_005finit-1"></a>
27926 <h4 class="subheading">gnutls_x509_dn_init</h4>
27927 <a name="gnutls_005fx509_005fdn_005finit"></a><dl>
27928 <dt><a name="index-gnutls_005fx509_005fdn_005finit"></a>Function: <em>int</em> <strong>gnutls_x509_dn_init</strong> <em>(gnutls_x509_dn_t * <var>dn</var>)</em></dt>
27929 <dd><p><var>dn</var>: the object to be initialized
27930 </p>
27931 <p>This function initializes a <code>gnutls_x509_dn_t</code>  structure.
27932 </p>
27933 <p>The object returned must be deallocated using
27934 <code>gnutls_x509_dn_deinit()</code> .
27935 </p>
27936 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
27937 negative error value.
27938 </p>
27939 <p><strong>Since:</strong> 2.4.0
27940 </p></dd></dl>
27941
27942 <a name="gnutls_005fx509_005fdn_005foid_005fknown-1"></a>
27943 <h4 class="subheading">gnutls_x509_dn_oid_known</h4>
27944 <a name="gnutls_005fx509_005fdn_005foid_005fknown"></a><dl>
27945 <dt><a name="index-gnutls_005fx509_005fdn_005foid_005fknown"></a>Function: <em>int</em> <strong>gnutls_x509_dn_oid_known</strong> <em>(const char * <var>oid</var>)</em></dt>
27946 <dd><p><var>oid</var>: holds an Object Identifier in a null terminated string
27947 </p>
27948 <p>This function will inform about known DN OIDs. This is useful since
27949 functions like <code>gnutls_x509_crt_set_dn_by_oid()</code>  use the information
27950 on known OIDs to properly encode their input. Object Identifiers
27951 that are not known are not encoded by these functions, and their
27952 input is stored directly into the ASN.1 structure. In that case of
27953 unknown OIDs, you have the responsibility of DER encoding your
27954 data.
27955 </p>
27956 <p><strong>Returns:</strong> 1 on known OIDs and 0 otherwise.
27957 </p></dd></dl>
27958
27959 <a name="gnutls_005fx509_005fdn_005foid_005fname-1"></a>
27960 <h4 class="subheading">gnutls_x509_dn_oid_name</h4>
27961 <a name="gnutls_005fx509_005fdn_005foid_005fname"></a><dl>
27962 <dt><a name="index-gnutls_005fx509_005fdn_005foid_005fname"></a>Function: <em>const char *</em> <strong>gnutls_x509_dn_oid_name</strong> <em>(const char * <var>oid</var>, unsigned int <var>flags</var>)</em></dt>
27963 <dd><p><var>oid</var>: holds an Object Identifier in a null terminated string
27964 </p>
27965 <p><var>flags</var>: 0 or GNUTLS_X509_DN_OID_*
27966 </p>
27967 <p>This function will return the name of a known DN OID. If
27968 <code>GNUTLS_X509_DN_OID_RETURN_OID</code>  is specified this function
27969 will return the given OID if no descriptive name has been
27970 found.
27971 </p>
27972 <p><strong>Returns:</strong> A null terminated string or NULL otherwise.
27973 </p>
27974 <p><strong>Since:</strong> 3.0
27975 </p></dd></dl>
27976
27977 <a name="gnutls_005fx509_005fext_005fdeinit-1"></a>
27978 <h4 class="subheading">gnutls_x509_ext_deinit</h4>
27979 <a name="gnutls_005fx509_005fext_005fdeinit"></a><dl>
27980 <dt><a name="index-gnutls_005fx509_005fext_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_ext_deinit</strong> <em>(gnutls_x509_ext_st * <var>ext</var>)</em></dt>
27981 <dd><p><var>ext</var>: The extensions structure
27982 </p>
27983 <p>This function will deinitialize an extensions structure.
27984 </p>
27985 <p><strong>Since:</strong> 3.3.8
27986 </p></dd></dl>
27987
27988 <a name="gnutls_005fx509_005fext_005fexport_005faia-1"></a>
27989 <h4 class="subheading">gnutls_x509_ext_export_aia</h4>
27990 <a name="gnutls_005fx509_005fext_005fexport_005faia"></a><dl>
27991 <dt><a name="index-gnutls_005fx509_005fext_005fexport_005faia"></a>Function: <em>int</em> <strong>gnutls_x509_ext_export_aia</strong> <em>(gnutls_x509_aia_t <var>aia</var>, gnutls_datum_t * <var>ext</var>)</em></dt>
27992 <dd><p><var>aia</var>: The authority info access structure
27993 </p>
27994 <p><var>ext</var>: The DER-encoded extension data; must be freed using <code>gnutls_free()</code> .
27995 </p>
27996 <p>This function will DER encode the Authority Information Access (AIA)
27997 extension; see RFC 5280 section 4.2.2.1 for more information on the
27998 extension.
27999 </p>
28000 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28001 negative error value.
28002 </p>
28003 <p><strong>Since:</strong> 3.3.0
28004 </p></dd></dl>
28005
28006 <a name="gnutls_005fx509_005fext_005fexport_005fauthority_005fkey_005fid-1"></a>
28007 <h4 class="subheading">gnutls_x509_ext_export_authority_key_id</h4>
28008 <a name="gnutls_005fx509_005fext_005fexport_005fauthority_005fkey_005fid"></a><dl>
28009 <dt><a name="index-gnutls_005fx509_005fext_005fexport_005fauthority_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_ext_export_authority_key_id</strong> <em>(gnutls_x509_aki_t <var>aki</var>, gnutls_datum_t * <var>ext</var>)</em></dt>
28010 <dd><p><var>aki</var>: An initialized authority key identifier structure
28011 </p>
28012 <p><var>ext</var>: The DER-encoded extension data; must be freed using <code>gnutls_free()</code> .
28013 </p>
28014 <p>This function will convert the provided key identifier to a
28015 DER-encoded PKIX AuthorityKeyIdentifier extension.
28016 The output data in  <code>ext</code> will be allocated using
28017 <code>gnutls_malloc()</code> .
28018 </p>
28019 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28020 </p>
28021 <p><strong>Since:</strong> 3.3.0
28022 </p></dd></dl>
28023
28024 <a name="gnutls_005fx509_005fext_005fexport_005fbasic_005fconstraints-1"></a>
28025 <h4 class="subheading">gnutls_x509_ext_export_basic_constraints</h4>
28026 <a name="gnutls_005fx509_005fext_005fexport_005fbasic_005fconstraints"></a><dl>
28027 <dt><a name="index-gnutls_005fx509_005fext_005fexport_005fbasic_005fconstraints"></a>Function: <em>int</em> <strong>gnutls_x509_ext_export_basic_constraints</strong> <em>(unsigned int <var>ca</var>, int <var>pathlen</var>, gnutls_datum_t * <var>ext</var>)</em></dt>
28028 <dd><p><var>ca</var>: non-zero for a CA
28029 </p>
28030 <p><var>pathlen</var>: The path length constraint (set to -1 for no constraint)
28031 </p>
28032 <p><var>ext</var>: The DER-encoded extension data; must be freed using <code>gnutls_free()</code> .
28033 </p>
28034 <p>This function will convert the parameters provided to a basic constraints
28035 DER encoded extension (2.5.29.19).
28036 The  <code>ext</code> data will be allocated using
28037 <code>gnutls_malloc()</code> .
28038 </p>
28039 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28040 negative error value.
28041 </p>
28042 <p><strong>Since:</strong> 3.3.0
28043 </p></dd></dl>
28044
28045 <a name="gnutls_005fx509_005fext_005fexport_005fcrl_005fdist_005fpoints-1"></a>
28046 <h4 class="subheading">gnutls_x509_ext_export_crl_dist_points</h4>
28047 <a name="gnutls_005fx509_005fext_005fexport_005fcrl_005fdist_005fpoints"></a><dl>
28048 <dt><a name="index-gnutls_005fx509_005fext_005fexport_005fcrl_005fdist_005fpoints"></a>Function: <em>int</em> <strong>gnutls_x509_ext_export_crl_dist_points</strong> <em>(gnutls_x509_crl_dist_points_t <var>cdp</var>, gnutls_datum_t * <var>ext</var>)</em></dt>
28049 <dd><p><var>cdp</var>: A pointer to an initialized CRL distribution points structure.
28050 </p>
28051 <p><var>ext</var>: The DER-encoded extension data; must be freed using <code>gnutls_free()</code> .
28052 </p>
28053 <p>This function will convert the provided policies, to a certificate policy
28054 DER encoded extension (2.5.29.31).
28055 </p>
28056 <p>The  <code>ext</code> data will be allocated using <code>gnutls_malloc()</code> .
28057 </p>
28058 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28059 </p>
28060 <p><strong>Since:</strong> 3.3.0
28061 </p></dd></dl>
28062
28063 <a name="gnutls_005fx509_005fext_005fexport_005fkey_005fpurposes-1"></a>
28064 <h4 class="subheading">gnutls_x509_ext_export_key_purposes</h4>
28065 <a name="gnutls_005fx509_005fext_005fexport_005fkey_005fpurposes"></a><dl>
28066 <dt><a name="index-gnutls_005fx509_005fext_005fexport_005fkey_005fpurposes"></a>Function: <em>int</em> <strong>gnutls_x509_ext_export_key_purposes</strong> <em>(gnutls_x509_key_purposes_t <var>p</var>, gnutls_datum_t * <var>ext</var>)</em></dt>
28067 <dd><p><var>p</var>: The key purposes structure
28068 </p>
28069 <p><var>ext</var>: The DER-encoded extension data; must be freed using <code>gnutls_free()</code> .
28070 </p>
28071 <p>This function will convert the key purposes structure to a
28072 DER-encoded PKIX ExtKeyUsageSyntax (2.5.29.37) extension. The output data in
28073  <code>ext</code> will be allocated usin <code>gnutls_malloc()</code> .
28074 </p>
28075 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28076 </p>
28077 <p><strong>Since:</strong> 3.3.0
28078 </p></dd></dl>
28079
28080 <a name="gnutls_005fx509_005fext_005fexport_005fkey_005fusage-1"></a>
28081 <h4 class="subheading">gnutls_x509_ext_export_key_usage</h4>
28082 <a name="gnutls_005fx509_005fext_005fexport_005fkey_005fusage"></a><dl>
28083 <dt><a name="index-gnutls_005fx509_005fext_005fexport_005fkey_005fusage"></a>Function: <em>int</em> <strong>gnutls_x509_ext_export_key_usage</strong> <em>(unsigned int <var>usage</var>, gnutls_datum_t * <var>ext</var>)</em></dt>
28084 <dd><p><var>usage</var>: an ORed sequence of the GNUTLS_KEY_* elements.
28085 </p>
28086 <p><var>ext</var>: The DER-encoded extension data; must be freed using <code>gnutls_free()</code> .
28087 </p>
28088 <p>This function will convert the keyUsage bit string to a DER
28089 encoded PKIX extension. The  <code>ext</code> data will be allocated using
28090 <code>gnutls_malloc()</code> .
28091 </p>
28092 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28093 negative error value.
28094 </p>
28095 <p><strong>Since:</strong> 3.3.0
28096 </p></dd></dl>
28097
28098 <a name="gnutls_005fx509_005fext_005fexport_005fname_005fconstraints-1"></a>
28099 <h4 class="subheading">gnutls_x509_ext_export_name_constraints</h4>
28100 <a name="gnutls_005fx509_005fext_005fexport_005fname_005fconstraints"></a><dl>
28101 <dt><a name="index-gnutls_005fx509_005fext_005fexport_005fname_005fconstraints"></a>Function: <em>int</em> <strong>gnutls_x509_ext_export_name_constraints</strong> <em>(gnutls_x509_name_constraints_t <var>nc</var>, gnutls_datum_t * <var>ext</var>)</em></dt>
28102 <dd><p><var>nc</var>: The nameconstraints structure
28103 </p>
28104 <p><var>ext</var>: The DER-encoded extension data; must be freed using <code>gnutls_free()</code> .
28105 </p>
28106 <p>This function will convert the provided name constraints structure to a
28107 DER-encoded PKIX NameConstraints (2.5.29.30) extension. The output data in
28108  <code>ext</code> will be allocated usin <code>gnutls_malloc()</code> .
28109 </p>
28110 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28111 </p>
28112 <p><strong>Since:</strong> 3.3.0
28113 </p></dd></dl>
28114
28115 <a name="gnutls_005fx509_005fext_005fexport_005fpolicies-1"></a>
28116 <h4 class="subheading">gnutls_x509_ext_export_policies</h4>
28117 <a name="gnutls_005fx509_005fext_005fexport_005fpolicies"></a><dl>
28118 <dt><a name="index-gnutls_005fx509_005fext_005fexport_005fpolicies"></a>Function: <em>int</em> <strong>gnutls_x509_ext_export_policies</strong> <em>(gnutls_x509_policies_t <var>policies</var>, gnutls_datum_t * <var>ext</var>)</em></dt>
28119 <dd><p><var>policies</var>: A pointer to an initialized policies structure.
28120 </p>
28121 <p><var>ext</var>: The DER-encoded extension data; must be freed using <code>gnutls_free()</code> .
28122 </p>
28123 <p>This function will convert the provided policies, to a certificate policy
28124 DER encoded extension (2.5.29.32).
28125 </p>
28126 <p>The  <code>ext</code> data will be allocated using <code>gnutls_malloc()</code> .
28127 </p>
28128 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28129 </p>
28130 <p><strong>Since:</strong> 3.3.0
28131 </p></dd></dl>
28132
28133 <a name="gnutls_005fx509_005fext_005fexport_005fprivate_005fkey_005fusage_005fperiod-1"></a>
28134 <h4 class="subheading">gnutls_x509_ext_export_private_key_usage_period</h4>
28135 <a name="gnutls_005fx509_005fext_005fexport_005fprivate_005fkey_005fusage_005fperiod"></a><dl>
28136 <dt><a name="index-gnutls_005fx509_005fext_005fexport_005fprivate_005fkey_005fusage_005fperiod"></a>Function: <em>int</em> <strong>gnutls_x509_ext_export_private_key_usage_period</strong> <em>(time_t <var>activation</var>, time_t <var>expiration</var>, gnutls_datum_t * <var>ext</var>)</em></dt>
28137 <dd><p><var>activation</var>: The activation time
28138 </p>
28139 <p><var>expiration</var>: The expiration time
28140 </p>
28141 <p><var>ext</var>: The DER-encoded extension data; must be freed using <code>gnutls_free()</code> .
28142 </p>
28143 <p>This function will convert the periods provided to a private key
28144 usage DER encoded extension (2.5.29.16).
28145 The  <code>ext</code> data will be allocated using
28146 <code>gnutls_malloc()</code> .
28147 </p>
28148 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28149 negative error value.
28150 </p>
28151 <p><strong>Since:</strong> 3.3.0
28152 </p></dd></dl>
28153
28154 <a name="gnutls_005fx509_005fext_005fexport_005fproxy-1"></a>
28155 <h4 class="subheading">gnutls_x509_ext_export_proxy</h4>
28156 <a name="gnutls_005fx509_005fext_005fexport_005fproxy"></a><dl>
28157 <dt><a name="index-gnutls_005fx509_005fext_005fexport_005fproxy"></a>Function: <em>int</em> <strong>gnutls_x509_ext_export_proxy</strong> <em>(int <var>pathLenConstraint</var>, const char * <var>policyLanguage</var>, const char * <var>policy</var>, size_t <var>sizeof_policy</var>, gnutls_datum_t * <var>ext</var>)</em></dt>
28158 <dd><p><var>pathLenConstraint</var>: non-negative error codes indicate maximum length of path,
28159 and negative error codes indicate that the pathLenConstraints field should
28160 not be present.
28161 </p>
28162 <p><var>policyLanguage</var>: OID describing the language of  <code>policy</code> .
28163 </p>
28164 <p><var>policy</var>: uint8_t byte array with policy language, can be <code>NULL</code>
28165 </p>
28166 <p><var>sizeof_policy</var>: size of  <code>policy</code> .
28167 </p>
28168 <p><var>ext</var>: The DER-encoded extension data; must be freed using <code>gnutls_free()</code> .
28169 </p>
28170 <p>This function will convert the parameters provided to a proxyCertInfo extension.
28171 </p>
28172 <p>The  <code>ext</code> data will be allocated using
28173 <code>gnutls_malloc()</code> .
28174 </p>
28175 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28176 negative error value.
28177 </p>
28178 <p><strong>Since:</strong> 3.3.0
28179 </p></dd></dl>
28180
28181 <a name="gnutls_005fx509_005fext_005fexport_005fsubject_005falt_005fnames-1"></a>
28182 <h4 class="subheading">gnutls_x509_ext_export_subject_alt_names</h4>
28183 <a name="gnutls_005fx509_005fext_005fexport_005fsubject_005falt_005fnames"></a><dl>
28184 <dt><a name="index-gnutls_005fx509_005fext_005fexport_005fsubject_005falt_005fnames"></a>Function: <em>int</em> <strong>gnutls_x509_ext_export_subject_alt_names</strong> <em>(gnutls_subject_alt_names_t <var>sans</var>, gnutls_datum_t * <var>ext</var>)</em></dt>
28185 <dd><p><var>sans</var>: The alternative names structure
28186 </p>
28187 <p><var>ext</var>: The DER-encoded extension data; must be freed using <code>gnutls_free()</code> .
28188 </p>
28189 <p>This function will convert the provided alternative names structure to a
28190 DER-encoded SubjectAltName PKIX extension. The output data in  <code>ext</code> will be allocated using
28191 <code>gnutls_malloc()</code> .
28192 </p>
28193 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28194 </p>
28195 <p><strong>Since:</strong> 3.3.0
28196 </p></dd></dl>
28197
28198 <a name="gnutls_005fx509_005fext_005fexport_005fsubject_005fkey_005fid-1"></a>
28199 <h4 class="subheading">gnutls_x509_ext_export_subject_key_id</h4>
28200 <a name="gnutls_005fx509_005fext_005fexport_005fsubject_005fkey_005fid"></a><dl>
28201 <dt><a name="index-gnutls_005fx509_005fext_005fexport_005fsubject_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_ext_export_subject_key_id</strong> <em>(const gnutls_datum_t * <var>id</var>, gnutls_datum_t * <var>ext</var>)</em></dt>
28202 <dd><p><var>id</var>: The key identifier
28203 </p>
28204 <p><var>ext</var>: The DER-encoded extension data; must be freed using <code>gnutls_free()</code> .
28205 </p>
28206 <p>This function will convert the provided key identifier to a
28207 DER-encoded PKIX SubjectKeyIdentifier extension.
28208 The output data in  <code>ext</code> will be allocated using
28209 <code>gnutls_malloc()</code> .
28210 </p>
28211 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28212 </p>
28213 <p><strong>Since:</strong> 3.3.0
28214 </p></dd></dl>
28215
28216 <a name="gnutls_005fx509_005fext_005fimport_005faia-1"></a>
28217 <h4 class="subheading">gnutls_x509_ext_import_aia</h4>
28218 <a name="gnutls_005fx509_005fext_005fimport_005faia"></a><dl>
28219 <dt><a name="index-gnutls_005fx509_005fext_005fimport_005faia"></a>Function: <em>int</em> <strong>gnutls_x509_ext_import_aia</strong> <em>(const gnutls_datum_t * <var>ext</var>, gnutls_x509_aia_t <var>aia</var>, unsigned int <var>flags</var>)</em></dt>
28220 <dd><p><var>ext</var>: The DER-encoded extension data
28221 </p>
28222 <p><var>aia</var>: The authority info access structure
28223 </p>
28224 <p><var>flags</var>: should be zero
28225 </p>
28226 <p>This function extracts the Authority Information Access (AIA)
28227 extension from the provided DER-encoded data; see RFC 5280 section 4.2.2.1
28228 for more information on the extension.  The
28229 AIA extension holds a sequence of AccessDescription (AD) data.
28230 </p>
28231 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28232 </p>
28233 <p><strong>Since:</strong> 3.3.0
28234 </p></dd></dl>
28235
28236 <a name="gnutls_005fx509_005fext_005fimport_005fauthority_005fkey_005fid-1"></a>
28237 <h4 class="subheading">gnutls_x509_ext_import_authority_key_id</h4>
28238 <a name="gnutls_005fx509_005fext_005fimport_005fauthority_005fkey_005fid"></a><dl>
28239 <dt><a name="index-gnutls_005fx509_005fext_005fimport_005fauthority_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_ext_import_authority_key_id</strong> <em>(const gnutls_datum_t * <var>ext</var>, gnutls_x509_aki_t <var>aki</var>, unsigned int <var>flags</var>)</em></dt>
28240 <dd><p><var>ext</var>: a DER encoded extension
28241 </p>
28242 <p><var>aki</var>: An initialized authority key identifier structure
28243 </p>
28244 <p><var>flags</var>: should be zero
28245 </p>
28246 <p>This function will return the subject key ID stored in the provided
28247 AuthorityKeyIdentifier extension.
28248 </p>
28249 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
28250 if the extension is not present, otherwise a negative error value.
28251 </p>
28252 <p><strong>Since:</strong> 3.3.0
28253 </p></dd></dl>
28254
28255 <a name="gnutls_005fx509_005fext_005fimport_005fbasic_005fconstraints-1"></a>
28256 <h4 class="subheading">gnutls_x509_ext_import_basic_constraints</h4>
28257 <a name="gnutls_005fx509_005fext_005fimport_005fbasic_005fconstraints"></a><dl>
28258 <dt><a name="index-gnutls_005fx509_005fext_005fimport_005fbasic_005fconstraints"></a>Function: <em>int</em> <strong>gnutls_x509_ext_import_basic_constraints</strong> <em>(const gnutls_datum_t * <var>ext</var>, unsigned int * <var>ca</var>, int * <var>pathlen</var>)</em></dt>
28259 <dd><p><var>ext</var>: the DER encoded extension data
28260 </p>
28261 <p><var>ca</var>: will be non zero if the CA status is true
28262 </p>
28263 <p><var>pathlen</var>: the path length constraint; will be set to -1 for no limit
28264 </p>
28265 <p>This function will return the CA status and path length constraint
28266 as written in the PKIX extension 2.5.29.19.
28267 </p>
28268 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28269 negative error value.
28270 </p>
28271 <p><strong>Since:</strong> 3.3.0
28272 </p></dd></dl>
28273
28274 <a name="gnutls_005fx509_005fext_005fimport_005fcrl_005fdist_005fpoints-1"></a>
28275 <h4 class="subheading">gnutls_x509_ext_import_crl_dist_points</h4>
28276 <a name="gnutls_005fx509_005fext_005fimport_005fcrl_005fdist_005fpoints"></a><dl>
28277 <dt><a name="index-gnutls_005fx509_005fext_005fimport_005fcrl_005fdist_005fpoints"></a>Function: <em>int</em> <strong>gnutls_x509_ext_import_crl_dist_points</strong> <em>(const gnutls_datum_t * <var>ext</var>, gnutls_x509_crl_dist_points_t <var>cdp</var>, unsigned int <var>flags</var>)</em></dt>
28278 <dd><p><var>ext</var>: the DER encoded extension data
28279 </p>
28280 <p><var>cdp</var>: A pointer to an initialized CRL distribution points structure.
28281 </p>
28282 <p><var>flags</var>: should be zero
28283 </p>
28284 <p>This function will extract the CRL distribution points extension (2.5.29.31)
28285 and store it into the provided structure.
28286 </p>
28287 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28288 </p>
28289 <p><strong>Since:</strong> 3.3.0
28290 </p></dd></dl>
28291
28292 <a name="gnutls_005fx509_005fext_005fimport_005fkey_005fpurposes-1"></a>
28293 <h4 class="subheading">gnutls_x509_ext_import_key_purposes</h4>
28294 <a name="gnutls_005fx509_005fext_005fimport_005fkey_005fpurposes"></a><dl>
28295 <dt><a name="index-gnutls_005fx509_005fext_005fimport_005fkey_005fpurposes"></a>Function: <em>int</em> <strong>gnutls_x509_ext_import_key_purposes</strong> <em>(const gnutls_datum_t * <var>ext</var>, gnutls_x509_key_purposes_t <var>p</var>, unsigned int <var>flags</var>)</em></dt>
28296 <dd><p><var>ext</var>: The DER-encoded extension data
28297 </p>
28298 <p><var>p</var>: The key purposes structure
28299 </p>
28300 <p><var>flags</var>: should be zero
28301 </p>
28302 <p>This function will extract the key purposes in the provided DER-encoded
28303 ExtKeyUsageSyntax PKIX extension, to a <code>gnutls_x509_key_purposes_t</code>  structure.
28304 The structure must be initialized.
28305 </p>
28306 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28307 </p>
28308 <p><strong>Since:</strong> 3.3.0
28309 </p></dd></dl>
28310
28311 <a name="gnutls_005fx509_005fext_005fimport_005fkey_005fusage-1"></a>
28312 <h4 class="subheading">gnutls_x509_ext_import_key_usage</h4>
28313 <a name="gnutls_005fx509_005fext_005fimport_005fkey_005fusage"></a><dl>
28314 <dt><a name="index-gnutls_005fx509_005fext_005fimport_005fkey_005fusage"></a>Function: <em>int</em> <strong>gnutls_x509_ext_import_key_usage</strong> <em>(const gnutls_datum_t * <var>ext</var>, unsigned int * <var>key_usage</var>)</em></dt>
28315 <dd><p><var>ext</var>: the DER encoded extension data
28316 </p>
28317 <p><var>key_usage</var>: where the key usage bits will be stored
28318 </p>
28319 <p>This function will return certificate&rsquo;s key usage, by reading the DER
28320 data of the keyUsage X.509 extension (2.5.29.15). The key usage value will ORed
28321 values of the: <code>GNUTLS_KEY_DIGITAL_SIGNATURE</code> ,
28322 <code>GNUTLS_KEY_NON_REPUDIATION</code> , <code>GNUTLS_KEY_KEY_ENCIPHERMENT</code> ,
28323 <code>GNUTLS_KEY_DATA_ENCIPHERMENT</code> , <code>GNUTLS_KEY_KEY_AGREEMENT</code> ,
28324 <code>GNUTLS_KEY_KEY_CERT_SIGN</code> , <code>GNUTLS_KEY_CRL_SIGN</code> ,
28325 <code>GNUTLS_KEY_ENCIPHER_ONLY</code> , <code>GNUTLS_KEY_DECIPHER_ONLY</code> .
28326 </p>
28327 <p><strong>Returns:</strong> the certificate key usage, or a negative error code in case of
28328 parsing error.  If the certificate does not contain the keyUsage
28329 extension <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be
28330 returned.
28331 </p>
28332 <p><strong>Since:</strong> 3.3.0
28333 </p></dd></dl>
28334
28335 <a name="gnutls_005fx509_005fext_005fimport_005fname_005fconstraints-1"></a>
28336 <h4 class="subheading">gnutls_x509_ext_import_name_constraints</h4>
28337 <a name="gnutls_005fx509_005fext_005fimport_005fname_005fconstraints"></a><dl>
28338 <dt><a name="index-gnutls_005fx509_005fext_005fimport_005fname_005fconstraints"></a>Function: <em>int</em> <strong>gnutls_x509_ext_import_name_constraints</strong> <em>(const gnutls_datum_t * <var>ext</var>, gnutls_x509_name_constraints_t <var>nc</var>, unsigned int <var>flags</var>)</em></dt>
28339 <dd><p><var>ext</var>: a DER encoded extension
28340 </p>
28341 <p><var>nc</var>: The nameconstraints intermediate structure
28342 </p>
28343 <p><var>flags</var>: zero or <code>GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND</code>
28344 </p>
28345 <p>This function will return an intermediate structure containing
28346 the name constraints of the provided NameConstraints extension. That
28347 structure can be used in combination with <code>gnutls_x509_name_constraints_check()</code>
28348 to verify whether a server&rsquo;s name is in accordance with the constraints.
28349 </p>
28350 <p>When the  <code>flags</code> is set to <code>GNUTLS_NAME_CONSTRAINTS_FLAG_APPEND</code> , then if
28351 the  <code>nc</code> structure is empty
28352 this function will behave identically as if the flag was not set.
28353 Otherwise if there are elements in the  <code>nc</code> structure then only the
28354 excluded constraints will be appended to the constraints.
28355 </p>
28356 <p>Note that  <code>nc</code> must be initialized prior to calling this function.
28357 </p>
28358 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
28359 if the extension is not present, otherwise a negative error value.
28360 </p>
28361 <p><strong>Since:</strong> 3.3.0
28362 </p></dd></dl>
28363
28364 <a name="gnutls_005fx509_005fext_005fimport_005fpolicies-1"></a>
28365 <h4 class="subheading">gnutls_x509_ext_import_policies</h4>
28366 <a name="gnutls_005fx509_005fext_005fimport_005fpolicies"></a><dl>
28367 <dt><a name="index-gnutls_005fx509_005fext_005fimport_005fpolicies"></a>Function: <em>int</em> <strong>gnutls_x509_ext_import_policies</strong> <em>(const gnutls_datum_t * <var>ext</var>, gnutls_x509_policies_t <var>policies</var>, unsigned int <var>flags</var>)</em></dt>
28368 <dd><p><var>ext</var>: the DER encoded extension data
28369 </p>
28370 <p><var>policies</var>: A pointer to an initialized policies structures.
28371 </p>
28372 <p><var>flags</var>: should be zero
28373 </p>
28374 <p>This function will extract the certificate policy extension (2.5.29.32)
28375 and store it the provided structure.
28376 </p>
28377 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28378 </p>
28379 <p><strong>Since:</strong> 3.3.0
28380 </p></dd></dl>
28381
28382 <a name="gnutls_005fx509_005fext_005fimport_005fprivate_005fkey_005fusage_005fperiod-1"></a>
28383 <h4 class="subheading">gnutls_x509_ext_import_private_key_usage_period</h4>
28384 <a name="gnutls_005fx509_005fext_005fimport_005fprivate_005fkey_005fusage_005fperiod"></a><dl>
28385 <dt><a name="index-gnutls_005fx509_005fext_005fimport_005fprivate_005fkey_005fusage_005fperiod"></a>Function: <em>int</em> <strong>gnutls_x509_ext_import_private_key_usage_period</strong> <em>(const gnutls_datum_t * <var>ext</var>, time_t * <var>activation</var>, time_t * <var>expiration</var>)</em></dt>
28386 <dd><p><var>ext</var>: the DER encoded extension data
28387 </p>
28388 <p><var>activation</var>: Will hold the activation time
28389 </p>
28390 <p><var>expiration</var>: Will hold the expiration time
28391 </p>
28392 <p>This function will return the expiration and activation
28393 times of the private key as written in the
28394 PKIX extension 2.5.29.16.
28395 </p>
28396 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28397 negative error value.
28398 </p>
28399 <p><strong>Since:</strong> 3.3.0
28400 </p></dd></dl>
28401
28402 <a name="gnutls_005fx509_005fext_005fimport_005fproxy-1"></a>
28403 <h4 class="subheading">gnutls_x509_ext_import_proxy</h4>
28404 <a name="gnutls_005fx509_005fext_005fimport_005fproxy"></a><dl>
28405 <dt><a name="index-gnutls_005fx509_005fext_005fimport_005fproxy"></a>Function: <em>int</em> <strong>gnutls_x509_ext_import_proxy</strong> <em>(const gnutls_datum_t * <var>ext</var>, int * <var>pathlen</var>, char ** <var>policyLanguage</var>, char ** <var>policy</var>, size_t * <var>sizeof_policy</var>)</em></dt>
28406 <dd><p><var>ext</var>: the DER encoded extension data
28407 </p>
28408 <p><var>pathlen</var>: pointer to output integer indicating path length (may be
28409 NULL), non-negative error codes indicate a present pCPathLenConstraint
28410 field and the actual value, -1 indicate that the field is absent.
28411 </p>
28412 <p><var>policyLanguage</var>: output variable with OID of policy language
28413 </p>
28414 <p><var>policy</var>: output variable with policy data
28415 </p>
28416 <p><var>sizeof_policy</var>: output variable size of policy data
28417 </p>
28418 <p>This function will return the information from a proxy certificate
28419 extension. It reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14).
28420 The  <code>policyLanguage</code> and  <code>policy</code> values must be deinitialized using <code>gnutls_free()</code>  after use.
28421 </p>
28422 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28423 negative error value.
28424 </p>
28425 <p><strong>Since:</strong> 3.3.0
28426 </p></dd></dl>
28427
28428 <a name="gnutls_005fx509_005fext_005fimport_005fsubject_005falt_005fnames-1"></a>
28429 <h4 class="subheading">gnutls_x509_ext_import_subject_alt_names</h4>
28430 <a name="gnutls_005fx509_005fext_005fimport_005fsubject_005falt_005fnames"></a><dl>
28431 <dt><a name="index-gnutls_005fx509_005fext_005fimport_005fsubject_005falt_005fnames"></a>Function: <em>int</em> <strong>gnutls_x509_ext_import_subject_alt_names</strong> <em>(const gnutls_datum_t * <var>ext</var>, gnutls_subject_alt_names_t <var>sans</var>, unsigned int <var>flags</var>)</em></dt>
28432 <dd><p><var>ext</var>: The DER-encoded extension data
28433 </p>
28434 <p><var>sans</var>: The alternative names structure
28435 </p>
28436 <p><var>flags</var>: should be zero
28437 </p>
28438 <p>This function will export the alternative names in the provided DER-encoded
28439 SubjectAltName PKIX extension, to a <code>gnutls_subject_alt_names_t</code>  structure. The structure
28440 must have been initialized.
28441 </p>
28442 <p>This function will succeed even if there no subject alternative names
28443 in the structure.
28444 </p>
28445 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28446 </p>
28447 <p><strong>Since:</strong> 3.3.0
28448 </p></dd></dl>
28449
28450 <a name="gnutls_005fx509_005fext_005fimport_005fsubject_005fkey_005fid-1"></a>
28451 <h4 class="subheading">gnutls_x509_ext_import_subject_key_id</h4>
28452 <a name="gnutls_005fx509_005fext_005fimport_005fsubject_005fkey_005fid"></a><dl>
28453 <dt><a name="index-gnutls_005fx509_005fext_005fimport_005fsubject_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_ext_import_subject_key_id</strong> <em>(const gnutls_datum_t * <var>ext</var>, gnutls_datum_t * <var>id</var>)</em></dt>
28454 <dd><p><var>ext</var>: a DER encoded extension
28455 </p>
28456 <p><var>id</var>: will contain the subject key ID
28457 </p>
28458 <p>This function will return the subject key ID stored in the provided
28459 SubjectKeyIdentifier extension. The ID will be allocated using
28460 <code>gnutls_malloc()</code> .
28461 </p>
28462 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
28463 if the extension is not present, otherwise a negative error value.
28464 </p>
28465 <p><strong>Since:</strong> 3.3.0
28466 </p></dd></dl>
28467
28468 <a name="gnutls_005fx509_005fext_005fprint-1"></a>
28469 <h4 class="subheading">gnutls_x509_ext_print</h4>
28470 <a name="gnutls_005fx509_005fext_005fprint"></a><dl>
28471 <dt><a name="index-gnutls_005fx509_005fext_005fprint"></a>Function: <em>int</em> <strong>gnutls_x509_ext_print</strong> <em>(gnutls_x509_ext_st * <var>exts</var>, unsigned int <var>exts_size</var>, gnutls_certificate_print_formats_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
28472 <dd><p><var>exts</var>: The structures to be printed
28473 </p>
28474 <p><var>exts_size</var>: the number of available structures
28475 </p>
28476 <p><var>format</var>: Indicate the format to use
28477 </p>
28478 <p><var>out</var>: Newly allocated datum with null terminated string.
28479 </p>
28480 <p>This function will pretty print X.509 certificate extensions,
28481 suitable for display to a human.
28482 </p>
28483 <p>The output  <code>out</code> needs to be deallocated using <code>gnutls_free()</code> .
28484 </p>
28485 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28486 negative error value.
28487 </p></dd></dl>
28488
28489 <a name="gnutls_005fx509_005fkey_005fpurpose_005fdeinit-1"></a>
28490 <h4 class="subheading">gnutls_x509_key_purpose_deinit</h4>
28491 <a name="gnutls_005fx509_005fkey_005fpurpose_005fdeinit"></a><dl>
28492 <dt><a name="index-gnutls_005fx509_005fkey_005fpurpose_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_key_purpose_deinit</strong> <em>(gnutls_x509_key_purposes_t <var>p</var>)</em></dt>
28493 <dd><p><var>p</var>: The key purposes structure
28494 </p>
28495 <p>This function will deinitialize an alternative names structure.
28496 </p>
28497 <p><strong>Since:</strong> 3.3.0
28498 </p></dd></dl>
28499
28500 <a name="gnutls_005fx509_005fkey_005fpurpose_005fget-1"></a>
28501 <h4 class="subheading">gnutls_x509_key_purpose_get</h4>
28502 <a name="gnutls_005fx509_005fkey_005fpurpose_005fget"></a><dl>
28503 <dt><a name="index-gnutls_005fx509_005fkey_005fpurpose_005fget"></a>Function: <em>int</em> <strong>gnutls_x509_key_purpose_get</strong> <em>(gnutls_x509_key_purposes_t <var>p</var>, unsigned <var>idx</var>, gnutls_datum_t * <var>oid</var>)</em></dt>
28504 <dd><p><var>p</var>: The key purposes structure
28505 </p>
28506 <p><var>idx</var>: The index of the key purpose to retrieve
28507 </p>
28508 <p><var>oid</var>: Will hold the object identifier of the key purpose (to be treated as constant)
28509 </p>
28510 <p>This function will retrieve the specified by the index key purpose in the
28511 purposes structure. The object identifier will be a null terminated string.
28512 </p>
28513 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
28514 if the index is out of bounds, otherwise a negative error value.
28515 </p>
28516 <p><strong>Since:</strong> 3.3.0
28517 </p></dd></dl>
28518
28519 <a name="gnutls_005fx509_005fkey_005fpurpose_005finit-1"></a>
28520 <h4 class="subheading">gnutls_x509_key_purpose_init</h4>
28521 <a name="gnutls_005fx509_005fkey_005fpurpose_005finit"></a><dl>
28522 <dt><a name="index-gnutls_005fx509_005fkey_005fpurpose_005finit"></a>Function: <em>int</em> <strong>gnutls_x509_key_purpose_init</strong> <em>(gnutls_x509_key_purposes_t * <var>p</var>)</em></dt>
28523 <dd><p><var>p</var>: The key purposes structure
28524 </p>
28525 <p>This function will initialize an alternative names structure.
28526 </p>
28527 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28528 </p>
28529 <p><strong>Since:</strong> 3.3.0
28530 </p></dd></dl>
28531
28532 <a name="gnutls_005fx509_005fkey_005fpurpose_005fset-1"></a>
28533 <h4 class="subheading">gnutls_x509_key_purpose_set</h4>
28534 <a name="gnutls_005fx509_005fkey_005fpurpose_005fset"></a><dl>
28535 <dt><a name="index-gnutls_005fx509_005fkey_005fpurpose_005fset"></a>Function: <em>int</em> <strong>gnutls_x509_key_purpose_set</strong> <em>(gnutls_x509_key_purposes_t <var>p</var>, const char * <var>oid</var>)</em></dt>
28536 <dd><p><var>p</var>: The key purposes structure
28537 </p>
28538 <p><var>oid</var>: The object identifier of the key purpose
28539 </p>
28540 <p>This function will store the specified key purpose in the
28541 purposes structure.
28542 </p>
28543 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0), otherwise a negative error value.
28544 </p>
28545 <p><strong>Since:</strong> 3.3.0
28546 </p></dd></dl>
28547
28548 <a name="gnutls_005fx509_005fname_005fconstraints_005fadd_005fexcluded-1"></a>
28549 <h4 class="subheading">gnutls_x509_name_constraints_add_excluded</h4>
28550 <a name="gnutls_005fx509_005fname_005fconstraints_005fadd_005fexcluded"></a><dl>
28551 <dt><a name="index-gnutls_005fx509_005fname_005fconstraints_005fadd_005fexcluded"></a>Function: <em>int</em> <strong>gnutls_x509_name_constraints_add_excluded</strong> <em>(gnutls_x509_name_constraints_t <var>nc</var>, gnutls_x509_subject_alt_name_t <var>type</var>, const gnutls_datum_t * <var>name</var>)</em></dt>
28552 <dd><p><var>nc</var>: The nameconstraints structure
28553 </p>
28554 <p><var>type</var>: The type of the constraints
28555 </p>
28556 <p><var>name</var>: The data of the constraints
28557 </p>
28558 <p>This function will add a name constraint to the list of excluded
28559 constraints. The constraints  <code>type</code> can be any of the following types:
28560 <code>GNUTLS_SAN_DNSNAME</code> , <code>GNUTLS_SAN_RFC822NAME</code> , <code>GNUTLS_SAN_DN</code> ,
28561 <code>GNUTLS_SAN_URI</code> , <code>GNUTLS_SAN_IPADDRESS</code> . For the latter, an IP address
28562 in network byte order is expected, followed by its network mask (which is
28563 4 bytes in IPv4 or 16-bytes in IPv6).
28564 </p>
28565 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28566 </p>
28567 <p><strong>Since:</strong> 3.3.0
28568 </p></dd></dl>
28569
28570 <a name="gnutls_005fx509_005fname_005fconstraints_005fadd_005fpermitted-1"></a>
28571 <h4 class="subheading">gnutls_x509_name_constraints_add_permitted</h4>
28572 <a name="gnutls_005fx509_005fname_005fconstraints_005fadd_005fpermitted"></a><dl>
28573 <dt><a name="index-gnutls_005fx509_005fname_005fconstraints_005fadd_005fpermitted"></a>Function: <em>int</em> <strong>gnutls_x509_name_constraints_add_permitted</strong> <em>(gnutls_x509_name_constraints_t <var>nc</var>, gnutls_x509_subject_alt_name_t <var>type</var>, const gnutls_datum_t * <var>name</var>)</em></dt>
28574 <dd><p><var>nc</var>: The nameconstraints structure
28575 </p>
28576 <p><var>type</var>: The type of the constraints
28577 </p>
28578 <p><var>name</var>: The data of the constraints
28579 </p>
28580 <p>This function will add a name constraint to the list of permitted
28581 constraints. The constraints  <code>type</code> can be any of the following types:
28582 <code>GNUTLS_SAN_DNSNAME</code> , <code>GNUTLS_SAN_RFC822NAME</code> , <code>GNUTLS_SAN_DN</code> ,
28583 <code>GNUTLS_SAN_URI</code> , <code>GNUTLS_SAN_IPADDRESS</code> . For the latter, an IP address
28584 in network byte order is expected, followed by its network mask.
28585 </p>
28586 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28587 </p>
28588 <p><strong>Since:</strong> 3.3.0
28589 </p></dd></dl>
28590
28591 <a name="gnutls_005fx509_005fname_005fconstraints_005fcheck-1"></a>
28592 <h4 class="subheading">gnutls_x509_name_constraints_check</h4>
28593 <a name="gnutls_005fx509_005fname_005fconstraints_005fcheck"></a><dl>
28594 <dt><a name="index-gnutls_005fx509_005fname_005fconstraints_005fcheck"></a>Function: <em>unsigned</em> <strong>gnutls_x509_name_constraints_check</strong> <em>(gnutls_x509_name_constraints_t <var>nc</var>, gnutls_x509_subject_alt_name_t <var>type</var>, const gnutls_datum_t * <var>name</var>)</em></dt>
28595 <dd><p><var>nc</var>: the extracted name constraints structure
28596 </p>
28597 <p><var>type</var>: the type of the constraint to check (of type gnutls_x509_subject_alt_name_t)
28598 </p>
28599 <p><var>name</var>: the name to be checked
28600 </p>
28601 <p>This function will check the provided name against the constraints in
28602  <code>nc</code> using the RFC5280 rules. Currently this function is limited to DNS
28603 names and emails (of type <code>GNUTLS_SAN_DNSNAME</code>  and <code>GNUTLS_SAN_RFC822NAME</code> ).
28604 </p>
28605 <p><strong>Returns:</strong> zero if the provided name is not acceptable, and non-zero otherwise.
28606 </p>
28607 <p><strong>Since:</strong> 3.3.0
28608 </p></dd></dl>
28609
28610 <a name="gnutls_005fx509_005fname_005fconstraints_005fcheck_005fcrt-1"></a>
28611 <h4 class="subheading">gnutls_x509_name_constraints_check_crt</h4>
28612 <a name="gnutls_005fx509_005fname_005fconstraints_005fcheck_005fcrt"></a><dl>
28613 <dt><a name="index-gnutls_005fx509_005fname_005fconstraints_005fcheck_005fcrt"></a>Function: <em>unsigned</em> <strong>gnutls_x509_name_constraints_check_crt</strong> <em>(gnutls_x509_name_constraints_t <var>nc</var>, gnutls_x509_subject_alt_name_t <var>type</var>, gnutls_x509_crt_t <var>cert</var>)</em></dt>
28614 <dd><p><var>nc</var>: the extracted name constraints structure
28615 </p>
28616 <p><var>type</var>: the type of the constraint to check (of type gnutls_x509_subject_alt_name_t)
28617 </p>
28618 <p><var>cert</var>: the certificate to be checked
28619 </p>
28620 <p>This function will check the provided certificate names against the constraints in
28621  <code>nc</code> using the RFC5280 rules. It will traverse all the certificate&rsquo;s names and
28622 alternative names.
28623 </p>
28624 <p>Currently this function is limited to DNS
28625 names and emails (of type <code>GNUTLS_SAN_DNSNAME</code>  and <code>GNUTLS_SAN_RFC822NAME</code> ).
28626 </p>
28627 <p><strong>Returns:</strong> zero if the provided name is not acceptable, and non-zero otherwise.
28628 </p>
28629 <p><strong>Since:</strong> 3.3.0
28630 </p></dd></dl>
28631
28632 <a name="gnutls_005fx509_005fname_005fconstraints_005fdeinit-1"></a>
28633 <h4 class="subheading">gnutls_x509_name_constraints_deinit</h4>
28634 <a name="gnutls_005fx509_005fname_005fconstraints_005fdeinit"></a><dl>
28635 <dt><a name="index-gnutls_005fx509_005fname_005fconstraints_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_name_constraints_deinit</strong> <em>(gnutls_x509_name_constraints_t <var>nc</var>)</em></dt>
28636 <dd><p><var>nc</var>: The nameconstraints structure
28637 </p>
28638 <p>This function will deinitialize a name constraints structure.
28639 </p>
28640 <p><strong>Since:</strong> 3.3.0
28641 </p></dd></dl>
28642
28643 <a name="gnutls_005fx509_005fname_005fconstraints_005fget_005fexcluded-1"></a>
28644 <h4 class="subheading">gnutls_x509_name_constraints_get_excluded</h4>
28645 <a name="gnutls_005fx509_005fname_005fconstraints_005fget_005fexcluded"></a><dl>
28646 <dt><a name="index-gnutls_005fx509_005fname_005fconstraints_005fget_005fexcluded"></a>Function: <em>int</em> <strong>gnutls_x509_name_constraints_get_excluded</strong> <em>(gnutls_x509_name_constraints_t <var>nc</var>, unsigned <var>idx</var>, unsigned * <var>type</var>, gnutls_datum_t * <var>name</var>)</em></dt>
28647 <dd><p><var>nc</var>: the extracted name constraints structure
28648 </p>
28649 <p><var>idx</var>: the index of the constraint
28650 </p>
28651 <p><var>type</var>: the type of the constraint (of type gnutls_x509_subject_alt_name_t)
28652 </p>
28653 <p><var>name</var>: the name in the constraint (of the specific type)
28654 </p>
28655 <p>This function will return an intermediate structure containing
28656 the name constraints of the provided CA certificate. That
28657 structure can be used in combination with <code>gnutls_x509_name_constraints_check()</code>
28658 to verify whether a server&rsquo;s name is in accordance with the constraints.
28659 </p>
28660 <p>The name should be treated as constant and valid for the lifetime of  <code>nc</code> .
28661 </p>
28662 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
28663 if the extension is not present, otherwise a negative error value.
28664 </p>
28665 <p><strong>Since:</strong> 3.3.0
28666 </p></dd></dl>
28667
28668 <a name="gnutls_005fx509_005fname_005fconstraints_005fget_005fpermitted-1"></a>
28669 <h4 class="subheading">gnutls_x509_name_constraints_get_permitted</h4>
28670 <a name="gnutls_005fx509_005fname_005fconstraints_005fget_005fpermitted"></a><dl>
28671 <dt><a name="index-gnutls_005fx509_005fname_005fconstraints_005fget_005fpermitted"></a>Function: <em>int</em> <strong>gnutls_x509_name_constraints_get_permitted</strong> <em>(gnutls_x509_name_constraints_t <var>nc</var>, unsigned <var>idx</var>, unsigned * <var>type</var>, gnutls_datum_t * <var>name</var>)</em></dt>
28672 <dd><p><var>nc</var>: the extracted name constraints structure
28673 </p>
28674 <p><var>idx</var>: the index of the constraint
28675 </p>
28676 <p><var>type</var>: the type of the constraint (of type gnutls_x509_subject_alt_name_t)
28677 </p>
28678 <p><var>name</var>: the name in the constraint (of the specific type)
28679 </p>
28680 <p>This function will return an intermediate structure containing
28681 the name constraints of the provided CA certificate. That
28682 structure can be used in combination with <code>gnutls_x509_name_constraints_check()</code>
28683 to verify whether a server&rsquo;s name is in accordance with the constraints.
28684 </p>
28685 <p>The name should be treated as constant and valid for the lifetime of  <code>nc</code> .
28686 </p>
28687 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
28688 if the extension is not present, otherwise a negative error value.
28689 </p>
28690 <p><strong>Since:</strong> 3.3.0
28691 </p></dd></dl>
28692
28693 <a name="gnutls_005fx509_005fname_005fconstraints_005finit-1"></a>
28694 <h4 class="subheading">gnutls_x509_name_constraints_init</h4>
28695 <a name="gnutls_005fx509_005fname_005fconstraints_005finit"></a><dl>
28696 <dt><a name="index-gnutls_005fx509_005fname_005fconstraints_005finit"></a>Function: <em>int</em> <strong>gnutls_x509_name_constraints_init</strong> <em>(gnutls_x509_name_constraints_t * <var>nc</var>)</em></dt>
28697 <dd><p><var>nc</var>: The nameconstraints structure
28698 </p>
28699 <p>This function will initialize a name constraints structure.
28700 </p>
28701 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28702 </p>
28703 <p><strong>Since:</strong> 3.3.0
28704 </p></dd></dl>
28705
28706 <a name="gnutls_005fx509_005fothername_005fto_005fvirtual-1"></a>
28707 <h4 class="subheading">gnutls_x509_othername_to_virtual</h4>
28708 <a name="gnutls_005fx509_005fothername_005fto_005fvirtual"></a><dl>
28709 <dt><a name="index-gnutls_005fx509_005fothername_005fto_005fvirtual"></a>Function: <em>int</em> <strong>gnutls_x509_othername_to_virtual</strong> <em>(const char * <var>oid</var>, const gnutls_datum_t * <var>othername</var>, unsigned int * <var>virt_type</var>, gnutls_datum_t * <var>virt</var>)</em></dt>
28710 <dd><p><var>oid</var>: The othername object identifier
28711 </p>
28712 <p><var>othername</var>: &ndash; undescribed &ndash;
28713 </p>
28714 <p><var>virt_type</var>: GNUTLS_SAN_OTHERNAME_XXX
28715 </p>
28716 <p><var>virt</var>: allocated printable data
28717 </p>
28718 <p>This function will parse and convert the othername data to a virtual
28719 type supported by gnutls.
28720 </p>
28721 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28722 </p>
28723 <p><strong>Since:</strong> 3.3.8
28724 </p></dd></dl>
28725
28726 <a name="gnutls_005fx509_005fpolicies_005fdeinit-1"></a>
28727 <h4 class="subheading">gnutls_x509_policies_deinit</h4>
28728 <a name="gnutls_005fx509_005fpolicies_005fdeinit"></a><dl>
28729 <dt><a name="index-gnutls_005fx509_005fpolicies_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_policies_deinit</strong> <em>(gnutls_x509_policies_t <var>policies</var>)</em></dt>
28730 <dd><p><var>policies</var>: The authority key identifier structure
28731 </p>
28732 <p>This function will deinitialize an authority key identifier structure.
28733 </p>
28734 <p><strong>Since:</strong> 3.3.0
28735 </p></dd></dl>
28736
28737 <a name="gnutls_005fx509_005fpolicies_005fget-1"></a>
28738 <h4 class="subheading">gnutls_x509_policies_get</h4>
28739 <a name="gnutls_005fx509_005fpolicies_005fget"></a><dl>
28740 <dt><a name="index-gnutls_005fx509_005fpolicies_005fget"></a>Function: <em>int</em> <strong>gnutls_x509_policies_get</strong> <em>(gnutls_x509_policies_t <var>policies</var>, unsigned int <var>seq</var>, struct gnutls_x509_policy_st * <var>policy</var>)</em></dt>
28741 <dd><p><var>policies</var>: The policies structure
28742 </p>
28743 <p><var>seq</var>: The index of the name to get
28744 </p>
28745 <p><var>policy</var>: Will hold the policy
28746 </p>
28747 <p>This function will return a specific policy as stored in
28748 the  <code>policies</code> structure. The returned values should be treated as constant
28749 and valid for the lifetime of  <code>policies</code> .
28750 </p>
28751 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
28752 if the index is out of bounds, otherwise a negative error value.
28753 </p>
28754 <p><strong>Since:</strong> 3.3.0
28755 </p></dd></dl>
28756
28757 <a name="gnutls_005fx509_005fpolicies_005finit-1"></a>
28758 <h4 class="subheading">gnutls_x509_policies_init</h4>
28759 <a name="gnutls_005fx509_005fpolicies_005finit"></a><dl>
28760 <dt><a name="index-gnutls_005fx509_005fpolicies_005finit"></a>Function: <em>int</em> <strong>gnutls_x509_policies_init</strong> <em>(gnutls_x509_policies_t * <var>policies</var>)</em></dt>
28761 <dd><p><var>policies</var>: The authority key ID structure
28762 </p>
28763 <p>This function will initialize an authority key ID structure.
28764 </p>
28765 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a negative error value.
28766 </p>
28767 <p><strong>Since:</strong> 3.3.0
28768 </p></dd></dl>
28769
28770 <a name="gnutls_005fx509_005fpolicies_005fset-1"></a>
28771 <h4 class="subheading">gnutls_x509_policies_set</h4>
28772 <a name="gnutls_005fx509_005fpolicies_005fset"></a><dl>
28773 <dt><a name="index-gnutls_005fx509_005fpolicies_005fset"></a>Function: <em>int</em> <strong>gnutls_x509_policies_set</strong> <em>(gnutls_x509_policies_t <var>policies</var>, const struct gnutls_x509_policy_st * <var>policy</var>)</em></dt>
28774 <dd><p><var>policies</var>: An initialized policies structure
28775 </p>
28776 <p><var>policy</var>: Contains the policy to set
28777 </p>
28778 <p>This function will store the specified policy in
28779 the provided  <code>policies</code> structure.
28780 </p>
28781 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0), otherwise a negative error value.
28782 </p>
28783 <p><strong>Since:</strong> 3.3.0
28784 </p></dd></dl>
28785
28786 <a name="gnutls_005fx509_005fpolicy_005frelease-1"></a>
28787 <h4 class="subheading">gnutls_x509_policy_release</h4>
28788 <a name="gnutls_005fx509_005fpolicy_005frelease"></a><dl>
28789 <dt><a name="index-gnutls_005fx509_005fpolicy_005frelease"></a>Function: <em>void</em> <strong>gnutls_x509_policy_release</strong> <em>(struct gnutls_x509_policy_st * <var>policy</var>)</em></dt>
28790 <dd><p><var>policy</var>: a certificate policy
28791 </p>
28792 <p>This function will deinitialize all memory associated with the provided
28793  <code>policy</code> . The policy is allocated using <code>gnutls_x509_crt_get_policy()</code> .
28794 </p>
28795 <p><strong>Since:</strong> 3.1.5
28796 </p></dd></dl>
28797
28798 <a name="gnutls_005fx509_005fprivkey_005fcpy-1"></a>
28799 <h4 class="subheading">gnutls_x509_privkey_cpy</h4>
28800 <a name="gnutls_005fx509_005fprivkey_005fcpy"></a><dl>
28801 <dt><a name="index-gnutls_005fx509_005fprivkey_005fcpy"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_cpy</strong> <em>(gnutls_x509_privkey_t <var>dst</var>, gnutls_x509_privkey_t <var>src</var>)</em></dt>
28802 <dd><p><var>dst</var>: The destination key, which should be initialized.
28803 </p>
28804 <p><var>src</var>: The source key
28805 </p>
28806 <p>This function will copy a private key from source to destination
28807 key. Destination has to be initialized.
28808 </p>
28809 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28810 negative error value.
28811 </p></dd></dl>
28812
28813 <a name="gnutls_005fx509_005fprivkey_005fdeinit-1"></a>
28814 <h4 class="subheading">gnutls_x509_privkey_deinit</h4>
28815 <a name="gnutls_005fx509_005fprivkey_005fdeinit"></a><dl>
28816 <dt><a name="index-gnutls_005fx509_005fprivkey_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_privkey_deinit</strong> <em>(gnutls_x509_privkey_t <var>key</var>)</em></dt>
28817 <dd><p><var>key</var>: The structure to be deinitialized
28818 </p>
28819 <p>This function will deinitialize a private key structure.
28820 </p></dd></dl>
28821
28822 <a name="gnutls_005fx509_005fprivkey_005fexport-1"></a>
28823 <h4 class="subheading">gnutls_x509_privkey_export</h4>
28824 <a name="gnutls_005fx509_005fprivkey_005fexport"></a><dl>
28825 <dt><a name="index-gnutls_005fx509_005fprivkey_005fexport"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_export</strong> <em>(gnutls_x509_privkey_t <var>key</var>, gnutls_x509_crt_fmt_t <var>format</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
28826 <dd><p><var>key</var>: Holds the key
28827 </p>
28828 <p><var>format</var>: the format of output params. One of PEM or DER.
28829 </p>
28830 <p><var>output_data</var>: will contain a private key PEM or DER encoded
28831 </p>
28832 <p><var>output_data_size</var>: holds the size of output_data (and will be
28833 replaced by the actual size of parameters)
28834 </p>
28835 <p>This function will export the private key to a PKCS1 structure for
28836 RSA keys, or an integer sequence for DSA keys.  The DSA keys are in
28837 the same format with the parameters used by openssl.
28838 </p>
28839 <p>If the buffer provided is not long enough to hold the output, then
28840 * <code>output_data_size</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>
28841 will be returned.
28842 </p>
28843 <p>If the structure is PEM encoded, it will have a header
28844 of &quot;BEGIN RSA PRIVATE KEY&quot;.
28845 </p>
28846 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28847 negative error value.
28848 </p></dd></dl>
28849
28850 <a name="gnutls_005fx509_005fprivkey_005fexport2-1"></a>
28851 <h4 class="subheading">gnutls_x509_privkey_export2</h4>
28852 <a name="gnutls_005fx509_005fprivkey_005fexport2"></a><dl>
28853 <dt><a name="index-gnutls_005fx509_005fprivkey_005fexport2"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_export2</strong> <em>(gnutls_x509_privkey_t <var>key</var>, gnutls_x509_crt_fmt_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
28854 <dd><p><var>key</var>: Holds the key
28855 </p>
28856 <p><var>format</var>: the format of output params. One of PEM or DER.
28857 </p>
28858 <p><var>out</var>: will contain a private key PEM or DER encoded
28859 </p>
28860 <p>This function will export the private key to a PKCS1 structure for
28861 RSA keys, or an integer sequence for DSA keys.  The DSA keys are in
28862 the same format with the parameters used by openssl.
28863 </p>
28864 <p>The output buffer is allocated using <code>gnutls_malloc()</code> .
28865 </p>
28866 <p>If the structure is PEM encoded, it will have a header
28867 of &quot;BEGIN RSA PRIVATE KEY&quot;.
28868 </p>
28869 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28870 negative error value.
28871 </p>
28872 <p>Since 3.1.3
28873 </p></dd></dl>
28874
28875 <a name="gnutls_005fx509_005fprivkey_005fexport2_005fpkcs8-1"></a>
28876 <h4 class="subheading">gnutls_x509_privkey_export2_pkcs8</h4>
28877 <a name="gnutls_005fx509_005fprivkey_005fexport2_005fpkcs8"></a><dl>
28878 <dt><a name="index-gnutls_005fx509_005fprivkey_005fexport2_005fpkcs8"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_export2_pkcs8</strong> <em>(gnutls_x509_privkey_t <var>key</var>, gnutls_x509_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>, gnutls_datum_t * <var>out</var>)</em></dt>
28879 <dd><p><var>key</var>: Holds the key
28880 </p>
28881 <p><var>format</var>: the format of output params. One of PEM or DER.
28882 </p>
28883 <p><var>password</var>: the password that will be used to encrypt the key.
28884 </p>
28885 <p><var>flags</var>: an ORed sequence of gnutls_pkcs_encrypt_flags_t
28886 </p>
28887 <p><var>out</var>: will contain a private key PEM or DER encoded
28888 </p>
28889 <p>This function will export the private key to a PKCS8 structure.
28890 Both RSA and DSA keys can be exported. For DSA keys we use
28891 PKCS <code>11</code>  definitions. If the flags do not specify the encryption
28892 cipher, then the default 3DES (PBES2) will be used.
28893 </p>
28894 <p>The  <code>password</code> can be either ASCII or UTF-8 in the default PBES2
28895 encryption schemas, or ASCII for the PKCS12 schemas.
28896 </p>
28897 <p>The output buffer is allocated using <code>gnutls_malloc()</code> .
28898 </p>
28899 <p>If the structure is PEM encoded, it will have a header
28900 of &quot;BEGIN ENCRYPTED PRIVATE KEY&quot; or &quot;BEGIN PRIVATE KEY&quot; if
28901 encryption is not used.
28902 </p>
28903 <p><strong>Returns:</strong> In case of failure a negative error code will be
28904 returned, and 0 on success.
28905 </p>
28906 <p>Since 3.1.3
28907 </p></dd></dl>
28908
28909 <a name="gnutls_005fx509_005fprivkey_005fexport_005fdsa_005fraw-1"></a>
28910 <h4 class="subheading">gnutls_x509_privkey_export_dsa_raw</h4>
28911 <a name="gnutls_005fx509_005fprivkey_005fexport_005fdsa_005fraw"></a><dl>
28912 <dt><a name="index-gnutls_005fx509_005fprivkey_005fexport_005fdsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_export_dsa_raw</strong> <em>(gnutls_x509_privkey_t <var>key</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>g</var>, gnutls_datum_t * <var>y</var>, gnutls_datum_t * <var>x</var>)</em></dt>
28913 <dd><p><var>key</var>: a structure that holds the DSA parameters
28914 </p>
28915 <p><var>p</var>: will hold the p
28916 </p>
28917 <p><var>q</var>: will hold the q
28918 </p>
28919 <p><var>g</var>: will hold the g
28920 </p>
28921 <p><var>y</var>: will hold the y
28922 </p>
28923 <p><var>x</var>: will hold the x
28924 </p>
28925 <p>This function will export the DSA private key&rsquo;s parameters found
28926 in the given structure. The new parameters will be allocated using
28927 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
28928 </p>
28929 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28930 negative error value.
28931 </p></dd></dl>
28932
28933 <a name="gnutls_005fx509_005fprivkey_005fexport_005fecc_005fraw-1"></a>
28934 <h4 class="subheading">gnutls_x509_privkey_export_ecc_raw</h4>
28935 <a name="gnutls_005fx509_005fprivkey_005fexport_005fecc_005fraw"></a><dl>
28936 <dt><a name="index-gnutls_005fx509_005fprivkey_005fexport_005fecc_005fraw"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_export_ecc_raw</strong> <em>(gnutls_x509_privkey_t <var>key</var>, gnutls_ecc_curve_t * <var>curve</var>, gnutls_datum_t * <var>x</var>, gnutls_datum_t * <var>y</var>, gnutls_datum_t * <var>k</var>)</em></dt>
28937 <dd><p><var>key</var>: a structure that holds the rsa parameters
28938 </p>
28939 <p><var>curve</var>: will hold the curve
28940 </p>
28941 <p><var>x</var>: will hold the x coordinate
28942 </p>
28943 <p><var>y</var>: will hold the y coordinate
28944 </p>
28945 <p><var>k</var>: will hold the private key
28946 </p>
28947 <p>This function will export the ECC private key&rsquo;s parameters found
28948 in the given structure. The new parameters will be allocated using
28949 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
28950 </p>
28951 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
28952 negative error value.
28953 </p>
28954 <p><strong>Since:</strong> 3.0
28955 </p></dd></dl>
28956
28957 <a name="gnutls_005fx509_005fprivkey_005fexport_005fpkcs8-1"></a>
28958 <h4 class="subheading">gnutls_x509_privkey_export_pkcs8</h4>
28959 <a name="gnutls_005fx509_005fprivkey_005fexport_005fpkcs8"></a><dl>
28960 <dt><a name="index-gnutls_005fx509_005fprivkey_005fexport_005fpkcs8"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_export_pkcs8</strong> <em>(gnutls_x509_privkey_t <var>key</var>, gnutls_x509_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
28961 <dd><p><var>key</var>: Holds the key
28962 </p>
28963 <p><var>format</var>: the format of output params. One of PEM or DER.
28964 </p>
28965 <p><var>password</var>: the password that will be used to encrypt the key.
28966 </p>
28967 <p><var>flags</var>: an ORed sequence of gnutls_pkcs_encrypt_flags_t
28968 </p>
28969 <p><var>output_data</var>: will contain a private key PEM or DER encoded
28970 </p>
28971 <p><var>output_data_size</var>: holds the size of output_data (and will be
28972 replaced by the actual size of parameters)
28973 </p>
28974 <p>This function will export the private key to a PKCS8 structure.
28975 Both RSA and DSA keys can be exported. For DSA keys we use
28976 PKCS <code>11</code>  definitions. If the flags do not specify the encryption
28977 cipher, then the default 3DES (PBES2) will be used.
28978 </p>
28979 <p>The  <code>password</code> can be either ASCII or UTF-8 in the default PBES2
28980 encryption schemas, or ASCII for the PKCS12 schemas.
28981 </p>
28982 <p>If the buffer provided is not long enough to hold the output, then
28983 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
28984 be returned.
28985 </p>
28986 <p>If the structure is PEM encoded, it will have a header
28987 of &quot;BEGIN ENCRYPTED PRIVATE KEY&quot; or &quot;BEGIN PRIVATE KEY&quot; if
28988 encryption is not used.
28989 </p>
28990 <p><strong>Returns:</strong> In case of failure a negative error code will be
28991 returned, and 0 on success.
28992 </p></dd></dl>
28993
28994 <a name="gnutls_005fx509_005fprivkey_005fexport_005frsa_005fraw-1"></a>
28995 <h4 class="subheading">gnutls_x509_privkey_export_rsa_raw</h4>
28996 <a name="gnutls_005fx509_005fprivkey_005fexport_005frsa_005fraw"></a><dl>
28997 <dt><a name="index-gnutls_005fx509_005fprivkey_005fexport_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_export_rsa_raw</strong> <em>(gnutls_x509_privkey_t <var>key</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>, gnutls_datum_t * <var>d</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>u</var>)</em></dt>
28998 <dd><p><var>key</var>: a structure that holds the rsa parameters
28999 </p>
29000 <p><var>m</var>: will hold the modulus
29001 </p>
29002 <p><var>e</var>: will hold the public exponent
29003 </p>
29004 <p><var>d</var>: will hold the private exponent
29005 </p>
29006 <p><var>p</var>: will hold the first prime (p)
29007 </p>
29008 <p><var>q</var>: will hold the second prime (q)
29009 </p>
29010 <p><var>u</var>: will hold the coefficient
29011 </p>
29012 <p>This function will export the RSA private key&rsquo;s parameters found
29013 in the given structure. The new parameters will be allocated using
29014 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
29015 </p>
29016 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29017 negative error value.
29018 </p></dd></dl>
29019
29020 <a name="gnutls_005fx509_005fprivkey_005fexport_005frsa_005fraw2-1"></a>
29021 <h4 class="subheading">gnutls_x509_privkey_export_rsa_raw2</h4>
29022 <a name="gnutls_005fx509_005fprivkey_005fexport_005frsa_005fraw2"></a><dl>
29023 <dt><a name="index-gnutls_005fx509_005fprivkey_005fexport_005frsa_005fraw2"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_export_rsa_raw2</strong> <em>(gnutls_x509_privkey_t <var>key</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>, gnutls_datum_t * <var>d</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>u</var>, gnutls_datum_t * <var>e1</var>, gnutls_datum_t * <var>e2</var>)</em></dt>
29024 <dd><p><var>key</var>: a structure that holds the rsa parameters
29025 </p>
29026 <p><var>m</var>: will hold the modulus
29027 </p>
29028 <p><var>e</var>: will hold the public exponent
29029 </p>
29030 <p><var>d</var>: will hold the private exponent
29031 </p>
29032 <p><var>p</var>: will hold the first prime (p)
29033 </p>
29034 <p><var>q</var>: will hold the second prime (q)
29035 </p>
29036 <p><var>u</var>: will hold the coefficient
29037 </p>
29038 <p><var>e1</var>: will hold e1 = d mod (p-1)
29039 </p>
29040 <p><var>e2</var>: will hold e2 = d mod (q-1)
29041 </p>
29042 <p>This function will export the RSA private key&rsquo;s parameters found
29043 in the given structure. The new parameters will be allocated using
29044 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
29045 </p>
29046 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29047 negative error value.
29048 </p>
29049 <p><strong>Since:</strong> 2.12.0
29050 </p></dd></dl>
29051
29052 <a name="gnutls_005fx509_005fprivkey_005ffix-1"></a>
29053 <h4 class="subheading">gnutls_x509_privkey_fix</h4>
29054 <a name="gnutls_005fx509_005fprivkey_005ffix"></a><dl>
29055 <dt><a name="index-gnutls_005fx509_005fprivkey_005ffix"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_fix</strong> <em>(gnutls_x509_privkey_t <var>key</var>)</em></dt>
29056 <dd><p><var>key</var>: Holds the key
29057 </p>
29058 <p>This function will recalculate the secondary parameters in a key.
29059 In RSA keys, this can be the coefficient and exponent1,2.
29060 </p>
29061 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29062 negative error value.
29063 </p></dd></dl>
29064
29065 <a name="gnutls_005fx509_005fprivkey_005fgenerate-1"></a>
29066 <h4 class="subheading">gnutls_x509_privkey_generate</h4>
29067 <a name="gnutls_005fx509_005fprivkey_005fgenerate"></a><dl>
29068 <dt><a name="index-gnutls_005fx509_005fprivkey_005fgenerate"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_generate</strong> <em>(gnutls_x509_privkey_t <var>key</var>, gnutls_pk_algorithm_t <var>algo</var>, unsigned int <var>bits</var>, unsigned int <var>flags</var>)</em></dt>
29069 <dd><p><var>key</var>: should contain a <code>gnutls_x509_privkey_t</code>  structure
29070 </p>
29071 <p><var>algo</var>: is one of the algorithms in <code>gnutls_pk_algorithm_t</code> .
29072 </p>
29073 <p><var>bits</var>: the size of the modulus
29074 </p>
29075 <p><var>flags</var>: unused for now.  Must be 0.
29076 </p>
29077 <p>This function will generate a random private key. Note that this
29078 function must be called on an empty private key.
29079 </p>
29080 <p>Note that when generating an elliptic curve key, the curve
29081 can be substituted in the place of the bits parameter using the
29082 <code>GNUTLS_CURVE_TO_BITS()</code>  macro.
29083 </p>
29084 <p>For DSA keys, if the subgroup size needs to be specified check
29085 the <code>GNUTLS_SUBGROUP_TO_BITS()</code>  macro.
29086 </p>
29087 <p>Do not set the number of bits directly, use <code>gnutls_sec_param_to_pk_bits()</code> .
29088 </p>
29089 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29090 negative error value.
29091 </p></dd></dl>
29092
29093 <a name="gnutls_005fx509_005fprivkey_005fget_005fkey_005fid-1"></a>
29094 <h4 class="subheading">gnutls_x509_privkey_get_key_id</h4>
29095 <a name="gnutls_005fx509_005fprivkey_005fget_005fkey_005fid"></a><dl>
29096 <dt><a name="index-gnutls_005fx509_005fprivkey_005fget_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_get_key_id</strong> <em>(gnutls_x509_privkey_t <var>key</var>, unsigned int <var>flags</var>, unsigned char * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
29097 <dd><p><var>key</var>: Holds the key
29098 </p>
29099 <p><var>flags</var>: should be 0 for now
29100 </p>
29101 <p><var>output_data</var>: will contain the key ID
29102 </p>
29103 <p><var>output_data_size</var>: holds the size of output_data (and will be
29104 replaced by the actual size of parameters)
29105 </p>
29106 <p>This function will return a unique ID that depends on the public key
29107 parameters. This ID can be used in checking whether a certificate
29108 corresponds to the given key.
29109 </p>
29110 <p>If the buffer provided is not long enough to hold the output, then
29111 * <code>output_data_size</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  will
29112 be returned.  The output will normally be a SHA-1 hash output,
29113 which is 20 bytes.
29114 </p>
29115 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29116 negative error value.
29117 </p></dd></dl>
29118
29119 <a name="gnutls_005fx509_005fprivkey_005fget_005fpk_005falgorithm-1"></a>
29120 <h4 class="subheading">gnutls_x509_privkey_get_pk_algorithm</h4>
29121 <a name="gnutls_005fx509_005fprivkey_005fget_005fpk_005falgorithm"></a><dl>
29122 <dt><a name="index-gnutls_005fx509_005fprivkey_005fget_005fpk_005falgorithm"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_get_pk_algorithm</strong> <em>(gnutls_x509_privkey_t <var>key</var>)</em></dt>
29123 <dd><p><var>key</var>: should contain a <code>gnutls_x509_privkey_t</code>  structure
29124 </p>
29125 <p>This function will return the public key algorithm of a private
29126 key.
29127 </p>
29128 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code>  enumeration on
29129 success, or a negative error code on error.
29130 </p></dd></dl>
29131
29132 <a name="gnutls_005fx509_005fprivkey_005fget_005fpk_005falgorithm2-1"></a>
29133 <h4 class="subheading">gnutls_x509_privkey_get_pk_algorithm2</h4>
29134 <a name="gnutls_005fx509_005fprivkey_005fget_005fpk_005falgorithm2"></a><dl>
29135 <dt><a name="index-gnutls_005fx509_005fprivkey_005fget_005fpk_005falgorithm2"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_get_pk_algorithm2</strong> <em>(gnutls_x509_privkey_t <var>key</var>, unsigned int * <var>bits</var>)</em></dt>
29136 <dd><p><var>key</var>: should contain a <code>gnutls_x509_privkey_t</code>  structure
29137 </p>
29138 <p><var>bits</var>: The number of bits in the public key algorithm
29139 </p>
29140 <p>This function will return the public key algorithm of a private
29141 key.
29142 </p>
29143 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code>  enumeration on
29144 success, or a negative error code on error.
29145 </p></dd></dl>
29146
29147 <a name="gnutls_005fx509_005fprivkey_005fimport-1"></a>
29148 <h4 class="subheading">gnutls_x509_privkey_import</h4>
29149 <a name="gnutls_005fx509_005fprivkey_005fimport"></a><dl>
29150 <dt><a name="index-gnutls_005fx509_005fprivkey_005fimport"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_import</strong> <em>(gnutls_x509_privkey_t <var>key</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>)</em></dt>
29151 <dd><p><var>key</var>: The structure to store the parsed key
29152 </p>
29153 <p><var>data</var>: The DER or PEM encoded certificate.
29154 </p>
29155 <p><var>format</var>: One of DER or PEM
29156 </p>
29157 <p>This function will convert the given DER or PEM encoded key to the
29158 native <code>gnutls_x509_privkey_t</code>  format. The output will be stored in
29159  <code>key</code> .
29160 </p>
29161 <p>If the key is PEM encoded it should have a header that contains &quot;PRIVATE
29162 KEY&quot;. Note that this function falls back to PKCS <code>8</code>  decoding without
29163 password, if the default format fails to import.
29164 </p>
29165 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29166 negative error value.
29167 </p></dd></dl>
29168
29169 <a name="gnutls_005fx509_005fprivkey_005fimport2-1"></a>
29170 <h4 class="subheading">gnutls_x509_privkey_import2</h4>
29171 <a name="gnutls_005fx509_005fprivkey_005fimport2"></a><dl>
29172 <dt><a name="index-gnutls_005fx509_005fprivkey_005fimport2-1"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_import2</strong> <em>(gnutls_x509_privkey_t <var>key</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>)</em></dt>
29173 <dd><p><var>key</var>: The structure to store the parsed key
29174 </p>
29175 <p><var>data</var>: The DER or PEM encoded key.
29176 </p>
29177 <p><var>format</var>: One of DER or PEM
29178 </p>
29179 <p><var>password</var>: A password (optional)
29180 </p>
29181 <p><var>flags</var>: an ORed sequence of gnutls_pkcs_encrypt_flags_t
29182 </p>
29183 <p>This function will import the given DER or PEM encoded key, to
29184 the native <code>gnutls_x509_privkey_t</code>  format, irrespective of the
29185 input format. The input format is auto-detected.
29186 </p>
29187 <p>The supported formats are basic unencrypted key, PKCS8, PKCS12,
29188 and the openssl format.
29189 </p>
29190 <p>If the provided key is encrypted but no password was given, then
29191 <code>GNUTLS_E_DECRYPTION_FAILED</code>  is returned.
29192 </p>
29193 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29194 negative error value.
29195 </p></dd></dl>
29196
29197 <a name="gnutls_005fx509_005fprivkey_005fimport_005fdsa_005fraw-1"></a>
29198 <h4 class="subheading">gnutls_x509_privkey_import_dsa_raw</h4>
29199 <a name="gnutls_005fx509_005fprivkey_005fimport_005fdsa_005fraw"></a><dl>
29200 <dt><a name="index-gnutls_005fx509_005fprivkey_005fimport_005fdsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_import_dsa_raw</strong> <em>(gnutls_x509_privkey_t <var>key</var>, const gnutls_datum_t * <var>p</var>, const gnutls_datum_t * <var>q</var>, const gnutls_datum_t * <var>g</var>, const gnutls_datum_t * <var>y</var>, const gnutls_datum_t * <var>x</var>)</em></dt>
29201 <dd><p><var>key</var>: The structure to store the parsed key
29202 </p>
29203 <p><var>p</var>: holds the p
29204 </p>
29205 <p><var>q</var>: holds the q
29206 </p>
29207 <p><var>g</var>: holds the g
29208 </p>
29209 <p><var>y</var>: holds the y
29210 </p>
29211 <p><var>x</var>: holds the x
29212 </p>
29213 <p>This function will convert the given DSA raw parameters to the
29214 native <code>gnutls_x509_privkey_t</code>  format.  The output will be stored
29215 in  <code>key</code> .
29216 </p>
29217 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29218 negative error value.
29219 </p></dd></dl>
29220
29221 <a name="gnutls_005fx509_005fprivkey_005fimport_005fecc_005fraw-1"></a>
29222 <h4 class="subheading">gnutls_x509_privkey_import_ecc_raw</h4>
29223 <a name="gnutls_005fx509_005fprivkey_005fimport_005fecc_005fraw"></a><dl>
29224 <dt><a name="index-gnutls_005fx509_005fprivkey_005fimport_005fecc_005fraw"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_import_ecc_raw</strong> <em>(gnutls_x509_privkey_t <var>key</var>, gnutls_ecc_curve_t <var>curve</var>, const gnutls_datum_t * <var>x</var>, const gnutls_datum_t * <var>y</var>, const gnutls_datum_t * <var>k</var>)</em></dt>
29225 <dd><p><var>key</var>: The structure to store the parsed key
29226 </p>
29227 <p><var>curve</var>: holds the curve
29228 </p>
29229 <p><var>x</var>: holds the x
29230 </p>
29231 <p><var>y</var>: holds the y
29232 </p>
29233 <p><var>k</var>: holds the k
29234 </p>
29235 <p>This function will convert the given elliptic curve parameters to the
29236 native <code>gnutls_x509_privkey_t</code>  format.  The output will be stored
29237 in  <code>key</code> .
29238 </p>
29239 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29240 negative error value.
29241 </p>
29242 <p><strong>Since:</strong> 3.0
29243 </p></dd></dl>
29244
29245 <a name="gnutls_005fx509_005fprivkey_005fimport_005fopenssl-1"></a>
29246 <h4 class="subheading">gnutls_x509_privkey_import_openssl</h4>
29247 <a name="gnutls_005fx509_005fprivkey_005fimport_005fopenssl"></a><dl>
29248 <dt><a name="index-gnutls_005fx509_005fprivkey_005fimport_005fopenssl-1"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_import_openssl</strong> <em>(gnutls_x509_privkey_t <var>key</var>, const gnutls_datum_t * <var>data</var>, const char * <var>password</var>)</em></dt>
29249 <dd><p><var>key</var>: The structure to store the parsed key
29250 </p>
29251 <p><var>data</var>: The DER or PEM encoded key.
29252 </p>
29253 <p><var>password</var>: the password to decrypt the key (if it is encrypted).
29254 </p>
29255 <p>This function will convert the given PEM encrypted to
29256 the native gnutls_x509_privkey_t format. The
29257 output will be stored in  <code>key</code> .
29258 </p>
29259 <p>The  <code>password</code> should be in ASCII. If the password is not provided
29260 or wrong then <code>GNUTLS_E_DECRYPTION_FAILED</code>  will be returned.
29261 </p>
29262 <p>If the Certificate is PEM encoded it should have a header of
29263 &quot;PRIVATE KEY&quot; and the &quot;DEK-Info&quot; header.
29264 </p>
29265 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29266 negative error value.
29267 </p></dd></dl>
29268
29269 <a name="gnutls_005fx509_005fprivkey_005fimport_005fpkcs8-1"></a>
29270 <h4 class="subheading">gnutls_x509_privkey_import_pkcs8</h4>
29271 <a name="gnutls_005fx509_005fprivkey_005fimport_005fpkcs8"></a><dl>
29272 <dt><a name="index-gnutls_005fx509_005fprivkey_005fimport_005fpkcs8"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_import_pkcs8</strong> <em>(gnutls_x509_privkey_t <var>key</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>)</em></dt>
29273 <dd><p><var>key</var>: The structure to store the parsed key
29274 </p>
29275 <p><var>data</var>: The DER or PEM encoded key.
29276 </p>
29277 <p><var>format</var>: One of DER or PEM
29278 </p>
29279 <p><var>password</var>: the password to decrypt the key (if it is encrypted).
29280 </p>
29281 <p><var>flags</var>: 0 if encrypted or GNUTLS_PKCS_PLAIN if not encrypted.
29282 </p>
29283 <p>This function will convert the given DER or PEM encoded PKCS8 2.0
29284 encrypted key to the native gnutls_x509_privkey_t format. The
29285 output will be stored in  <code>key</code> .  Both RSA and DSA keys can be
29286 imported, and flags can only be used to indicate an unencrypted
29287 key.
29288 </p>
29289 <p>The  <code>password</code> can be either ASCII or UTF-8 in the default PBES2
29290 encryption schemas, or ASCII for the PKCS12 schemas.
29291 </p>
29292 <p>If the Certificate is PEM encoded it should have a header of
29293 &quot;ENCRYPTED PRIVATE KEY&quot;, or &quot;PRIVATE KEY&quot;. You only need to
29294 specify the flags if the key is DER encoded, since in that case
29295 the encryption status cannot be auto-detected.
29296 </p>
29297 <p>If the <code>GNUTLS_PKCS_PLAIN</code>  flag is specified and the supplied data
29298 are encrypted then <code>GNUTLS_E_DECRYPTION_FAILED</code>  is returned.
29299 </p>
29300 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29301 negative error value.
29302 </p></dd></dl>
29303
29304 <a name="gnutls_005fx509_005fprivkey_005fimport_005frsa_005fraw-1"></a>
29305 <h4 class="subheading">gnutls_x509_privkey_import_rsa_raw</h4>
29306 <a name="gnutls_005fx509_005fprivkey_005fimport_005frsa_005fraw"></a><dl>
29307 <dt><a name="index-gnutls_005fx509_005fprivkey_005fimport_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_import_rsa_raw</strong> <em>(gnutls_x509_privkey_t <var>key</var>, const gnutls_datum_t * <var>m</var>, const gnutls_datum_t * <var>e</var>, const gnutls_datum_t * <var>d</var>, const gnutls_datum_t * <var>p</var>, const gnutls_datum_t * <var>q</var>, const gnutls_datum_t * <var>u</var>)</em></dt>
29308 <dd><p><var>key</var>: The structure to store the parsed key
29309 </p>
29310 <p><var>m</var>: holds the modulus
29311 </p>
29312 <p><var>e</var>: holds the public exponent
29313 </p>
29314 <p><var>d</var>: holds the private exponent
29315 </p>
29316 <p><var>p</var>: holds the first prime (p)
29317 </p>
29318 <p><var>q</var>: holds the second prime (q)
29319 </p>
29320 <p><var>u</var>: holds the coefficient
29321 </p>
29322 <p>This function will convert the given RSA raw parameters to the
29323 native <code>gnutls_x509_privkey_t</code>  format.  The output will be stored in
29324  <code>key</code> .
29325 </p>
29326 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29327 negative error value.
29328 </p></dd></dl>
29329
29330 <a name="gnutls_005fx509_005fprivkey_005fimport_005frsa_005fraw2-1"></a>
29331 <h4 class="subheading">gnutls_x509_privkey_import_rsa_raw2</h4>
29332 <a name="gnutls_005fx509_005fprivkey_005fimport_005frsa_005fraw2"></a><dl>
29333 <dt><a name="index-gnutls_005fx509_005fprivkey_005fimport_005frsa_005fraw2"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_import_rsa_raw2</strong> <em>(gnutls_x509_privkey_t <var>key</var>, const gnutls_datum_t * <var>m</var>, const gnutls_datum_t * <var>e</var>, const gnutls_datum_t * <var>d</var>, const gnutls_datum_t * <var>p</var>, const gnutls_datum_t * <var>q</var>, const gnutls_datum_t * <var>u</var>, const gnutls_datum_t * <var>e1</var>, const gnutls_datum_t * <var>e2</var>)</em></dt>
29334 <dd><p><var>key</var>: The structure to store the parsed key
29335 </p>
29336 <p><var>m</var>: holds the modulus
29337 </p>
29338 <p><var>e</var>: holds the public exponent
29339 </p>
29340 <p><var>d</var>: holds the private exponent
29341 </p>
29342 <p><var>p</var>: holds the first prime (p)
29343 </p>
29344 <p><var>q</var>: holds the second prime (q)
29345 </p>
29346 <p><var>u</var>: holds the coefficient (optional)
29347 </p>
29348 <p><var>e1</var>: holds e1 = d mod (p-1) (optional)
29349 </p>
29350 <p><var>e2</var>: holds e2 = d mod (q-1) (optional)
29351 </p>
29352 <p>This function will convert the given RSA raw parameters to the
29353 native <code>gnutls_x509_privkey_t</code>  format.  The output will be stored in
29354  <code>key</code> .
29355 </p>
29356 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29357 negative error value.
29358 </p></dd></dl>
29359
29360 <a name="gnutls_005fx509_005fprivkey_005finit-1"></a>
29361 <h4 class="subheading">gnutls_x509_privkey_init</h4>
29362 <a name="gnutls_005fx509_005fprivkey_005finit"></a><dl>
29363 <dt><a name="index-gnutls_005fx509_005fprivkey_005finit"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_init</strong> <em>(gnutls_x509_privkey_t * <var>key</var>)</em></dt>
29364 <dd><p><var>key</var>: The structure to be initialized
29365 </p>
29366 <p>This function will initialize an private key structure.
29367 </p>
29368 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29369 negative error value.
29370 </p></dd></dl>
29371
29372 <a name="gnutls_005fx509_005fprivkey_005fsec_005fparam-1"></a>
29373 <h4 class="subheading">gnutls_x509_privkey_sec_param</h4>
29374 <a name="gnutls_005fx509_005fprivkey_005fsec_005fparam"></a><dl>
29375 <dt><a name="index-gnutls_005fx509_005fprivkey_005fsec_005fparam"></a>Function: <em>gnutls_sec_param_t</em> <strong>gnutls_x509_privkey_sec_param</strong> <em>(gnutls_x509_privkey_t <var>key</var>)</em></dt>
29376 <dd><p><var>key</var>: a key structure
29377 </p>
29378 <p>This function will return the security parameter appropriate with
29379 this private key.
29380 </p>
29381 <p><strong>Returns:</strong> On success, a valid security parameter is returned otherwise
29382 <code>GNUTLS_SEC_PARAM_UNKNOWN</code>  is returned.
29383 </p>
29384 <p><strong>Since:</strong> 2.12.0
29385 </p></dd></dl>
29386
29387 <a name="gnutls_005fx509_005fprivkey_005fverify_005fparams-1"></a>
29388 <h4 class="subheading">gnutls_x509_privkey_verify_params</h4>
29389 <a name="gnutls_005fx509_005fprivkey_005fverify_005fparams"></a><dl>
29390 <dt><a name="index-gnutls_005fx509_005fprivkey_005fverify_005fparams"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_verify_params</strong> <em>(gnutls_x509_privkey_t <var>key</var>)</em></dt>
29391 <dd><p><var>key</var>: should contain a <code>gnutls_x509_privkey_t</code>  structure
29392 </p>
29393 <p>This function will verify the private key parameters.
29394 </p>
29395 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29396 negative error value.
29397 </p></dd></dl>
29398
29399 <a name="gnutls_005fx509_005frdn_005fget-1"></a>
29400 <h4 class="subheading">gnutls_x509_rdn_get</h4>
29401 <a name="gnutls_005fx509_005frdn_005fget"></a><dl>
29402 <dt><a name="index-gnutls_005fx509_005frdn_005fget"></a>Function: <em>int</em> <strong>gnutls_x509_rdn_get</strong> <em>(const gnutls_datum_t * <var>idn</var>, char * <var>buf</var>, size_t * <var>buf_size</var>)</em></dt>
29403 <dd><p><var>idn</var>: should contain a DER encoded RDN sequence
29404 </p>
29405 <p><var>buf</var>: a pointer to a structure to hold the peer&rsquo;s name
29406 </p>
29407 <p><var>buf_size</var>: holds the size of  <code>buf</code>
29408 </p>
29409 <p>This function will return the name of the given RDN sequence.  The
29410 name will be in the form &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as described in
29411 RFC4514.
29412 </p>
29413 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or
29414 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  is returned and * <code>buf_size</code> is
29415 updated if the provided buffer is not long enough, otherwise a
29416 negative error value.
29417 </p></dd></dl>
29418
29419 <a name="gnutls_005fx509_005frdn_005fget_005fby_005foid-1"></a>
29420 <h4 class="subheading">gnutls_x509_rdn_get_by_oid</h4>
29421 <a name="gnutls_005fx509_005frdn_005fget_005fby_005foid"></a><dl>
29422 <dt><a name="index-gnutls_005fx509_005frdn_005fget_005fby_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_rdn_get_by_oid</strong> <em>(const gnutls_datum_t * <var>idn</var>, const char * <var>oid</var>, int <var>indx</var>, unsigned int <var>raw_flag</var>, void * <var>buf</var>, size_t * <var>buf_size</var>)</em></dt>
29423 <dd><p><var>idn</var>: should contain a DER encoded RDN sequence
29424 </p>
29425 <p><var>oid</var>: an Object Identifier
29426 </p>
29427 <p><var>indx</var>: In case multiple same OIDs exist in the RDN indicates which
29428 to send. Use 0 for the first one.
29429 </p>
29430 <p><var>raw_flag</var>: If non-zero then the raw DER data are returned.
29431 </p>
29432 <p><var>buf</var>: a pointer to a structure to hold the peer&rsquo;s name
29433 </p>
29434 <p><var>buf_size</var>: holds the size of  <code>buf</code>
29435 </p>
29436 <p>This function will return the name of the given Object identifier,
29437 of the RDN sequence.  The name will be encoded using the rules
29438 from RFC4514.
29439 </p>
29440 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or
29441 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  is returned and * <code>buf_size</code> is
29442 updated if the provided buffer is not long enough, otherwise a
29443 negative error value.
29444 </p></dd></dl>
29445
29446 <a name="gnutls_005fx509_005frdn_005fget_005foid-1"></a>
29447 <h4 class="subheading">gnutls_x509_rdn_get_oid</h4>
29448 <a name="gnutls_005fx509_005frdn_005fget_005foid"></a><dl>
29449 <dt><a name="index-gnutls_005fx509_005frdn_005fget_005foid"></a>Function: <em>int</em> <strong>gnutls_x509_rdn_get_oid</strong> <em>(const gnutls_datum_t * <var>idn</var>, int <var>indx</var>, void * <var>buf</var>, size_t * <var>buf_size</var>)</em></dt>
29450 <dd><p><var>idn</var>: should contain a DER encoded RDN sequence
29451 </p>
29452 <p><var>indx</var>: Indicates which OID to return. Use 0 for the first one.
29453 </p>
29454 <p><var>buf</var>: a pointer to a structure to hold the peer&rsquo;s name OID
29455 </p>
29456 <p><var>buf_size</var>: holds the size of  <code>buf</code>
29457 </p>
29458 <p>This function will return the specified Object identifier, of the
29459 RDN sequence.
29460 </p>
29461 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, or
29462 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  is returned and * <code>buf_size</code> is
29463 updated if the provided buffer is not long enough, otherwise a
29464 negative error value.
29465 </p>
29466 <p><strong>Since:</strong> 2.4.0
29467 </p></dd></dl>
29468
29469 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005fcas-1"></a>
29470 <h4 class="subheading">gnutls_x509_trust_list_add_cas</h4>
29471 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005fcas"></a><dl>
29472 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fadd_005fcas-1"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_add_cas</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, const gnutls_x509_crt_t * <var>clist</var>, unsigned <var>clist_size</var>, unsigned int <var>flags</var>)</em></dt>
29473 <dd><p><var>list</var>: The structure of the list
29474 </p>
29475 <p><var>clist</var>: A list of CAs
29476 </p>
29477 <p><var>clist_size</var>: The length of the CA list
29478 </p>
29479 <p><var>flags</var>: should be 0 or an or&rsquo;ed sequence of <code>GNUTLS_TL</code>  options.
29480 </p>
29481 <p>This function will add the given certificate authorities
29482 to the trusted list. The list of CAs must not be deinitialized
29483 during this structure&rsquo;s lifetime.
29484 </p>
29485 <p>If the flag <code>GNUTLS_TL_NO_DUPLICATES</code>  is specified, then
29486 the provided  <code>clist</code> entries that are duplicates will not be
29487 added to the list and will be deinitialized.
29488 </p>
29489 <p><strong>Returns:</strong> The number of added elements is returned.
29490 </p>
29491 <p><strong>Since:</strong> 3.0.0
29492 </p></dd></dl>
29493
29494 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005fcrls-1"></a>
29495 <h4 class="subheading">gnutls_x509_trust_list_add_crls</h4>
29496 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005fcrls"></a><dl>
29497 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fadd_005fcrls-1"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_add_crls</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, const gnutls_x509_crl_t * <var>crl_list</var>, int <var>crl_size</var>, unsigned int <var>flags</var>, unsigned int <var>verification_flags</var>)</em></dt>
29498 <dd><p><var>list</var>: The structure of the list
29499 </p>
29500 <p><var>crl_list</var>: A list of CRLs
29501 </p>
29502 <p><var>crl_size</var>: The length of the CRL list
29503 </p>
29504 <p><var>flags</var>: if GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified before being added.
29505 </p>
29506 <p><var>verification_flags</var>: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
29507 </p>
29508 <p>This function will add the given certificate revocation lists
29509 to the trusted list. The list of CRLs must not be deinitialized
29510 during this structure&rsquo;s lifetime.
29511 </p>
29512 <p>This function must be called after <code>gnutls_x509_trust_list_add_cas()</code>
29513 to allow verifying the CRLs for validity. If the flag <code>GNUTLS_TL_NO_DUPLICATES</code>
29514 is given, then any provided CRLs that are a duplicate, will be deinitialized
29515 and not added to the list (that assumes that <code>gnutls_x509_trust_list_deinit()</code>
29516 will be called with all=1).
29517 </p>
29518 <p><strong>Returns:</strong> The number of added elements is returned.
29519 </p>
29520 <p><strong>Since:</strong> 3.0
29521 </p></dd></dl>
29522
29523 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005fnamed_005fcrt-1"></a>
29524 <h4 class="subheading">gnutls_x509_trust_list_add_named_crt</h4>
29525 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005fnamed_005fcrt"></a><dl>
29526 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fadd_005fnamed_005fcrt-1"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_add_named_crt</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, gnutls_x509_crt_t <var>cert</var>, const void * <var>name</var>, size_t <var>name_size</var>, unsigned int <var>flags</var>)</em></dt>
29527 <dd><p><var>list</var>: The structure of the list
29528 </p>
29529 <p><var>cert</var>: A certificate
29530 </p>
29531 <p><var>name</var>: An identifier for the certificate
29532 </p>
29533 <p><var>name_size</var>: The size of the identifier
29534 </p>
29535 <p><var>flags</var>: should be 0.
29536 </p>
29537 <p>This function will add the given certificate to the trusted
29538 list and associate it with a name. The certificate will not be
29539 be used for verification with <code>gnutls_x509_trust_list_verify_crt()</code>
29540 but only with <code>gnutls_x509_trust_list_verify_named_crt()</code> .
29541 </p>
29542 <p>In principle this function can be used to set individual &quot;server&quot;
29543 certificates that are trusted by the user for that specific server
29544 but for no other purposes.
29545 </p>
29546 <p>The certificate must not be deinitialized during the lifetime
29547 of the trusted list.
29548 </p>
29549 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29550 negative error value.
29551 </p>
29552 <p><strong>Since:</strong> 3.0.0
29553 </p></dd></dl>
29554
29555 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005fsystem_005ftrust-1"></a>
29556 <h4 class="subheading">gnutls_x509_trust_list_add_system_trust</h4>
29557 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005fsystem_005ftrust"></a><dl>
29558 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fadd_005fsystem_005ftrust-1"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_add_system_trust</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, unsigned int <var>tl_flags</var>, unsigned int <var>tl_vflags</var>)</em></dt>
29559 <dd><p><var>list</var>: The structure of the list
29560 </p>
29561 <p><var>tl_flags</var>: GNUTLS_TL_*
29562 </p>
29563 <p><var>tl_vflags</var>: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
29564 </p>
29565 <p>This function adds the system&rsquo;s default trusted certificate
29566 authorities to the trusted list. Note that on unsupported systems
29567 this function returns <code>GNUTLS_E_UNIMPLEMENTED_FEATURE</code> .
29568 </p>
29569 <p>This function implies the flag <code>GNUTLS_TL_NO_DUPLICATES</code> .
29570 </p>
29571 <p><strong>Returns:</strong> The number of added elements or a negative error code on error.
29572 </p>
29573 <p><strong>Since:</strong> 3.1
29574 </p></dd></dl>
29575
29576 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005fdir-1"></a>
29577 <h4 class="subheading">gnutls_x509_trust_list_add_trust_dir</h4>
29578 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005fdir"></a><dl>
29579 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005fdir"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_add_trust_dir</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, const char * <var>ca_dir</var>, const char * <var>crl_dir</var>, gnutls_x509_crt_fmt_t <var>type</var>, unsigned int <var>tl_flags</var>, unsigned int <var>tl_vflags</var>)</em></dt>
29580 <dd><p><var>list</var>: The structure of the list
29581 </p>
29582 <p><var>ca_dir</var>: A directory containing the CAs (optional)
29583 </p>
29584 <p><var>crl_dir</var>: A directory containing a list of CRLs (optional)
29585 </p>
29586 <p><var>type</var>: The format of the certificates
29587 </p>
29588 <p><var>tl_flags</var>: GNUTLS_TL_*
29589 </p>
29590 <p><var>tl_vflags</var>: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
29591 </p>
29592 <p>This function will add the given certificate authorities
29593 to the trusted list. Only directories are accepted by
29594 this function.
29595 </p>
29596 <p><strong>Returns:</strong> The number of added elements is returned.
29597 </p>
29598 <p><strong>Since:</strong> 3.3.6
29599 </p></dd></dl>
29600
29601 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005ffile-1"></a>
29602 <h4 class="subheading">gnutls_x509_trust_list_add_trust_file</h4>
29603 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005ffile"></a><dl>
29604 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005ffile-1"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_add_trust_file</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, const char * <var>ca_file</var>, const char * <var>crl_file</var>, gnutls_x509_crt_fmt_t <var>type</var>, unsigned int <var>tl_flags</var>, unsigned int <var>tl_vflags</var>)</em></dt>
29605 <dd><p><var>list</var>: The structure of the list
29606 </p>
29607 <p><var>ca_file</var>: A file containing a list of CAs (optional)
29608 </p>
29609 <p><var>crl_file</var>: A file containing a list of CRLs (optional)
29610 </p>
29611 <p><var>type</var>: The format of the certificates
29612 </p>
29613 <p><var>tl_flags</var>: GNUTLS_TL_*
29614 </p>
29615 <p><var>tl_vflags</var>: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
29616 </p>
29617 <p>This function will add the given certificate authorities
29618 to the trusted list. PKCS <code>11</code>  URLs are also accepted, instead
29619 of files, by this function. A PKCS <code>11</code>  URL implies a trust
29620 database (a specially marked module in p11-kit); the URL &quot;pkcs11:&quot;
29621 implies all trust databases in the system. Only a single URL specifying
29622 trust databases can be set; they cannot be stacked with multiple calls.
29623 </p>
29624 <p><strong>Returns:</strong> The number of added elements is returned.
29625 </p>
29626 <p><strong>Since:</strong> 3.1
29627 </p></dd></dl>
29628
29629 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005fmem-1"></a>
29630 <h4 class="subheading">gnutls_x509_trust_list_add_trust_mem</h4>
29631 <a name="gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005fmem"></a><dl>
29632 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005fmem-1"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_add_trust_mem</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, const gnutls_datum_t * <var>cas</var>, const gnutls_datum_t * <var>crls</var>, gnutls_x509_crt_fmt_t <var>type</var>, unsigned int <var>tl_flags</var>, unsigned int <var>tl_vflags</var>)</em></dt>
29633 <dd><p><var>list</var>: The structure of the list
29634 </p>
29635 <p><var>cas</var>: A buffer containing a list of CAs (optional)
29636 </p>
29637 <p><var>crls</var>: A buffer containing a list of CRLs (optional)
29638 </p>
29639 <p><var>type</var>: The format of the certificates
29640 </p>
29641 <p><var>tl_flags</var>: GNUTLS_TL_*
29642 </p>
29643 <p><var>tl_vflags</var>: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
29644 </p>
29645 <p>This function will add the given certificate authorities
29646 to the trusted list.
29647 </p>
29648 <p><strong>Returns:</strong> The number of added elements is returned.
29649 </p>
29650 <p><strong>Since:</strong> 3.1
29651 </p></dd></dl>
29652
29653 <a name="gnutls_005fx509_005ftrust_005flist_005fdeinit-1"></a>
29654 <h4 class="subheading">gnutls_x509_trust_list_deinit</h4>
29655 <a name="gnutls_005fx509_005ftrust_005flist_005fdeinit"></a><dl>
29656 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_x509_trust_list_deinit</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, unsigned int <var>all</var>)</em></dt>
29657 <dd><p><var>list</var>: The structure to be deinitialized
29658 </p>
29659 <p><var>all</var>: if non-zero it will deinitialize all the certificates and CRLs contained in the structure.
29660 </p>
29661 <p>This function will deinitialize a trust list. Note that the
29662  <code>all</code> flag should be typically non-zero unless you have specified
29663 your certificates using <code>gnutls_x509_trust_list_add_cas()</code>  and you
29664 want to prevent them from being deinitialized by this function.
29665 </p>
29666 <p><strong>Since:</strong> 3.0.0
29667 </p></dd></dl>
29668
29669 <a name="gnutls_005fx509_005ftrust_005flist_005fget_005fissuer-1"></a>
29670 <h4 class="subheading">gnutls_x509_trust_list_get_issuer</h4>
29671 <a name="gnutls_005fx509_005ftrust_005flist_005fget_005fissuer"></a><dl>
29672 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fget_005fissuer"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_get_issuer</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, gnutls_x509_crt_t <var>cert</var>, gnutls_x509_crt_t * <var>issuer</var>, unsigned int <var>flags</var>)</em></dt>
29673 <dd><p><var>list</var>: The structure of the list
29674 </p>
29675 <p><var>cert</var>: is the certificate to find issuer for
29676 </p>
29677 <p><var>issuer</var>: Will hold the issuer if any. Should be treated as constant.
29678 </p>
29679 <p><var>flags</var>: Use zero or <code>GNUTLS_TL_GET_COPY</code>
29680 </p>
29681 <p>This function will find the issuer of the given certificate.
29682 If the flag <code>GNUTLS_TL_GET_COPY</code>  is specified a copy of the issuer
29683 will be returned which must be freed using <code>gnutls_x509_crt_deinit()</code> .
29684 Note that the flag <code>GNUTLS_TL_GET_COPY</code>  is required for this function
29685 to work with PKCS <code>11</code>  trust lists in a thread-safe way.
29686 </p>
29687 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29688 negative error value.
29689 </p>
29690 <p><strong>Since:</strong> 3.0
29691 </p></dd></dl>
29692
29693 <a name="gnutls_005fx509_005ftrust_005flist_005finit-1"></a>
29694 <h4 class="subheading">gnutls_x509_trust_list_init</h4>
29695 <a name="gnutls_005fx509_005ftrust_005flist_005finit"></a><dl>
29696 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005finit"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_init</strong> <em>(gnutls_x509_trust_list_t * <var>list</var>, unsigned int <var>size</var>)</em></dt>
29697 <dd><p><var>list</var>: The structure to be initialized
29698 </p>
29699 <p><var>size</var>: The size of the internal hash table. Use (0) for default size.
29700 </p>
29701 <p>This function will initialize an X.509 trust list structure.
29702 </p>
29703 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29704 negative error value.
29705 </p>
29706 <p><strong>Since:</strong> 3.0.0
29707 </p></dd></dl>
29708
29709 <a name="gnutls_005fx509_005ftrust_005flist_005fremove_005fcas-1"></a>
29710 <h4 class="subheading">gnutls_x509_trust_list_remove_cas</h4>
29711 <a name="gnutls_005fx509_005ftrust_005flist_005fremove_005fcas"></a><dl>
29712 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fremove_005fcas"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_remove_cas</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, const gnutls_x509_crt_t * <var>clist</var>, int <var>clist_size</var>)</em></dt>
29713 <dd><p><var>list</var>: The structure of the list
29714 </p>
29715 <p><var>clist</var>: A list of CAs
29716 </p>
29717 <p><var>clist_size</var>: The length of the CA list
29718 </p>
29719 <p>This function will remove the given certificate authorities
29720 from the trusted list.
29721 </p>
29722 <p>Note that this function can accept certificates and authorities
29723 not yet known. In that case they will be kept in a separate
29724 black list that will be used during certificate verification.
29725 Unlike <code>gnutls_x509_trust_list_add_cas()</code>  there is no deinitialization
29726 restriction for  certificate list provided in this function.
29727 </p>
29728 <p><strong>Returns:</strong> The number of removed elements is returned.
29729 </p>
29730 <p><strong>Since:</strong> 3.1.10
29731 </p></dd></dl>
29732
29733 <a name="gnutls_005fx509_005ftrust_005flist_005fremove_005ftrust_005ffile-1"></a>
29734 <h4 class="subheading">gnutls_x509_trust_list_remove_trust_file</h4>
29735 <a name="gnutls_005fx509_005ftrust_005flist_005fremove_005ftrust_005ffile"></a><dl>
29736 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fremove_005ftrust_005ffile"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_remove_trust_file</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, const char * <var>ca_file</var>, gnutls_x509_crt_fmt_t <var>type</var>)</em></dt>
29737 <dd><p><var>list</var>: The structure of the list
29738 </p>
29739 <p><var>ca_file</var>: A file containing a list of CAs
29740 </p>
29741 <p><var>type</var>: The format of the certificates
29742 </p>
29743 <p>This function will remove the given certificate authorities
29744 from the trusted list, and add them into a black list when needed.
29745 PKCS 11 URLs are also accepted, instead
29746 of files, by this function.
29747 </p>
29748 <p>See also <code>gnutls_x509_trust_list_remove_cas()</code> .
29749 </p>
29750 <p><strong>Returns:</strong> The number of added elements is returned.
29751 </p>
29752 <p><strong>Since:</strong> 3.1.10
29753 </p></dd></dl>
29754
29755 <a name="gnutls_005fx509_005ftrust_005flist_005fremove_005ftrust_005fmem-1"></a>
29756 <h4 class="subheading">gnutls_x509_trust_list_remove_trust_mem</h4>
29757 <a name="gnutls_005fx509_005ftrust_005flist_005fremove_005ftrust_005fmem"></a><dl>
29758 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fremove_005ftrust_005fmem"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_remove_trust_mem</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, const gnutls_datum_t * <var>cas</var>, gnutls_x509_crt_fmt_t <var>type</var>)</em></dt>
29759 <dd><p><var>list</var>: The structure of the list
29760 </p>
29761 <p><var>cas</var>: A buffer containing a list of CAs (optional)
29762 </p>
29763 <p><var>type</var>: The format of the certificates
29764 </p>
29765 <p>This function will remove the provided certificate authorities
29766 from the trusted list, and add them into a black list when needed.
29767 </p>
29768 <p>See also <code>gnutls_x509_trust_list_remove_cas()</code> .
29769 </p>
29770 <p><strong>Returns:</strong> The number of removed elements is returned.
29771 </p>
29772 <p><strong>Since:</strong> 3.1.10
29773 </p></dd></dl>
29774
29775 <a name="gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt-1"></a>
29776 <h4 class="subheading">gnutls_x509_trust_list_verify_crt</h4>
29777 <a name="gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt"></a><dl>
29778 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt-1"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_verify_crt</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, gnutls_x509_crt_t * <var>cert_list</var>, unsigned int <var>cert_list_size</var>, unsigned int <var>flags</var>, unsigned int * <var>voutput</var>, gnutls_verify_output_function <var>func</var>)</em></dt>
29779 <dd><p><var>list</var>: The structure of the list
29780 </p>
29781 <p><var>cert_list</var>: is the certificate list to be verified
29782 </p>
29783 <p><var>cert_list_size</var>: is the certificate list size
29784 </p>
29785 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
29786 </p>
29787 <p><var>voutput</var>: will hold the certificate verification output.
29788 </p>
29789 <p><var>func</var>: If non-null will be called on each chain element verification with the output.
29790 </p>
29791 <p>This function will try to verify the given certificate and return
29792 its status. The  <code>verify</code> parameter will hold an OR&rsquo;ed sequence of
29793 <code>gnutls_certificate_status_t</code>  flags.
29794 </p>
29795 <p>Additionally a certificate verification profile can be specified
29796 from the ones in <code>gnutls_certificate_verification_profiles_t</code>  by
29797 ORing the result of <code>GNUTLS_PROFILE_TO_VFLAGS()</code>  to the verification
29798 flags.
29799 </p>
29800 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29801 negative error value.
29802 </p>
29803 <p><strong>Since:</strong> 3.0
29804 </p></dd></dl>
29805
29806 <a name="gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt2-1"></a>
29807 <h4 class="subheading">gnutls_x509_trust_list_verify_crt2</h4>
29808 <a name="gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt2"></a><dl>
29809 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt2-1"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_verify_crt2</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, gnutls_x509_crt_t * <var>cert_list</var>, unsigned int <var>cert_list_size</var>, gnutls_typed_vdata_st * <var>data</var>, unsigned int <var>elements</var>, unsigned int <var>flags</var>, unsigned int * <var>voutput</var>, gnutls_verify_output_function <var>func</var>)</em></dt>
29810 <dd><p><var>list</var>: The structure of the list
29811 </p>
29812 <p><var>cert_list</var>: is the certificate list to be verified
29813 </p>
29814 <p><var>cert_list_size</var>: is the certificate list size
29815 </p>
29816 <p><var>data</var>: an array of typed data
29817 </p>
29818 <p><var>elements</var>: the number of data elements
29819 </p>
29820 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
29821 </p>
29822 <p><var>voutput</var>: will hold the certificate verification output.
29823 </p>
29824 <p><var>func</var>: If non-null will be called on each chain element verification with the output.
29825 </p>
29826 <p>This function will try to verify the given certificate and return
29827 its status. The  <code>verify</code> parameter will hold an OR&rsquo;ed sequence of
29828 <code>gnutls_certificate_status_t</code>  flags.
29829 </p>
29830 <p>Additionally a certificate verification profile can be specified
29831 from the ones in <code>gnutls_certificate_verification_profiles_t</code>  by
29832 ORing the result of <code>GNUTLS_PROFILE_TO_VFLAGS()</code>  to the verification
29833 flags.
29834 </p>
29835 <p>The acceptable  <code>data</code> types are <code>GNUTLS_DT_DNS_HOSTNAME</code>  and <code>GNUTLS_DT_KEY_PURPOSE_OID</code> .
29836 The former accepts as data a null-terminated hostname, and the latter a null-terminated
29837 object identifier (e.g., <code>GNUTLS_KP_TLS_WWW_SERVER</code> ).
29838 If a DNS hostname is provided then this function will compare
29839 the hostname in the certificate against the given. If names do not match the
29840 <code>GNUTLS_CERT_UNEXPECTED_OWNER</code>  status flag will be set.
29841 If a key purpose OID is provided and the end-certificate contains the extended key
29842 usage PKIX extension, it will be required to be have the provided key purpose
29843 or be marked for any purpose, otherwise verification will fail with <code>GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE</code>  status.
29844 </p>
29845 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29846 negative error value. Note that verification failure will not result to an
29847 error code, only  <code>voutput</code> will be updated.
29848 </p>
29849 <p><strong>Since:</strong> 3.3.8
29850 </p></dd></dl>
29851
29852 <a name="gnutls_005fx509_005ftrust_005flist_005fverify_005fnamed_005fcrt-1"></a>
29853 <h4 class="subheading">gnutls_x509_trust_list_verify_named_crt</h4>
29854 <a name="gnutls_005fx509_005ftrust_005flist_005fverify_005fnamed_005fcrt"></a><dl>
29855 <dt><a name="index-gnutls_005fx509_005ftrust_005flist_005fverify_005fnamed_005fcrt-1"></a>Function: <em>int</em> <strong>gnutls_x509_trust_list_verify_named_crt</strong> <em>(gnutls_x509_trust_list_t <var>list</var>, gnutls_x509_crt_t <var>cert</var>, const void * <var>name</var>, size_t <var>name_size</var>, unsigned int <var>flags</var>, unsigned int * <var>voutput</var>, gnutls_verify_output_function <var>func</var>)</em></dt>
29856 <dd><p><var>list</var>: The structure of the list
29857 </p>
29858 <p><var>cert</var>: is the certificate to be verified
29859 </p>
29860 <p><var>name</var>: is the certificate&rsquo;s name
29861 </p>
29862 <p><var>name_size</var>: is the certificate&rsquo;s name size
29863 </p>
29864 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
29865 </p>
29866 <p><var>voutput</var>: will hold the certificate verification output.
29867 </p>
29868 <p><var>func</var>: If non-null will be called on each chain element verification with the output.
29869 </p>
29870 <p>This function will try to find a certificate that is associated with the provided
29871 name &ndash;see <code>gnutls_x509_trust_list_add_named_crt()</code> . If a match is found the certificate is considered valid.
29872 In addition to that this function will also check CRLs.
29873 The  <code>voutput</code> parameter will hold an OR&rsquo;ed sequence of <code>gnutls_certificate_status_t</code>  flags.
29874 </p>
29875 <p>Additionally a certificate verification profile can be specified
29876 from the ones in <code>gnutls_certificate_verification_profiles_t</code>  by
29877 ORing the result of <code>GNUTLS_PROFILE_TO_VFLAGS()</code>  to the verification
29878 flags.
29879 </p>
29880 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29881 negative error value.
29882 </p>
29883 <p><strong>Since:</strong> 3.0.0
29884 </p></dd></dl>
29885
29886
29887 <hr>
29888 <a name="OCSP-API"></a>
29889 <div class="header">
29890 <p>
29891 Next: <a href="#OpenPGP-API" accesskey="n" rel="next">OpenPGP API</a>, Previous: <a href="#X509-certificate-API" accesskey="p" rel="prev">X509 certificate API</a>, Up: <a href="#API-reference" accesskey="u" rel="up">API reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
29892 </div>
29893 <a name="OCSP-API-1"></a>
29894 <h3 class="section">E.4 <acronym>OCSP</acronym> API</h3>
29895 <a name="index-OCSP-Functions"></a>
29896
29897 <p>The following functions are for <acronym>OCSP</acronym> certificate status
29898 checking.  Their prototypes lie in <samp>gnutls/ocsp.h</samp>.
29899 </p>
29900
29901 <a name="gnutls_005focsp_005freq_005fadd_005fcert-1"></a>
29902 <h4 class="subheading">gnutls_ocsp_req_add_cert</h4>
29903 <a name="gnutls_005focsp_005freq_005fadd_005fcert"></a><dl>
29904 <dt><a name="index-gnutls_005focsp_005freq_005fadd_005fcert"></a>Function: <em>int</em> <strong>gnutls_ocsp_req_add_cert</strong> <em>(gnutls_ocsp_req_t <var>req</var>, gnutls_digest_algorithm_t <var>digest</var>, gnutls_x509_crt_t <var>issuer</var>, gnutls_x509_crt_t <var>cert</var>)</em></dt>
29905 <dd><p><var>req</var>: should contain a <code>gnutls_ocsp_req_t</code>  structure
29906 </p>
29907 <p><var>digest</var>: hash algorithm, a <code>gnutls_digest_algorithm_t</code>  value
29908 </p>
29909 <p><var>issuer</var>: issuer of  <code>subject</code> certificate
29910 </p>
29911 <p><var>cert</var>: certificate to request status for
29912 </p>
29913 <p>This function will add another request to the OCSP request for a
29914 particular certificate.  The issuer name hash, issuer key hash, and
29915 serial number fields is populated as follows.  The issuer name and
29916 the serial number is taken from  <code>cert</code> .  The issuer key is taken
29917 from  <code>issuer</code> .  The hashed values will be hashed using the  <code>digest</code> algorithm, normally <code>GNUTLS_DIG_SHA1</code> .
29918 </p>
29919 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29920 negative error code is returned.
29921 </p></dd></dl>
29922
29923 <a name="gnutls_005focsp_005freq_005fadd_005fcert_005fid-1"></a>
29924 <h4 class="subheading">gnutls_ocsp_req_add_cert_id</h4>
29925 <a name="gnutls_005focsp_005freq_005fadd_005fcert_005fid"></a><dl>
29926 <dt><a name="index-gnutls_005focsp_005freq_005fadd_005fcert_005fid"></a>Function: <em>int</em> <strong>gnutls_ocsp_req_add_cert_id</strong> <em>(gnutls_ocsp_req_t <var>req</var>, gnutls_digest_algorithm_t <var>digest</var>, const gnutls_datum_t * <var>issuer_name_hash</var>, const gnutls_datum_t * <var>issuer_key_hash</var>, const gnutls_datum_t * <var>serial_number</var>)</em></dt>
29927 <dd><p><var>req</var>: should contain a <code>gnutls_ocsp_req_t</code>  structure
29928 </p>
29929 <p><var>digest</var>: hash algorithm, a <code>gnutls_digest_algorithm_t</code>  value
29930 </p>
29931 <p><var>issuer_name_hash</var>: hash of issuer&rsquo;s DN
29932 </p>
29933 <p><var>issuer_key_hash</var>: hash of issuer&rsquo;s public key
29934 </p>
29935 <p><var>serial_number</var>: serial number of certificate to check
29936 </p>
29937 <p>This function will add another request to the OCSP request for a
29938 particular certificate having the issuer name hash of
29939  <code>issuer_name_hash</code> and issuer key hash of  <code>issuer_key_hash</code> (both
29940 hashed using  <code>digest</code> ) and serial number  <code>serial_number</code> .
29941 </p>
29942 <p>The information needed corresponds to the CertID structure:
29943 </p>
29944 <p>&lt;informalexample&gt;&lt;programlisting&gt;
29945 CertID          ::=     SEQUENCE {
29946 hashAlgorithm       AlgorithmIdentifier,
29947 issuerNameHash      OCTET STRING, &ndash; Hash of Issuer&rsquo;s DN
29948 issuerKeyHash       OCTET STRING, &ndash; Hash of Issuers public key
29949 serialNumber        CertificateSerialNumber }
29950 &lt;/programlisting&gt;&lt;/informalexample&gt;
29951 </p>
29952 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
29953 negative error code is returned.
29954 </p></dd></dl>
29955
29956 <a name="gnutls_005focsp_005freq_005fdeinit-1"></a>
29957 <h4 class="subheading">gnutls_ocsp_req_deinit</h4>
29958 <a name="gnutls_005focsp_005freq_005fdeinit"></a><dl>
29959 <dt><a name="index-gnutls_005focsp_005freq_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_ocsp_req_deinit</strong> <em>(gnutls_ocsp_req_t <var>req</var>)</em></dt>
29960 <dd><p><var>req</var>: The structure to be deinitialized
29961 </p>
29962 <p>This function will deinitialize a OCSP request structure.
29963 </p></dd></dl>
29964
29965 <a name="gnutls_005focsp_005freq_005fexport-1"></a>
29966 <h4 class="subheading">gnutls_ocsp_req_export</h4>
29967 <a name="gnutls_005focsp_005freq_005fexport"></a><dl>
29968 <dt><a name="index-gnutls_005focsp_005freq_005fexport"></a>Function: <em>int</em> <strong>gnutls_ocsp_req_export</strong> <em>(gnutls_ocsp_req_t <var>req</var>, gnutls_datum_t * <var>data</var>)</em></dt>
29969 <dd><p><var>req</var>: Holds the OCSP request
29970 </p>
29971 <p><var>data</var>: newly allocate buffer holding DER encoded OCSP request
29972 </p>
29973 <p>This function will export the OCSP request to DER format.
29974 </p>
29975 <p><strong>Returns:</strong> In case of failure a negative error code will be
29976 returned, and 0 on success.
29977 </p></dd></dl>
29978
29979 <a name="gnutls_005focsp_005freq_005fget_005fcert_005fid-1"></a>
29980 <h4 class="subheading">gnutls_ocsp_req_get_cert_id</h4>
29981 <a name="gnutls_005focsp_005freq_005fget_005fcert_005fid"></a><dl>
29982 <dt><a name="index-gnutls_005focsp_005freq_005fget_005fcert_005fid"></a>Function: <em>int</em> <strong>gnutls_ocsp_req_get_cert_id</strong> <em>(gnutls_ocsp_req_t <var>req</var>, unsigned <var>indx</var>, gnutls_digest_algorithm_t * <var>digest</var>, gnutls_datum_t * <var>issuer_name_hash</var>, gnutls_datum_t * <var>issuer_key_hash</var>, gnutls_datum_t * <var>serial_number</var>)</em></dt>
29983 <dd><p><var>req</var>: should contain a <code>gnutls_ocsp_req_t</code>  structure
29984 </p>
29985 <p><var>indx</var>: Specifies which extension OID to get. Use (0) to get the first one.
29986 </p>
29987 <p><var>digest</var>: output variable with <code>gnutls_digest_algorithm_t</code>  hash algorithm
29988 </p>
29989 <p><var>issuer_name_hash</var>: output buffer with hash of issuer&rsquo;s DN
29990 </p>
29991 <p><var>issuer_key_hash</var>: output buffer with hash of issuer&rsquo;s public key
29992 </p>
29993 <p><var>serial_number</var>: output buffer with serial number of certificate to check
29994 </p>
29995 <p>This function will return the certificate information of the
29996  <code>indx</code> &rsquo;ed request in the OCSP request.  The information returned
29997 corresponds to the CertID structure:
29998 </p>
29999 <p>&lt;informalexample&gt;&lt;programlisting&gt;
30000 CertID          ::=     SEQUENCE {
30001 hashAlgorithm       AlgorithmIdentifier,
30002 issuerNameHash      OCTET STRING, &ndash; Hash of Issuer&rsquo;s DN
30003 issuerKeyHash       OCTET STRING, &ndash; Hash of Issuers public key
30004 serialNumber        CertificateSerialNumber }
30005 &lt;/programlisting&gt;&lt;/informalexample&gt;
30006 </p>
30007 <p>Each of the pointers to output variables may be NULL to indicate
30008 that the caller is not interested in that value.
30009 </p>
30010 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30011 negative error code is returned.  If you have reached the last
30012 CertID available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be
30013 returned.
30014 </p></dd></dl>
30015
30016 <a name="gnutls_005focsp_005freq_005fget_005fextension-1"></a>
30017 <h4 class="subheading">gnutls_ocsp_req_get_extension</h4>
30018 <a name="gnutls_005focsp_005freq_005fget_005fextension"></a><dl>
30019 <dt><a name="index-gnutls_005focsp_005freq_005fget_005fextension"></a>Function: <em>int</em> <strong>gnutls_ocsp_req_get_extension</strong> <em>(gnutls_ocsp_req_t <var>req</var>, unsigned <var>indx</var>, gnutls_datum_t * <var>oid</var>, unsigned int * <var>critical</var>, gnutls_datum_t * <var>data</var>)</em></dt>
30020 <dd><p><var>req</var>: should contain a <code>gnutls_ocsp_req_t</code>  structure
30021 </p>
30022 <p><var>indx</var>: Specifies which extension OID to get. Use (0) to get the first one.
30023 </p>
30024 <p><var>oid</var>: will hold newly allocated buffer with OID of extension, may be NULL
30025 </p>
30026 <p><var>critical</var>: output variable with critical flag, may be NULL.
30027 </p>
30028 <p><var>data</var>: will hold newly allocated buffer with extension data, may be NULL
30029 </p>
30030 <p>This function will return all information about the requested
30031 extension in the OCSP request.  The information returned is the
30032 OID, the critical flag, and the data itself.  The extension OID
30033 will be stored as a string.  Any of  <code>oid</code> ,  <code>critical</code> , and  <code>data</code> may
30034 be NULL which means that the caller is not interested in getting
30035 that information back.
30036 </p>
30037 <p>The caller needs to deallocate memory by calling <code>gnutls_free()</code>  on
30038  <code>oid</code> -&gt;data and  <code>data</code> -&gt;data.
30039 </p>
30040 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30041 negative error code is returned.  If you have reached the last
30042 extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will
30043 be returned.
30044 </p></dd></dl>
30045
30046 <a name="gnutls_005focsp_005freq_005fget_005fnonce-1"></a>
30047 <h4 class="subheading">gnutls_ocsp_req_get_nonce</h4>
30048 <a name="gnutls_005focsp_005freq_005fget_005fnonce"></a><dl>
30049 <dt><a name="index-gnutls_005focsp_005freq_005fget_005fnonce"></a>Function: <em>int</em> <strong>gnutls_ocsp_req_get_nonce</strong> <em>(gnutls_ocsp_req_t <var>req</var>, unsigned int * <var>critical</var>, gnutls_datum_t * <var>nonce</var>)</em></dt>
30050 <dd><p><var>req</var>: should contain a <code>gnutls_ocsp_req_t</code>  structure
30051 </p>
30052 <p><var>critical</var>: whether nonce extension is marked critical, or NULL
30053 </p>
30054 <p><var>nonce</var>: will hold newly allocated buffer with nonce data
30055 </p>
30056 <p>This function will return the OCSP request nonce extension data.
30057 </p>
30058 <p>The caller needs to deallocate memory by calling <code>gnutls_free()</code>  on
30059  <code>nonce</code> -&gt;data.
30060 </p>
30061 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30062 negative error code is returned.
30063 </p></dd></dl>
30064
30065 <a name="gnutls_005focsp_005freq_005fget_005fversion-1"></a>
30066 <h4 class="subheading">gnutls_ocsp_req_get_version</h4>
30067 <a name="gnutls_005focsp_005freq_005fget_005fversion"></a><dl>
30068 <dt><a name="index-gnutls_005focsp_005freq_005fget_005fversion"></a>Function: <em>int</em> <strong>gnutls_ocsp_req_get_version</strong> <em>(gnutls_ocsp_req_t <var>req</var>)</em></dt>
30069 <dd><p><var>req</var>: should contain a <code>gnutls_ocsp_req_t</code>  structure
30070 </p>
30071 <p>This function will return the version of the OCSP request.
30072 Typically this is always 1 indicating version 1.
30073 </p>
30074 <p><strong>Returns:</strong> version of OCSP request, or a negative error code on error.
30075 </p></dd></dl>
30076
30077 <a name="gnutls_005focsp_005freq_005fimport-1"></a>
30078 <h4 class="subheading">gnutls_ocsp_req_import</h4>
30079 <a name="gnutls_005focsp_005freq_005fimport"></a><dl>
30080 <dt><a name="index-gnutls_005focsp_005freq_005fimport"></a>Function: <em>int</em> <strong>gnutls_ocsp_req_import</strong> <em>(gnutls_ocsp_req_t <var>req</var>, const gnutls_datum_t * <var>data</var>)</em></dt>
30081 <dd><p><var>req</var>: The structure to store the parsed request.
30082 </p>
30083 <p><var>data</var>: DER encoded OCSP request.
30084 </p>
30085 <p>This function will convert the given DER encoded OCSP request to
30086 the native <code>gnutls_ocsp_req_t</code>  format. The output will be stored in
30087  <code>req</code> .
30088 </p>
30089 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30090 negative error value.
30091 </p></dd></dl>
30092
30093 <a name="gnutls_005focsp_005freq_005finit-1"></a>
30094 <h4 class="subheading">gnutls_ocsp_req_init</h4>
30095 <a name="gnutls_005focsp_005freq_005finit"></a><dl>
30096 <dt><a name="index-gnutls_005focsp_005freq_005finit"></a>Function: <em>int</em> <strong>gnutls_ocsp_req_init</strong> <em>(gnutls_ocsp_req_t * <var>req</var>)</em></dt>
30097 <dd><p><var>req</var>: The structure to be initialized
30098 </p>
30099 <p>This function will initialize an OCSP request structure.
30100 </p>
30101 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30102 negative error value.
30103 </p></dd></dl>
30104
30105 <a name="gnutls_005focsp_005freq_005fprint-1"></a>
30106 <h4 class="subheading">gnutls_ocsp_req_print</h4>
30107 <a name="gnutls_005focsp_005freq_005fprint"></a><dl>
30108 <dt><a name="index-gnutls_005focsp_005freq_005fprint"></a>Function: <em>int</em> <strong>gnutls_ocsp_req_print</strong> <em>(gnutls_ocsp_req_t <var>req</var>, gnutls_ocsp_print_formats_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
30109 <dd><p><var>req</var>: The structure to be printed
30110 </p>
30111 <p><var>format</var>: Indicate the format to use
30112 </p>
30113 <p><var>out</var>: Newly allocated datum with (0) terminated string.
30114 </p>
30115 <p>This function will pretty print a OCSP request, suitable for
30116 display to a human.
30117 </p>
30118 <p>If the format is <code>GNUTLS_OCSP_PRINT_FULL</code>  then all fields of the
30119 request will be output, on multiple lines.
30120 </p>
30121 <p>The output  <code>out</code> -&gt;data needs to be deallocate using <code>gnutls_free()</code> .
30122 </p>
30123 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30124 negative error value.
30125 </p></dd></dl>
30126
30127 <a name="gnutls_005focsp_005freq_005frandomize_005fnonce-1"></a>
30128 <h4 class="subheading">gnutls_ocsp_req_randomize_nonce</h4>
30129 <a name="gnutls_005focsp_005freq_005frandomize_005fnonce"></a><dl>
30130 <dt><a name="index-gnutls_005focsp_005freq_005frandomize_005fnonce"></a>Function: <em>int</em> <strong>gnutls_ocsp_req_randomize_nonce</strong> <em>(gnutls_ocsp_req_t <var>req</var>)</em></dt>
30131 <dd><p><var>req</var>: should contain a <code>gnutls_ocsp_req_t</code>  structure
30132 </p>
30133 <p>This function will add or update an nonce extension to the OCSP
30134 request with a newly generated random value.
30135 </p>
30136 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30137 negative error code is returned.
30138 </p></dd></dl>
30139
30140 <a name="gnutls_005focsp_005freq_005fset_005fextension-1"></a>
30141 <h4 class="subheading">gnutls_ocsp_req_set_extension</h4>
30142 <a name="gnutls_005focsp_005freq_005fset_005fextension"></a><dl>
30143 <dt><a name="index-gnutls_005focsp_005freq_005fset_005fextension"></a>Function: <em>int</em> <strong>gnutls_ocsp_req_set_extension</strong> <em>(gnutls_ocsp_req_t <var>req</var>, const char * <var>oid</var>, unsigned int <var>critical</var>, const gnutls_datum_t * <var>data</var>)</em></dt>
30144 <dd><p><var>req</var>: should contain a <code>gnutls_ocsp_req_t</code>  structure
30145 </p>
30146 <p><var>oid</var>: buffer with OID of extension as a string.
30147 </p>
30148 <p><var>critical</var>: critical flag, normally false.
30149 </p>
30150 <p><var>data</var>: the extension data
30151 </p>
30152 <p>This function will add an extension to the OCSP request.  Calling
30153 this function multiple times for the same OID will overwrite values
30154 from earlier calls.
30155 </p>
30156 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30157 negative error code is returned.
30158 </p></dd></dl>
30159
30160 <a name="gnutls_005focsp_005freq_005fset_005fnonce-1"></a>
30161 <h4 class="subheading">gnutls_ocsp_req_set_nonce</h4>
30162 <a name="gnutls_005focsp_005freq_005fset_005fnonce"></a><dl>
30163 <dt><a name="index-gnutls_005focsp_005freq_005fset_005fnonce"></a>Function: <em>int</em> <strong>gnutls_ocsp_req_set_nonce</strong> <em>(gnutls_ocsp_req_t <var>req</var>, unsigned int <var>critical</var>, const gnutls_datum_t * <var>nonce</var>)</em></dt>
30164 <dd><p><var>req</var>: should contain a <code>gnutls_ocsp_req_t</code>  structure
30165 </p>
30166 <p><var>critical</var>: critical flag, normally false.
30167 </p>
30168 <p><var>nonce</var>: the nonce data
30169 </p>
30170 <p>This function will add an nonce extension to the OCSP request.
30171 Calling this function multiple times will overwrite values from
30172 earlier calls.
30173 </p>
30174 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30175 negative error code is returned.
30176 </p></dd></dl>
30177
30178 <a name="gnutls_005focsp_005fresp_005fcheck_005fcrt-1"></a>
30179 <h4 class="subheading">gnutls_ocsp_resp_check_crt</h4>
30180 <a name="gnutls_005focsp_005fresp_005fcheck_005fcrt"></a><dl>
30181 <dt><a name="index-gnutls_005focsp_005fresp_005fcheck_005fcrt"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_check_crt</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, unsigned int <var>indx</var>, gnutls_x509_crt_t <var>crt</var>)</em></dt>
30182 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30183 </p>
30184 <p><var>indx</var>: Specifies response number to get. Use (0) to get the first one.
30185 </p>
30186 <p><var>crt</var>: The certificate to check
30187 </p>
30188 <p>This function will check whether the OCSP response
30189 is about the provided certificate.
30190 </p>
30191 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30192 negative error code is returned.
30193 </p>
30194 <p><strong>Since:</strong> 3.1.3
30195 </p></dd></dl>
30196
30197 <a name="gnutls_005focsp_005fresp_005fdeinit-1"></a>
30198 <h4 class="subheading">gnutls_ocsp_resp_deinit</h4>
30199 <a name="gnutls_005focsp_005fresp_005fdeinit"></a><dl>
30200 <dt><a name="index-gnutls_005focsp_005fresp_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_ocsp_resp_deinit</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>)</em></dt>
30201 <dd><p><var>resp</var>: The structure to be deinitialized
30202 </p>
30203 <p>This function will deinitialize a OCSP response structure.
30204 </p></dd></dl>
30205
30206 <a name="gnutls_005focsp_005fresp_005fexport-1"></a>
30207 <h4 class="subheading">gnutls_ocsp_resp_export</h4>
30208 <a name="gnutls_005focsp_005fresp_005fexport"></a><dl>
30209 <dt><a name="index-gnutls_005focsp_005fresp_005fexport"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_export</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, gnutls_datum_t * <var>data</var>)</em></dt>
30210 <dd><p><var>resp</var>: Holds the OCSP response
30211 </p>
30212 <p><var>data</var>: newly allocate buffer holding DER encoded OCSP response
30213 </p>
30214 <p>This function will export the OCSP response to DER format.
30215 </p>
30216 <p><strong>Returns:</strong> In case of failure a negative error code will be
30217 returned, and 0 on success.
30218 </p></dd></dl>
30219
30220 <a name="gnutls_005focsp_005fresp_005fget_005fcerts-1"></a>
30221 <h4 class="subheading">gnutls_ocsp_resp_get_certs</h4>
30222 <a name="gnutls_005focsp_005fresp_005fget_005fcerts"></a><dl>
30223 <dt><a name="index-gnutls_005focsp_005fresp_005fget_005fcerts"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_get_certs</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, gnutls_x509_crt_t ** <var>certs</var>, size_t * <var>ncerts</var>)</em></dt>
30224 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30225 </p>
30226 <p><var>certs</var>: newly allocated array with <code>gnutls_x509_crt_t</code>  certificates
30227 </p>
30228 <p><var>ncerts</var>: output variable with number of allocated certs.
30229 </p>
30230 <p>This function will extract the X.509 certificates found in the
30231 Basic OCSP Response.  The  <code>certs</code> output variable will hold a newly
30232 allocated zero-terminated array with X.509 certificates.
30233 </p>
30234 <p>Every certificate in the array needs to be de-allocated with
30235 <code>gnutls_x509_crt_deinit()</code>  and the array itself must be freed using
30236 <code>gnutls_free()</code> .
30237 </p>
30238 <p>Both the  <code>certs</code> and  <code>ncerts</code> variables may be NULL.  Then the
30239 function will work as normal but will not return the NULL:d
30240 information.  This can be used to get the number of certificates
30241 only, or to just get the certificate array without its size.
30242 </p>
30243 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30244 negative error value.
30245 </p></dd></dl>
30246
30247 <a name="gnutls_005focsp_005fresp_005fget_005fextension-1"></a>
30248 <h4 class="subheading">gnutls_ocsp_resp_get_extension</h4>
30249 <a name="gnutls_005focsp_005fresp_005fget_005fextension"></a><dl>
30250 <dt><a name="index-gnutls_005focsp_005fresp_005fget_005fextension"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_get_extension</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, unsigned <var>indx</var>, gnutls_datum_t * <var>oid</var>, unsigned int * <var>critical</var>, gnutls_datum_t * <var>data</var>)</em></dt>
30251 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30252 </p>
30253 <p><var>indx</var>: Specifies which extension OID to get. Use (0) to get the first one.
30254 </p>
30255 <p><var>oid</var>: will hold newly allocated buffer with OID of extension, may be NULL
30256 </p>
30257 <p><var>critical</var>: output variable with critical flag, may be NULL.
30258 </p>
30259 <p><var>data</var>: will hold newly allocated buffer with extension data, may be NULL
30260 </p>
30261 <p>This function will return all information about the requested
30262 extension in the OCSP response.  The information returned is the
30263 OID, the critical flag, and the data itself.  The extension OID
30264 will be stored as a string.  Any of  <code>oid</code> ,  <code>critical</code> , and  <code>data</code> may
30265 be NULL which means that the caller is not interested in getting
30266 that information back.
30267 </p>
30268 <p>The caller needs to deallocate memory by calling <code>gnutls_free()</code>  on
30269  <code>oid</code> -&gt;data and  <code>data</code> -&gt;data.
30270 </p>
30271 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30272 negative error code is returned.  If you have reached the last
30273 extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will
30274 be returned.
30275 </p></dd></dl>
30276
30277 <a name="gnutls_005focsp_005fresp_005fget_005fnonce-1"></a>
30278 <h4 class="subheading">gnutls_ocsp_resp_get_nonce</h4>
30279 <a name="gnutls_005focsp_005fresp_005fget_005fnonce"></a><dl>
30280 <dt><a name="index-gnutls_005focsp_005fresp_005fget_005fnonce"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_get_nonce</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, unsigned int * <var>critical</var>, gnutls_datum_t * <var>nonce</var>)</em></dt>
30281 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30282 </p>
30283 <p><var>critical</var>: whether nonce extension is marked critical
30284 </p>
30285 <p><var>nonce</var>: will hold newly allocated buffer with nonce data
30286 </p>
30287 <p>This function will return the Basic OCSP Response nonce extension
30288 data.
30289 </p>
30290 <p>The caller needs to deallocate memory by calling <code>gnutls_free()</code>  on
30291  <code>nonce</code> -&gt;data.
30292 </p>
30293 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30294 negative error code is returned.
30295 </p></dd></dl>
30296
30297 <a name="gnutls_005focsp_005fresp_005fget_005fproduced-1"></a>
30298 <h4 class="subheading">gnutls_ocsp_resp_get_produced</h4>
30299 <a name="gnutls_005focsp_005fresp_005fget_005fproduced"></a><dl>
30300 <dt><a name="index-gnutls_005focsp_005fresp_005fget_005fproduced"></a>Function: <em>time_t</em> <strong>gnutls_ocsp_resp_get_produced</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>)</em></dt>
30301 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30302 </p>
30303 <p>This function will return the time when the OCSP response was
30304 signed.
30305 </p>
30306 <p><strong>Returns:</strong> signing time, or (time_t)-1 on error.
30307 </p></dd></dl>
30308
30309 <a name="gnutls_005focsp_005fresp_005fget_005fresponder-1"></a>
30310 <h4 class="subheading">gnutls_ocsp_resp_get_responder</h4>
30311 <a name="gnutls_005focsp_005fresp_005fget_005fresponder"></a><dl>
30312 <dt><a name="index-gnutls_005focsp_005fresp_005fget_005fresponder"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_get_responder</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, gnutls_datum_t * <var>dn</var>)</em></dt>
30313 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30314 </p>
30315 <p><var>dn</var>: newly allocated buffer with name
30316 </p>
30317 <p>This function will extract the name of the Basic OCSP Response in
30318 the provided buffer. The name will be in the form
30319 &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as described in RFC2253. The output string
30320 will be ASCII or UTF-8 encoded, depending on the certificate data.
30321 </p>
30322 <p>The caller needs to deallocate memory by calling <code>gnutls_free()</code>  on
30323  <code>dn</code> -&gt;data.
30324 </p>
30325 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30326 negative error code is returned.
30327 </p></dd></dl>
30328
30329 <a name="gnutls_005focsp_005fresp_005fget_005fresponse-1"></a>
30330 <h4 class="subheading">gnutls_ocsp_resp_get_response</h4>
30331 <a name="gnutls_005focsp_005fresp_005fget_005fresponse"></a><dl>
30332 <dt><a name="index-gnutls_005focsp_005fresp_005fget_005fresponse"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_get_response</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, gnutls_datum_t * <var>response_type_oid</var>, gnutls_datum_t * <var>response</var>)</em></dt>
30333 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30334 </p>
30335 <p><var>response_type_oid</var>: newly allocated output buffer with response type OID
30336 </p>
30337 <p><var>response</var>: newly allocated output buffer with DER encoded response
30338 </p>
30339 <p>This function will extract the response type OID in and the
30340 response data from an OCSP response.  Normally the
30341  <code>response_type_oid</code> is always &quot;1.3.6.1.5.5.7.48.1.1&quot; which means the
30342  <code>response</code> should be decoded as a Basic OCSP Response, but
30343 technically other response types could be used.
30344 </p>
30345 <p>This function is typically only useful when you want to extract the
30346 response type OID of an response for diagnostic purposes.
30347 Otherwise <code>gnutls_ocsp_resp_import()</code>  will decode the basic OCSP
30348 response part and the caller need not worry about that aspect.
30349 </p>
30350 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30351 negative error value.
30352 </p></dd></dl>
30353
30354 <a name="gnutls_005focsp_005fresp_005fget_005fsignature-1"></a>
30355 <h4 class="subheading">gnutls_ocsp_resp_get_signature</h4>
30356 <a name="gnutls_005focsp_005fresp_005fget_005fsignature"></a><dl>
30357 <dt><a name="index-gnutls_005focsp_005fresp_005fget_005fsignature"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_get_signature</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, gnutls_datum_t * <var>sig</var>)</em></dt>
30358 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30359 </p>
30360 <p><var>sig</var>: newly allocated output buffer with signature data
30361 </p>
30362 <p>This function will extract the signature field of a OCSP response.
30363 </p>
30364 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30365 negative error value.
30366 </p></dd></dl>
30367
30368 <a name="gnutls_005focsp_005fresp_005fget_005fsignature_005falgorithm-1"></a>
30369 <h4 class="subheading">gnutls_ocsp_resp_get_signature_algorithm</h4>
30370 <a name="gnutls_005focsp_005fresp_005fget_005fsignature_005falgorithm"></a><dl>
30371 <dt><a name="index-gnutls_005focsp_005fresp_005fget_005fsignature_005falgorithm"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_get_signature_algorithm</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>)</em></dt>
30372 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30373 </p>
30374 <p>This function will return a value of the <code>gnutls_sign_algorithm_t</code>
30375 enumeration that is the signature algorithm that has been used to
30376 sign the OCSP response.
30377 </p>
30378 <p><strong>Returns:</strong> a <code>gnutls_sign_algorithm_t</code>  value, or a negative error code
30379 on error.
30380 </p></dd></dl>
30381
30382 <a name="gnutls_005focsp_005fresp_005fget_005fsingle-1"></a>
30383 <h4 class="subheading">gnutls_ocsp_resp_get_single</h4>
30384 <a name="gnutls_005focsp_005fresp_005fget_005fsingle"></a><dl>
30385 <dt><a name="index-gnutls_005focsp_005fresp_005fget_005fsingle-1"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_get_single</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, unsigned <var>indx</var>, gnutls_digest_algorithm_t * <var>digest</var>, gnutls_datum_t * <var>issuer_name_hash</var>, gnutls_datum_t * <var>issuer_key_hash</var>, gnutls_datum_t * <var>serial_number</var>, unsigned int * <var>cert_status</var>, time_t * <var>this_update</var>, time_t * <var>next_update</var>, time_t * <var>revocation_time</var>, unsigned int * <var>revocation_reason</var>)</em></dt>
30386 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30387 </p>
30388 <p><var>indx</var>: Specifies response number to get. Use (0) to get the first one.
30389 </p>
30390 <p><var>digest</var>: output variable with <code>gnutls_digest_algorithm_t</code>  hash algorithm
30391 </p>
30392 <p><var>issuer_name_hash</var>: output buffer with hash of issuer&rsquo;s DN
30393 </p>
30394 <p><var>issuer_key_hash</var>: output buffer with hash of issuer&rsquo;s public key
30395 </p>
30396 <p><var>serial_number</var>: output buffer with serial number of certificate to check
30397 </p>
30398 <p><var>cert_status</var>: a certificate status, a <code>gnutls_ocsp_cert_status_t</code>  enum.
30399 </p>
30400 <p><var>this_update</var>: time at which the status is known to be correct.
30401 </p>
30402 <p><var>next_update</var>: when newer information will be available, or (time_t)-1 if unspecified
30403 </p>
30404 <p><var>revocation_time</var>: when  <code>cert_status</code> is <code>GNUTLS_OCSP_CERT_REVOKED</code> , holds time of revocation.
30405 </p>
30406 <p><var>revocation_reason</var>: revocation reason, a <code>gnutls_x509_crl_reason_t</code>  enum.
30407 </p>
30408 <p>This function will return the certificate information of the
30409  <code>indx</code> &rsquo;ed response in the Basic OCSP Response  <code>resp</code> .  The
30410 information returned corresponds to the OCSP SingleResponse structure
30411 except the final singleExtensions.
30412 </p>
30413 <p>Each of the pointers to output variables may be NULL to indicate
30414 that the caller is not interested in that value.
30415 </p>
30416 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30417 negative error code is returned.  If you have reached the last
30418 CertID available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be
30419 returned.
30420 </p></dd></dl>
30421
30422 <a name="gnutls_005focsp_005fresp_005fget_005fstatus-1"></a>
30423 <h4 class="subheading">gnutls_ocsp_resp_get_status</h4>
30424 <a name="gnutls_005focsp_005fresp_005fget_005fstatus"></a><dl>
30425 <dt><a name="index-gnutls_005focsp_005fresp_005fget_005fstatus"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_get_status</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>)</em></dt>
30426 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30427 </p>
30428 <p>This function will return the status of a OCSP response, an
30429 <code>gnutls_ocsp_resp_status_t</code>  enumeration.
30430 </p>
30431 <p><strong>Returns:</strong> status of OCSP request as a <code>gnutls_ocsp_resp_status_t</code> , or
30432 a negative error code on error.
30433 </p></dd></dl>
30434
30435 <a name="gnutls_005focsp_005fresp_005fget_005fversion-1"></a>
30436 <h4 class="subheading">gnutls_ocsp_resp_get_version</h4>
30437 <a name="gnutls_005focsp_005fresp_005fget_005fversion"></a><dl>
30438 <dt><a name="index-gnutls_005focsp_005fresp_005fget_005fversion"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_get_version</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>)</em></dt>
30439 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30440 </p>
30441 <p>This function will return the version of the Basic OCSP Response.
30442 Typically this is always 1 indicating version 1.
30443 </p>
30444 <p><strong>Returns:</strong> version of Basic OCSP response, or a negative error code
30445 on error.
30446 </p></dd></dl>
30447
30448 <a name="gnutls_005focsp_005fresp_005fimport-1"></a>
30449 <h4 class="subheading">gnutls_ocsp_resp_import</h4>
30450 <a name="gnutls_005focsp_005fresp_005fimport"></a><dl>
30451 <dt><a name="index-gnutls_005focsp_005fresp_005fimport"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_import</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, const gnutls_datum_t * <var>data</var>)</em></dt>
30452 <dd><p><var>resp</var>: The structure to store the parsed response.
30453 </p>
30454 <p><var>data</var>: DER encoded OCSP response.
30455 </p>
30456 <p>This function will convert the given DER encoded OCSP response to
30457 the native <code>gnutls_ocsp_resp_t</code>  format.  It also decodes the Basic
30458 OCSP Response part, if any.  The output will be stored in  <code>resp</code> .
30459 </p>
30460 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30461 negative error value.
30462 </p></dd></dl>
30463
30464 <a name="gnutls_005focsp_005fresp_005finit-1"></a>
30465 <h4 class="subheading">gnutls_ocsp_resp_init</h4>
30466 <a name="gnutls_005focsp_005fresp_005finit"></a><dl>
30467 <dt><a name="index-gnutls_005focsp_005fresp_005finit"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_init</strong> <em>(gnutls_ocsp_resp_t * <var>resp</var>)</em></dt>
30468 <dd><p><var>resp</var>: The structure to be initialized
30469 </p>
30470 <p>This function will initialize an OCSP response structure.
30471 </p>
30472 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30473 negative error value.
30474 </p></dd></dl>
30475
30476 <a name="gnutls_005focsp_005fresp_005fprint-1"></a>
30477 <h4 class="subheading">gnutls_ocsp_resp_print</h4>
30478 <a name="gnutls_005focsp_005fresp_005fprint"></a><dl>
30479 <dt><a name="index-gnutls_005focsp_005fresp_005fprint"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_print</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, gnutls_ocsp_print_formats_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
30480 <dd><p><var>resp</var>: The structure to be printed
30481 </p>
30482 <p><var>format</var>: Indicate the format to use
30483 </p>
30484 <p><var>out</var>: Newly allocated datum with (0) terminated string.
30485 </p>
30486 <p>This function will pretty print a OCSP response, suitable for
30487 display to a human.
30488 </p>
30489 <p>If the format is <code>GNUTLS_OCSP_PRINT_FULL</code>  then all fields of the
30490 response will be output, on multiple lines.
30491 </p>
30492 <p>The output  <code>out</code> -&gt;data needs to be deallocate using <code>gnutls_free()</code> .
30493 </p>
30494 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30495 negative error value.
30496 </p></dd></dl>
30497
30498 <a name="gnutls_005focsp_005fresp_005fverify-1"></a>
30499 <h4 class="subheading">gnutls_ocsp_resp_verify</h4>
30500 <a name="gnutls_005focsp_005fresp_005fverify"></a><dl>
30501 <dt><a name="index-gnutls_005focsp_005fresp_005fverify"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_verify</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, gnutls_x509_trust_list_t <var>trustlist</var>, unsigned int * <var>verify</var>, unsigned int <var>flags</var>)</em></dt>
30502 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30503 </p>
30504 <p><var>trustlist</var>: trust anchors as a <code>gnutls_x509_trust_list_t</code>  structure
30505 </p>
30506 <p><var>verify</var>: output variable with verification status, an <code>gnutls_ocsp_cert_status_t</code>
30507 </p>
30508 <p><var>flags</var>: verification flags, 0 for now.
30509 </p>
30510 <p>Verify signature of the Basic OCSP Response against the public key
30511 in the certificate of a trusted signer.  The  <code>trustlist</code> should be
30512 populated with trust anchors.  The function will extract the signer
30513 certificate from the Basic OCSP Response and will verify it against
30514 the  <code>trustlist</code> .  A trusted signer is a certificate that is either
30515 in  <code>trustlist</code> , or it is signed directly by a certificate in
30516  <code>trustlist</code> and has the id-ad-ocspSigning Extended Key Usage bit
30517 set.
30518 </p>
30519 <p>The output  <code>verify</code> variable will hold verification status codes
30520 (e.g., <code>GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND</code> ,
30521 <code>GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM</code> ) which are only valid if the
30522 function returned <code>GNUTLS_E_SUCCESS</code> .
30523 </p>
30524 <p>Note that the function returns <code>GNUTLS_E_SUCCESS</code>  even when
30525 verification failed.  The caller must always inspect the  <code>verify</code> variable to find out the verification status.
30526 </p>
30527 <p>The  <code>flags</code> variable should be 0 for now.
30528 </p>
30529 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30530 negative error value.
30531 </p></dd></dl>
30532
30533 <a name="gnutls_005focsp_005fresp_005fverify_005fdirect-1"></a>
30534 <h4 class="subheading">gnutls_ocsp_resp_verify_direct</h4>
30535 <a name="gnutls_005focsp_005fresp_005fverify_005fdirect"></a><dl>
30536 <dt><a name="index-gnutls_005focsp_005fresp_005fverify_005fdirect"></a>Function: <em>int</em> <strong>gnutls_ocsp_resp_verify_direct</strong> <em>(gnutls_ocsp_resp_t <var>resp</var>, gnutls_x509_crt_t <var>issuer</var>, unsigned int * <var>verify</var>, unsigned int <var>flags</var>)</em></dt>
30537 <dd><p><var>resp</var>: should contain a <code>gnutls_ocsp_resp_t</code>  structure
30538 </p>
30539 <p><var>issuer</var>: certificate believed to have signed the response
30540 </p>
30541 <p><var>verify</var>: output variable with verification status, an <code>gnutls_ocsp_cert_status_t</code>
30542 </p>
30543 <p><var>flags</var>: verification flags, 0 for now.
30544 </p>
30545 <p>Verify signature of the Basic OCSP Response against the public key
30546 in the  <code>issuer</code> certificate.
30547 </p>
30548 <p>The output  <code>verify</code> variable will hold verification status codes
30549 (e.g., <code>GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND</code> ,
30550 <code>GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM</code> ) which are only valid if the
30551 function returned <code>GNUTLS_E_SUCCESS</code> .
30552 </p>
30553 <p>Note that the function returns <code>GNUTLS_E_SUCCESS</code>  even when
30554 verification failed.  The caller must always inspect the  <code>verify</code> variable to find out the verification status.
30555 </p>
30556 <p>The  <code>flags</code> variable should be 0 for now.
30557 </p>
30558 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30559 negative error value.
30560 </p></dd></dl>
30561
30562
30563 <hr>
30564 <a name="OpenPGP-API"></a>
30565 <div class="header">
30566 <p>
30567 Next: <a href="#PKCS-12-API" accesskey="n" rel="next">PKCS 12 API</a>, Previous: <a href="#OCSP-API" accesskey="p" rel="prev">OCSP API</a>, Up: <a href="#API-reference" accesskey="u" rel="up">API reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
30568 </div>
30569 <a name="OpenPGP-API-1"></a>
30570 <h3 class="section">E.5 <acronym>OpenPGP</acronym> API</h3>
30571 <a name="index-OpenPGP-API"></a>
30572
30573 <p>The following functions are to be used for <acronym>OpenPGP</acronym>
30574 certificate handling.  Their prototypes lie in
30575 <samp>gnutls/openpgp.h</samp>.
30576 </p>
30577
30578 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey-1"></a>
30579 <h4 class="subheading">gnutls_certificate_set_openpgp_key</h4>
30580 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey"></a><dl>
30581 <dt><a name="index-gnutls_005fcertificate_005fset_005fopenpgp_005fkey"></a>Function: <em>int</em> <strong>gnutls_certificate_set_openpgp_key</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, gnutls_openpgp_crt_t <var>crt</var>, gnutls_openpgp_privkey_t <var>pkey</var>)</em></dt>
30582 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
30583 </p>
30584 <p><var>crt</var>: contains an openpgp public key
30585 </p>
30586 <p><var>pkey</var>: is an openpgp private key
30587 </p>
30588 <p>This function sets a certificate/private key pair in the
30589 gnutls_certificate_credentials_t structure.  This function may be
30590 called more than once (in case multiple keys/certificates exist
30591 for the server).
30592 </p>
30593 <p>Note that this function requires that the preferred key ids have
30594 been set and be used. See <code>gnutls_openpgp_crt_set_preferred_key_id()</code> .
30595 Otherwise the master key will be used.
30596 </p>
30597 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
30598 otherwise a negative error code is returned.
30599 </p></dd></dl>
30600
30601 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile-1"></a>
30602 <h4 class="subheading">gnutls_certificate_set_openpgp_key_file</h4>
30603 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile"></a><dl>
30604 <dt><a name="index-gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile"></a>Function: <em>int</em> <strong>gnutls_certificate_set_openpgp_key_file</strong> <em>(gnutls_certificate_credentials_t      <var>res</var>, const char * <var>certfile</var>, const char * <var>keyfile</var>, gnutls_openpgp_crt_fmt_t <var>format</var>)</em></dt>
30605 <dd><p><var>res</var>: the destination context to save the data.
30606 </p>
30607 <p><var>certfile</var>: the file that contains the public key.
30608 </p>
30609 <p><var>keyfile</var>: the file that contains the secret key.
30610 </p>
30611 <p><var>format</var>: the format of the keys
30612 </p>
30613 <p>This funtion is used to load OpenPGP keys into the GnuTLS
30614 credentials structure. The file should contain at least one valid non encrypted subkey.
30615 </p>
30616 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30617 negative error value.
30618 </p></dd></dl>
30619
30620 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile2-1"></a>
30621 <h4 class="subheading">gnutls_certificate_set_openpgp_key_file2</h4>
30622 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile2"></a><dl>
30623 <dt><a name="index-gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile2"></a>Function: <em>int</em> <strong>gnutls_certificate_set_openpgp_key_file2</strong> <em>(gnutls_certificate_credentials_t       <var>res</var>, const char * <var>certfile</var>, const char * <var>keyfile</var>, const char * <var>subkey_id</var>, gnutls_openpgp_crt_fmt_t <var>format</var>)</em></dt>
30624 <dd><p><var>res</var>: the destination context to save the data.
30625 </p>
30626 <p><var>certfile</var>: the file that contains the public key.
30627 </p>
30628 <p><var>keyfile</var>: the file that contains the secret key.
30629 </p>
30630 <p><var>subkey_id</var>: a hex encoded subkey id
30631 </p>
30632 <p><var>format</var>: the format of the keys
30633 </p>
30634 <p>This funtion is used to load OpenPGP keys into the GnuTLS credential
30635 structure. The file should contain at least one valid non encrypted subkey.
30636 </p>
30637 <p>The special keyword &quot;auto&quot; is also accepted as  <code>subkey_id</code> .  In that
30638 case the <code>gnutls_openpgp_crt_get_auth_subkey()</code>  will be used to
30639 retrieve the subkey.
30640 </p>
30641 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30642 negative error value.
30643 </p>
30644 <p><strong>Since:</strong> 2.4.0
30645 </p></dd></dl>
30646
30647 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005fmem-1"></a>
30648 <h4 class="subheading">gnutls_certificate_set_openpgp_key_mem</h4>
30649 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005fmem"></a><dl>
30650 <dt><a name="index-gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005fmem"></a>Function: <em>int</em> <strong>gnutls_certificate_set_openpgp_key_mem</strong> <em>(gnutls_certificate_credentials_t            <var>res</var>, const gnutls_datum_t * <var>cert</var>, const gnutls_datum_t * <var>key</var>, gnutls_openpgp_crt_fmt_t <var>format</var>)</em></dt>
30651 <dd><p><var>res</var>: the destination context to save the data.
30652 </p>
30653 <p><var>cert</var>: the datum that contains the public key.
30654 </p>
30655 <p><var>key</var>: the datum that contains the secret key.
30656 </p>
30657 <p><var>format</var>: the format of the keys
30658 </p>
30659 <p>This funtion is used to load OpenPGP keys into the GnuTLS credential
30660 structure. The datum should contain at least one valid non encrypted subkey.
30661 </p>
30662 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30663 negative error value.
30664 </p></dd></dl>
30665
30666 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005fmem2-1"></a>
30667 <h4 class="subheading">gnutls_certificate_set_openpgp_key_mem2</h4>
30668 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005fmem2"></a><dl>
30669 <dt><a name="index-gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005fmem2"></a>Function: <em>int</em> <strong>gnutls_certificate_set_openpgp_key_mem2</strong> <em>(gnutls_certificate_credentials_t      <var>res</var>, const gnutls_datum_t * <var>cert</var>, const gnutls_datum_t * <var>key</var>, const char * <var>subkey_id</var>, gnutls_openpgp_crt_fmt_t <var>format</var>)</em></dt>
30670 <dd><p><var>res</var>: the destination context to save the data.
30671 </p>
30672 <p><var>cert</var>: the datum that contains the public key.
30673 </p>
30674 <p><var>key</var>: the datum that contains the secret key.
30675 </p>
30676 <p><var>subkey_id</var>: a hex encoded subkey id
30677 </p>
30678 <p><var>format</var>: the format of the keys
30679 </p>
30680 <p>This funtion is used to load OpenPGP keys into the GnuTLS
30681 credentials structure. The datum should contain at least one valid non encrypted subkey.
30682 </p>
30683 <p>The special keyword &quot;auto&quot; is also accepted as  <code>subkey_id</code> .  In that
30684 case the <code>gnutls_openpgp_crt_get_auth_subkey()</code>  will be used to
30685 retrieve the subkey.
30686 </p>
30687 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30688 negative error value.
30689 </p>
30690 <p><strong>Since:</strong> 2.4.0
30691 </p></dd></dl>
30692
30693 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005ffile-1"></a>
30694 <h4 class="subheading">gnutls_certificate_set_openpgp_keyring_file</h4>
30695 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005ffile"></a><dl>
30696 <dt><a name="index-gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005ffile-1"></a>Function: <em>int</em> <strong>gnutls_certificate_set_openpgp_keyring_file</strong> <em>(gnutls_certificate_credentials_t <var>c</var>, const char * <var>file</var>, gnutls_openpgp_crt_fmt_t <var>format</var>)</em></dt>
30697 <dd><p><var>c</var>: A certificate credentials structure
30698 </p>
30699 <p><var>file</var>: filename of the keyring.
30700 </p>
30701 <p><var>format</var>: format of keyring.
30702 </p>
30703 <p>The function is used to set keyrings that will be used internally
30704 by various OpenPGP functions. For example to find a key when it
30705 is needed for an operations. The keyring will also be used at the
30706 verification functions.
30707 </p>
30708 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30709 negative error value.
30710 </p></dd></dl>
30711
30712 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005fmem-1"></a>
30713 <h4 class="subheading">gnutls_certificate_set_openpgp_keyring_mem</h4>
30714 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005fmem"></a><dl>
30715 <dt><a name="index-gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005fmem"></a>Function: <em>int</em> <strong>gnutls_certificate_set_openpgp_keyring_mem</strong> <em>(gnutls_certificate_credentials_t         <var>c</var>, const uint8_t * <var>data</var>, size_t <var>dlen</var>, gnutls_openpgp_crt_fmt_t <var>format</var>)</em></dt>
30716 <dd><p><var>c</var>: A certificate credentials structure
30717 </p>
30718 <p><var>data</var>: buffer with keyring data.
30719 </p>
30720 <p><var>dlen</var>: length of data buffer.
30721 </p>
30722 <p><var>format</var>: the format of the keyring
30723 </p>
30724 <p>The function is used to set keyrings that will be used internally
30725 by various OpenPGP functions. For example to find a key when it
30726 is needed for an operations. The keyring will also be used at the
30727 verification functions.
30728 </p>
30729 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
30730 negative error value.
30731 </p></dd></dl>
30732
30733 <a name="gnutls_005fopenpgp_005fcrt_005fcheck_005fhostname-1"></a>
30734 <h4 class="subheading">gnutls_openpgp_crt_check_hostname</h4>
30735 <a name="gnutls_005fopenpgp_005fcrt_005fcheck_005fhostname"></a><dl>
30736 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fcheck_005fhostname"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_check_hostname</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, const char * <var>hostname</var>)</em></dt>
30737 <dd><p><var>key</var>: should contain a <code>gnutls_openpgp_crt_t</code>  structure
30738 </p>
30739 <p><var>hostname</var>: A null terminated string that contains a DNS name
30740 </p>
30741 <p>This function will check if the given key&rsquo;s owner matches the
30742 given hostname. This is a basic implementation of the matching
30743 described in RFC2818 (HTTPS), which takes into account wildcards.
30744 </p>
30745 <p><strong>Returns:</strong> non-zero for a successful match, and zero on failure.
30746 </p></dd></dl>
30747
30748 <a name="gnutls_005fopenpgp_005fcrt_005fcheck_005fhostname2-1"></a>
30749 <h4 class="subheading">gnutls_openpgp_crt_check_hostname2</h4>
30750 <a name="gnutls_005fopenpgp_005fcrt_005fcheck_005fhostname2"></a><dl>
30751 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fcheck_005fhostname2"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_check_hostname2</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, const char * <var>hostname</var>, unsigned <var>flags</var>)</em></dt>
30752 <dd><p><var>key</var>: should contain a <code>gnutls_openpgp_crt_t</code>  structure
30753 </p>
30754 <p><var>hostname</var>: A null terminated string that contains a DNS name
30755 </p>
30756 <p><var>flags</var>: gnutls_certificate_verify_flags
30757 </p>
30758 <p>This function will check if the given key&rsquo;s owner matches the
30759 given hostname.
30760 </p>
30761 <p>Unless, the flag <code>GNUTLS_VERIFY_DO_NOT_ALLOW_WILDCARDS</code>  is specified,
30762 wildcards are only considered if the domain name consists of three
30763 components or more, and the wildcard starts at the leftmost position.
30764 </p>
30765 <p><strong>Returns:</strong> non-zero for a successful match, and zero on failure.
30766 </p></dd></dl>
30767
30768 <a name="gnutls_005fopenpgp_005fcrt_005fdeinit-1"></a>
30769 <h4 class="subheading">gnutls_openpgp_crt_deinit</h4>
30770 <a name="gnutls_005fopenpgp_005fcrt_005fdeinit"></a><dl>
30771 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_openpgp_crt_deinit</strong> <em>(gnutls_openpgp_crt_t <var>key</var>)</em></dt>
30772 <dd><p><var>key</var>: The structure to be initialized
30773 </p>
30774 <p>This function will deinitialize a key structure.
30775 </p></dd></dl>
30776
30777 <a name="gnutls_005fopenpgp_005fcrt_005fexport-1"></a>
30778 <h4 class="subheading">gnutls_openpgp_crt_export</h4>
30779 <a name="gnutls_005fopenpgp_005fcrt_005fexport"></a><dl>
30780 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fexport"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_export</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, gnutls_openpgp_crt_fmt_t <var>format</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
30781 <dd><p><var>key</var>: Holds the key.
30782 </p>
30783 <p><var>format</var>: One of gnutls_openpgp_crt_fmt_t elements.
30784 </p>
30785 <p><var>output_data</var>: will contain the raw or base64 encoded key
30786 </p>
30787 <p><var>output_data_size</var>: holds the size of output_data (and will
30788 be replaced by the actual size of parameters)
30789 </p>
30790 <p>This function will convert the given key to RAW or Base64 format.
30791 If the buffer provided is not long enough to hold the output, then
30792 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  will be returned.
30793 </p>
30794 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
30795 </p></dd></dl>
30796
30797 <a name="gnutls_005fopenpgp_005fcrt_005fexport2-1"></a>
30798 <h4 class="subheading">gnutls_openpgp_crt_export2</h4>
30799 <a name="gnutls_005fopenpgp_005fcrt_005fexport2"></a><dl>
30800 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fexport2"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_export2</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, gnutls_openpgp_crt_fmt_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
30801 <dd><p><var>key</var>: Holds the key.
30802 </p>
30803 <p><var>format</var>: One of gnutls_openpgp_crt_fmt_t elements.
30804 </p>
30805 <p><var>out</var>: will contain the raw or base64 encoded key
30806 </p>
30807 <p>This function will convert the given key to RAW or Base64 format.
30808 The output buffer is allocated using <code>gnutls_malloc()</code> .
30809 </p>
30810 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
30811 </p>
30812 <p><strong>Since:</strong> 3.1.3
30813 </p></dd></dl>
30814
30815 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fauth_005fsubkey-1"></a>
30816 <h4 class="subheading">gnutls_openpgp_crt_get_auth_subkey</h4>
30817 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fauth_005fsubkey"></a><dl>
30818 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fauth_005fsubkey"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_auth_subkey</strong> <em>(gnutls_openpgp_crt_t <var>crt</var>, gnutls_openpgp_keyid_t <var>keyid</var>, unsigned int <var>flag</var>)</em></dt>
30819 <dd><p><var>crt</var>: the structure that contains the OpenPGP public key.
30820 </p>
30821 <p><var>keyid</var>: the struct to save the keyid.
30822 </p>
30823 <p><var>flag</var>: Non-zero indicates that a valid subkey is always returned.
30824 </p>
30825 <p>Returns the 64-bit keyID of the first valid OpenPGP subkey marked
30826 for authentication.  If flag is non-zero and no authentication
30827 subkey exists, then a valid subkey will be returned even if it is
30828 not marked for authentication.
30829 </p>
30830 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
30831 </p></dd></dl>
30832
30833 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fcreation_005ftime-1"></a>
30834 <h4 class="subheading">gnutls_openpgp_crt_get_creation_time</h4>
30835 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fcreation_005ftime"></a><dl>
30836 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fcreation_005ftime"></a>Function: <em>time_t</em> <strong>gnutls_openpgp_crt_get_creation_time</strong> <em>(gnutls_openpgp_crt_t <var>key</var>)</em></dt>
30837 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
30838 </p>
30839 <p>Get key creation time.
30840 </p>
30841 <p><strong>Returns:</strong> the timestamp when the OpenPGP key was created.
30842 </p></dd></dl>
30843
30844 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fexpiration_005ftime-1"></a>
30845 <h4 class="subheading">gnutls_openpgp_crt_get_expiration_time</h4>
30846 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fexpiration_005ftime"></a><dl>
30847 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fexpiration_005ftime"></a>Function: <em>time_t</em> <strong>gnutls_openpgp_crt_get_expiration_time</strong> <em>(gnutls_openpgp_crt_t <var>key</var>)</em></dt>
30848 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
30849 </p>
30850 <p>Get key expiration time.  A value of &rsquo;0&rsquo; means that the key doesn&rsquo;t
30851 expire at all.
30852 </p>
30853 <p><strong>Returns:</strong> the time when the OpenPGP key expires.
30854 </p></dd></dl>
30855
30856 <a name="gnutls_005fopenpgp_005fcrt_005fget_005ffingerprint-1"></a>
30857 <h4 class="subheading">gnutls_openpgp_crt_get_fingerprint</h4>
30858 <a name="gnutls_005fopenpgp_005fcrt_005fget_005ffingerprint"></a><dl>
30859 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005ffingerprint"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_fingerprint</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, void * <var>fpr</var>, size_t * <var>fprlen</var>)</em></dt>
30860 <dd><p><var>key</var>: the raw data that contains the OpenPGP public key.
30861 </p>
30862 <p><var>fpr</var>: the buffer to save the fingerprint, must hold at least 20 bytes.
30863 </p>
30864 <p><var>fprlen</var>: the integer to save the length of the fingerprint.
30865 </p>
30866 <p>Get key fingerprint.  Depending on the algorithm, the fingerprint
30867 can be 16 or 20 bytes.
30868 </p>
30869 <p><strong>Returns:</strong> On success, 0 is returned.  Otherwise, an error code.
30870 </p></dd></dl>
30871
30872 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fkey_005fid-1"></a>
30873 <h4 class="subheading">gnutls_openpgp_crt_get_key_id</h4>
30874 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fkey_005fid"></a><dl>
30875 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_key_id</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, gnutls_openpgp_keyid_t <var>keyid</var>)</em></dt>
30876 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
30877 </p>
30878 <p><var>keyid</var>: the buffer to save the keyid.
30879 </p>
30880 <p>Get key id string.
30881 </p>
30882 <p><strong>Returns:</strong> the 64-bit keyID of the OpenPGP key.
30883 </p>
30884 <p><strong>Since:</strong> 2.4.0
30885 </p></dd></dl>
30886
30887 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fkey_005fusage-1"></a>
30888 <h4 class="subheading">gnutls_openpgp_crt_get_key_usage</h4>
30889 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fkey_005fusage"></a><dl>
30890 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fkey_005fusage"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_key_usage</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, unsigned int * <var>key_usage</var>)</em></dt>
30891 <dd><p><var>key</var>: should contain a gnutls_openpgp_crt_t structure
30892 </p>
30893 <p><var>key_usage</var>: where the key usage bits will be stored
30894 </p>
30895 <p>This function will return certificate&rsquo;s key usage, by checking the
30896 key algorithm. The key usage value will ORed values of the:
30897 <code>GNUTLS_KEY_DIGITAL_SIGNATURE</code> , <code>GNUTLS_KEY_KEY_ENCIPHERMENT</code> .
30898 </p>
30899 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
30900 </p></dd></dl>
30901
30902 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fname-1"></a>
30903 <h4 class="subheading">gnutls_openpgp_crt_get_name</h4>
30904 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fname"></a><dl>
30905 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fname"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_name</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, int <var>idx</var>, char * <var>buf</var>, size_t * <var>sizeof_buf</var>)</em></dt>
30906 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
30907 </p>
30908 <p><var>idx</var>: the index of the ID to extract
30909 </p>
30910 <p><var>buf</var>: a pointer to a structure to hold the name, may be <code>NULL</code>
30911 to only get the  <code>sizeof_buf</code> .
30912 </p>
30913 <p><var>sizeof_buf</var>: holds the maximum size of  <code>buf</code> , on return hold the
30914 actual/required size of  <code>buf</code> .
30915 </p>
30916 <p>Extracts the userID from the parsed OpenPGP key.
30917 </p>
30918 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, and if the index of the ID
30919 does not exist <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> , or an
30920 error code.
30921 </p></dd></dl>
30922
30923 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpk_005falgorithm-1"></a>
30924 <h4 class="subheading">gnutls_openpgp_crt_get_pk_algorithm</h4>
30925 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpk_005falgorithm"></a><dl>
30926 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fpk_005falgorithm"></a>Function: <em>gnutls_pk_algorithm_t</em> <strong>gnutls_openpgp_crt_get_pk_algorithm</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, unsigned int * <var>bits</var>)</em></dt>
30927 <dd><p><var>key</var>: is an OpenPGP key
30928 </p>
30929 <p><var>bits</var>: if bits is non null it will hold the size of the parameters&rsquo; in bits
30930 </p>
30931 <p>This function will return the public key algorithm of an OpenPGP
30932 certificate.
30933 </p>
30934 <p>If bits is non null, it should have enough size to hold the parameters
30935 size in bits. For RSA the bits returned is the modulus.
30936 For DSA the bits returned are of the public exponent.
30937 </p>
30938 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code>  enumeration on
30939 success, or GNUTLS_PK_UNKNOWN on error.
30940 </p></dd></dl>
30941
30942 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpk_005fdsa_005fraw-1"></a>
30943 <h4 class="subheading">gnutls_openpgp_crt_get_pk_dsa_raw</h4>
30944 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpk_005fdsa_005fraw"></a><dl>
30945 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fpk_005fdsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_pk_dsa_raw</strong> <em>(gnutls_openpgp_crt_t <var>crt</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>g</var>, gnutls_datum_t * <var>y</var>)</em></dt>
30946 <dd><p><var>crt</var>: Holds the certificate
30947 </p>
30948 <p><var>p</var>: will hold the p
30949 </p>
30950 <p><var>q</var>: will hold the q
30951 </p>
30952 <p><var>g</var>: will hold the g
30953 </p>
30954 <p><var>y</var>: will hold the y
30955 </p>
30956 <p>This function will export the DSA public key&rsquo;s parameters found in
30957 the given certificate.  The new parameters will be allocated using
30958 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
30959 </p>
30960 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
30961 </p>
30962 <p><strong>Since:</strong> 2.4.0
30963 </p></dd></dl>
30964
30965 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpk_005frsa_005fraw-1"></a>
30966 <h4 class="subheading">gnutls_openpgp_crt_get_pk_rsa_raw</h4>
30967 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpk_005frsa_005fraw"></a><dl>
30968 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fpk_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_pk_rsa_raw</strong> <em>(gnutls_openpgp_crt_t <var>crt</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>)</em></dt>
30969 <dd><p><var>crt</var>: Holds the certificate
30970 </p>
30971 <p><var>m</var>: will hold the modulus
30972 </p>
30973 <p><var>e</var>: will hold the public exponent
30974 </p>
30975 <p>This function will export the RSA public key&rsquo;s parameters found in
30976 the given structure.  The new parameters will be allocated using
30977 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
30978 </p>
30979 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
30980 </p>
30981 <p><strong>Since:</strong> 2.4.0
30982 </p></dd></dl>
30983
30984 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpreferred_005fkey_005fid-1"></a>
30985 <h4 class="subheading">gnutls_openpgp_crt_get_preferred_key_id</h4>
30986 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpreferred_005fkey_005fid"></a><dl>
30987 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fpreferred_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_preferred_key_id</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, gnutls_openpgp_keyid_t <var>keyid</var>)</em></dt>
30988 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
30989 </p>
30990 <p><var>keyid</var>: the struct to save the keyid.
30991 </p>
30992 <p>Get preferred key id.  If it hasn&rsquo;t been set it returns
30993 <code>GNUTLS_E_INVALID_REQUEST</code> .
30994 </p>
30995 <p><strong>Returns:</strong> the 64-bit preferred keyID of the OpenPGP key.
30996 </p></dd></dl>
30997
30998 <a name="gnutls_005fopenpgp_005fcrt_005fget_005frevoked_005fstatus-1"></a>
30999 <h4 class="subheading">gnutls_openpgp_crt_get_revoked_status</h4>
31000 <a name="gnutls_005fopenpgp_005fcrt_005fget_005frevoked_005fstatus"></a><dl>
31001 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005frevoked_005fstatus"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_revoked_status</strong> <em>(gnutls_openpgp_crt_t <var>key</var>)</em></dt>
31002 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
31003 </p>
31004 <p>Get revocation status of key.
31005 </p>
31006 <p><strong>Returns:</strong> true (1) if the key has been revoked, or false (0) if it
31007 has not.
31008 </p>
31009 <p><strong>Since:</strong> 2.4.0
31010 </p></dd></dl>
31011
31012 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fcount-1"></a>
31013 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_count</h4>
31014 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fcount"></a><dl>
31015 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fcount"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_subkey_count</strong> <em>(gnutls_openpgp_crt_t <var>key</var>)</em></dt>
31016 <dd><p><var>key</var>: is an OpenPGP key
31017 </p>
31018 <p>This function will return the number of subkeys present in the
31019 given OpenPGP certificate.
31020 </p>
31021 <p><strong>Returns:</strong> the number of subkeys, or a negative error code on error.
31022 </p>
31023 <p><strong>Since:</strong> 2.4.0
31024 </p></dd></dl>
31025
31026 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fcreation_005ftime-1"></a>
31027 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_creation_time</h4>
31028 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fcreation_005ftime"></a><dl>
31029 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fcreation_005ftime"></a>Function: <em>time_t</em> <strong>gnutls_openpgp_crt_get_subkey_creation_time</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, unsigned int <var>idx</var>)</em></dt>
31030 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
31031 </p>
31032 <p><var>idx</var>: the subkey index
31033 </p>
31034 <p>Get subkey creation time.
31035 </p>
31036 <p><strong>Returns:</strong> the timestamp when the OpenPGP sub-key was created.
31037 </p>
31038 <p><strong>Since:</strong> 2.4.0
31039 </p></dd></dl>
31040
31041 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fexpiration_005ftime-1"></a>
31042 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_expiration_time</h4>
31043 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fexpiration_005ftime"></a><dl>
31044 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fexpiration_005ftime"></a>Function: <em>time_t</em> <strong>gnutls_openpgp_crt_get_subkey_expiration_time</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, unsigned int <var>idx</var>)</em></dt>
31045 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
31046 </p>
31047 <p><var>idx</var>: the subkey index
31048 </p>
31049 <p>Get subkey expiration time.  A value of &rsquo;0&rsquo; means that the key
31050 doesn&rsquo;t expire at all.
31051 </p>
31052 <p><strong>Returns:</strong> the time when the OpenPGP key expires.
31053 </p>
31054 <p><strong>Since:</strong> 2.4.0
31055 </p></dd></dl>
31056
31057 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005ffingerprint-1"></a>
31058 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_fingerprint</h4>
31059 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005ffingerprint"></a><dl>
31060 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005ffingerprint"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_subkey_fingerprint</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, unsigned int <var>idx</var>, void * <var>fpr</var>, size_t * <var>fprlen</var>)</em></dt>
31061 <dd><p><var>key</var>: the raw data that contains the OpenPGP public key.
31062 </p>
31063 <p><var>idx</var>: the subkey index
31064 </p>
31065 <p><var>fpr</var>: the buffer to save the fingerprint, must hold at least 20 bytes.
31066 </p>
31067 <p><var>fprlen</var>: the integer to save the length of the fingerprint.
31068 </p>
31069 <p>Get key fingerprint of a subkey.  Depending on the algorithm, the
31070 fingerprint can be 16 or 20 bytes.
31071 </p>
31072 <p><strong>Returns:</strong> On success, 0 is returned.  Otherwise, an error code.
31073 </p>
31074 <p><strong>Since:</strong> 2.4.0
31075 </p></dd></dl>
31076
31077 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fid-1"></a>
31078 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_id</h4>
31079 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fid"></a><dl>
31080 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fid"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_subkey_id</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, unsigned int <var>idx</var>, gnutls_openpgp_keyid_t <var>keyid</var>)</em></dt>
31081 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
31082 </p>
31083 <p><var>idx</var>: the subkey index
31084 </p>
31085 <p><var>keyid</var>: the buffer to save the keyid.
31086 </p>
31087 <p>Get the subkey&rsquo;s key-id.
31088 </p>
31089 <p><strong>Returns:</strong> the 64-bit keyID of the OpenPGP key.
31090 </p></dd></dl>
31091
31092 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fidx-1"></a>
31093 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_idx</h4>
31094 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fidx"></a><dl>
31095 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fidx"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_subkey_idx</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, const gnutls_openpgp_keyid_t <var>keyid</var>)</em></dt>
31096 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
31097 </p>
31098 <p><var>keyid</var>: the keyid.
31099 </p>
31100 <p>Get subkey&rsquo;s index.
31101 </p>
31102 <p><strong>Returns:</strong> the index of the subkey or a negative error value.
31103 </p>
31104 <p><strong>Since:</strong> 2.4.0
31105 </p></dd></dl>
31106
31107 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005falgorithm-1"></a>
31108 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_pk_algorithm</h4>
31109 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005falgorithm"></a><dl>
31110 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005falgorithm"></a>Function: <em>gnutls_pk_algorithm_t</em> <strong>gnutls_openpgp_crt_get_subkey_pk_algorithm</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, unsigned int <var>idx</var>, unsigned int * <var>bits</var>)</em></dt>
31111 <dd><p><var>key</var>: is an OpenPGP key
31112 </p>
31113 <p><var>idx</var>: is the subkey index
31114 </p>
31115 <p><var>bits</var>: if bits is non null it will hold the size of the parameters&rsquo; in bits
31116 </p>
31117 <p>This function will return the public key algorithm of a subkey of an OpenPGP
31118 certificate.
31119 </p>
31120 <p>If bits is non null, it should have enough size to hold the
31121 parameters size in bits.  For RSA the bits returned is the modulus.
31122 For DSA the bits returned are of the public exponent.
31123 </p>
31124 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code>  enumeration on
31125 success, or GNUTLS_PK_UNKNOWN on error.
31126 </p>
31127 <p><strong>Since:</strong> 2.4.0
31128 </p></dd></dl>
31129
31130 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005fdsa_005fraw-1"></a>
31131 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_pk_dsa_raw</h4>
31132 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005fdsa_005fraw"></a><dl>
31133 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005fdsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_subkey_pk_dsa_raw</strong> <em>(gnutls_openpgp_crt_t <var>crt</var>, unsigned int <var>idx</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>g</var>, gnutls_datum_t * <var>y</var>)</em></dt>
31134 <dd><p><var>crt</var>: Holds the certificate
31135 </p>
31136 <p><var>idx</var>: Is the subkey index
31137 </p>
31138 <p><var>p</var>: will hold the p
31139 </p>
31140 <p><var>q</var>: will hold the q
31141 </p>
31142 <p><var>g</var>: will hold the g
31143 </p>
31144 <p><var>y</var>: will hold the y
31145 </p>
31146 <p>This function will export the DSA public key&rsquo;s parameters found in
31147 the given certificate.  The new parameters will be allocated using
31148 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
31149 </p>
31150 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
31151 </p>
31152 <p><strong>Since:</strong> 2.4.0
31153 </p></dd></dl>
31154
31155 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005frsa_005fraw-1"></a>
31156 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_pk_rsa_raw</h4>
31157 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005frsa_005fraw"></a><dl>
31158 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_subkey_pk_rsa_raw</strong> <em>(gnutls_openpgp_crt_t <var>crt</var>, unsigned int <var>idx</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>)</em></dt>
31159 <dd><p><var>crt</var>: Holds the certificate
31160 </p>
31161 <p><var>idx</var>: Is the subkey index
31162 </p>
31163 <p><var>m</var>: will hold the modulus
31164 </p>
31165 <p><var>e</var>: will hold the public exponent
31166 </p>
31167 <p>This function will export the RSA public key&rsquo;s parameters found in
31168 the given structure.  The new parameters will be allocated using
31169 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
31170 </p>
31171 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
31172 </p>
31173 <p><strong>Since:</strong> 2.4.0
31174 </p></dd></dl>
31175
31176 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005frevoked_005fstatus-1"></a>
31177 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_revoked_status</h4>
31178 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005frevoked_005fstatus"></a><dl>
31179 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005frevoked_005fstatus"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_subkey_revoked_status</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, unsigned int <var>idx</var>)</em></dt>
31180 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
31181 </p>
31182 <p><var>idx</var>: is the subkey index
31183 </p>
31184 <p>Get subkey revocation status.  A negative error code indicates an error.
31185 </p>
31186 <p><strong>Returns:</strong> true (1) if the key has been revoked, or false (0) if it
31187 has not.
31188 </p>
31189 <p><strong>Since:</strong> 2.4.0
31190 </p></dd></dl>
31191
31192 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fusage-1"></a>
31193 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_usage</h4>
31194 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fusage"></a><dl>
31195 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fusage"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_subkey_usage</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, unsigned int <var>idx</var>, unsigned int * <var>key_usage</var>)</em></dt>
31196 <dd><p><var>key</var>: should contain a gnutls_openpgp_crt_t structure
31197 </p>
31198 <p><var>idx</var>: the subkey index
31199 </p>
31200 <p><var>key_usage</var>: where the key usage bits will be stored
31201 </p>
31202 <p>This function will return certificate&rsquo;s key usage, by checking the
31203 key algorithm.  The key usage value will ORed values of
31204 <code>GNUTLS_KEY_DIGITAL_SIGNATURE</code>  or <code>GNUTLS_KEY_KEY_ENCIPHERMENT</code> .
31205 </p>
31206 <p>A negative error code may be returned in case of parsing error.
31207 </p>
31208 <p><strong>Returns:</strong> key usage value.
31209 </p>
31210 <p><strong>Since:</strong> 2.4.0
31211 </p></dd></dl>
31212
31213 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fversion-1"></a>
31214 <h4 class="subheading">gnutls_openpgp_crt_get_version</h4>
31215 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fversion"></a><dl>
31216 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fget_005fversion"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_get_version</strong> <em>(gnutls_openpgp_crt_t <var>key</var>)</em></dt>
31217 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
31218 </p>
31219 <p>Extract the version of the OpenPGP key.
31220 </p>
31221 <p><strong>Returns:</strong> the version number is returned, or a negative error code on errors.
31222 </p></dd></dl>
31223
31224 <a name="gnutls_005fopenpgp_005fcrt_005fimport-1"></a>
31225 <h4 class="subheading">gnutls_openpgp_crt_import</h4>
31226 <a name="gnutls_005fopenpgp_005fcrt_005fimport"></a><dl>
31227 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fimport"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_import</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, const gnutls_datum_t * <var>data</var>, gnutls_openpgp_crt_fmt_t <var>format</var>)</em></dt>
31228 <dd><p><var>key</var>: The structure to store the parsed key.
31229 </p>
31230 <p><var>data</var>: The RAW or BASE64 encoded key.
31231 </p>
31232 <p><var>format</var>: One of gnutls_openpgp_crt_fmt_t elements.
31233 </p>
31234 <p>This function will convert the given RAW or Base64 encoded key to
31235 the native <code>gnutls_openpgp_crt_t</code>  format. The output will be stored
31236 in &rsquo;key&rsquo;.
31237 </p>
31238 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
31239 </p></dd></dl>
31240
31241 <a name="gnutls_005fopenpgp_005fcrt_005finit-1"></a>
31242 <h4 class="subheading">gnutls_openpgp_crt_init</h4>
31243 <a name="gnutls_005fopenpgp_005fcrt_005finit"></a><dl>
31244 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005finit"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_init</strong> <em>(gnutls_openpgp_crt_t * <var>key</var>)</em></dt>
31245 <dd><p><var>key</var>: The structure to be initialized
31246 </p>
31247 <p>This function will initialize an OpenPGP key structure.
31248 </p>
31249 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
31250 </p></dd></dl>
31251
31252 <a name="gnutls_005fopenpgp_005fcrt_005fprint-1"></a>
31253 <h4 class="subheading">gnutls_openpgp_crt_print</h4>
31254 <a name="gnutls_005fopenpgp_005fcrt_005fprint"></a><dl>
31255 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fprint"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_print</strong> <em>(gnutls_openpgp_crt_t <var>cert</var>, gnutls_certificate_print_formats_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
31256 <dd><p><var>cert</var>: The structure to be printed
31257 </p>
31258 <p><var>format</var>: Indicate the format to use
31259 </p>
31260 <p><var>out</var>: Newly allocated datum with (0) terminated string.
31261 </p>
31262 <p>This function will pretty print an OpenPGP certificate, suitable
31263 for display to a human.
31264 </p>
31265 <p>The format should be (0) for future compatibility.
31266 </p>
31267 <p>The output  <code>out</code> needs to be deallocate using <code>gnutls_free()</code> .
31268 </p>
31269 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
31270 </p></dd></dl>
31271
31272 <a name="gnutls_005fopenpgp_005fcrt_005fset_005fpreferred_005fkey_005fid-1"></a>
31273 <h4 class="subheading">gnutls_openpgp_crt_set_preferred_key_id</h4>
31274 <a name="gnutls_005fopenpgp_005fcrt_005fset_005fpreferred_005fkey_005fid"></a><dl>
31275 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fset_005fpreferred_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_set_preferred_key_id</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, const gnutls_openpgp_keyid_t <var>keyid</var>)</em></dt>
31276 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
31277 </p>
31278 <p><var>keyid</var>: the selected keyid
31279 </p>
31280 <p>This allows setting a preferred key id for the given certificate.
31281 This key will be used by functions that involve key handling.
31282 </p>
31283 <p>If the provided  <code>keyid</code> is <code>NULL</code>  then the master key is
31284 set as preferred.
31285 </p>
31286 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
31287 otherwise a negative error code is returned.
31288 </p></dd></dl>
31289
31290 <a name="gnutls_005fopenpgp_005fcrt_005fverify_005fring-1"></a>
31291 <h4 class="subheading">gnutls_openpgp_crt_verify_ring</h4>
31292 <a name="gnutls_005fopenpgp_005fcrt_005fverify_005fring"></a><dl>
31293 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fverify_005fring-1"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_verify_ring</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, gnutls_openpgp_keyring_t <var>keyring</var>, unsigned int <var>flags</var>, unsigned int * <var>verify</var>)</em></dt>
31294 <dd><p><var>key</var>: the structure that holds the key.
31295 </p>
31296 <p><var>keyring</var>: holds the keyring to check against
31297 </p>
31298 <p><var>flags</var>: unused (should be 0)
31299 </p>
31300 <p><var>verify</var>: will hold the certificate verification output.
31301 </p>
31302 <p>Verify all signatures in the key, using the given set of keys
31303 (keyring).
31304 </p>
31305 <p>The key verification output will be put in  <code>verify</code> and will be one
31306 or more of the <code>gnutls_certificate_status_t</code>  enumerated elements
31307 bitwise or&rsquo;d.
31308 </p>
31309 <p>Note that this function does not verify using any &quot;web of trust&quot;.
31310 You may use GnuPG for that purpose, or any other external PGP
31311 application.
31312 </p>
31313 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
31314 </p></dd></dl>
31315
31316 <a name="gnutls_005fopenpgp_005fcrt_005fverify_005fself-1"></a>
31317 <h4 class="subheading">gnutls_openpgp_crt_verify_self</h4>
31318 <a name="gnutls_005fopenpgp_005fcrt_005fverify_005fself"></a><dl>
31319 <dt><a name="index-gnutls_005fopenpgp_005fcrt_005fverify_005fself-1"></a>Function: <em>int</em> <strong>gnutls_openpgp_crt_verify_self</strong> <em>(gnutls_openpgp_crt_t <var>key</var>, unsigned int <var>flags</var>, unsigned int * <var>verify</var>)</em></dt>
31320 <dd><p><var>key</var>: the structure that holds the key.
31321 </p>
31322 <p><var>flags</var>: unused (should be 0)
31323 </p>
31324 <p><var>verify</var>: will hold the key verification output.
31325 </p>
31326 <p>Verifies the self signature in the key.  The key verification
31327 output will be put in  <code>verify</code> and will be one or more of the
31328 gnutls_certificate_status_t enumerated elements bitwise or&rsquo;d.
31329 </p>
31330 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
31331 </p></dd></dl>
31332
31333 <a name="gnutls_005fopenpgp_005fkeyring_005fcheck_005fid-1"></a>
31334 <h4 class="subheading">gnutls_openpgp_keyring_check_id</h4>
31335 <a name="gnutls_005fopenpgp_005fkeyring_005fcheck_005fid"></a><dl>
31336 <dt><a name="index-gnutls_005fopenpgp_005fkeyring_005fcheck_005fid"></a>Function: <em>int</em> <strong>gnutls_openpgp_keyring_check_id</strong> <em>(gnutls_openpgp_keyring_t <var>ring</var>, const gnutls_openpgp_keyid_t <var>keyid</var>, unsigned int <var>flags</var>)</em></dt>
31337 <dd><p><var>ring</var>: holds the keyring to check against
31338 </p>
31339 <p><var>keyid</var>: will hold the keyid to check for.
31340 </p>
31341 <p><var>flags</var>: unused (should be 0)
31342 </p>
31343 <p>Check if a given key ID exists in the keyring.
31344 </p>
31345 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success (if keyid exists) and a
31346 negative error code on failure.
31347 </p></dd></dl>
31348
31349 <a name="gnutls_005fopenpgp_005fkeyring_005fdeinit-1"></a>
31350 <h4 class="subheading">gnutls_openpgp_keyring_deinit</h4>
31351 <a name="gnutls_005fopenpgp_005fkeyring_005fdeinit"></a><dl>
31352 <dt><a name="index-gnutls_005fopenpgp_005fkeyring_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_openpgp_keyring_deinit</strong> <em>(gnutls_openpgp_keyring_t <var>keyring</var>)</em></dt>
31353 <dd><p><var>keyring</var>: A pointer to the type to be initialized
31354 </p>
31355 <p>This function will deinitialize a keyring structure.
31356 </p></dd></dl>
31357
31358 <a name="gnutls_005fopenpgp_005fkeyring_005fget_005fcrt-1"></a>
31359 <h4 class="subheading">gnutls_openpgp_keyring_get_crt</h4>
31360 <a name="gnutls_005fopenpgp_005fkeyring_005fget_005fcrt"></a><dl>
31361 <dt><a name="index-gnutls_005fopenpgp_005fkeyring_005fget_005fcrt"></a>Function: <em>int</em> <strong>gnutls_openpgp_keyring_get_crt</strong> <em>(gnutls_openpgp_keyring_t <var>ring</var>, unsigned int <var>idx</var>, gnutls_openpgp_crt_t * <var>cert</var>)</em></dt>
31362 <dd><p><var>ring</var>: Holds the keyring.
31363 </p>
31364 <p><var>idx</var>: the index of the certificate to export
31365 </p>
31366 <p><var>cert</var>: An uninitialized <code>gnutls_openpgp_crt_t</code>  type
31367 </p>
31368 <p>This function will extract an OpenPGP certificate from the given
31369 keyring.  If the index given is out of range
31370 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be returned. The
31371 returned structure needs to be deinited.
31372 </p>
31373 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
31374 </p></dd></dl>
31375
31376 <a name="gnutls_005fopenpgp_005fkeyring_005fget_005fcrt_005fcount-1"></a>
31377 <h4 class="subheading">gnutls_openpgp_keyring_get_crt_count</h4>
31378 <a name="gnutls_005fopenpgp_005fkeyring_005fget_005fcrt_005fcount"></a><dl>
31379 <dt><a name="index-gnutls_005fopenpgp_005fkeyring_005fget_005fcrt_005fcount"></a>Function: <em>int</em> <strong>gnutls_openpgp_keyring_get_crt_count</strong> <em>(gnutls_openpgp_keyring_t <var>ring</var>)</em></dt>
31380 <dd><p><var>ring</var>: is an OpenPGP key ring
31381 </p>
31382 <p>This function will return the number of OpenPGP certificates
31383 present in the given keyring.
31384 </p>
31385 <p><strong>Returns:</strong> the number of subkeys, or a negative error code on error.
31386 </p></dd></dl>
31387
31388 <a name="gnutls_005fopenpgp_005fkeyring_005fimport-1"></a>
31389 <h4 class="subheading">gnutls_openpgp_keyring_import</h4>
31390 <a name="gnutls_005fopenpgp_005fkeyring_005fimport"></a><dl>
31391 <dt><a name="index-gnutls_005fopenpgp_005fkeyring_005fimport"></a>Function: <em>int</em> <strong>gnutls_openpgp_keyring_import</strong> <em>(gnutls_openpgp_keyring_t <var>keyring</var>, const gnutls_datum_t * <var>data</var>, gnutls_openpgp_crt_fmt_t <var>format</var>)</em></dt>
31392 <dd><p><var>keyring</var>: The structure to store the parsed key.
31393 </p>
31394 <p><var>data</var>: The RAW or BASE64 encoded keyring.
31395 </p>
31396 <p><var>format</var>: One of <code>gnutls_openpgp_keyring_fmt</code>  elements.
31397 </p>
31398 <p>This function will convert the given RAW or Base64 encoded keyring
31399 to the native <code>gnutls_openpgp_keyring_t</code>  format.  The output will be
31400 stored in &rsquo;keyring&rsquo;.
31401 </p>
31402 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
31403 </p></dd></dl>
31404
31405 <a name="gnutls_005fopenpgp_005fkeyring_005finit-1"></a>
31406 <h4 class="subheading">gnutls_openpgp_keyring_init</h4>
31407 <a name="gnutls_005fopenpgp_005fkeyring_005finit"></a><dl>
31408 <dt><a name="index-gnutls_005fopenpgp_005fkeyring_005finit"></a>Function: <em>int</em> <strong>gnutls_openpgp_keyring_init</strong> <em>(gnutls_openpgp_keyring_t * <var>keyring</var>)</em></dt>
31409 <dd><p><var>keyring</var>: A pointer to the type to be initialized
31410 </p>
31411 <p>This function will initialize an keyring structure.
31412 </p>
31413 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
31414 </p></dd></dl>
31415
31416 <a name="gnutls_005fopenpgp_005fprivkey_005fdeinit-1"></a>
31417 <h4 class="subheading">gnutls_openpgp_privkey_deinit</h4>
31418 <a name="gnutls_005fopenpgp_005fprivkey_005fdeinit"></a><dl>
31419 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_openpgp_privkey_deinit</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>)</em></dt>
31420 <dd><p><var>key</var>: The structure to be initialized
31421 </p>
31422 <p>This function will deinitialize a key structure.
31423 </p></dd></dl>
31424
31425 <a name="gnutls_005fopenpgp_005fprivkey_005fexport-1"></a>
31426 <h4 class="subheading">gnutls_openpgp_privkey_export</h4>
31427 <a name="gnutls_005fopenpgp_005fprivkey_005fexport"></a><dl>
31428 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fexport"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_export</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>, gnutls_openpgp_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
31429 <dd><p><var>key</var>: Holds the key.
31430 </p>
31431 <p><var>format</var>: One of gnutls_openpgp_crt_fmt_t elements.
31432 </p>
31433 <p><var>password</var>: the password that will be used to encrypt the key. (unused for now)
31434 </p>
31435 <p><var>flags</var>: (0) for future compatibility
31436 </p>
31437 <p><var>output_data</var>: will contain the key base64 encoded or raw
31438 </p>
31439 <p><var>output_data_size</var>: holds the size of output_data (and will be
31440 replaced by the actual size of parameters)
31441 </p>
31442 <p>This function will convert the given key to RAW or Base64 format.
31443 If the buffer provided is not long enough to hold the output, then
31444 GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
31445 </p>
31446 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
31447 </p>
31448 <p><strong>Since:</strong> 2.4.0
31449 </p></dd></dl>
31450
31451 <a name="gnutls_005fopenpgp_005fprivkey_005fexport2-1"></a>
31452 <h4 class="subheading">gnutls_openpgp_privkey_export2</h4>
31453 <a name="gnutls_005fopenpgp_005fprivkey_005fexport2"></a><dl>
31454 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fexport2"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_export2</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>, gnutls_openpgp_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>, gnutls_datum_t * <var>out</var>)</em></dt>
31455 <dd><p><var>key</var>: Holds the key.
31456 </p>
31457 <p><var>format</var>: One of gnutls_openpgp_crt_fmt_t elements.
31458 </p>
31459 <p><var>password</var>: the password that will be used to encrypt the key. (unused for now)
31460 </p>
31461 <p><var>flags</var>: (0) for future compatibility
31462 </p>
31463 <p><var>out</var>: will contain the raw or based64 encoded key
31464 </p>
31465 <p>This function will convert the given key to RAW or Base64 format.
31466 The output buffer is allocated using <code>gnutls_malloc()</code> .
31467 </p>
31468 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
31469 </p>
31470 <p><strong>Since:</strong> 3.1.3
31471 </p></dd></dl>
31472
31473 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005fdsa_005fraw-1"></a>
31474 <h4 class="subheading">gnutls_openpgp_privkey_export_dsa_raw</h4>
31475 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005fdsa_005fraw"></a><dl>
31476 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fexport_005fdsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_export_dsa_raw</strong> <em>(gnutls_openpgp_privkey_t <var>pkey</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>g</var>, gnutls_datum_t * <var>y</var>, gnutls_datum_t * <var>x</var>)</em></dt>
31477 <dd><p><var>pkey</var>: Holds the certificate
31478 </p>
31479 <p><var>p</var>: will hold the p
31480 </p>
31481 <p><var>q</var>: will hold the q
31482 </p>
31483 <p><var>g</var>: will hold the g
31484 </p>
31485 <p><var>y</var>: will hold the y
31486 </p>
31487 <p><var>x</var>: will hold the x
31488 </p>
31489 <p>This function will export the DSA private key&rsquo;s parameters found in
31490 the given certificate.  The new parameters will be allocated using
31491 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
31492 </p>
31493 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
31494 </p>
31495 <p><strong>Since:</strong> 2.4.0
31496 </p></dd></dl>
31497
31498 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005frsa_005fraw-1"></a>
31499 <h4 class="subheading">gnutls_openpgp_privkey_export_rsa_raw</h4>
31500 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005frsa_005fraw"></a><dl>
31501 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fexport_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_export_rsa_raw</strong> <em>(gnutls_openpgp_privkey_t <var>pkey</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>, gnutls_datum_t * <var>d</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>u</var>)</em></dt>
31502 <dd><p><var>pkey</var>: Holds the certificate
31503 </p>
31504 <p><var>m</var>: will hold the modulus
31505 </p>
31506 <p><var>e</var>: will hold the public exponent
31507 </p>
31508 <p><var>d</var>: will hold the private exponent
31509 </p>
31510 <p><var>p</var>: will hold the first prime (p)
31511 </p>
31512 <p><var>q</var>: will hold the second prime (q)
31513 </p>
31514 <p><var>u</var>: will hold the coefficient
31515 </p>
31516 <p>This function will export the RSA private key&rsquo;s parameters found in
31517 the given structure.  The new parameters will be allocated using
31518 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
31519 </p>
31520 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
31521 </p>
31522 <p><strong>Since:</strong> 2.4.0
31523 </p></dd></dl>
31524
31525 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005fsubkey_005fdsa_005fraw-1"></a>
31526 <h4 class="subheading">gnutls_openpgp_privkey_export_subkey_dsa_raw</h4>
31527 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005fsubkey_005fdsa_005fraw"></a><dl>
31528 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fexport_005fsubkey_005fdsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_export_subkey_dsa_raw</strong> <em>(gnutls_openpgp_privkey_t <var>pkey</var>, unsigned int <var>idx</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>g</var>, gnutls_datum_t * <var>y</var>, gnutls_datum_t * <var>x</var>)</em></dt>
31529 <dd><p><var>pkey</var>: Holds the certificate
31530 </p>
31531 <p><var>idx</var>: Is the subkey index
31532 </p>
31533 <p><var>p</var>: will hold the p
31534 </p>
31535 <p><var>q</var>: will hold the q
31536 </p>
31537 <p><var>g</var>: will hold the g
31538 </p>
31539 <p><var>y</var>: will hold the y
31540 </p>
31541 <p><var>x</var>: will hold the x
31542 </p>
31543 <p>This function will export the DSA private key&rsquo;s parameters found
31544 in the given certificate.  The new parameters will be allocated
31545 using <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
31546 </p>
31547 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
31548 </p>
31549 <p><strong>Since:</strong> 2.4.0
31550 </p></dd></dl>
31551
31552 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005fsubkey_005frsa_005fraw-1"></a>
31553 <h4 class="subheading">gnutls_openpgp_privkey_export_subkey_rsa_raw</h4>
31554 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005fsubkey_005frsa_005fraw"></a><dl>
31555 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fexport_005fsubkey_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_export_subkey_rsa_raw</strong> <em>(gnutls_openpgp_privkey_t <var>pkey</var>, unsigned int <var>idx</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>, gnutls_datum_t * <var>d</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>u</var>)</em></dt>
31556 <dd><p><var>pkey</var>: Holds the certificate
31557 </p>
31558 <p><var>idx</var>: Is the subkey index
31559 </p>
31560 <p><var>m</var>: will hold the modulus
31561 </p>
31562 <p><var>e</var>: will hold the public exponent
31563 </p>
31564 <p><var>d</var>: will hold the private exponent
31565 </p>
31566 <p><var>p</var>: will hold the first prime (p)
31567 </p>
31568 <p><var>q</var>: will hold the second prime (q)
31569 </p>
31570 <p><var>u</var>: will hold the coefficient
31571 </p>
31572 <p>This function will export the RSA private key&rsquo;s parameters found in
31573 the given structure.  The new parameters will be allocated using
31574 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
31575 </p>
31576 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
31577 </p>
31578 <p><strong>Since:</strong> 2.4.0
31579 </p></dd></dl>
31580
31581 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005ffingerprint-1"></a>
31582 <h4 class="subheading">gnutls_openpgp_privkey_get_fingerprint</h4>
31583 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005ffingerprint"></a><dl>
31584 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fget_005ffingerprint"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_get_fingerprint</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>, void * <var>fpr</var>, size_t * <var>fprlen</var>)</em></dt>
31585 <dd><p><var>key</var>: the raw data that contains the OpenPGP secret key.
31586 </p>
31587 <p><var>fpr</var>: the buffer to save the fingerprint, must hold at least 20 bytes.
31588 </p>
31589 <p><var>fprlen</var>: the integer to save the length of the fingerprint.
31590 </p>
31591 <p>Get the fingerprint of the OpenPGP key. Depends on the
31592 algorithm, the fingerprint can be 16 or 20 bytes.
31593 </p>
31594 <p><strong>Returns:</strong> On success, 0 is returned, or an error code.
31595 </p>
31596 <p><strong>Since:</strong> 2.4.0
31597 </p></dd></dl>
31598
31599 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fkey_005fid-1"></a>
31600 <h4 class="subheading">gnutls_openpgp_privkey_get_key_id</h4>
31601 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fkey_005fid"></a><dl>
31602 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fget_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_get_key_id</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>, gnutls_openpgp_keyid_t <var>keyid</var>)</em></dt>
31603 <dd><p><var>key</var>: the structure that contains the OpenPGP secret key.
31604 </p>
31605 <p><var>keyid</var>: the buffer to save the keyid.
31606 </p>
31607 <p>Get key-id.
31608 </p>
31609 <p><strong>Returns:</strong> the 64-bit keyID of the OpenPGP key.
31610 </p>
31611 <p><strong>Since:</strong> 2.4.0
31612 </p></dd></dl>
31613
31614 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fpk_005falgorithm-1"></a>
31615 <h4 class="subheading">gnutls_openpgp_privkey_get_pk_algorithm</h4>
31616 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fpk_005falgorithm"></a><dl>
31617 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fget_005fpk_005falgorithm"></a>Function: <em>gnutls_pk_algorithm_t</em> <strong>gnutls_openpgp_privkey_get_pk_algorithm</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>, unsigned int * <var>bits</var>)</em></dt>
31618 <dd><p><var>key</var>: is an OpenPGP key
31619 </p>
31620 <p><var>bits</var>: if bits is non null it will hold the size of the parameters&rsquo; in bits
31621 </p>
31622 <p>This function will return the public key algorithm of an OpenPGP
31623 certificate.
31624 </p>
31625 <p>If bits is non null, it should have enough size to hold the parameters
31626 size in bits. For RSA the bits returned is the modulus.
31627 For DSA the bits returned are of the public exponent.
31628 </p>
31629 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code>  enumeration on
31630 success, or a negative error code on error.
31631 </p>
31632 <p><strong>Since:</strong> 2.4.0
31633 </p></dd></dl>
31634
31635 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fpreferred_005fkey_005fid-1"></a>
31636 <h4 class="subheading">gnutls_openpgp_privkey_get_preferred_key_id</h4>
31637 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fpreferred_005fkey_005fid"></a><dl>
31638 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fget_005fpreferred_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_get_preferred_key_id</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>, gnutls_openpgp_keyid_t <var>keyid</var>)</em></dt>
31639 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
31640 </p>
31641 <p><var>keyid</var>: the struct to save the keyid.
31642 </p>
31643 <p>Get the preferred key-id for the key.
31644 </p>
31645 <p><strong>Returns:</strong> the 64-bit preferred keyID of the OpenPGP key, or if it
31646 hasn&rsquo;t been set it returns <code>GNUTLS_E_INVALID_REQUEST</code> .
31647 </p></dd></dl>
31648
31649 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005frevoked_005fstatus-1"></a>
31650 <h4 class="subheading">gnutls_openpgp_privkey_get_revoked_status</h4>
31651 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005frevoked_005fstatus"></a><dl>
31652 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fget_005frevoked_005fstatus"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_get_revoked_status</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>)</em></dt>
31653 <dd><p><var>key</var>: the structure that contains the OpenPGP private key.
31654 </p>
31655 <p>Get revocation status of key.
31656 </p>
31657 <p><strong>Returns:</strong> true (1) if the key has been revoked, or false (0) if it
31658 has not, or a negative error code indicates an error.
31659 </p>
31660 <p><strong>Since:</strong> 2.4.0
31661 </p></dd></dl>
31662
31663 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fcount-1"></a>
31664 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_count</h4>
31665 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fcount"></a><dl>
31666 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fcount"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_get_subkey_count</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>)</em></dt>
31667 <dd><p><var>key</var>: is an OpenPGP key
31668 </p>
31669 <p>This function will return the number of subkeys present in the
31670 given OpenPGP certificate.
31671 </p>
31672 <p><strong>Returns:</strong> the number of subkeys, or a negative error code on error.
31673 </p>
31674 <p><strong>Since:</strong> 2.4.0
31675 </p></dd></dl>
31676
31677 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fcreation_005ftime-1"></a>
31678 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_creation_time</h4>
31679 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fcreation_005ftime"></a><dl>
31680 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fcreation_005ftime"></a>Function: <em>time_t</em> <strong>gnutls_openpgp_privkey_get_subkey_creation_time</strong> <em>(gnutls_openpgp_privkey_t       <var>key</var>, unsigned int <var>idx</var>)</em></dt>
31681 <dd><p><var>key</var>: the structure that contains the OpenPGP private key.
31682 </p>
31683 <p><var>idx</var>: the subkey index
31684 </p>
31685 <p>Get subkey creation time.
31686 </p>
31687 <p><strong>Returns:</strong> the timestamp when the OpenPGP key was created.
31688 </p>
31689 <p><strong>Since:</strong> 2.4.0
31690 </p></dd></dl>
31691
31692 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fexpiration_005ftime-1"></a>
31693 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_expiration_time</h4>
31694 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fexpiration_005ftime"></a><dl>
31695 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fexpiration_005ftime"></a>Function: <em>time_t</em> <strong>gnutls_openpgp_privkey_get_subkey_expiration_time</strong> <em>(gnutls_openpgp_privkey_t         <var>key</var>, unsigned int <var>idx</var>)</em></dt>
31696 <dd><p><var>key</var>: the structure that contains the OpenPGP private key.
31697 </p>
31698 <p><var>idx</var>: the subkey index
31699 </p>
31700 <p>Get subkey expiration time.  A value of &rsquo;0&rsquo; means that the key
31701 doesn&rsquo;t expire at all.
31702 </p>
31703 <p><strong>Returns:</strong> the time when the OpenPGP key expires.
31704 </p>
31705 <p><strong>Since:</strong> 2.4.0
31706 </p></dd></dl>
31707
31708 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005ffingerprint-1"></a>
31709 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_fingerprint</h4>
31710 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005ffingerprint"></a><dl>
31711 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005ffingerprint"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_get_subkey_fingerprint</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>, unsigned int <var>idx</var>, void * <var>fpr</var>, size_t * <var>fprlen</var>)</em></dt>
31712 <dd><p><var>key</var>: the raw data that contains the OpenPGP secret key.
31713 </p>
31714 <p><var>idx</var>: the subkey index
31715 </p>
31716 <p><var>fpr</var>: the buffer to save the fingerprint, must hold at least 20 bytes.
31717 </p>
31718 <p><var>fprlen</var>: the integer to save the length of the fingerprint.
31719 </p>
31720 <p>Get the fingerprint of an OpenPGP subkey.  Depends on the
31721 algorithm, the fingerprint can be 16 or 20 bytes.
31722 </p>
31723 <p><strong>Returns:</strong> On success, 0 is returned, or an error code.
31724 </p>
31725 <p><strong>Since:</strong> 2.4.0
31726 </p></dd></dl>
31727
31728 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fid-1"></a>
31729 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_id</h4>
31730 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fid"></a><dl>
31731 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fid"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_get_subkey_id</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>, unsigned int <var>idx</var>, gnutls_openpgp_keyid_t <var>keyid</var>)</em></dt>
31732 <dd><p><var>key</var>: the structure that contains the OpenPGP secret key.
31733 </p>
31734 <p><var>idx</var>: the subkey index
31735 </p>
31736 <p><var>keyid</var>: the buffer to save the keyid.
31737 </p>
31738 <p>Get the key-id for the subkey.
31739 </p>
31740 <p><strong>Returns:</strong> the 64-bit keyID of the OpenPGP key.
31741 </p>
31742 <p><strong>Since:</strong> 2.4.0
31743 </p></dd></dl>
31744
31745 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fidx-1"></a>
31746 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_idx</h4>
31747 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fidx"></a><dl>
31748 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fidx"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_get_subkey_idx</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>, const gnutls_openpgp_keyid_t <var>keyid</var>)</em></dt>
31749 <dd><p><var>key</var>: the structure that contains the OpenPGP private key.
31750 </p>
31751 <p><var>keyid</var>: the keyid.
31752 </p>
31753 <p>Get index of subkey.
31754 </p>
31755 <p><strong>Returns:</strong> the index of the subkey or a negative error value.
31756 </p>
31757 <p><strong>Since:</strong> 2.4.0
31758 </p></dd></dl>
31759
31760 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fpk_005falgorithm-1"></a>
31761 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_pk_algorithm</h4>
31762 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fpk_005falgorithm"></a><dl>
31763 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fpk_005falgorithm"></a>Function: <em>gnutls_pk_algorithm_t</em> <strong>gnutls_openpgp_privkey_get_subkey_pk_algorithm</strong> <em>(gnutls_openpgp_privkey_t             <var>key</var>, unsigned int <var>idx</var>, unsigned int * <var>bits</var>)</em></dt>
31764 <dd><p><var>key</var>: is an OpenPGP key
31765 </p>
31766 <p><var>idx</var>: is the subkey index
31767 </p>
31768 <p><var>bits</var>: if bits is non null it will hold the size of the parameters&rsquo; in bits
31769 </p>
31770 <p>This function will return the public key algorithm of a subkey of an OpenPGP
31771 certificate.
31772 </p>
31773 <p>If bits is non null, it should have enough size to hold the parameters
31774 size in bits. For RSA the bits returned is the modulus.
31775 For DSA the bits returned are of the public exponent.
31776 </p>
31777 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code>  enumeration on
31778 success, or a negative error code on error.
31779 </p>
31780 <p><strong>Since:</strong> 2.4.0
31781 </p></dd></dl>
31782
31783 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005frevoked_005fstatus-1"></a>
31784 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_revoked_status</h4>
31785 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005frevoked_005fstatus"></a><dl>
31786 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005frevoked_005fstatus"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_get_subkey_revoked_status</strong> <em>(gnutls_openpgp_privkey_t        <var>key</var>, unsigned int <var>idx</var>)</em></dt>
31787 <dd><p><var>key</var>: the structure that contains the OpenPGP private key.
31788 </p>
31789 <p><var>idx</var>: is the subkey index
31790 </p>
31791 <p>Get revocation status of key.
31792 </p>
31793 <p><strong>Returns:</strong> true (1) if the key has been revoked, or false (0) if it
31794 has not, or a negative error code indicates an error.
31795 </p>
31796 <p><strong>Since:</strong> 2.4.0
31797 </p></dd></dl>
31798
31799 <a name="gnutls_005fopenpgp_005fprivkey_005fimport-1"></a>
31800 <h4 class="subheading">gnutls_openpgp_privkey_import</h4>
31801 <a name="gnutls_005fopenpgp_005fprivkey_005fimport"></a><dl>
31802 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fimport"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_import</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>, const gnutls_datum_t * <var>data</var>, gnutls_openpgp_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>)</em></dt>
31803 <dd><p><var>key</var>: The structure to store the parsed key.
31804 </p>
31805 <p><var>data</var>: The RAW or BASE64 encoded key.
31806 </p>
31807 <p><var>format</var>: One of <code>gnutls_openpgp_crt_fmt_t</code>  elements.
31808 </p>
31809 <p><var>password</var>: not used for now
31810 </p>
31811 <p><var>flags</var>: should be (0)
31812 </p>
31813 <p>This function will convert the given RAW or Base64 encoded key to
31814 the native gnutls_openpgp_privkey_t format.  The output will be
31815 stored in &rsquo;key&rsquo;.
31816 </p>
31817 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
31818 </p></dd></dl>
31819
31820 <a name="gnutls_005fopenpgp_005fprivkey_005finit-1"></a>
31821 <h4 class="subheading">gnutls_openpgp_privkey_init</h4>
31822 <a name="gnutls_005fopenpgp_005fprivkey_005finit"></a><dl>
31823 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005finit"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_init</strong> <em>(gnutls_openpgp_privkey_t * <var>key</var>)</em></dt>
31824 <dd><p><var>key</var>: The structure to be initialized
31825 </p>
31826 <p>This function will initialize an OpenPGP key structure.
31827 </p>
31828 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
31829 </p></dd></dl>
31830
31831 <a name="gnutls_005fopenpgp_005fprivkey_005fsec_005fparam-1"></a>
31832 <h4 class="subheading">gnutls_openpgp_privkey_sec_param</h4>
31833 <a name="gnutls_005fopenpgp_005fprivkey_005fsec_005fparam"></a><dl>
31834 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fsec_005fparam"></a>Function: <em>gnutls_sec_param_t</em> <strong>gnutls_openpgp_privkey_sec_param</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>)</em></dt>
31835 <dd><p><var>key</var>: a key structure
31836 </p>
31837 <p>This function will return the security parameter appropriate with
31838 this private key.
31839 </p>
31840 <p><strong>Returns:</strong> On success, a valid security parameter is returned otherwise
31841 <code>GNUTLS_SEC_PARAM_UNKNOWN</code>  is returned.
31842 </p>
31843 <p><strong>Since:</strong> 2.12.0
31844 </p></dd></dl>
31845
31846 <a name="gnutls_005fopenpgp_005fprivkey_005fset_005fpreferred_005fkey_005fid-1"></a>
31847 <h4 class="subheading">gnutls_openpgp_privkey_set_preferred_key_id</h4>
31848 <a name="gnutls_005fopenpgp_005fprivkey_005fset_005fpreferred_005fkey_005fid"></a><dl>
31849 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fset_005fpreferred_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_set_preferred_key_id</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>, const gnutls_openpgp_keyid_t          <var>keyid</var>)</em></dt>
31850 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
31851 </p>
31852 <p><var>keyid</var>: the selected keyid
31853 </p>
31854 <p>This allows setting a preferred key id for the given certificate.
31855 This key will be used by functions that involve key handling.
31856 </p>
31857 <p>If the provided  <code>keyid</code> is <code>NULL</code>  then the master key is
31858 set as preferred.
31859 </p>
31860 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
31861 otherwise a negative error code is returned.
31862 </p></dd></dl>
31863
31864 <a name="gnutls_005fopenpgp_005fset_005frecv_005fkey_005ffunction-1"></a>
31865 <h4 class="subheading">gnutls_openpgp_set_recv_key_function</h4>
31866 <a name="gnutls_005fopenpgp_005fset_005frecv_005fkey_005ffunction"></a><dl>
31867 <dt><a name="index-gnutls_005fopenpgp_005fset_005frecv_005fkey_005ffunction"></a>Function: <em>void</em> <strong>gnutls_openpgp_set_recv_key_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_openpgp_recv_key_func <var>func</var>)</em></dt>
31868 <dd><p><var>session</var>: a TLS session
31869 </p>
31870 <p><var>func</var>: the callback
31871 </p>
31872 <p>This funtion will set a key retrieval function for OpenPGP keys. This
31873 callback is only useful in server side, and will be used if the peer
31874 sent a key fingerprint instead of a full key.
31875 </p>
31876 <p>The retrieved key must be allocated using <code>gnutls_malloc()</code> .
31877 </p></dd></dl>
31878
31879
31880 <hr>
31881 <a name="PKCS-12-API"></a>
31882 <div class="header">
31883 <p>
31884 Next: <a href="#PKCS-11-API" accesskey="n" rel="next">PKCS 11 API</a>, Previous: <a href="#OpenPGP-API" accesskey="p" rel="prev">OpenPGP API</a>, Up: <a href="#API-reference" accesskey="u" rel="up">API reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
31885 </div>
31886 <a name="PKCS-12-API-1"></a>
31887 <h3 class="section">E.6 PKCS 12 API</h3>
31888
31889 <p>The following functions are to be used for PKCS 12 handling.
31890 Their prototypes lie in <samp>gnutls/pkcs12.h</samp>.
31891 </p>
31892
31893 <a name="gnutls_005fpkcs12_005fbag_005fdecrypt-1"></a>
31894 <h4 class="subheading">gnutls_pkcs12_bag_decrypt</h4>
31895 <a name="gnutls_005fpkcs12_005fbag_005fdecrypt"></a><dl>
31896 <dt><a name="index-gnutls_005fpkcs12_005fbag_005fdecrypt"></a>Function: <em>int</em> <strong>gnutls_pkcs12_bag_decrypt</strong> <em>(gnutls_pkcs12_bag_t <var>bag</var>, const char * <var>pass</var>)</em></dt>
31897 <dd><p><var>bag</var>: The bag
31898 </p>
31899 <p><var>pass</var>: The password used for encryption, must be ASCII.
31900 </p>
31901 <p>This function will decrypt the given encrypted bag and return 0 on
31902 success.
31903 </p>
31904 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
31905 otherwise a negative error code is returned.
31906 </p></dd></dl>
31907
31908 <a name="gnutls_005fpkcs12_005fbag_005fdeinit-1"></a>
31909 <h4 class="subheading">gnutls_pkcs12_bag_deinit</h4>
31910 <a name="gnutls_005fpkcs12_005fbag_005fdeinit"></a><dl>
31911 <dt><a name="index-gnutls_005fpkcs12_005fbag_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_pkcs12_bag_deinit</strong> <em>(gnutls_pkcs12_bag_t <var>bag</var>)</em></dt>
31912 <dd><p><var>bag</var>: The structure to be initialized
31913 </p>
31914 <p>This function will deinitialize a PKCS12 Bag structure.
31915 </p></dd></dl>
31916
31917 <a name="gnutls_005fpkcs12_005fbag_005fencrypt-1"></a>
31918 <h4 class="subheading">gnutls_pkcs12_bag_encrypt</h4>
31919 <a name="gnutls_005fpkcs12_005fbag_005fencrypt"></a><dl>
31920 <dt><a name="index-gnutls_005fpkcs12_005fbag_005fencrypt"></a>Function: <em>int</em> <strong>gnutls_pkcs12_bag_encrypt</strong> <em>(gnutls_pkcs12_bag_t <var>bag</var>, const char * <var>pass</var>, unsigned int <var>flags</var>)</em></dt>
31921 <dd><p><var>bag</var>: The bag
31922 </p>
31923 <p><var>pass</var>: The password used for encryption, must be ASCII
31924 </p>
31925 <p><var>flags</var>: should be one of <code>gnutls_pkcs_encrypt_flags_t</code>  elements bitwise or&rsquo;d
31926 </p>
31927 <p>This function will encrypt the given bag.
31928 </p>
31929 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
31930 otherwise a negative error code is returned.
31931 </p></dd></dl>
31932
31933 <a name="gnutls_005fpkcs12_005fbag_005fget_005fcount-1"></a>
31934 <h4 class="subheading">gnutls_pkcs12_bag_get_count</h4>
31935 <a name="gnutls_005fpkcs12_005fbag_005fget_005fcount"></a><dl>
31936 <dt><a name="index-gnutls_005fpkcs12_005fbag_005fget_005fcount"></a>Function: <em>int</em> <strong>gnutls_pkcs12_bag_get_count</strong> <em>(gnutls_pkcs12_bag_t <var>bag</var>)</em></dt>
31937 <dd><p><var>bag</var>: The bag
31938 </p>
31939 <p>This function will return the number of the elements withing the bag.
31940 </p>
31941 <p><strong>Returns:</strong> Number of elements in bag, or an negative error code on
31942 error.
31943 </p></dd></dl>
31944
31945 <a name="gnutls_005fpkcs12_005fbag_005fget_005fdata-1"></a>
31946 <h4 class="subheading">gnutls_pkcs12_bag_get_data</h4>
31947 <a name="gnutls_005fpkcs12_005fbag_005fget_005fdata"></a><dl>
31948 <dt><a name="index-gnutls_005fpkcs12_005fbag_005fget_005fdata"></a>Function: <em>int</em> <strong>gnutls_pkcs12_bag_get_data</strong> <em>(gnutls_pkcs12_bag_t <var>bag</var>, int <var>indx</var>, gnutls_datum_t * <var>data</var>)</em></dt>
31949 <dd><p><var>bag</var>: The bag
31950 </p>
31951 <p><var>indx</var>: The element of the bag to get the data from
31952 </p>
31953 <p><var>data</var>: where the bag&rsquo;s data will be. Should be treated as constant.
31954 </p>
31955 <p>This function will return the bag&rsquo;s data. The data is a constant
31956 that is stored into the bag.  Should not be accessed after the bag
31957 is deleted.
31958 </p>
31959 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
31960 negative error value.
31961 </p></dd></dl>
31962
31963 <a name="gnutls_005fpkcs12_005fbag_005fget_005ffriendly_005fname-1"></a>
31964 <h4 class="subheading">gnutls_pkcs12_bag_get_friendly_name</h4>
31965 <a name="gnutls_005fpkcs12_005fbag_005fget_005ffriendly_005fname"></a><dl>
31966 <dt><a name="index-gnutls_005fpkcs12_005fbag_005fget_005ffriendly_005fname"></a>Function: <em>int</em> <strong>gnutls_pkcs12_bag_get_friendly_name</strong> <em>(gnutls_pkcs12_bag_t <var>bag</var>, int <var>indx</var>, char ** <var>name</var>)</em></dt>
31967 <dd><p><var>bag</var>: The bag
31968 </p>
31969 <p><var>indx</var>: The bag&rsquo;s element to add the id
31970 </p>
31971 <p><var>name</var>: will hold a pointer to the name (to be treated as const)
31972 </p>
31973 <p>This function will return the friendly name, of the specified bag
31974 element.  The key ID is usually used to distinguish the local
31975 private key and the certificate pair.
31976 </p>
31977 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
31978 negative error value. or a negative error code on error.
31979 </p></dd></dl>
31980
31981 <a name="gnutls_005fpkcs12_005fbag_005fget_005fkey_005fid-1"></a>
31982 <h4 class="subheading">gnutls_pkcs12_bag_get_key_id</h4>
31983 <a name="gnutls_005fpkcs12_005fbag_005fget_005fkey_005fid"></a><dl>
31984 <dt><a name="index-gnutls_005fpkcs12_005fbag_005fget_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_pkcs12_bag_get_key_id</strong> <em>(gnutls_pkcs12_bag_t <var>bag</var>, int <var>indx</var>, gnutls_datum_t * <var>id</var>)</em></dt>
31985 <dd><p><var>bag</var>: The bag
31986 </p>
31987 <p><var>indx</var>: The bag&rsquo;s element to add the id
31988 </p>
31989 <p><var>id</var>: where the ID will be copied (to be treated as const)
31990 </p>
31991 <p>This function will return the key ID, of the specified bag element.
31992 The key ID is usually used to distinguish the local private key and
31993 the certificate pair.
31994 </p>
31995 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
31996 negative error value. or a negative error code on error.
31997 </p></dd></dl>
31998
31999 <a name="gnutls_005fpkcs12_005fbag_005fget_005ftype-1"></a>
32000 <h4 class="subheading">gnutls_pkcs12_bag_get_type</h4>
32001 <a name="gnutls_005fpkcs12_005fbag_005fget_005ftype"></a><dl>
32002 <dt><a name="index-gnutls_005fpkcs12_005fbag_005fget_005ftype"></a>Function: <em>gnutls_pkcs12_bag_type_t</em> <strong>gnutls_pkcs12_bag_get_type</strong> <em>(gnutls_pkcs12_bag_t <var>bag</var>, int <var>indx</var>)</em></dt>
32003 <dd><p><var>bag</var>: The bag
32004 </p>
32005 <p><var>indx</var>: The element of the bag to get the type
32006 </p>
32007 <p>This function will return the bag&rsquo;s type.
32008 </p>
32009 <p><strong>Returns:</strong> One of the <code>gnutls_pkcs12_bag_type_t</code>  enumerations.
32010 </p></dd></dl>
32011
32012 <a name="gnutls_005fpkcs12_005fbag_005finit-1"></a>
32013 <h4 class="subheading">gnutls_pkcs12_bag_init</h4>
32014 <a name="gnutls_005fpkcs12_005fbag_005finit"></a><dl>
32015 <dt><a name="index-gnutls_005fpkcs12_005fbag_005finit"></a>Function: <em>int</em> <strong>gnutls_pkcs12_bag_init</strong> <em>(gnutls_pkcs12_bag_t * <var>bag</var>)</em></dt>
32016 <dd><p><var>bag</var>: The structure to be initialized
32017 </p>
32018 <p>This function will initialize a PKCS12 bag structure. PKCS12 Bags
32019 usually contain private keys, lists of X.509 Certificates and X.509
32020 Certificate revocation lists.
32021 </p>
32022 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32023 negative error value.
32024 </p></dd></dl>
32025
32026 <a name="gnutls_005fpkcs12_005fbag_005fset_005fcrl-1"></a>
32027 <h4 class="subheading">gnutls_pkcs12_bag_set_crl</h4>
32028 <a name="gnutls_005fpkcs12_005fbag_005fset_005fcrl"></a><dl>
32029 <dt><a name="index-gnutls_005fpkcs12_005fbag_005fset_005fcrl"></a>Function: <em>int</em> <strong>gnutls_pkcs12_bag_set_crl</strong> <em>(gnutls_pkcs12_bag_t <var>bag</var>, gnutls_x509_crl_t <var>crl</var>)</em></dt>
32030 <dd><p><var>bag</var>: The bag
32031 </p>
32032 <p><var>crl</var>: the CRL to be copied.
32033 </p>
32034 <p>This function will insert the given CRL into the
32035 bag. This is just a wrapper over <code>gnutls_pkcs12_bag_set_data()</code> .
32036 </p>
32037 <p><strong>Returns:</strong> the index of the added bag on success, or a negative error code
32038 on failure.
32039 </p></dd></dl>
32040
32041 <a name="gnutls_005fpkcs12_005fbag_005fset_005fcrt-1"></a>
32042 <h4 class="subheading">gnutls_pkcs12_bag_set_crt</h4>
32043 <a name="gnutls_005fpkcs12_005fbag_005fset_005fcrt"></a><dl>
32044 <dt><a name="index-gnutls_005fpkcs12_005fbag_005fset_005fcrt"></a>Function: <em>int</em> <strong>gnutls_pkcs12_bag_set_crt</strong> <em>(gnutls_pkcs12_bag_t <var>bag</var>, gnutls_x509_crt_t <var>crt</var>)</em></dt>
32045 <dd><p><var>bag</var>: The bag
32046 </p>
32047 <p><var>crt</var>: the certificate to be copied.
32048 </p>
32049 <p>This function will insert the given certificate into the
32050 bag. This is just a wrapper over <code>gnutls_pkcs12_bag_set_data()</code> .
32051 </p>
32052 <p><strong>Returns:</strong> the index of the added bag on success, or a negative
32053 value on failure.
32054 </p></dd></dl>
32055
32056 <a name="gnutls_005fpkcs12_005fbag_005fset_005fdata-1"></a>
32057 <h4 class="subheading">gnutls_pkcs12_bag_set_data</h4>
32058 <a name="gnutls_005fpkcs12_005fbag_005fset_005fdata"></a><dl>
32059 <dt><a name="index-gnutls_005fpkcs12_005fbag_005fset_005fdata"></a>Function: <em>int</em> <strong>gnutls_pkcs12_bag_set_data</strong> <em>(gnutls_pkcs12_bag_t <var>bag</var>, gnutls_pkcs12_bag_type_t <var>type</var>, const gnutls_datum_t * <var>data</var>)</em></dt>
32060 <dd><p><var>bag</var>: The bag
32061 </p>
32062 <p><var>type</var>: The data&rsquo;s type
32063 </p>
32064 <p><var>data</var>: the data to be copied.
32065 </p>
32066 <p>This function will insert the given data of the given type into
32067 the bag.
32068 </p>
32069 <p><strong>Returns:</strong> the index of the added bag on success, or a negative
32070 value on error.
32071 </p></dd></dl>
32072
32073 <a name="gnutls_005fpkcs12_005fbag_005fset_005ffriendly_005fname-1"></a>
32074 <h4 class="subheading">gnutls_pkcs12_bag_set_friendly_name</h4>
32075 <a name="gnutls_005fpkcs12_005fbag_005fset_005ffriendly_005fname"></a><dl>
32076 <dt><a name="index-gnutls_005fpkcs12_005fbag_005fset_005ffriendly_005fname"></a>Function: <em>int</em> <strong>gnutls_pkcs12_bag_set_friendly_name</strong> <em>(gnutls_pkcs12_bag_t <var>bag</var>, int <var>indx</var>, const char * <var>name</var>)</em></dt>
32077 <dd><p><var>bag</var>: The bag
32078 </p>
32079 <p><var>indx</var>: The bag&rsquo;s element to add the id
32080 </p>
32081 <p><var>name</var>: the name
32082 </p>
32083 <p>This function will add the given key friendly name, to the
32084 specified, by the index, bag element. The name will be encoded as
32085 a &rsquo;Friendly name&rsquo; bag attribute, which is usually used to set a
32086 user name to the local private key and the certificate pair.
32087 </p>
32088 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32089 negative error value. or a negative error code on error.
32090 </p></dd></dl>
32091
32092 <a name="gnutls_005fpkcs12_005fbag_005fset_005fkey_005fid-1"></a>
32093 <h4 class="subheading">gnutls_pkcs12_bag_set_key_id</h4>
32094 <a name="gnutls_005fpkcs12_005fbag_005fset_005fkey_005fid"></a><dl>
32095 <dt><a name="index-gnutls_005fpkcs12_005fbag_005fset_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_pkcs12_bag_set_key_id</strong> <em>(gnutls_pkcs12_bag_t <var>bag</var>, int <var>indx</var>, const gnutls_datum_t * <var>id</var>)</em></dt>
32096 <dd><p><var>bag</var>: The bag
32097 </p>
32098 <p><var>indx</var>: The bag&rsquo;s element to add the id
32099 </p>
32100 <p><var>id</var>: the ID
32101 </p>
32102 <p>This function will add the given key ID, to the specified, by the
32103 index, bag element. The key ID will be encoded as a &rsquo;Local key
32104 identifier&rsquo; bag attribute, which is usually used to distinguish
32105 the local private key and the certificate pair.
32106 </p>
32107 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32108 negative error value. or a negative error code on error.
32109 </p></dd></dl>
32110
32111 <a name="gnutls_005fpkcs12_005fdeinit-1"></a>
32112 <h4 class="subheading">gnutls_pkcs12_deinit</h4>
32113 <a name="gnutls_005fpkcs12_005fdeinit"></a><dl>
32114 <dt><a name="index-gnutls_005fpkcs12_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_pkcs12_deinit</strong> <em>(gnutls_pkcs12_t <var>pkcs12</var>)</em></dt>
32115 <dd><p><var>pkcs12</var>: The structure to be initialized
32116 </p>
32117 <p>This function will deinitialize a PKCS12 structure.
32118 </p></dd></dl>
32119
32120 <a name="gnutls_005fpkcs12_005fexport-1"></a>
32121 <h4 class="subheading">gnutls_pkcs12_export</h4>
32122 <a name="gnutls_005fpkcs12_005fexport"></a><dl>
32123 <dt><a name="index-gnutls_005fpkcs12_005fexport"></a>Function: <em>int</em> <strong>gnutls_pkcs12_export</strong> <em>(gnutls_pkcs12_t <var>pkcs12</var>, gnutls_x509_crt_fmt_t <var>format</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
32124 <dd><p><var>pkcs12</var>: Holds the pkcs12 structure
32125 </p>
32126 <p><var>format</var>: the format of output params. One of PEM or DER.
32127 </p>
32128 <p><var>output_data</var>: will contain a structure PEM or DER encoded
32129 </p>
32130 <p><var>output_data_size</var>: holds the size of output_data (and will be
32131 replaced by the actual size of parameters)
32132 </p>
32133 <p>This function will export the pkcs12 structure to DER or PEM format.
32134 </p>
32135 <p>If the buffer provided is not long enough to hold the output, then
32136 *output_data_size will be updated and GNUTLS_E_SHORT_MEMORY_BUFFER
32137 will be returned.
32138 </p>
32139 <p>If the structure is PEM encoded, it will have a header
32140 of &quot;BEGIN PKCS12&quot;.
32141 </p>
32142 <p><strong>Returns:</strong> In case of failure a negative error code will be
32143 returned, and 0 on success.
32144 </p></dd></dl>
32145
32146 <a name="gnutls_005fpkcs12_005fexport2-1"></a>
32147 <h4 class="subheading">gnutls_pkcs12_export2</h4>
32148 <a name="gnutls_005fpkcs12_005fexport2"></a><dl>
32149 <dt><a name="index-gnutls_005fpkcs12_005fexport2"></a>Function: <em>int</em> <strong>gnutls_pkcs12_export2</strong> <em>(gnutls_pkcs12_t <var>pkcs12</var>, gnutls_x509_crt_fmt_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
32150 <dd><p><var>pkcs12</var>: Holds the pkcs12 structure
32151 </p>
32152 <p><var>format</var>: the format of output params. One of PEM or DER.
32153 </p>
32154 <p><var>out</var>: will contain a structure PEM or DER encoded
32155 </p>
32156 <p>This function will export the pkcs12 structure to DER or PEM format.
32157 </p>
32158 <p>The output buffer is allocated using <code>gnutls_malloc()</code> .
32159 </p>
32160 <p>If the structure is PEM encoded, it will have a header
32161 of &quot;BEGIN PKCS12&quot;.
32162 </p>
32163 <p><strong>Returns:</strong> In case of failure a negative error code will be
32164 returned, and 0 on success.
32165 </p>
32166 <p><strong>Since:</strong> 3.1.3
32167 </p></dd></dl>
32168
32169 <a name="gnutls_005fpkcs12_005fgenerate_005fmac-1"></a>
32170 <h4 class="subheading">gnutls_pkcs12_generate_mac</h4>
32171 <a name="gnutls_005fpkcs12_005fgenerate_005fmac"></a><dl>
32172 <dt><a name="index-gnutls_005fpkcs12_005fgenerate_005fmac"></a>Function: <em>int</em> <strong>gnutls_pkcs12_generate_mac</strong> <em>(gnutls_pkcs12_t <var>pkcs12</var>, const char * <var>pass</var>)</em></dt>
32173 <dd><p><var>pkcs12</var>: should contain a gnutls_pkcs12_t structure
32174 </p>
32175 <p><var>pass</var>: The password for the MAC
32176 </p>
32177 <p>This function will generate a MAC for the PKCS12 structure.
32178 </p>
32179 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32180 negative error value.
32181 </p></dd></dl>
32182
32183 <a name="gnutls_005fpkcs12_005fget_005fbag-1"></a>
32184 <h4 class="subheading">gnutls_pkcs12_get_bag</h4>
32185 <a name="gnutls_005fpkcs12_005fget_005fbag"></a><dl>
32186 <dt><a name="index-gnutls_005fpkcs12_005fget_005fbag"></a>Function: <em>int</em> <strong>gnutls_pkcs12_get_bag</strong> <em>(gnutls_pkcs12_t <var>pkcs12</var>, int <var>indx</var>, gnutls_pkcs12_bag_t <var>bag</var>)</em></dt>
32187 <dd><p><var>pkcs12</var>: should contain a gnutls_pkcs12_t structure
32188 </p>
32189 <p><var>indx</var>: contains the index of the bag to extract
32190 </p>
32191 <p><var>bag</var>: An initialized bag, where the contents of the bag will be copied
32192 </p>
32193 <p>This function will return a Bag from the PKCS12 structure.
32194 </p>
32195 <p>After the last Bag has been read
32196 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  will be returned.
32197 </p>
32198 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32199 negative error value.
32200 </p></dd></dl>
32201
32202 <a name="gnutls_005fpkcs12_005fimport-1"></a>
32203 <h4 class="subheading">gnutls_pkcs12_import</h4>
32204 <a name="gnutls_005fpkcs12_005fimport"></a><dl>
32205 <dt><a name="index-gnutls_005fpkcs12_005fimport"></a>Function: <em>int</em> <strong>gnutls_pkcs12_import</strong> <em>(gnutls_pkcs12_t <var>pkcs12</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned int <var>flags</var>)</em></dt>
32206 <dd><p><var>pkcs12</var>: The structure to store the parsed PKCS12.
32207 </p>
32208 <p><var>data</var>: The DER or PEM encoded PKCS12.
32209 </p>
32210 <p><var>format</var>: One of DER or PEM
32211 </p>
32212 <p><var>flags</var>: an ORed sequence of gnutls_privkey_pkcs8_flags
32213 </p>
32214 <p>This function will convert the given DER or PEM encoded PKCS12
32215 to the native gnutls_pkcs12_t format. The output will be stored in &rsquo;pkcs12&rsquo;.
32216 </p>
32217 <p>If the PKCS12 is PEM encoded it should have a header of &quot;PKCS12&quot;.
32218 </p>
32219 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32220 negative error value.
32221 </p></dd></dl>
32222
32223 <a name="gnutls_005fpkcs12_005finit-1"></a>
32224 <h4 class="subheading">gnutls_pkcs12_init</h4>
32225 <a name="gnutls_005fpkcs12_005finit"></a><dl>
32226 <dt><a name="index-gnutls_005fpkcs12_005finit"></a>Function: <em>int</em> <strong>gnutls_pkcs12_init</strong> <em>(gnutls_pkcs12_t * <var>pkcs12</var>)</em></dt>
32227 <dd><p><var>pkcs12</var>: The structure to be initialized
32228 </p>
32229 <p>This function will initialize a PKCS12 structure. PKCS12 structures
32230 usually contain lists of X.509 Certificates and X.509 Certificate
32231 revocation lists.
32232 </p>
32233 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32234 negative error value.
32235 </p></dd></dl>
32236
32237 <a name="gnutls_005fpkcs12_005fset_005fbag-1"></a>
32238 <h4 class="subheading">gnutls_pkcs12_set_bag</h4>
32239 <a name="gnutls_005fpkcs12_005fset_005fbag"></a><dl>
32240 <dt><a name="index-gnutls_005fpkcs12_005fset_005fbag"></a>Function: <em>int</em> <strong>gnutls_pkcs12_set_bag</strong> <em>(gnutls_pkcs12_t <var>pkcs12</var>, gnutls_pkcs12_bag_t <var>bag</var>)</em></dt>
32241 <dd><p><var>pkcs12</var>: should contain a gnutls_pkcs12_t structure
32242 </p>
32243 <p><var>bag</var>: An initialized bag
32244 </p>
32245 <p>This function will insert a Bag into the PKCS12 structure.
32246 </p>
32247 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32248 negative error value.
32249 </p></dd></dl>
32250
32251 <a name="gnutls_005fpkcs12_005fsimple_005fparse-1"></a>
32252 <h4 class="subheading">gnutls_pkcs12_simple_parse</h4>
32253 <a name="gnutls_005fpkcs12_005fsimple_005fparse"></a><dl>
32254 <dt><a name="index-gnutls_005fpkcs12_005fsimple_005fparse-1"></a>Function: <em>int</em> <strong>gnutls_pkcs12_simple_parse</strong> <em>(gnutls_pkcs12_t <var>p12</var>, const char * <var>password</var>, gnutls_x509_privkey_t * <var>key</var>, gnutls_x509_crt_t ** <var>chain</var>, unsigned int * <var>chain_len</var>, gnutls_x509_crt_t ** <var>extra_certs</var>, unsigned int * <var>extra_certs_len</var>, gnutls_x509_crl_t * <var>crl</var>, unsigned int <var>flags</var>)</em></dt>
32255 <dd><p><var>p12</var>: should contain a gnutls_pkcs12_t structure
32256 </p>
32257 <p><var>password</var>: optional password used to decrypt the structure, bags and keys.
32258 </p>
32259 <p><var>key</var>: a structure to store the parsed private key.
32260 </p>
32261 <p><var>chain</var>: the corresponding to key certificate chain (may be <code>NULL</code> )
32262 </p>
32263 <p><var>chain_len</var>: will be updated with the number of additional (may be <code>NULL</code> )
32264 </p>
32265 <p><var>extra_certs</var>: optional pointer to receive an array of additional
32266 certificates found in the PKCS12 structure (may be <code>NULL</code> ).
32267 </p>
32268 <p><var>extra_certs_len</var>: will be updated with the number of additional
32269 certs (may be <code>NULL</code> ).
32270 </p>
32271 <p><var>crl</var>: an optional structure to store the parsed CRL (may be <code>NULL</code> ).
32272 </p>
32273 <p><var>flags</var>: should be zero or one of GNUTLS_PKCS12_SP_*
32274 </p>
32275 <p>This function parses a PKCS12 structure in  <code>pkcs12</code> and extracts the
32276 private key, the corresponding certificate chain, any additional
32277 certificates and a CRL.
32278 </p>
32279 <p>The  <code>extra_certs</code> and  <code>extra_certs_len</code> parameters are optional
32280 and both may be set to <code>NULL</code> . If either is non-<code>NULL</code> , then both must
32281 be set. The value for  <code>extra_certs</code> is allocated
32282 using <code>gnutls_malloc()</code> .
32283 </p>
32284 <p>Encrypted PKCS12 bags and PKCS8 private keys are supported, but
32285 only with password based security and the same password for all
32286 operations.
32287 </p>
32288 <p>Note that a PKCS12 structure may contain many keys and/or certificates,
32289 and there is no way to identify which key/certificate pair you want.
32290 For this reason this function is useful for PKCS12 files that contain
32291 only one key/certificate pair and/or one CRL.
32292 </p>
32293 <p>If the provided structure has encrypted fields but no password
32294 is provided then this function returns <code>GNUTLS_E_DECRYPTION_FAILED</code> .
32295 </p>
32296 <p>Note that normally the chain constructed does not include self signed
32297 certificates, to comply with TLS&rsquo; requirements. If, however, the flag
32298 <code>GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED</code>  is specified then
32299 self signed certificates will be included in the chain.
32300 </p>
32301 <p>Prior to using this function the PKCS <code>12</code>  structure integrity must
32302 be verified using <code>gnutls_pkcs12_verify_mac()</code> .
32303 </p>
32304 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32305 negative error value.
32306 </p>
32307 <p><strong>Since:</strong> 3.1.0
32308 </p></dd></dl>
32309
32310 <a name="gnutls_005fpkcs12_005fverify_005fmac-1"></a>
32311 <h4 class="subheading">gnutls_pkcs12_verify_mac</h4>
32312 <a name="gnutls_005fpkcs12_005fverify_005fmac"></a><dl>
32313 <dt><a name="index-gnutls_005fpkcs12_005fverify_005fmac"></a>Function: <em>int</em> <strong>gnutls_pkcs12_verify_mac</strong> <em>(gnutls_pkcs12_t <var>pkcs12</var>, const char * <var>pass</var>)</em></dt>
32314 <dd><p><var>pkcs12</var>: should contain a gnutls_pkcs12_t structure
32315 </p>
32316 <p><var>pass</var>: The password for the MAC
32317 </p>
32318 <p>This function will verify the MAC for the PKCS12 structure.
32319 </p>
32320 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32321 negative error value.
32322 </p></dd></dl>
32323
32324
32325 <hr>
32326 <a name="PKCS-11-API"></a>
32327 <div class="header">
32328 <p>
32329 Next: <a href="#TPM-API" accesskey="n" rel="next">TPM API</a>, Previous: <a href="#PKCS-12-API" accesskey="p" rel="prev">PKCS 12 API</a>, Up: <a href="#API-reference" accesskey="u" rel="up">API reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
32330 </div>
32331 <a name="Hardware-token-via-PKCS-11-API"></a>
32332 <h3 class="section">E.7 Hardware token via PKCS 11 API</h3>
32333
32334 <p>The following functions are to be used for PKCS 11 handling.
32335 Their prototypes lie in <samp>gnutls/pkcs11.h</samp>.
32336 </p>
32337
32338 <a name="gnutls_005fpkcs11_005fadd_005fprovider-1"></a>
32339 <h4 class="subheading">gnutls_pkcs11_add_provider</h4>
32340 <a name="gnutls_005fpkcs11_005fadd_005fprovider"></a><dl>
32341 <dt><a name="index-gnutls_005fpkcs11_005fadd_005fprovider"></a>Function: <em>int</em> <strong>gnutls_pkcs11_add_provider</strong> <em>(const char * <var>name</var>, const char * <var>params</var>)</em></dt>
32342 <dd><p><var>name</var>: The filename of the module
32343 </p>
32344 <p><var>params</var>: should be NULL
32345 </p>
32346 <p>This function will load and add a PKCS 11 module to the module
32347 list used in gnutls. After this function is called the module will
32348 be used for PKCS 11 operations.
32349 </p>
32350 <p>When loading a module to be used for certificate verification,
32351 use the string &rsquo;trusted&rsquo; as  <code>params</code> .
32352 </p>
32353 <p>Note that this function is not thread safe.
32354 </p>
32355 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32356 negative error value.
32357 </p>
32358 <p><strong>Since:</strong> 2.12.0
32359 </p></dd></dl>
32360
32361 <a name="gnutls_005fpkcs11_005fcopy_005fsecret_005fkey-1"></a>
32362 <h4 class="subheading">gnutls_pkcs11_copy_secret_key</h4>
32363 <a name="gnutls_005fpkcs11_005fcopy_005fsecret_005fkey"></a><dl>
32364 <dt><a name="index-gnutls_005fpkcs11_005fcopy_005fsecret_005fkey"></a>Function: <em>int</em> <strong>gnutls_pkcs11_copy_secret_key</strong> <em>(const char * <var>token_url</var>, gnutls_datum_t * <var>key</var>, const char * <var>label</var>, unsigned int <var>key_usage</var>, unsigned int <var>flags</var>)</em></dt>
32365 <dd><p><var>token_url</var>: A PKCS <code>11</code>  URL specifying a token
32366 </p>
32367 <p><var>key</var>: The raw key
32368 </p>
32369 <p><var>label</var>: A name to be used for the stored data
32370 </p>
32371 <p><var>key_usage</var>: One of GNUTLS_KEY_*
32372 </p>
32373 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_FLAG_*
32374 </p>
32375 <p>This function will copy a raw secret (symmetric) key into a PKCS <code>11</code>
32376 token specified by a URL. The key can be marked as sensitive or not.
32377 </p>
32378 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32379 negative error value.
32380 </p>
32381 <p><strong>Since:</strong> 2.12.0
32382 </p></dd></dl>
32383
32384 <a name="gnutls_005fpkcs11_005fcopy_005fx509_005fcrt-1"></a>
32385 <h4 class="subheading">gnutls_pkcs11_copy_x509_crt</h4>
32386 <a name="gnutls_005fpkcs11_005fcopy_005fx509_005fcrt"></a><dl>
32387 <dt><a name="index-gnutls_005fpkcs11_005fcopy_005fx509_005fcrt-1"></a>Function: <em>int</em> <strong>gnutls_pkcs11_copy_x509_crt</strong> <em>(const char * <var>token_url</var>, gnutls_x509_crt_t <var>crt</var>, const char * <var>label</var>, unsigned int <var>flags</var>)</em></dt>
32388 <dd><p><var>token_url</var>: A PKCS <code>11</code>  URL specifying a token
32389 </p>
32390 <p><var>crt</var>: The certificate to copy
32391 </p>
32392 <p><var>label</var>: The name to be used for the stored data
32393 </p>
32394 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_FLAG_*
32395 </p>
32396 <p>This function will copy a certificate into a PKCS <code>11</code>  token specified by
32397 a URL. The certificate can be marked as trusted or not.
32398 </p>
32399 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32400 negative error value.
32401 </p>
32402 <p><strong>Since:</strong> 2.12.0
32403 </p></dd></dl>
32404
32405 <a name="gnutls_005fpkcs11_005fcopy_005fx509_005fcrt2-1"></a>
32406 <h4 class="subheading">gnutls_pkcs11_copy_x509_crt2</h4>
32407 <a name="gnutls_005fpkcs11_005fcopy_005fx509_005fcrt2"></a><dl>
32408 <dt><a name="index-gnutls_005fpkcs11_005fcopy_005fx509_005fcrt2"></a>Function: <em>int</em> <strong>gnutls_pkcs11_copy_x509_crt2</strong> <em>(const char * <var>token_url</var>, gnutls_x509_crt_t <var>crt</var>, const char * <var>label</var>, const gnutls_datum_t * <var>cid</var>, unsigned int <var>flags</var>)</em></dt>
32409 <dd><p><var>token_url</var>: A PKCS <code>11</code>  URL specifying a token
32410 </p>
32411 <p><var>crt</var>: The certificate to copy
32412 </p>
32413 <p><var>label</var>: The name to be used for the stored data
32414 </p>
32415 <p><var>cid</var>: The CKA_ID to set for the object -if NULL, the ID will be derived from the public key
32416 </p>
32417 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_FLAG_*
32418 </p>
32419 <p>This function will copy a certificate into a PKCS <code>11</code>  token specified by
32420 a URL. The certificate can be marked as trusted or not.
32421 </p>
32422 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32423 negative error value.
32424 </p>
32425 <p><strong>Since:</strong> 3.3.26
32426 </p></dd></dl>
32427
32428 <a name="gnutls_005fpkcs11_005fcopy_005fx509_005fprivkey-1"></a>
32429 <h4 class="subheading">gnutls_pkcs11_copy_x509_privkey</h4>
32430 <a name="gnutls_005fpkcs11_005fcopy_005fx509_005fprivkey"></a><dl>
32431 <dt><a name="index-gnutls_005fpkcs11_005fcopy_005fx509_005fprivkey-1"></a>Function: <em>int</em> <strong>gnutls_pkcs11_copy_x509_privkey</strong> <em>(const char * <var>token_url</var>, gnutls_x509_privkey_t <var>key</var>, const char * <var>label</var>, unsigned int <var>key_usage</var>, unsigned int <var>flags</var>)</em></dt>
32432 <dd><p><var>token_url</var>: A PKCS <code>11</code>  URL specifying a token
32433 </p>
32434 <p><var>key</var>: A private key
32435 </p>
32436 <p><var>label</var>: A name to be used for the stored data
32437 </p>
32438 <p><var>key_usage</var>: One of GNUTLS_KEY_*
32439 </p>
32440 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
32441 </p>
32442 <p>This function will copy a private key into a PKCS <code>11</code>  token specified by
32443 a URL. It is highly recommended flags to contain <code>GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE</code>
32444 unless there is a strong reason not to.
32445 </p>
32446 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32447 negative error value.
32448 </p>
32449 <p><strong>Since:</strong> 2.12.0
32450 </p></dd></dl>
32451
32452 <a name="gnutls_005fpkcs11_005fcopy_005fx509_005fprivkey2-1"></a>
32453 <h4 class="subheading">gnutls_pkcs11_copy_x509_privkey2</h4>
32454 <a name="gnutls_005fpkcs11_005fcopy_005fx509_005fprivkey2"></a><dl>
32455 <dt><a name="index-gnutls_005fpkcs11_005fcopy_005fx509_005fprivkey2"></a>Function: <em>int</em> <strong>gnutls_pkcs11_copy_x509_privkey2</strong> <em>(const char * <var>token_url</var>, gnutls_x509_privkey_t <var>key</var>, const char * <var>label</var>, const gnutls_datum_t * <var>cid</var>, unsigned int <var>key_usage</var>, unsigned int <var>flags</var>)</em></dt>
32456 <dd><p><var>token_url</var>: A PKCS <code>11</code>  URL specifying a token
32457 </p>
32458 <p><var>key</var>: A private key
32459 </p>
32460 <p><var>label</var>: A name to be used for the stored data
32461 </p>
32462 <p><var>cid</var>: The CKA_ID to set for the object -if NULL, the ID will be derived from the public key
32463 </p>
32464 <p><var>key_usage</var>: One of GNUTLS_KEY_*
32465 </p>
32466 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
32467 </p>
32468 <p>This function will copy a private key into a PKCS <code>11</code>  token specified by
32469 a URL. It is highly recommended flags to contain <code>GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE</code>
32470 unless there is a strong reason not to.
32471 </p>
32472 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32473 negative error value.
32474 </p>
32475 <p><strong>Since:</strong> 3.3.26
32476 </p></dd></dl>
32477
32478 <a name="gnutls_005fpkcs11_005fcrt_005fis_005fknown-1"></a>
32479 <h4 class="subheading">gnutls_pkcs11_crt_is_known</h4>
32480 <a name="gnutls_005fpkcs11_005fcrt_005fis_005fknown"></a><dl>
32481 <dt><a name="index-gnutls_005fpkcs11_005fcrt_005fis_005fknown"></a>Function: <em>int</em> <strong>gnutls_pkcs11_crt_is_known</strong> <em>(const char * <var>url</var>, gnutls_x509_crt_t <var>cert</var>, unsigned int <var>flags</var>)</em></dt>
32482 <dd><p><var>url</var>: A PKCS 11 url identifying a token
32483 </p>
32484 <p><var>cert</var>: is the certificate to find issuer for
32485 </p>
32486 <p><var>flags</var>: Use zero or flags from <code>GNUTLS_PKCS11_OBJ_FLAG</code> .
32487 </p>
32488 <p>This function will check whether the provided certificate is stored
32489 in the specified token. This is useful in combination with
32490 <code>GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_TRUSTED</code>  or
32491 <code>GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED</code> ,
32492 to check whether a CA is present or a certificate is blacklisted in
32493 a trust PKCS <code>11</code>  module.
32494 </p>
32495 <p>This function can be used with a  <code>url</code> of &quot;pkcs11:&quot;, and in that case all modules
32496 will be searched. To restrict the modules to the marked as trusted in p11-kit
32497 use the <code>GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE</code>  flag.
32498 </p>
32499 <p>Note that the flag <code>GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED</code>  is
32500 specific to p11-kit trust modules.
32501 </p>
32502 <p><strong>Returns:</strong> If the certificate exists non-zero is returned, otherwise zero.
32503 </p>
32504 <p><strong>Since:</strong> 3.3.0
32505 </p></dd></dl>
32506
32507 <a name="gnutls_005fpkcs11_005fdeinit-1"></a>
32508 <h4 class="subheading">gnutls_pkcs11_deinit</h4>
32509 <a name="gnutls_005fpkcs11_005fdeinit"></a><dl>
32510 <dt><a name="index-gnutls_005fpkcs11_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_pkcs11_deinit</strong> <em>( <var>void</var>)</em></dt>
32511 <dd>
32512 <p>This function will deinitialize the PKCS 11 subsystem in gnutls.
32513 This function is only needed if you need to deinitialize the
32514 subsystem without calling <code>gnutls_global_deinit()</code> .
32515 </p>
32516 <p><strong>Since:</strong> 2.12.0
32517 </p></dd></dl>
32518
32519 <a name="gnutls_005fpkcs11_005fdelete_005furl-1"></a>
32520 <h4 class="subheading">gnutls_pkcs11_delete_url</h4>
32521 <a name="gnutls_005fpkcs11_005fdelete_005furl"></a><dl>
32522 <dt><a name="index-gnutls_005fpkcs11_005fdelete_005furl-1"></a>Function: <em>int</em> <strong>gnutls_pkcs11_delete_url</strong> <em>(const char * <var>object_url</var>, unsigned int <var>flags</var>)</em></dt>
32523 <dd><p><var>object_url</var>: The URL of the object to delete.
32524 </p>
32525 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
32526 </p>
32527 <p>This function will delete objects matching the given URL.
32528 Note that not all tokens support the delete operation.
32529 </p>
32530 <p><strong>Returns:</strong> On success, the number of objects deleted is returned, otherwise a
32531 negative error value.
32532 </p>
32533 <p><strong>Since:</strong> 2.12.0
32534 </p></dd></dl>
32535
32536 <a name="gnutls_005fpkcs11_005fget_005fpin_005ffunction-1"></a>
32537 <h4 class="subheading">gnutls_pkcs11_get_pin_function</h4>
32538 <a name="gnutls_005fpkcs11_005fget_005fpin_005ffunction"></a><dl>
32539 <dt><a name="index-gnutls_005fpkcs11_005fget_005fpin_005ffunction"></a>Function: <em>gnutls_pin_callback_t</em> <strong>gnutls_pkcs11_get_pin_function</strong> <em>(void ** <var>userdata</var>)</em></dt>
32540 <dd><p><var>userdata</var>: data to be supplied to callback
32541 </p>
32542 <p>This function will return the callback function set using
32543 <code>gnutls_pkcs11_set_pin_function()</code> .
32544 </p>
32545 <p><strong>Returns:</strong> The function set or NULL otherwise.
32546 </p>
32547 <p><strong>Since:</strong> 3.1.0
32548 </p></dd></dl>
32549
32550 <a name="gnutls_005fpkcs11_005fget_005fraw_005fissuer-1"></a>
32551 <h4 class="subheading">gnutls_pkcs11_get_raw_issuer</h4>
32552 <a name="gnutls_005fpkcs11_005fget_005fraw_005fissuer"></a><dl>
32553 <dt><a name="index-gnutls_005fpkcs11_005fget_005fraw_005fissuer"></a>Function: <em>int</em> <strong>gnutls_pkcs11_get_raw_issuer</strong> <em>(const char * <var>url</var>, gnutls_x509_crt_t <var>cert</var>, gnutls_datum_t * <var>issuer</var>, gnutls_x509_crt_fmt_t <var>fmt</var>, unsigned int <var>flags</var>)</em></dt>
32554 <dd><p><var>url</var>: A PKCS 11 url identifying a token
32555 </p>
32556 <p><var>cert</var>: is the certificate to find issuer for
32557 </p>
32558 <p><var>issuer</var>: Will hold the issuer if any in an allocated buffer.
32559 </p>
32560 <p><var>fmt</var>: The format of the exported issuer.
32561 </p>
32562 <p><var>flags</var>: Use zero or flags from <code>GNUTLS_PKCS11_OBJ_FLAG</code> .
32563 </p>
32564 <p>This function will return the issuer of a given certificate, if it
32565 is stored in the token. By default only marked as trusted issuers
32566 are retuned. If any issuer should be returned specify
32567 <code>GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY</code>  in  <code>flags</code> .
32568 </p>
32569 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32570 negative error value.
32571 </p>
32572 <p><strong>Since:</strong> 3.2.7
32573 </p></dd></dl>
32574
32575 <a name="gnutls_005fpkcs11_005finit-1"></a>
32576 <h4 class="subheading">gnutls_pkcs11_init</h4>
32577 <a name="gnutls_005fpkcs11_005finit"></a><dl>
32578 <dt><a name="index-gnutls_005fpkcs11_005finit-1"></a>Function: <em>int</em> <strong>gnutls_pkcs11_init</strong> <em>(unsigned int <var>flags</var>, const char * <var>deprecated_config_file</var>)</em></dt>
32579 <dd><p><var>flags</var>: An ORed sequence of <code>GNUTLS_PKCS11_FLAG_</code> *
32580 </p>
32581 <p><var>deprecated_config_file</var>: either NULL or the location of a deprecated
32582 configuration file
32583 </p>
32584 <p>This function will initialize the PKCS 11 subsystem in gnutls. It will
32585 read configuration files if <code>GNUTLS_PKCS11_FLAG_AUTO</code>  is used or allow
32586 you to independently load PKCS 11 modules using <code>gnutls_pkcs11_add_provider()</code>
32587 if <code>GNUTLS_PKCS11_FLAG_MANUAL</code>  is specified.
32588 </p>
32589 <p>Normally you don&rsquo;t need to call this function since it is being called
32590 when the first PKCS 11 operation is requested using the <code>GNUTLS_PKCS11_FLAG_AUTO</code>
32591 flag. If another flags are required then it must be called independently
32592 prior to any PKCS 11 operation.
32593 </p>
32594 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32595 negative error value.
32596 </p>
32597 <p><strong>Since:</strong> 2.12.0
32598 </p></dd></dl>
32599
32600 <a name="gnutls_005fpkcs11_005fobj_005fdeinit-1"></a>
32601 <h4 class="subheading">gnutls_pkcs11_obj_deinit</h4>
32602 <a name="gnutls_005fpkcs11_005fobj_005fdeinit"></a><dl>
32603 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_pkcs11_obj_deinit</strong> <em>(gnutls_pkcs11_obj_t <var>obj</var>)</em></dt>
32604 <dd><p><var>obj</var>: The structure to be initialized
32605 </p>
32606 <p>This function will deinitialize a certificate structure.
32607 </p>
32608 <p><strong>Since:</strong> 2.12.0
32609 </p></dd></dl>
32610
32611 <a name="gnutls_005fpkcs11_005fobj_005fexport-1"></a>
32612 <h4 class="subheading">gnutls_pkcs11_obj_export</h4>
32613 <a name="gnutls_005fpkcs11_005fobj_005fexport"></a><dl>
32614 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fexport"></a>Function: <em>int</em> <strong>gnutls_pkcs11_obj_export</strong> <em>(gnutls_pkcs11_obj_t <var>obj</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
32615 <dd><p><var>obj</var>: Holds the object
32616 </p>
32617 <p><var>output_data</var>: will contain the object data
32618 </p>
32619 <p><var>output_data_size</var>: holds the size of output_data (and will be
32620 replaced by the actual size of parameters)
32621 </p>
32622 <p>This function will export the PKCS11 object data.  It is normal for
32623 data to be inaccesible and in that case <code>GNUTLS_E_INVALID_REQUEST</code>
32624 will be returned.
32625 </p>
32626 <p>If the buffer provided is not long enough to hold the output, then
32627 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
32628 be returned.
32629 </p>
32630 <p><strong>Returns:</strong> In case of failure a negative error code will be
32631 returned, and <code>GNUTLS_E_SUCCESS</code>  (0) on success.
32632 </p>
32633 <p><strong>Since:</strong> 2.12.0
32634 </p></dd></dl>
32635
32636 <a name="gnutls_005fpkcs11_005fobj_005fexport2-1"></a>
32637 <h4 class="subheading">gnutls_pkcs11_obj_export2</h4>
32638 <a name="gnutls_005fpkcs11_005fobj_005fexport2"></a><dl>
32639 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fexport2"></a>Function: <em>int</em> <strong>gnutls_pkcs11_obj_export2</strong> <em>(gnutls_pkcs11_obj_t <var>obj</var>, gnutls_datum_t * <var>out</var>)</em></dt>
32640 <dd><p><var>obj</var>: Holds the object
32641 </p>
32642 <p><var>out</var>: will contain the object data
32643 </p>
32644 <p>This function will export the PKCS11 object data.  It is normal for
32645 data to be inaccesible and in that case <code>GNUTLS_E_INVALID_REQUEST</code>
32646 will be returned.
32647 </p>
32648 <p>The output buffer is allocated using <code>gnutls_malloc()</code> .
32649 </p>
32650 <p><strong>Returns:</strong> In case of failure a negative error code will be
32651 returned, and <code>GNUTLS_E_SUCCESS</code>  (0) on success.
32652 </p>
32653 <p><strong>Since:</strong> 3.1.3
32654 </p></dd></dl>
32655
32656 <a name="gnutls_005fpkcs11_005fobj_005fexport3-1"></a>
32657 <h4 class="subheading">gnutls_pkcs11_obj_export3</h4>
32658 <a name="gnutls_005fpkcs11_005fobj_005fexport3"></a><dl>
32659 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fexport3"></a>Function: <em>int</em> <strong>gnutls_pkcs11_obj_export3</strong> <em>(gnutls_pkcs11_obj_t <var>obj</var>, gnutls_x509_crt_fmt_t <var>fmt</var>, gnutls_datum_t * <var>out</var>)</em></dt>
32660 <dd><p><var>obj</var>: Holds the object
32661 </p>
32662 <p><var>fmt</var>: The format of the exported data
32663 </p>
32664 <p><var>out</var>: will contain the object data
32665 </p>
32666 <p>This function will export the PKCS11 object data.  It is normal for
32667 data to be inaccesible and in that case <code>GNUTLS_E_INVALID_REQUEST</code>
32668 will be returned.
32669 </p>
32670 <p>The output buffer is allocated using <code>gnutls_malloc()</code> .
32671 </p>
32672 <p><strong>Returns:</strong> In case of failure a negative error code will be
32673 returned, and <code>GNUTLS_E_SUCCESS</code>  (0) on success.
32674 </p>
32675 <p><strong>Since:</strong> 3.2.7
32676 </p></dd></dl>
32677
32678 <a name="gnutls_005fpkcs11_005fobj_005fexport_005furl-1"></a>
32679 <h4 class="subheading">gnutls_pkcs11_obj_export_url</h4>
32680 <a name="gnutls_005fpkcs11_005fobj_005fexport_005furl"></a><dl>
32681 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fexport_005furl"></a>Function: <em>int</em> <strong>gnutls_pkcs11_obj_export_url</strong> <em>(gnutls_pkcs11_obj_t <var>obj</var>, gnutls_pkcs11_url_type_t <var>detailed</var>, char ** <var>url</var>)</em></dt>
32682 <dd><p><var>obj</var>: Holds the PKCS 11 certificate
32683 </p>
32684 <p><var>detailed</var>: non zero if a detailed URL is required
32685 </p>
32686 <p><var>url</var>: will contain an allocated url
32687 </p>
32688 <p>This function will export a URL identifying the given certificate.
32689 </p>
32690 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32691 negative error value.
32692 </p>
32693 <p><strong>Since:</strong> 2.12.0
32694 </p></dd></dl>
32695
32696 <a name="gnutls_005fpkcs11_005fobj_005fflags_005fget_005fstr-1"></a>
32697 <h4 class="subheading">gnutls_pkcs11_obj_flags_get_str</h4>
32698 <a name="gnutls_005fpkcs11_005fobj_005fflags_005fget_005fstr"></a><dl>
32699 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fflags_005fget_005fstr"></a>Function: <em>char *</em> <strong>gnutls_pkcs11_obj_flags_get_str</strong> <em>(unsigned int <var>flags</var>)</em></dt>
32700 <dd><p><var>flags</var>: holds the flags
32701 </p>
32702 <p>This function given an or-sequence of <code>GNUTLS_PKCS11_OBJ_FLAG_MARK</code> ,
32703 will return an allocated string with its description. The string
32704 needs to be deallocated using <code>gnutls_free()</code> .
32705 </p>
32706 <p><strong>Returns:</strong> If flags is zero <code>NULL</code>  is returned, otherwise an allocated string.
32707 </p>
32708 <p><strong>Since:</strong> 3.3.7
32709 </p></dd></dl>
32710
32711 <a name="gnutls_005fpkcs11_005fobj_005fget_005fexts-1"></a>
32712 <h4 class="subheading">gnutls_pkcs11_obj_get_exts</h4>
32713 <a name="gnutls_005fpkcs11_005fobj_005fget_005fexts"></a><dl>
32714 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fget_005fexts"></a>Function: <em>int</em> <strong>gnutls_pkcs11_obj_get_exts</strong> <em>(gnutls_pkcs11_obj_t <var>obj</var>, gnutls_x509_ext_st ** <var>exts</var>, unsigned int * <var>exts_size</var>, unsigned int <var>flags</var>)</em></dt>
32715 <dd><p><var>obj</var>: should contain a <code>gnutls_pkcs11_obj_t</code>  type
32716 </p>
32717 <p><var>exts</var>: a pointer to a <code>gnutls_x509_ext_st</code>  pointer
32718 </p>
32719 <p><var>exts_size</var>: will be updated with the number of  <code>exts</code>
32720 </p>
32721 <p><var>flags</var>: Or sequence of <code>GNUTLS_PKCS11_OBJ_</code> * flags
32722 </p>
32723 <p>This function will return information about attached extensions
32724 that associate to the provided object (which should be a certificate).
32725 The extensions are the attached p11-kit trust module extensions.
32726 </p>
32727 <p>Each element of  <code>exts</code> must be deinitialized using <code>gnutls_x509_ext_deinit()</code>
32728 while  <code>exts</code> should be deallocated using <code>gnutls_free()</code> .
32729 </p>
32730 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success or a negative error code on error.
32731 </p>
32732 <p><strong>Since:</strong> 3.3.8
32733 </p></dd></dl>
32734
32735 <a name="gnutls_005fpkcs11_005fobj_005fget_005fflags-1"></a>
32736 <h4 class="subheading">gnutls_pkcs11_obj_get_flags</h4>
32737 <a name="gnutls_005fpkcs11_005fobj_005fget_005fflags"></a><dl>
32738 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fget_005fflags"></a>Function: <em>int</em> <strong>gnutls_pkcs11_obj_get_flags</strong> <em>(gnutls_pkcs11_obj_t <var>obj</var>, unsigned int * <var>oflags</var>)</em></dt>
32739 <dd><p><var>obj</var>: The structure that holds the object
32740 </p>
32741 <p><var>oflags</var>: Will hold the output flags
32742 </p>
32743 <p>This function will return the flags of the object being
32744 stored in the structure. The  <code>oflags</code> are the <code>GNUTLS_PKCS11_OBJ_FLAG_MARK</code>
32745 flags.
32746 </p>
32747 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32748 negative error value.
32749 </p>
32750 <p><strong>Since:</strong> 3.3.7
32751 </p></dd></dl>
32752
32753 <a name="gnutls_005fpkcs11_005fobj_005fget_005finfo-1"></a>
32754 <h4 class="subheading">gnutls_pkcs11_obj_get_info</h4>
32755 <a name="gnutls_005fpkcs11_005fobj_005fget_005finfo"></a><dl>
32756 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fget_005finfo-1"></a>Function: <em>int</em> <strong>gnutls_pkcs11_obj_get_info</strong> <em>(gnutls_pkcs11_obj_t <var>obj</var>, gnutls_pkcs11_obj_info_t <var>itype</var>, void * <var>output</var>, size_t * <var>output_size</var>)</em></dt>
32757 <dd><p><var>obj</var>: should contain a <code>gnutls_pkcs11_obj_t</code>  structure
32758 </p>
32759 <p><var>itype</var>: Denotes the type of information requested
32760 </p>
32761 <p><var>output</var>: where output will be stored
32762 </p>
32763 <p><var>output_size</var>: contains the maximum size of the output and will be overwritten with actual
32764 </p>
32765 <p>This function will return information about the PKCS11 certificate
32766 such as the label, id as well as token information where the key is
32767 stored. When output is text it returns null terminated string
32768 although  <code>output_size</code> contains the size of the actual data only.
32769 </p>
32770 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success or a negative error code on error.
32771 </p>
32772 <p><strong>Since:</strong> 2.12.0
32773 </p></dd></dl>
32774
32775 <a name="gnutls_005fpkcs11_005fobj_005fget_005ftype-1"></a>
32776 <h4 class="subheading">gnutls_pkcs11_obj_get_type</h4>
32777 <a name="gnutls_005fpkcs11_005fobj_005fget_005ftype"></a><dl>
32778 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fget_005ftype"></a>Function: <em>gnutls_pkcs11_obj_type_t</em> <strong>gnutls_pkcs11_obj_get_type</strong> <em>(gnutls_pkcs11_obj_t <var>obj</var>)</em></dt>
32779 <dd><p><var>obj</var>: Holds the PKCS 11 object
32780 </p>
32781 <p>This function will return the type of the object being
32782 stored in the structure.
32783 </p>
32784 <p><strong>Returns:</strong> The type of the object
32785 </p>
32786 <p><strong>Since:</strong> 2.12.0
32787 </p></dd></dl>
32788
32789 <a name="gnutls_005fpkcs11_005fobj_005fimport_005furl-1"></a>
32790 <h4 class="subheading">gnutls_pkcs11_obj_import_url</h4>
32791 <a name="gnutls_005fpkcs11_005fobj_005fimport_005furl"></a><dl>
32792 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fimport_005furl"></a>Function: <em>int</em> <strong>gnutls_pkcs11_obj_import_url</strong> <em>(gnutls_pkcs11_obj_t <var>obj</var>, const char * <var>url</var>, unsigned int <var>flags</var>)</em></dt>
32793 <dd><p><var>obj</var>: The structure to store the object
32794 </p>
32795 <p><var>url</var>: a PKCS 11 url identifying the key
32796 </p>
32797 <p><var>flags</var>: Or sequence of GNUTLS_PKCS11_OBJ_* flags
32798 </p>
32799 <p>This function will &quot;import&quot; a PKCS 11 URL identifying an object (e.g. certificate)
32800 to the <code>gnutls_pkcs11_obj_t</code>  structure. This does not involve any
32801 parsing (such as X.509 or OpenPGP) since the <code>gnutls_pkcs11_obj_t</code>  is
32802 format agnostic. Only data are transferred.
32803 </p>
32804 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32805 negative error value.
32806 </p>
32807 <p><strong>Since:</strong> 2.12.0
32808 </p></dd></dl>
32809
32810 <a name="gnutls_005fpkcs11_005fobj_005finit-1"></a>
32811 <h4 class="subheading">gnutls_pkcs11_obj_init</h4>
32812 <a name="gnutls_005fpkcs11_005fobj_005finit"></a><dl>
32813 <dt><a name="index-gnutls_005fpkcs11_005fobj_005finit"></a>Function: <em>int</em> <strong>gnutls_pkcs11_obj_init</strong> <em>(gnutls_pkcs11_obj_t * <var>obj</var>)</em></dt>
32814 <dd><p><var>obj</var>: The structure to be initialized
32815 </p>
32816 <p>This function will initialize a pkcs11 certificate structure.
32817 </p>
32818 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32819 negative error value.
32820 </p>
32821 <p><strong>Since:</strong> 2.12.0
32822 </p></dd></dl>
32823
32824 <a name="gnutls_005fpkcs11_005fobj_005flist_005fimport_005furl-1"></a>
32825 <h4 class="subheading">gnutls_pkcs11_obj_list_import_url</h4>
32826 <a name="gnutls_005fpkcs11_005fobj_005flist_005fimport_005furl"></a><dl>
32827 <dt><a name="index-gnutls_005fpkcs11_005fobj_005flist_005fimport_005furl"></a>Function: <em>int</em> <strong>gnutls_pkcs11_obj_list_import_url</strong> <em>(gnutls_pkcs11_obj_t * <var>p_list</var>, unsigned int * <var>n_list</var>, const char * <var>url</var>, gnutls_pkcs11_obj_attr_t <var>attrs</var>, unsigned int <var>flags</var>)</em></dt>
32828 <dd><p><var>p_list</var>: An uninitialized object list (may be NULL)
32829 </p>
32830 <p><var>n_list</var>: initially should hold the maximum size of the list. Will contain the actual size.
32831 </p>
32832 <p><var>url</var>: A PKCS 11 url identifying a set of objects
32833 </p>
32834 <p><var>attrs</var>: Attributes of type <code>gnutls_pkcs11_obj_attr_t</code>  that can be used to limit output
32835 </p>
32836 <p><var>flags</var>: Or sequence of GNUTLS_PKCS11_OBJ_* flags
32837 </p>
32838 <p>This function will initialize and set values to an object list
32839 by using all objects identified by a PKCS 11 URL.
32840 </p>
32841 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32842 negative error value.
32843 </p>
32844 <p><strong>Since:</strong> 2.12.0
32845 </p></dd></dl>
32846
32847 <a name="gnutls_005fpkcs11_005fobj_005flist_005fimport_005furl2-1"></a>
32848 <h4 class="subheading">gnutls_pkcs11_obj_list_import_url2</h4>
32849 <a name="gnutls_005fpkcs11_005fobj_005flist_005fimport_005furl2"></a><dl>
32850 <dt><a name="index-gnutls_005fpkcs11_005fobj_005flist_005fimport_005furl2"></a>Function: <em>int</em> <strong>gnutls_pkcs11_obj_list_import_url2</strong> <em>(gnutls_pkcs11_obj_t ** <var>p_list</var>, unsigned int * <var>n_list</var>, const char * <var>url</var>, gnutls_pkcs11_obj_attr_t <var>attrs</var>, unsigned int <var>flags</var>)</em></dt>
32851 <dd><p><var>p_list</var>: An uninitialized object list (may be NULL)
32852 </p>
32853 <p><var>n_list</var>: It will contain the size of the list.
32854 </p>
32855 <p><var>url</var>: A PKCS 11 url identifying a set of objects
32856 </p>
32857 <p><var>attrs</var>: Attributes of type <code>gnutls_pkcs11_obj_attr_t</code>  that can be used to limit output
32858 </p>
32859 <p><var>flags</var>: Or sequence of GNUTLS_PKCS11_OBJ_* flags
32860 </p>
32861 <p>This function will initialize and set values to an object list
32862 by using all objects identified by the PKCS 11 URL. The output
32863 is stored in  <code>p_list</code> , which will be initialized.
32864 </p>
32865 <p>All returned objects must be deinitialized using <code>gnutls_pkcs11_obj_deinit()</code> ,
32866 and  <code>p_list</code> must be free&rsquo;d using <code>gnutls_free()</code> .
32867 </p>
32868 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32869 negative error value.
32870 </p>
32871 <p><strong>Since:</strong> 3.1.0
32872 </p></dd></dl>
32873
32874 <a name="gnutls_005fpkcs11_005fobj_005fset_005finfo-1"></a>
32875 <h4 class="subheading">gnutls_pkcs11_obj_set_info</h4>
32876 <a name="gnutls_005fpkcs11_005fobj_005fset_005finfo"></a><dl>
32877 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fset_005finfo"></a>Function: <em>int</em> <strong>gnutls_pkcs11_obj_set_info</strong> <em>(gnutls_pkcs11_obj_t <var>obj</var>, gnutls_pkcs11_obj_info_t <var>itype</var>, const void * <var>data</var>, size_t <var>data_size</var>, unsigned <var>flags</var>)</em></dt>
32878 <dd><p><var>obj</var>: should contain a <code>gnutls_pkcs11_obj_t</code>  structure
32879 </p>
32880 <p><var>itype</var>: Denotes the type of information to be set
32881 </p>
32882 <p><var>data</var>: the data to set
32883 </p>
32884 <p><var>data_size</var>: the size of data
32885 </p>
32886 <p><var>flags</var>: Or sequence of GNUTLS_PKCS11_OBJ_* flags
32887 </p>
32888 <p>This function will set attributes on the provided object.
32889 Available options for  <code>itype</code> are <code>GNUTLS_PKCS11_OBJ_LABEL</code> ,
32890 <code>GNUTLS_PKCS11_OBJ_ID_HEX</code> , and <code>GNUTLS_PKCS11_OBJ_ID</code> .
32891 </p>
32892 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success or a negative error code on error.
32893 </p>
32894 <p><strong>Since:</strong> 3.3.26
32895 </p></dd></dl>
32896
32897 <a name="gnutls_005fpkcs11_005fobj_005fset_005fpin_005ffunction-1"></a>
32898 <h4 class="subheading">gnutls_pkcs11_obj_set_pin_function</h4>
32899 <a name="gnutls_005fpkcs11_005fobj_005fset_005fpin_005ffunction"></a><dl>
32900 <dt><a name="index-gnutls_005fpkcs11_005fobj_005fset_005fpin_005ffunction"></a>Function: <em>void</em> <strong>gnutls_pkcs11_obj_set_pin_function</strong> <em>(gnutls_pkcs11_obj_t <var>obj</var>, gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</em></dt>
32901 <dd><p><var>obj</var>: The object structure
32902 </p>
32903 <p><var>fn</var>: the callback
32904 </p>
32905 <p><var>userdata</var>: data associated with the callback
32906 </p>
32907 <p>This function will set a callback function to be used when
32908 required to access the object. This function overrides the global
32909 set using <code>gnutls_pkcs11_set_pin_function()</code> .
32910 </p>
32911 <p><strong>Since:</strong> 3.1.0
32912 </p></dd></dl>
32913
32914 <a name="gnutls_005fpkcs11_005fprivkey_005fdeinit-1"></a>
32915 <h4 class="subheading">gnutls_pkcs11_privkey_deinit</h4>
32916 <a name="gnutls_005fpkcs11_005fprivkey_005fdeinit"></a><dl>
32917 <dt><a name="index-gnutls_005fpkcs11_005fprivkey_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_pkcs11_privkey_deinit</strong> <em>(gnutls_pkcs11_privkey_t <var>key</var>)</em></dt>
32918 <dd><p><var>key</var>: The structure to be initialized
32919 </p>
32920 <p>This function will deinitialize a private key structure.
32921 </p></dd></dl>
32922
32923 <a name="gnutls_005fpkcs11_005fprivkey_005fexport_005fpubkey-1"></a>
32924 <h4 class="subheading">gnutls_pkcs11_privkey_export_pubkey</h4>
32925 <a name="gnutls_005fpkcs11_005fprivkey_005fexport_005fpubkey"></a><dl>
32926 <dt><a name="index-gnutls_005fpkcs11_005fprivkey_005fexport_005fpubkey"></a>Function: <em>int</em> <strong>gnutls_pkcs11_privkey_export_pubkey</strong> <em>(gnutls_pkcs11_privkey_t <var>pkey</var>, gnutls_x509_crt_fmt_t <var>fmt</var>, gnutls_datum_t * <var>data</var>, unsigned int <var>flags</var>)</em></dt>
32927 <dd><p><var>pkey</var>: The private key
32928 </p>
32929 <p><var>fmt</var>: the format of output params. PEM or DER.
32930 </p>
32931 <p><var>data</var>: will hold the public key
32932 </p>
32933 <p><var>flags</var>: should be zero
32934 </p>
32935 <p>This function will extract the public key (modulus and public
32936 exponent) from the private key specified by the  <code>url</code> private key.
32937 This public key will be stored in  <code>pubkey</code> in the format specified
32938 by  <code>fmt</code> .  <code>pubkey</code> should be deinitialized using <code>gnutls_free()</code> .
32939 </p>
32940 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32941 negative error value.
32942 </p>
32943 <p><strong>Since:</strong> 3.3.7
32944 </p></dd></dl>
32945
32946 <a name="gnutls_005fpkcs11_005fprivkey_005fexport_005furl-1"></a>
32947 <h4 class="subheading">gnutls_pkcs11_privkey_export_url</h4>
32948 <a name="gnutls_005fpkcs11_005fprivkey_005fexport_005furl"></a><dl>
32949 <dt><a name="index-gnutls_005fpkcs11_005fprivkey_005fexport_005furl"></a>Function: <em>int</em> <strong>gnutls_pkcs11_privkey_export_url</strong> <em>(gnutls_pkcs11_privkey_t <var>key</var>, gnutls_pkcs11_url_type_t <var>detailed</var>, char ** <var>url</var>)</em></dt>
32950 <dd><p><var>key</var>: Holds the PKCS 11 key
32951 </p>
32952 <p><var>detailed</var>: non zero if a detailed URL is required
32953 </p>
32954 <p><var>url</var>: will contain an allocated url
32955 </p>
32956 <p>This function will export a URL identifying the given key.
32957 </p>
32958 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32959 negative error value.
32960 </p></dd></dl>
32961
32962 <a name="gnutls_005fpkcs11_005fprivkey_005fgenerate-1"></a>
32963 <h4 class="subheading">gnutls_pkcs11_privkey_generate</h4>
32964 <a name="gnutls_005fpkcs11_005fprivkey_005fgenerate"></a><dl>
32965 <dt><a name="index-gnutls_005fpkcs11_005fprivkey_005fgenerate"></a>Function: <em>int</em> <strong>gnutls_pkcs11_privkey_generate</strong> <em>(const char * <var>url</var>, gnutls_pk_algorithm_t <var>pk</var>, unsigned int <var>bits</var>, const char * <var>label</var>, unsigned int <var>flags</var>)</em></dt>
32966 <dd><p><var>url</var>: a token URL
32967 </p>
32968 <p><var>pk</var>: the public key algorithm
32969 </p>
32970 <p><var>bits</var>: the security bits
32971 </p>
32972 <p><var>label</var>: a label
32973 </p>
32974 <p><var>flags</var>: should be zero
32975 </p>
32976 <p>This function will generate a private key in the specified
32977 by the  <code>url</code> token. The private key will be generate within
32978 the token and will not be exportable.
32979 </p>
32980 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
32981 negative error value.
32982 </p>
32983 <p><strong>Since:</strong> 3.0
32984 </p></dd></dl>
32985
32986 <a name="gnutls_005fpkcs11_005fprivkey_005fgenerate2-1"></a>
32987 <h4 class="subheading">gnutls_pkcs11_privkey_generate2</h4>
32988 <a name="gnutls_005fpkcs11_005fprivkey_005fgenerate2"></a><dl>
32989 <dt><a name="index-gnutls_005fpkcs11_005fprivkey_005fgenerate2"></a>Function: <em>int</em> <strong>gnutls_pkcs11_privkey_generate2</strong> <em>(const char * <var>url</var>, gnutls_pk_algorithm_t <var>pk</var>, unsigned int <var>bits</var>, const char * <var>label</var>, gnutls_x509_crt_fmt_t <var>fmt</var>, gnutls_datum_t * <var>pubkey</var>, unsigned int <var>flags</var>)</em></dt>
32990 <dd><p><var>url</var>: a token URL
32991 </p>
32992 <p><var>pk</var>: the public key algorithm
32993 </p>
32994 <p><var>bits</var>: the security bits
32995 </p>
32996 <p><var>label</var>: a label
32997 </p>
32998 <p><var>fmt</var>: the format of output params. PEM or DER
32999 </p>
33000 <p><var>pubkey</var>: will hold the public key (may be <code>NULL</code> )
33001 </p>
33002 <p><var>flags</var>: zero or an OR&rsquo;ed sequence of <code>GNUTLS_PKCS11_OBJ_FLAGs</code>
33003 </p>
33004 <p>This function will generate a private key in the specified
33005 by the  <code>url</code> token. The private key will be generate within
33006 the token and will not be exportable. This function will
33007 store the DER-encoded public key in the SubjectPublicKeyInfo format
33008 in  <code>pubkey</code> . The  <code>pubkey</code> should be deinitialized using <code>gnutls_free()</code> .
33009 </p>
33010 <p>Note that when generating an elliptic curve key, the curve
33011 can be substituted in the place of the bits parameter using the
33012 <code>GNUTLS_CURVE_TO_BITS()</code>  macro.
33013 </p>
33014 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33015 negative error value.
33016 </p>
33017 <p><strong>Since:</strong> 3.1.5
33018 </p></dd></dl>
33019
33020 <a name="gnutls_005fpkcs11_005fprivkey_005fgenerate3-1"></a>
33021 <h4 class="subheading">gnutls_pkcs11_privkey_generate3</h4>
33022 <a name="gnutls_005fpkcs11_005fprivkey_005fgenerate3"></a><dl>
33023 <dt><a name="index-gnutls_005fpkcs11_005fprivkey_005fgenerate3"></a>Function: <em>int</em> <strong>gnutls_pkcs11_privkey_generate3</strong> <em>(const char * <var>url</var>, gnutls_pk_algorithm_t <var>pk</var>, unsigned int <var>bits</var>, const char * <var>label</var>, const gnutls_datum_t * <var>cid</var>, gnutls_x509_crt_fmt_t <var>fmt</var>, gnutls_datum_t * <var>pubkey</var>, unsigned int <var>flags</var>)</em></dt>
33024 <dd><p><var>url</var>: a token URL
33025 </p>
33026 <p><var>pk</var>: the public key algorithm
33027 </p>
33028 <p><var>bits</var>: the security bits
33029 </p>
33030 <p><var>label</var>: a label
33031 </p>
33032 <p><var>cid</var>: The CKA_ID to use for the new object
33033 </p>
33034 <p><var>fmt</var>: the format of output params. PEM or DER
33035 </p>
33036 <p><var>pubkey</var>: will hold the public key (may be <code>NULL</code> )
33037 </p>
33038 <p><var>flags</var>: zero or an OR&rsquo;ed sequence of <code>GNUTLS_PKCS11_OBJ_FLAGs</code>
33039 </p>
33040 <p>This function will generate a private key in the specified
33041 by the  <code>url</code> token. The private key will be generate within
33042 the token and will not be exportable. This function will
33043 store the DER-encoded public key in the SubjectPublicKeyInfo format
33044 in  <code>pubkey</code> . The  <code>pubkey</code> should be deinitialized using <code>gnutls_free()</code> .
33045 </p>
33046 <p>Note that when generating an elliptic curve key, the curve
33047 can be substituted in the place of the bits parameter using the
33048 <code>GNUTLS_CURVE_TO_BITS()</code>  macro.
33049 </p>
33050 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33051 negative error value.
33052 </p>
33053 <p><strong>Since:</strong> 3.3.26
33054 </p></dd></dl>
33055
33056 <a name="gnutls_005fpkcs11_005fprivkey_005fget_005finfo-1"></a>
33057 <h4 class="subheading">gnutls_pkcs11_privkey_get_info</h4>
33058 <a name="gnutls_005fpkcs11_005fprivkey_005fget_005finfo"></a><dl>
33059 <dt><a name="index-gnutls_005fpkcs11_005fprivkey_005fget_005finfo"></a>Function: <em>int</em> <strong>gnutls_pkcs11_privkey_get_info</strong> <em>(gnutls_pkcs11_privkey_t <var>pkey</var>, gnutls_pkcs11_obj_info_t <var>itype</var>, void * <var>output</var>, size_t * <var>output_size</var>)</em></dt>
33060 <dd><p><var>pkey</var>: should contain a <code>gnutls_pkcs11_privkey_t</code>  structure
33061 </p>
33062 <p><var>itype</var>: Denotes the type of information requested
33063 </p>
33064 <p><var>output</var>: where output will be stored
33065 </p>
33066 <p><var>output_size</var>: contains the maximum size of the output and will be overwritten with actual
33067 </p>
33068 <p>This function will return information about the PKCS 11 private key such
33069 as the label, id as well as token information where the key is stored. When
33070 output is text it returns null terminated string although <code>output_size</code>  contains
33071 the size of the actual data only.
33072 </p>
33073 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success or a negative error code on error.
33074 </p></dd></dl>
33075
33076 <a name="gnutls_005fpkcs11_005fprivkey_005fget_005fpk_005falgorithm-1"></a>
33077 <h4 class="subheading">gnutls_pkcs11_privkey_get_pk_algorithm</h4>
33078 <a name="gnutls_005fpkcs11_005fprivkey_005fget_005fpk_005falgorithm"></a><dl>
33079 <dt><a name="index-gnutls_005fpkcs11_005fprivkey_005fget_005fpk_005falgorithm"></a>Function: <em>int</em> <strong>gnutls_pkcs11_privkey_get_pk_algorithm</strong> <em>(gnutls_pkcs11_privkey_t <var>key</var>, unsigned int * <var>bits</var>)</em></dt>
33080 <dd><p><var>key</var>: should contain a <code>gnutls_pkcs11_privkey_t</code>  structure
33081 </p>
33082 <p><var>bits</var>: if bits is non null it will hold the size of the parameters&rsquo; in bits
33083 </p>
33084 <p>This function will return the public key algorithm of a private
33085 key.
33086 </p>
33087 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code>  enumeration on
33088 success, or a negative error code on error.
33089 </p></dd></dl>
33090
33091 <a name="gnutls_005fpkcs11_005fprivkey_005fimport_005furl-1"></a>
33092 <h4 class="subheading">gnutls_pkcs11_privkey_import_url</h4>
33093 <a name="gnutls_005fpkcs11_005fprivkey_005fimport_005furl"></a><dl>
33094 <dt><a name="index-gnutls_005fpkcs11_005fprivkey_005fimport_005furl"></a>Function: <em>int</em> <strong>gnutls_pkcs11_privkey_import_url</strong> <em>(gnutls_pkcs11_privkey_t <var>pkey</var>, const char * <var>url</var>, unsigned int <var>flags</var>)</em></dt>
33095 <dd><p><var>pkey</var>: The structure to store the parsed key
33096 </p>
33097 <p><var>url</var>: a PKCS 11 url identifying the key
33098 </p>
33099 <p><var>flags</var>: Or sequence of GNUTLS_PKCS11_OBJ_* flags
33100 </p>
33101 <p>This function will &quot;import&quot; a PKCS 11 URL identifying a private
33102 key to the <code>gnutls_pkcs11_privkey_t</code>  structure. In reality since
33103 in most cases keys cannot be exported, the private key structure
33104 is being associated with the available operations on the token.
33105 </p>
33106 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33107 negative error value.
33108 </p></dd></dl>
33109
33110 <a name="gnutls_005fpkcs11_005fprivkey_005finit-1"></a>
33111 <h4 class="subheading">gnutls_pkcs11_privkey_init</h4>
33112 <a name="gnutls_005fpkcs11_005fprivkey_005finit"></a><dl>
33113 <dt><a name="index-gnutls_005fpkcs11_005fprivkey_005finit"></a>Function: <em>int</em> <strong>gnutls_pkcs11_privkey_init</strong> <em>(gnutls_pkcs11_privkey_t * <var>key</var>)</em></dt>
33114 <dd><p><var>key</var>: The structure to be initialized
33115 </p>
33116 <p>This function will initialize an private key structure.
33117 </p>
33118 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33119 negative error value.
33120 </p></dd></dl>
33121
33122 <a name="gnutls_005fpkcs11_005fprivkey_005fset_005fpin_005ffunction-1"></a>
33123 <h4 class="subheading">gnutls_pkcs11_privkey_set_pin_function</h4>
33124 <a name="gnutls_005fpkcs11_005fprivkey_005fset_005fpin_005ffunction"></a><dl>
33125 <dt><a name="index-gnutls_005fpkcs11_005fprivkey_005fset_005fpin_005ffunction"></a>Function: <em>void</em> <strong>gnutls_pkcs11_privkey_set_pin_function</strong> <em>(gnutls_pkcs11_privkey_t <var>key</var>, gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</em></dt>
33126 <dd><p><var>key</var>: The private key
33127 </p>
33128 <p><var>fn</var>: the callback
33129 </p>
33130 <p><var>userdata</var>: data associated with the callback
33131 </p>
33132 <p>This function will set a callback function to be used when
33133 required to access the object. This function overrides the global
33134 set using <code>gnutls_pkcs11_set_pin_function()</code> .
33135 </p>
33136 <p><strong>Since:</strong> 3.1.0
33137 </p></dd></dl>
33138
33139 <a name="gnutls_005fpkcs11_005fprivkey_005fstatus-1"></a>
33140 <h4 class="subheading">gnutls_pkcs11_privkey_status</h4>
33141 <a name="gnutls_005fpkcs11_005fprivkey_005fstatus"></a><dl>
33142 <dt><a name="index-gnutls_005fpkcs11_005fprivkey_005fstatus"></a>Function: <em>int</em> <strong>gnutls_pkcs11_privkey_status</strong> <em>(gnutls_pkcs11_privkey_t <var>key</var>)</em></dt>
33143 <dd><p><var>key</var>: Holds the key
33144 </p>
33145 <p>Checks the status of the private key token.
33146 </p>
33147 <p><strong>Returns:</strong> this function will return non-zero if the token
33148 holding the private key is still available (inserted), and zero otherwise.
33149 </p>
33150 <p><strong>Since:</strong> 3.1.9
33151 </p></dd></dl>
33152
33153 <a name="gnutls_005fpkcs11_005freinit-1"></a>
33154 <h4 class="subheading">gnutls_pkcs11_reinit</h4>
33155 <a name="gnutls_005fpkcs11_005freinit"></a><dl>
33156 <dt><a name="index-gnutls_005fpkcs11_005freinit"></a>Function: <em>int</em> <strong>gnutls_pkcs11_reinit</strong> <em>( <var>void</var>)</em></dt>
33157 <dd>
33158 <p>This function will reinitialize the PKCS 11 subsystem in gnutls.
33159 This is required by PKCS 11 when an application uses <code>fork()</code> . The
33160 reinitialization function must be called on the child.
33161 </p>
33162 <p>Note that since GnuTLS 3.3.0, the reinitialization of the PKCS <code>11</code>
33163 subsystem occurs automatically after fork.
33164 </p>
33165 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33166 negative error value.
33167 </p>
33168 <p><strong>Since:</strong> 3.0
33169 </p></dd></dl>
33170
33171 <a name="gnutls_005fpkcs11_005fset_005fpin_005ffunction-1"></a>
33172 <h4 class="subheading">gnutls_pkcs11_set_pin_function</h4>
33173 <a name="gnutls_005fpkcs11_005fset_005fpin_005ffunction"></a><dl>
33174 <dt><a name="index-gnutls_005fpkcs11_005fset_005fpin_005ffunction"></a>Function: <em>void</em> <strong>gnutls_pkcs11_set_pin_function</strong> <em>(gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</em></dt>
33175 <dd><p><var>fn</var>: The PIN callback, a <code>gnutls_pin_callback_t()</code>  function.
33176 </p>
33177 <p><var>userdata</var>: data to be supplied to callback
33178 </p>
33179 <p>This function will set a callback function to be used when a PIN is
33180 required for PKCS 11 operations.  See
33181 <code>gnutls_pin_callback_t()</code>  on how the callback should behave.
33182 </p>
33183 <p><strong>Since:</strong> 2.12.0
33184 </p></dd></dl>
33185
33186 <a name="gnutls_005fpkcs11_005fset_005ftoken_005ffunction-1"></a>
33187 <h4 class="subheading">gnutls_pkcs11_set_token_function</h4>
33188 <a name="gnutls_005fpkcs11_005fset_005ftoken_005ffunction"></a><dl>
33189 <dt><a name="index-gnutls_005fpkcs11_005fset_005ftoken_005ffunction"></a>Function: <em>void</em> <strong>gnutls_pkcs11_set_token_function</strong> <em>(gnutls_pkcs11_token_callback_t <var>fn</var>, void * <var>userdata</var>)</em></dt>
33190 <dd><p><var>fn</var>: The token callback
33191 </p>
33192 <p><var>userdata</var>: data to be supplied to callback
33193 </p>
33194 <p>This function will set a callback function to be used when a token
33195 needs to be inserted to continue PKCS 11 operations.
33196 </p>
33197 <p><strong>Since:</strong> 2.12.0
33198 </p></dd></dl>
33199
33200 <a name="gnutls_005fpkcs11_005ftoken_005fget_005fflags-1"></a>
33201 <h4 class="subheading">gnutls_pkcs11_token_get_flags</h4>
33202 <a name="gnutls_005fpkcs11_005ftoken_005fget_005fflags"></a><dl>
33203 <dt><a name="index-gnutls_005fpkcs11_005ftoken_005fget_005fflags"></a>Function: <em>int</em> <strong>gnutls_pkcs11_token_get_flags</strong> <em>(const char * <var>url</var>, unsigned int * <var>flags</var>)</em></dt>
33204 <dd><p><var>url</var>: should contain a PKCS 11 URL
33205 </p>
33206 <p><var>flags</var>: The output flags (GNUTLS_PKCS11_TOKEN_*)
33207 </p>
33208 <p>This function will return information about the PKCS 11 token flags.
33209 </p>
33210 <p>The supported flags are: <code>GNUTLS_PKCS11_TOKEN_HW</code>  and <code>GNUTLS_PKCS11_TOKEN_TRUSTED</code> .
33211 </p>
33212 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success or a negative error code on error.
33213 </p>
33214 <p><strong>Since:</strong> 2.12.0
33215 </p></dd></dl>
33216
33217 <a name="gnutls_005fpkcs11_005ftoken_005fget_005finfo-1"></a>
33218 <h4 class="subheading">gnutls_pkcs11_token_get_info</h4>
33219 <a name="gnutls_005fpkcs11_005ftoken_005fget_005finfo"></a><dl>
33220 <dt><a name="index-gnutls_005fpkcs11_005ftoken_005fget_005finfo"></a>Function: <em>int</em> <strong>gnutls_pkcs11_token_get_info</strong> <em>(const char * <var>url</var>, gnutls_pkcs11_token_info_t <var>ttype</var>, void * <var>output</var>, size_t * <var>output_size</var>)</em></dt>
33221 <dd><p><var>url</var>: should contain a PKCS 11 URL
33222 </p>
33223 <p><var>ttype</var>: Denotes the type of information requested
33224 </p>
33225 <p><var>output</var>: where output will be stored
33226 </p>
33227 <p><var>output_size</var>: contains the maximum size of the output and will be overwritten with actual
33228 </p>
33229 <p>This function will return information about the PKCS 11 token such
33230 as the label, id, etc.
33231 </p>
33232 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success or a negative error code
33233 on error.
33234 </p>
33235 <p><strong>Since:</strong> 2.12.0
33236 </p></dd></dl>
33237
33238 <a name="gnutls_005fpkcs11_005ftoken_005fget_005fmechanism-1"></a>
33239 <h4 class="subheading">gnutls_pkcs11_token_get_mechanism</h4>
33240 <a name="gnutls_005fpkcs11_005ftoken_005fget_005fmechanism"></a><dl>
33241 <dt><a name="index-gnutls_005fpkcs11_005ftoken_005fget_005fmechanism"></a>Function: <em>int</em> <strong>gnutls_pkcs11_token_get_mechanism</strong> <em>(const char * <var>url</var>, unsigned int <var>idx</var>, unsigned long * <var>mechanism</var>)</em></dt>
33242 <dd><p><var>url</var>: should contain a PKCS 11 URL
33243 </p>
33244 <p><var>idx</var>: The index of the mechanism
33245 </p>
33246 <p><var>mechanism</var>: The PKCS <code>11</code>  mechanism ID
33247 </p>
33248 <p>This function will return the names of the supported mechanisms
33249 by the token. It should be called with an increasing index until
33250 it return GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE.
33251 </p>
33252 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success or a negative error code on error.
33253 </p>
33254 <p><strong>Since:</strong> 2.12.0
33255 </p></dd></dl>
33256
33257 <a name="gnutls_005fpkcs11_005ftoken_005fget_005frandom-1"></a>
33258 <h4 class="subheading">gnutls_pkcs11_token_get_random</h4>
33259 <a name="gnutls_005fpkcs11_005ftoken_005fget_005frandom"></a><dl>
33260 <dt><a name="index-gnutls_005fpkcs11_005ftoken_005fget_005frandom"></a>Function: <em>int</em> <strong>gnutls_pkcs11_token_get_random</strong> <em>(const char * <var>token_url</var>, void * <var>rnddata</var>, size_t <var>len</var>)</em></dt>
33261 <dd><p><var>token_url</var>: A PKCS <code>11</code>  URL specifying a token
33262 </p>
33263 <p><var>rnddata</var>: A pointer to the memory area to be filled with random data
33264 </p>
33265 <p><var>len</var>: The number of bytes of randomness to request
33266 </p>
33267 <p>This function will get random data from the given token.
33268 It will store rnddata and fill the memory pointed to by rnddata with
33269 len random bytes from the token.
33270 </p>
33271 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33272 negative error value.
33273 </p></dd></dl>
33274
33275 <a name="gnutls_005fpkcs11_005ftoken_005fget_005furl-1"></a>
33276 <h4 class="subheading">gnutls_pkcs11_token_get_url</h4>
33277 <a name="gnutls_005fpkcs11_005ftoken_005fget_005furl"></a><dl>
33278 <dt><a name="index-gnutls_005fpkcs11_005ftoken_005fget_005furl"></a>Function: <em>int</em> <strong>gnutls_pkcs11_token_get_url</strong> <em>(unsigned int <var>seq</var>, gnutls_pkcs11_url_type_t <var>detailed</var>, char ** <var>url</var>)</em></dt>
33279 <dd><p><var>seq</var>: sequence number starting from 0
33280 </p>
33281 <p><var>detailed</var>: non zero if a detailed URL is required
33282 </p>
33283 <p><var>url</var>: will contain an allocated url
33284 </p>
33285 <p>This function will return the URL for each token available
33286 in system. The url has to be released using <code>gnutls_free()</code>
33287 </p>
33288 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned,
33289 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>  if the sequence number
33290 exceeds the available tokens, otherwise a negative error value.
33291 </p>
33292 <p><strong>Since:</strong> 2.12.0
33293 </p></dd></dl>
33294
33295 <a name="gnutls_005fpkcs11_005ftoken_005finit-1"></a>
33296 <h4 class="subheading">gnutls_pkcs11_token_init</h4>
33297 <a name="gnutls_005fpkcs11_005ftoken_005finit"></a><dl>
33298 <dt><a name="index-gnutls_005fpkcs11_005ftoken_005finit"></a>Function: <em>int</em> <strong>gnutls_pkcs11_token_init</strong> <em>(const char * <var>token_url</var>, const char * <var>so_pin</var>, const char * <var>label</var>)</em></dt>
33299 <dd><p><var>token_url</var>: A PKCS <code>11</code>  URL specifying a token
33300 </p>
33301 <p><var>so_pin</var>: Security Officer&rsquo;s PIN
33302 </p>
33303 <p><var>label</var>: A name to be used for the token
33304 </p>
33305 <p>This function will initialize (format) a token. If the token is
33306 at a factory defaults state the security officer&rsquo;s PIN given will be
33307 set to be the default. Otherwise it should match the officer&rsquo;s PIN.
33308 </p>
33309 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33310 negative error value.
33311 </p></dd></dl>
33312
33313 <a name="gnutls_005fpkcs11_005ftoken_005fset_005fpin-1"></a>
33314 <h4 class="subheading">gnutls_pkcs11_token_set_pin</h4>
33315 <a name="gnutls_005fpkcs11_005ftoken_005fset_005fpin"></a><dl>
33316 <dt><a name="index-gnutls_005fpkcs11_005ftoken_005fset_005fpin"></a>Function: <em>int</em> <strong>gnutls_pkcs11_token_set_pin</strong> <em>(const char * <var>token_url</var>, const char * <var>oldpin</var>, const char * <var>newpin</var>, unsigned int <var>flags</var>)</em></dt>
33317 <dd><p><var>token_url</var>: A PKCS <code>11</code>  URL specifying a token
33318 </p>
33319 <p><var>oldpin</var>: old user&rsquo;s PIN
33320 </p>
33321 <p><var>newpin</var>: new user&rsquo;s PIN
33322 </p>
33323 <p><var>flags</var>: one of <code>gnutls_pin_flag_t</code> .
33324 </p>
33325 <p>This function will modify or set a user&rsquo;s PIN for the given token.
33326 If it is called to set a user pin for first time the oldpin must
33327 be NULL.
33328 </p>
33329 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33330 negative error value.
33331 </p></dd></dl>
33332
33333 <a name="gnutls_005fpkcs11_005ftype_005fget_005fname-1"></a>
33334 <h4 class="subheading">gnutls_pkcs11_type_get_name</h4>
33335 <a name="gnutls_005fpkcs11_005ftype_005fget_005fname"></a><dl>
33336 <dt><a name="index-gnutls_005fpkcs11_005ftype_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_pkcs11_type_get_name</strong> <em>(gnutls_pkcs11_obj_type_t <var>type</var>)</em></dt>
33337 <dd><p><var>type</var>: Holds the PKCS 11 object type, a <code>gnutls_pkcs11_obj_type_t</code> .
33338 </p>
33339 <p>This function will return a human readable description of the
33340 PKCS11 object type  <code>obj</code> .  It will return &quot;Unknown&quot; for unknown
33341 types.
33342 </p>
33343 <p><strong>Returns:</strong> human readable string labeling the PKCS11 object type
33344  <code>type</code> .
33345 </p>
33346 <p><strong>Since:</strong> 2.12.0
33347 </p></dd></dl>
33348
33349 <a name="gnutls_005fx509_005fcrt_005fimport_005fpkcs11-1"></a>
33350 <h4 class="subheading">gnutls_x509_crt_import_pkcs11</h4>
33351 <a name="gnutls_005fx509_005fcrt_005fimport_005fpkcs11"></a><dl>
33352 <dt><a name="index-gnutls_005fx509_005fcrt_005fimport_005fpkcs11"></a>Function: <em>int</em> <strong>gnutls_x509_crt_import_pkcs11</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_pkcs11_obj_t <var>pkcs11_crt</var>)</em></dt>
33353 <dd><p><var>crt</var>: A certificate of type <code>gnutls_x509_crt_t</code>
33354 </p>
33355 <p><var>pkcs11_crt</var>: A PKCS 11 object that contains a certificate
33356 </p>
33357 <p>This function will import a PKCS 11 certificate to a <code>gnutls_x509_crt_t</code>
33358 structure.
33359 </p>
33360 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33361 negative error value.
33362 </p>
33363 <p><strong>Since:</strong> 2.12.0
33364 </p></dd></dl>
33365
33366 <a name="gnutls_005fx509_005fcrt_005fimport_005fpkcs11_005furl-1"></a>
33367 <h4 class="subheading">gnutls_x509_crt_import_pkcs11_url</h4>
33368 <a name="gnutls_005fx509_005fcrt_005fimport_005fpkcs11_005furl"></a><dl>
33369 <dt><a name="index-gnutls_005fx509_005fcrt_005fimport_005fpkcs11_005furl"></a>Function: <em>int</em> <strong>gnutls_x509_crt_import_pkcs11_url</strong> <em>(gnutls_x509_crt_t <var>crt</var>, const char * <var>url</var>, unsigned int <var>flags</var>)</em></dt>
33370 <dd><p><var>crt</var>: A certificate of type <code>gnutls_x509_crt_t</code>
33371 </p>
33372 <p><var>url</var>: A PKCS 11 url
33373 </p>
33374 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
33375 </p>
33376 <p>This function will import a PKCS 11 certificate directly from a token
33377 without involving the <code>gnutls_pkcs11_obj_t</code>  structure. This function will
33378 fail if the certificate stored is not of X.509 type.
33379 </p>
33380 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33381 negative error value.
33382 </p>
33383 <p><strong>Since:</strong> 2.12.0
33384 </p></dd></dl>
33385
33386 <a name="gnutls_005fx509_005fcrt_005flist_005fimport_005fpkcs11-1"></a>
33387 <h4 class="subheading">gnutls_x509_crt_list_import_pkcs11</h4>
33388 <a name="gnutls_005fx509_005fcrt_005flist_005fimport_005fpkcs11"></a><dl>
33389 <dt><a name="index-gnutls_005fx509_005fcrt_005flist_005fimport_005fpkcs11"></a>Function: <em>int</em> <strong>gnutls_x509_crt_list_import_pkcs11</strong> <em>(gnutls_x509_crt_t * <var>certs</var>, unsigned int <var>cert_max</var>, gnutls_pkcs11_obj_t * const <var>objs</var>, unsigned int <var>flags</var>)</em></dt>
33390 <dd><p><var>certs</var>: A list of certificates of type <code>gnutls_x509_crt_t</code>
33391 </p>
33392 <p><var>cert_max</var>: The maximum size of the list
33393 </p>
33394 <p><var>objs</var>: A list of PKCS 11 objects
33395 </p>
33396 <p><var>flags</var>: 0 for now
33397 </p>
33398 <p>This function will import a PKCS 11 certificate list to a list of
33399 <code>gnutls_x509_crt_t</code>  structure. These must not be initialized.
33400 </p>
33401 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33402 negative error value.
33403 </p>
33404 <p><strong>Since:</strong> 2.12.0
33405 </p></dd></dl>
33406
33407
33408 <hr>
33409 <a name="TPM-API"></a>
33410 <div class="header">
33411 <p>
33412 Next: <a href="#Abstract-key-API" accesskey="n" rel="next">Abstract key API</a>, Previous: <a href="#PKCS-11-API" accesskey="p" rel="prev">PKCS 11 API</a>, Up: <a href="#API-reference" accesskey="u" rel="up">API reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
33413 </div>
33414 <a name="TPM-API-1"></a>
33415 <h3 class="section">E.8 TPM API</h3>
33416
33417 <p>The following functions are to be used for TPM handling.
33418 Their prototypes lie in <samp>gnutls/tpm.h</samp>.
33419 </p>
33420
33421 <a name="gnutls_005ftpm_005fget_005fregistered-1"></a>
33422 <h4 class="subheading">gnutls_tpm_get_registered</h4>
33423 <a name="gnutls_005ftpm_005fget_005fregistered"></a><dl>
33424 <dt><a name="index-gnutls_005ftpm_005fget_005fregistered"></a>Function: <em>int</em> <strong>gnutls_tpm_get_registered</strong> <em>(gnutls_tpm_key_list_t * <var>list</var>)</em></dt>
33425 <dd><p><var>list</var>: a list to store the keys
33426 </p>
33427 <p>This function will get a list of stored keys in the TPM. The uuid
33428 of those keys
33429 </p>
33430 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33431 negative error value.
33432 </p>
33433 <p><strong>Since:</strong> 3.1.0
33434 </p></dd></dl>
33435
33436 <a name="gnutls_005ftpm_005fkey_005flist_005fdeinit-1"></a>
33437 <h4 class="subheading">gnutls_tpm_key_list_deinit</h4>
33438 <a name="gnutls_005ftpm_005fkey_005flist_005fdeinit"></a><dl>
33439 <dt><a name="index-gnutls_005ftpm_005fkey_005flist_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_tpm_key_list_deinit</strong> <em>(gnutls_tpm_key_list_t <var>list</var>)</em></dt>
33440 <dd><p><var>list</var>: a list of the keys
33441 </p>
33442 <p>This function will deinitialize the list of stored keys in the TPM.
33443 </p>
33444 <p><strong>Since:</strong> 3.1.0
33445 </p></dd></dl>
33446
33447 <a name="gnutls_005ftpm_005fkey_005flist_005fget_005furl-1"></a>
33448 <h4 class="subheading">gnutls_tpm_key_list_get_url</h4>
33449 <a name="gnutls_005ftpm_005fkey_005flist_005fget_005furl"></a><dl>
33450 <dt><a name="index-gnutls_005ftpm_005fkey_005flist_005fget_005furl"></a>Function: <em>int</em> <strong>gnutls_tpm_key_list_get_url</strong> <em>(gnutls_tpm_key_list_t <var>list</var>, unsigned int <var>idx</var>, char ** <var>url</var>, unsigned int <var>flags</var>)</em></dt>
33451 <dd><p><var>list</var>: a list of the keys
33452 </p>
33453 <p><var>idx</var>: The index of the key (starting from zero)
33454 </p>
33455 <p><var>url</var>: The URL to be returned
33456 </p>
33457 <p><var>flags</var>: should be zero
33458 </p>
33459 <p>This function will return for each given index a URL of
33460 the corresponding key.
33461 If the provided index is out of bounds then <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
33462 is returned.
33463 </p>
33464 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33465 negative error value.
33466 </p>
33467 <p><strong>Since:</strong> 3.1.0
33468 </p></dd></dl>
33469
33470 <a name="gnutls_005ftpm_005fprivkey_005fdelete-1"></a>
33471 <h4 class="subheading">gnutls_tpm_privkey_delete</h4>
33472 <a name="gnutls_005ftpm_005fprivkey_005fdelete"></a><dl>
33473 <dt><a name="index-gnutls_005ftpm_005fprivkey_005fdelete-2"></a>Function: <em>int</em> <strong>gnutls_tpm_privkey_delete</strong> <em>(const char * <var>url</var>, const char * <var>srk_password</var>)</em></dt>
33474 <dd><p><var>url</var>: the URL describing the key
33475 </p>
33476 <p><var>srk_password</var>: a password for the SRK key
33477 </p>
33478 <p>This function will unregister the private key from the TPM
33479 chip.
33480 </p>
33481 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33482 negative error value.
33483 </p>
33484 <p><strong>Since:</strong> 3.1.0
33485 </p></dd></dl>
33486
33487 <a name="gnutls_005ftpm_005fprivkey_005fgenerate-1"></a>
33488 <h4 class="subheading">gnutls_tpm_privkey_generate</h4>
33489 <a name="gnutls_005ftpm_005fprivkey_005fgenerate"></a><dl>
33490 <dt><a name="index-gnutls_005ftpm_005fprivkey_005fgenerate-1"></a>Function: <em>int</em> <strong>gnutls_tpm_privkey_generate</strong> <em>(gnutls_pk_algorithm_t <var>pk</var>, unsigned int <var>bits</var>, const char * <var>srk_password</var>, const char * <var>key_password</var>, gnutls_tpmkey_fmt_t <var>format</var>, gnutls_x509_crt_fmt_t <var>pub_format</var>, gnutls_datum_t * <var>privkey</var>, gnutls_datum_t * <var>pubkey</var>, unsigned int <var>flags</var>)</em></dt>
33491 <dd><p><var>pk</var>: the public key algorithm
33492 </p>
33493 <p><var>bits</var>: the security bits
33494 </p>
33495 <p><var>srk_password</var>: a password to protect the exported key (optional)
33496 </p>
33497 <p><var>key_password</var>: the password for the TPM (optional)
33498 </p>
33499 <p><var>format</var>: the format of the private key
33500 </p>
33501 <p><var>pub_format</var>: the format of the public key
33502 </p>
33503 <p><var>privkey</var>: the generated key
33504 </p>
33505 <p><var>pubkey</var>: the corresponding public key (may be null)
33506 </p>
33507 <p><var>flags</var>: should be a list of GNUTLS_TPM_* flags
33508 </p>
33509 <p>This function will generate a private key in the TPM
33510 chip. The private key will be generated within the chip
33511 and will be exported in a wrapped with TPM&rsquo;s master key
33512 form. Furthermore the wrapped key can be protected with
33513 the provided  <code>password</code> .
33514 </p>
33515 <p>Note that bits in TPM is quantized value. If the input value
33516 is not one of the allowed values, then it will be quantized to
33517 one of 512, 1024, 2048, 4096, 8192 and 16384.
33518 </p>
33519 <p>Allowed flags are:
33520 </p>
33521 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33522 negative error value.
33523 </p>
33524 <p><strong>Since:</strong> 3.1.0
33525 </p></dd></dl>
33526
33527
33528 <hr>
33529 <a name="Abstract-key-API"></a>
33530 <div class="header">
33531 <p>
33532 Next: <a href="#DANE-API" accesskey="n" rel="next">DANE API</a>, Previous: <a href="#TPM-API" accesskey="p" rel="prev">TPM API</a>, Up: <a href="#API-reference" accesskey="u" rel="up">API reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
33533 </div>
33534 <a name="Abstract-key-API-1"></a>
33535 <h3 class="section">E.9 Abstract key API</h3>
33536
33537 <p>The following functions are to be used for abstract key handling.
33538 Their prototypes lie in <samp>gnutls/abstract.h</samp>.
33539 </p>
33540
33541 <a name="gnutls_005fcertificate_005fset_005fkey-1"></a>
33542 <h4 class="subheading">gnutls_certificate_set_key</h4>
33543 <a name="gnutls_005fcertificate_005fset_005fkey"></a><dl>
33544 <dt><a name="index-gnutls_005fcertificate_005fset_005fkey-1"></a>Function: <em>int</em> <strong>gnutls_certificate_set_key</strong> <em>(gnutls_certificate_credentials_t <var>res</var>, const char ** <var>names</var>, int <var>names_size</var>, gnutls_pcert_st * <var>pcert_list</var>, int <var>pcert_list_size</var>, gnutls_privkey_t <var>key</var>)</em></dt>
33545 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
33546 </p>
33547 <p><var>names</var>: is an array of DNS name of the certificate (NULL if none)
33548 </p>
33549 <p><var>names_size</var>: holds the size of the names list
33550 </p>
33551 <p><var>pcert_list</var>: contains a certificate list (path) for the specified private key
33552 </p>
33553 <p><var>pcert_list_size</var>: holds the size of the certificate list
33554 </p>
33555 <p><var>key</var>: is a <code>gnutls_privkey_t</code>  key
33556 </p>
33557 <p>This function sets a certificate/private key pair in the
33558 gnutls_certificate_credentials_t structure.  This function may be
33559 called more than once, in case multiple keys/certificates exist for
33560 the server.  For clients that wants to send more than its own end
33561 entity certificate (e.g., also an intermediate CA cert) then put
33562 the certificate chain in  <code>pcert_list</code> .
33563 </p>
33564 <p>Note that the  <code>pcert_list</code> and  <code>key</code> will become part of the credentials
33565 structure and must not be deallocated. They will be automatically deallocated
33566 when the  <code>res</code> structure is deinitialized.
33567 </p>
33568 <p>If that function fails to load the  <code>res</code> structure is at an undefined state, it must
33569 not be reused to load other keys or certificates.
33570 </p>
33571 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success, or a negative error code.
33572 </p>
33573 <p><strong>Since:</strong> 3.0
33574 </p></dd></dl>
33575
33576 <a name="gnutls_005fcertificate_005fset_005fretrieve_005ffunction2-1"></a>
33577 <h4 class="subheading">gnutls_certificate_set_retrieve_function2</h4>
33578 <a name="gnutls_005fcertificate_005fset_005fretrieve_005ffunction2"></a><dl>
33579 <dt><a name="index-gnutls_005fcertificate_005fset_005fretrieve_005ffunction2"></a>Function: <em>void</em> <strong>gnutls_certificate_set_retrieve_function2</strong> <em>(gnutls_certificate_credentials_t <var>cred</var>, gnutls_certificate_retrieve_function2 * <var>func</var>)</em></dt>
33580 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
33581 </p>
33582 <p><var>func</var>: is the callback function
33583 </p>
33584 <p>This function sets a callback to be called in order to retrieve the
33585 certificate to be used in the handshake.
33586 </p>
33587 <p>The callback&rsquo;s function prototype is:
33588 int (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int nreqs,
33589 const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length, gnutls_pcert_st** pcert,
33590 unsigned int *pcert_length, gnutls_privkey_t * pkey);
33591 </p>
33592 <p><code>req_ca_dn</code> is only used in X.509 certificates.
33593 Contains a list with the CA names that the server considers trusted.
33594 Normally we should send a certificate that is signed
33595 by one of these CAs. These names are DER encoded. To get a more
33596 meaningful value use the function <code>gnutls_x509_rdn_get()</code> .
33597 </p>
33598 <p><code>pk_algos</code> contains a list with server&rsquo;s acceptable signature algorithms.
33599 The certificate returned should support the server&rsquo;s given algorithms.
33600 </p>
33601 <p><code>pcert</code> should contain a single certificate and public key or a list of them.
33602 </p>
33603 <p><code>pcert_length</code> is the size of the previous list.
33604 </p>
33605 <p><code>pkey</code> is the private key.
33606 </p>
33607 <p>If the callback function is provided then gnutls will call it, in the
33608 handshake, after the certificate request message has been received.
33609 All the provided by the callback values will not be released or
33610 modified by gnutls.
33611 </p>
33612 <p>In server side pk_algos and req_ca_dn are NULL.
33613 </p>
33614 <p>The callback function should set the certificate list to be sent,
33615 and return 0 on success. If no certificate was selected then the
33616 number of certificates should be set to zero. The value (-1)
33617 indicates error and the handshake will be terminated.
33618 </p>
33619 <p><strong>Since:</strong> 3.0
33620 </p></dd></dl>
33621
33622 <a name="gnutls_005fpcert_005fdeinit-1"></a>
33623 <h4 class="subheading">gnutls_pcert_deinit</h4>
33624 <a name="gnutls_005fpcert_005fdeinit"></a><dl>
33625 <dt><a name="index-gnutls_005fpcert_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_pcert_deinit</strong> <em>(gnutls_pcert_st * <var>pcert</var>)</em></dt>
33626 <dd><p><var>pcert</var>: The structure to be deinitialized
33627 </p>
33628 <p>This function will deinitialize a pcert structure.
33629 </p>
33630 <p><strong>Since:</strong> 3.0
33631 </p></dd></dl>
33632
33633 <a name="gnutls_005fpcert_005fimport_005fopenpgp-1"></a>
33634 <h4 class="subheading">gnutls_pcert_import_openpgp</h4>
33635 <a name="gnutls_005fpcert_005fimport_005fopenpgp"></a><dl>
33636 <dt><a name="index-gnutls_005fpcert_005fimport_005fopenpgp"></a>Function: <em>int</em> <strong>gnutls_pcert_import_openpgp</strong> <em>(gnutls_pcert_st * <var>pcert</var>, gnutls_openpgp_crt_t <var>crt</var>, unsigned int <var>flags</var>)</em></dt>
33637 <dd><p><var>pcert</var>: The pcert structure
33638 </p>
33639 <p><var>crt</var>: The raw certificate to be imported
33640 </p>
33641 <p><var>flags</var>: zero for now
33642 </p>
33643 <p>This convenience function will import the given certificate to a
33644 <code>gnutls_pcert_st</code>  structure. The structure must be deinitialized
33645 afterwards using <code>gnutls_pcert_deinit()</code> ;
33646 </p>
33647 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33648 negative error value.
33649 </p>
33650 <p><strong>Since:</strong> 3.0
33651 </p></dd></dl>
33652
33653 <a name="gnutls_005fpcert_005fimport_005fopenpgp_005fraw-1"></a>
33654 <h4 class="subheading">gnutls_pcert_import_openpgp_raw</h4>
33655 <a name="gnutls_005fpcert_005fimport_005fopenpgp_005fraw"></a><dl>
33656 <dt><a name="index-gnutls_005fpcert_005fimport_005fopenpgp_005fraw"></a>Function: <em>int</em> <strong>gnutls_pcert_import_openpgp_raw</strong> <em>(gnutls_pcert_st * <var>pcert</var>, const gnutls_datum_t * <var>cert</var>, gnutls_openpgp_crt_fmt_t <var>format</var>, gnutls_openpgp_keyid_t <var>keyid</var>, unsigned int <var>flags</var>)</em></dt>
33657 <dd><p><var>pcert</var>: The pcert structure
33658 </p>
33659 <p><var>cert</var>: The raw certificate to be imported
33660 </p>
33661 <p><var>format</var>: The format of the certificate
33662 </p>
33663 <p><var>keyid</var>: The key ID to use (NULL for the master key)
33664 </p>
33665 <p><var>flags</var>: zero for now
33666 </p>
33667 <p>This convenience function will import the given certificate to a
33668 <code>gnutls_pcert_st</code>  structure. The structure must be deinitialized
33669 afterwards using <code>gnutls_pcert_deinit()</code> ;
33670 </p>
33671 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33672 negative error value.
33673 </p>
33674 <p><strong>Since:</strong> 3.0
33675 </p></dd></dl>
33676
33677 <a name="gnutls_005fpcert_005fimport_005fx509-1"></a>
33678 <h4 class="subheading">gnutls_pcert_import_x509</h4>
33679 <a name="gnutls_005fpcert_005fimport_005fx509"></a><dl>
33680 <dt><a name="index-gnutls_005fpcert_005fimport_005fx509"></a>Function: <em>int</em> <strong>gnutls_pcert_import_x509</strong> <em>(gnutls_pcert_st * <var>pcert</var>, gnutls_x509_crt_t <var>crt</var>, unsigned int <var>flags</var>)</em></dt>
33681 <dd><p><var>pcert</var>: The pcert structure
33682 </p>
33683 <p><var>crt</var>: The raw certificate to be imported
33684 </p>
33685 <p><var>flags</var>: zero for now
33686 </p>
33687 <p>This convenience function will import the given certificate to a
33688 <code>gnutls_pcert_st</code>  structure. The structure must be deinitialized
33689 afterwards using <code>gnutls_pcert_deinit()</code> ;
33690 </p>
33691 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33692 negative error value.
33693 </p>
33694 <p><strong>Since:</strong> 3.0
33695 </p></dd></dl>
33696
33697 <a name="gnutls_005fpcert_005fimport_005fx509_005fraw-1"></a>
33698 <h4 class="subheading">gnutls_pcert_import_x509_raw</h4>
33699 <a name="gnutls_005fpcert_005fimport_005fx509_005fraw"></a><dl>
33700 <dt><a name="index-gnutls_005fpcert_005fimport_005fx509_005fraw"></a>Function: <em>int</em> <strong>gnutls_pcert_import_x509_raw</strong> <em>(gnutls_pcert_st * <var>pcert</var>, const gnutls_datum_t * <var>cert</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned int <var>flags</var>)</em></dt>
33701 <dd><p><var>pcert</var>: The pcert structure
33702 </p>
33703 <p><var>cert</var>: The raw certificate to be imported
33704 </p>
33705 <p><var>format</var>: The format of the certificate
33706 </p>
33707 <p><var>flags</var>: zero for now
33708 </p>
33709 <p>This convenience function will import the given certificate to a
33710 <code>gnutls_pcert_st</code>  structure. The structure must be deinitialized
33711 afterwards using <code>gnutls_pcert_deinit()</code> ;
33712 </p>
33713 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33714 negative error value.
33715 </p>
33716 <p><strong>Since:</strong> 3.0
33717 </p></dd></dl>
33718
33719 <a name="gnutls_005fpcert_005flist_005fimport_005fx509_005fraw-1"></a>
33720 <h4 class="subheading">gnutls_pcert_list_import_x509_raw</h4>
33721 <a name="gnutls_005fpcert_005flist_005fimport_005fx509_005fraw"></a><dl>
33722 <dt><a name="index-gnutls_005fpcert_005flist_005fimport_005fx509_005fraw"></a>Function: <em>int</em> <strong>gnutls_pcert_list_import_x509_raw</strong> <em>(gnutls_pcert_st * <var>pcerts</var>, unsigned int * <var>pcert_max</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned int <var>flags</var>)</em></dt>
33723 <dd><p><var>pcerts</var>: The structures to store the parsed certificate. Must not be initialized.
33724 </p>
33725 <p><var>pcert_max</var>: Initially must hold the maximum number of certs. It will be updated with the number of certs available.
33726 </p>
33727 <p><var>data</var>: The certificates.
33728 </p>
33729 <p><var>format</var>: One of DER or PEM.
33730 </p>
33731 <p><var>flags</var>: must be (0) or an OR&rsquo;d sequence of gnutls_certificate_import_flags.
33732 </p>
33733 <p>This function will convert the given PEM encoded certificate list
33734 to the native gnutls_x509_crt_t format. The output will be stored
33735 in  <code>certs</code> .  They will be automatically initialized.
33736 </p>
33737 <p>If the Certificate is PEM encoded it should have a header of &quot;X509
33738 CERTIFICATE&quot;, or &quot;CERTIFICATE&quot;.
33739 </p>
33740 <p><strong>Returns:</strong> the number of certificates read or a negative error value.
33741 </p>
33742 <p><strong>Since:</strong> 3.0
33743 </p></dd></dl>
33744
33745 <a name="gnutls_005fprivkey_005fdecrypt_005fdata-1"></a>
33746 <h4 class="subheading">gnutls_privkey_decrypt_data</h4>
33747 <a name="gnutls_005fprivkey_005fdecrypt_005fdata"></a><dl>
33748 <dt><a name="index-gnutls_005fprivkey_005fdecrypt_005fdata-1"></a>Function: <em>int</em> <strong>gnutls_privkey_decrypt_data</strong> <em>(gnutls_privkey_t <var>key</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>ciphertext</var>, gnutls_datum_t * <var>plaintext</var>)</em></dt>
33749 <dd><p><var>key</var>: Holds the key
33750 </p>
33751 <p><var>flags</var>: zero for now
33752 </p>
33753 <p><var>ciphertext</var>: holds the data to be decrypted
33754 </p>
33755 <p><var>plaintext</var>: will contain the decrypted data, allocated with <code>gnutls_malloc()</code>
33756 </p>
33757 <p>This function will decrypt the given data using the algorithm
33758 supported by the private key.
33759 </p>
33760 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33761 negative error value.
33762 </p>
33763 <p><strong>Since:</strong> 2.12.0
33764 </p></dd></dl>
33765
33766 <a name="gnutls_005fprivkey_005fdeinit-1"></a>
33767 <h4 class="subheading">gnutls_privkey_deinit</h4>
33768 <a name="gnutls_005fprivkey_005fdeinit"></a><dl>
33769 <dt><a name="index-gnutls_005fprivkey_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_privkey_deinit</strong> <em>(gnutls_privkey_t <var>key</var>)</em></dt>
33770 <dd><p><var>key</var>: The structure to be deinitialized
33771 </p>
33772 <p>This function will deinitialize a private key structure.
33773 </p>
33774 <p><strong>Since:</strong> 2.12.0
33775 </p></dd></dl>
33776
33777 <a name="gnutls_005fprivkey_005fexport_005fdsa_005fraw-1"></a>
33778 <h4 class="subheading">gnutls_privkey_export_dsa_raw</h4>
33779 <a name="gnutls_005fprivkey_005fexport_005fdsa_005fraw"></a><dl>
33780 <dt><a name="index-gnutls_005fprivkey_005fexport_005fdsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_privkey_export_dsa_raw</strong> <em>(gnutls_privkey_t <var>key</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>g</var>, gnutls_datum_t * <var>y</var>, gnutls_datum_t * <var>x</var>)</em></dt>
33781 <dd><p><var>key</var>: Holds the public key
33782 </p>
33783 <p><var>p</var>: will hold the p
33784 </p>
33785 <p><var>q</var>: will hold the q
33786 </p>
33787 <p><var>g</var>: will hold the g
33788 </p>
33789 <p><var>y</var>: will hold the y
33790 </p>
33791 <p><var>x</var>: will hold the x
33792 </p>
33793 <p>This function will export the DSA private key&rsquo;s parameters found
33794 in the given structure. The new parameters will be allocated using
33795 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
33796 </p>
33797 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
33798 </p>
33799 <p><strong>Since:</strong> 3.3.0
33800 </p></dd></dl>
33801
33802 <a name="gnutls_005fprivkey_005fexport_005fecc_005fraw-1"></a>
33803 <h4 class="subheading">gnutls_privkey_export_ecc_raw</h4>
33804 <a name="gnutls_005fprivkey_005fexport_005fecc_005fraw"></a><dl>
33805 <dt><a name="index-gnutls_005fprivkey_005fexport_005fecc_005fraw"></a>Function: <em>int</em> <strong>gnutls_privkey_export_ecc_raw</strong> <em>(gnutls_privkey_t <var>key</var>, gnutls_ecc_curve_t * <var>curve</var>, gnutls_datum_t * <var>x</var>, gnutls_datum_t * <var>y</var>, gnutls_datum_t * <var>k</var>)</em></dt>
33806 <dd><p><var>key</var>: Holds the public key
33807 </p>
33808 <p><var>curve</var>: will hold the curve
33809 </p>
33810 <p><var>x</var>: will hold the x coordinate
33811 </p>
33812 <p><var>y</var>: will hold the y coordinate
33813 </p>
33814 <p><var>k</var>: will hold the private key
33815 </p>
33816 <p>This function will export the ECC private key&rsquo;s parameters found
33817 in the given structure. The new parameters will be allocated using
33818 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
33819 </p>
33820 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
33821 </p>
33822 <p><strong>Since:</strong> 3.3.0
33823 </p></dd></dl>
33824
33825 <a name="gnutls_005fprivkey_005fexport_005frsa_005fraw-1"></a>
33826 <h4 class="subheading">gnutls_privkey_export_rsa_raw</h4>
33827 <a name="gnutls_005fprivkey_005fexport_005frsa_005fraw"></a><dl>
33828 <dt><a name="index-gnutls_005fprivkey_005fexport_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_privkey_export_rsa_raw</strong> <em>(gnutls_privkey_t <var>key</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>, gnutls_datum_t * <var>d</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>u</var>, gnutls_datum_t * <var>e1</var>, gnutls_datum_t * <var>e2</var>)</em></dt>
33829 <dd><p><var>key</var>: Holds the certificate
33830 </p>
33831 <p><var>m</var>: will hold the modulus
33832 </p>
33833 <p><var>e</var>: will hold the public exponent
33834 </p>
33835 <p><var>d</var>: will hold the private exponent
33836 </p>
33837 <p><var>p</var>: will hold the first prime (p)
33838 </p>
33839 <p><var>q</var>: will hold the second prime (q)
33840 </p>
33841 <p><var>u</var>: will hold the coefficient
33842 </p>
33843 <p><var>e1</var>: will hold e1 = d mod (p-1)
33844 </p>
33845 <p><var>e2</var>: will hold e2 = d mod (q-1)
33846 </p>
33847 <p>This function will export the RSA private key&rsquo;s parameters found
33848 in the given structure. The new parameters will be allocated using
33849 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
33850 </p>
33851 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
33852 </p>
33853 <p><strong>Since:</strong> 3.3.0
33854 </p></dd></dl>
33855
33856 <a name="gnutls_005fprivkey_005fgenerate-1"></a>
33857 <h4 class="subheading">gnutls_privkey_generate</h4>
33858 <a name="gnutls_005fprivkey_005fgenerate"></a><dl>
33859 <dt><a name="index-gnutls_005fprivkey_005fgenerate"></a>Function: <em>int</em> <strong>gnutls_privkey_generate</strong> <em>(gnutls_privkey_t <var>pkey</var>, gnutls_pk_algorithm_t <var>algo</var>, unsigned int <var>bits</var>, unsigned int <var>flags</var>)</em></dt>
33860 <dd><p><var>pkey</var>: The private key
33861 </p>
33862 <p><var>algo</var>: is one of the algorithms in <code>gnutls_pk_algorithm_t</code> .
33863 </p>
33864 <p><var>bits</var>: the size of the modulus
33865 </p>
33866 <p><var>flags</var>: unused for now.  Must be 0.
33867 </p>
33868 <p>This function will generate a random private key. Note that this
33869 function must be called on an empty private key.
33870 </p>
33871 <p>Note that when generating an elliptic curve key, the curve
33872 can be substituted in the place of the bits parameter using the
33873 <code>GNUTLS_CURVE_TO_BITS()</code>  macro.
33874 </p>
33875 <p>Do not set the number of bits directly, use <code>gnutls_sec_param_to_pk_bits()</code> .
33876 </p>
33877 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33878 negative error value.
33879 </p>
33880 <p><strong>Since:</strong> 3.3.0
33881 </p></dd></dl>
33882
33883 <a name="gnutls_005fprivkey_005fget_005fpk_005falgorithm-1"></a>
33884 <h4 class="subheading">gnutls_privkey_get_pk_algorithm</h4>
33885 <a name="gnutls_005fprivkey_005fget_005fpk_005falgorithm"></a><dl>
33886 <dt><a name="index-gnutls_005fprivkey_005fget_005fpk_005falgorithm"></a>Function: <em>int</em> <strong>gnutls_privkey_get_pk_algorithm</strong> <em>(gnutls_privkey_t <var>key</var>, unsigned int * <var>bits</var>)</em></dt>
33887 <dd><p><var>key</var>: should contain a <code>gnutls_privkey_t</code>  structure
33888 </p>
33889 <p><var>bits</var>: If set will return the number of bits of the parameters (may be NULL)
33890 </p>
33891 <p>This function will return the public key algorithm of a private
33892 key and if possible will return a number of bits that indicates
33893 the security parameter of the key.
33894 </p>
33895 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code>  enumeration on
33896 success, or a negative error code on error.
33897 </p>
33898 <p><strong>Since:</strong> 2.12.0
33899 </p></dd></dl>
33900
33901 <a name="gnutls_005fprivkey_005fget_005ftype-1"></a>
33902 <h4 class="subheading">gnutls_privkey_get_type</h4>
33903 <a name="gnutls_005fprivkey_005fget_005ftype"></a><dl>
33904 <dt><a name="index-gnutls_005fprivkey_005fget_005ftype"></a>Function: <em>gnutls_privkey_type_t</em> <strong>gnutls_privkey_get_type</strong> <em>(gnutls_privkey_t <var>key</var>)</em></dt>
33905 <dd><p><var>key</var>: should contain a <code>gnutls_privkey_t</code>  structure
33906 </p>
33907 <p>This function will return the type of the private key. This is
33908 actually the type of the subsystem used to set this private key.
33909 </p>
33910 <p><strong>Returns:</strong> a member of the <code>gnutls_privkey_type_t</code>  enumeration on
33911 success, or a negative error code on error.
33912 </p>
33913 <p><strong>Since:</strong> 2.12.0
33914 </p></dd></dl>
33915
33916 <a name="gnutls_005fprivkey_005fimport_005fdsa_005fraw-1"></a>
33917 <h4 class="subheading">gnutls_privkey_import_dsa_raw</h4>
33918 <a name="gnutls_005fprivkey_005fimport_005fdsa_005fraw"></a><dl>
33919 <dt><a name="index-gnutls_005fprivkey_005fimport_005fdsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_privkey_import_dsa_raw</strong> <em>(gnutls_privkey_t <var>key</var>, const gnutls_datum_t * <var>p</var>, const gnutls_datum_t * <var>q</var>, const gnutls_datum_t * <var>g</var>, const gnutls_datum_t * <var>y</var>, const gnutls_datum_t * <var>x</var>)</em></dt>
33920 <dd><p><var>key</var>: The structure to store the parsed key
33921 </p>
33922 <p><var>p</var>: holds the p
33923 </p>
33924 <p><var>q</var>: holds the q
33925 </p>
33926 <p><var>g</var>: holds the g
33927 </p>
33928 <p><var>y</var>: holds the y
33929 </p>
33930 <p><var>x</var>: holds the x
33931 </p>
33932 <p>This function will convert the given DSA raw parameters to the
33933 native <code>gnutls_privkey_t</code>  format.  The output will be stored
33934 in  <code>key</code> .
33935 </p>
33936 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33937 negative error value.
33938 </p></dd></dl>
33939
33940 <a name="gnutls_005fprivkey_005fimport_005fecc_005fraw-1"></a>
33941 <h4 class="subheading">gnutls_privkey_import_ecc_raw</h4>
33942 <a name="gnutls_005fprivkey_005fimport_005fecc_005fraw"></a><dl>
33943 <dt><a name="index-gnutls_005fprivkey_005fimport_005fecc_005fraw"></a>Function: <em>int</em> <strong>gnutls_privkey_import_ecc_raw</strong> <em>(gnutls_privkey_t <var>key</var>, gnutls_ecc_curve_t <var>curve</var>, const gnutls_datum_t * <var>x</var>, const gnutls_datum_t * <var>y</var>, const gnutls_datum_t * <var>k</var>)</em></dt>
33944 <dd><p><var>key</var>: The structure to store the parsed key
33945 </p>
33946 <p><var>curve</var>: holds the curve
33947 </p>
33948 <p><var>x</var>: holds the x
33949 </p>
33950 <p><var>y</var>: holds the y
33951 </p>
33952 <p><var>k</var>: holds the k
33953 </p>
33954 <p>This function will convert the given elliptic curve parameters to the
33955 native <code>gnutls_privkey_t</code>  format.  The output will be stored
33956 in  <code>key</code> .
33957 </p>
33958 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33959 negative error value.
33960 </p>
33961 <p><strong>Since:</strong> 3.0
33962 </p></dd></dl>
33963
33964 <a name="gnutls_005fprivkey_005fimport_005fext-1"></a>
33965 <h4 class="subheading">gnutls_privkey_import_ext</h4>
33966 <a name="gnutls_005fprivkey_005fimport_005fext"></a><dl>
33967 <dt><a name="index-gnutls_005fprivkey_005fimport_005fext"></a>Function: <em>int</em> <strong>gnutls_privkey_import_ext</strong> <em>(gnutls_privkey_t <var>pkey</var>, gnutls_pk_algorithm_t <var>pk</var>, void * <var>userdata</var>, gnutls_privkey_sign_func <var>sign_func</var>, gnutls_privkey_decrypt_func <var>decrypt_func</var>, unsigned int <var>flags</var>)</em></dt>
33968 <dd><p><var>pkey</var>: The private key
33969 </p>
33970 <p><var>pk</var>: The public key algorithm
33971 </p>
33972 <p><var>userdata</var>: private data to be provided to the callbacks
33973 </p>
33974 <p><var>sign_func</var>: callback for signature operations
33975 </p>
33976 <p><var>decrypt_func</var>: callback for decryption operations
33977 </p>
33978 <p><var>flags</var>: Flags for the import
33979 </p>
33980 <p>This function will associate the given callbacks with the
33981 <code>gnutls_privkey_t</code>  structure. At least one of the two callbacks
33982 must be non-null.
33983 </p>
33984 <p>See also <code>gnutls_privkey_import_ext2()</code> .
33985 </p>
33986 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
33987 negative error value.
33988 </p>
33989 <p><strong>Since:</strong> 3.0
33990 </p></dd></dl>
33991
33992 <a name="gnutls_005fprivkey_005fimport_005fext2-1"></a>
33993 <h4 class="subheading">gnutls_privkey_import_ext2</h4>
33994 <a name="gnutls_005fprivkey_005fimport_005fext2"></a><dl>
33995 <dt><a name="index-gnutls_005fprivkey_005fimport_005fext2-1"></a>Function: <em>int</em> <strong>gnutls_privkey_import_ext2</strong> <em>(gnutls_privkey_t <var>pkey</var>, gnutls_pk_algorithm_t <var>pk</var>, void * <var>userdata</var>, gnutls_privkey_sign_func <var>sign_func</var>, gnutls_privkey_decrypt_func <var>decrypt_func</var>, gnutls_privkey_deinit_func <var>deinit_func</var>, unsigned int <var>flags</var>)</em></dt>
33996 <dd><p><var>pkey</var>: The private key
33997 </p>
33998 <p><var>pk</var>: The public key algorithm
33999 </p>
34000 <p><var>userdata</var>: private data to be provided to the callbacks
34001 </p>
34002 <p><var>sign_func</var>: callback for signature operations
34003 </p>
34004 <p><var>decrypt_func</var>: callback for decryption operations
34005 </p>
34006 <p><var>deinit_func</var>: a deinitialization function
34007 </p>
34008 <p><var>flags</var>: Flags for the import
34009 </p>
34010 <p>This function will associate the given callbacks with the
34011 <code>gnutls_privkey_t</code>  structure. At least one of the two callbacks
34012 must be non-null. If a deinitialization function is provided
34013 then flags is assumed to contain <code>GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE</code> .
34014 </p>
34015 <p>Note that the signing function is supposed to &quot;raw&quot; sign data, i.e.,
34016 without any hashing or preprocessing. In case of RSA the DigestInfo
34017 will be provided, and the signing function is expected to do the PKCS <code>1</code>
34018 1.5 padding and the exponentiation.
34019 </p>
34020 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34021 negative error value.
34022 </p>
34023 <p><strong>Since:</strong> 3.1
34024 </p></dd></dl>
34025
34026 <a name="gnutls_005fprivkey_005fimport_005fopenpgp-1"></a>
34027 <h4 class="subheading">gnutls_privkey_import_openpgp</h4>
34028 <a name="gnutls_005fprivkey_005fimport_005fopenpgp"></a><dl>
34029 <dt><a name="index-gnutls_005fprivkey_005fimport_005fopenpgp"></a>Function: <em>int</em> <strong>gnutls_privkey_import_openpgp</strong> <em>(gnutls_privkey_t <var>pkey</var>, gnutls_openpgp_privkey_t <var>key</var>, unsigned int <var>flags</var>)</em></dt>
34030 <dd><p><var>pkey</var>: The private key
34031 </p>
34032 <p><var>key</var>: The private key to be imported
34033 </p>
34034 <p><var>flags</var>: Flags for the import
34035 </p>
34036 <p>This function will import the given private key to the abstract
34037 <code>gnutls_privkey_t</code>  structure.
34038 </p>
34039 <p>The <code>gnutls_openpgp_privkey_t</code>  object must not be deallocated
34040 during the lifetime of this structure. The subkey set as
34041 preferred will be used, or the master key otherwise.
34042 </p>
34043 <p><code>flags</code> might be zero or one of <code>GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE</code>
34044 and <code>GNUTLS_PRIVKEY_IMPORT_COPY</code> .
34045 </p>
34046 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34047 negative error value.
34048 </p>
34049 <p><strong>Since:</strong> 2.12.0
34050 </p></dd></dl>
34051
34052 <a name="gnutls_005fprivkey_005fimport_005fopenpgp_005fraw-1"></a>
34053 <h4 class="subheading">gnutls_privkey_import_openpgp_raw</h4>
34054 <a name="gnutls_005fprivkey_005fimport_005fopenpgp_005fraw"></a><dl>
34055 <dt><a name="index-gnutls_005fprivkey_005fimport_005fopenpgp_005fraw"></a>Function: <em>int</em> <strong>gnutls_privkey_import_openpgp_raw</strong> <em>(gnutls_privkey_t <var>pkey</var>, const gnutls_datum_t * <var>data</var>, gnutls_openpgp_crt_fmt_t <var>format</var>, const gnutls_openpgp_keyid_t <var>keyid</var>, const char * <var>password</var>)</em></dt>
34056 <dd><p><var>pkey</var>: The private key
34057 </p>
34058 <p><var>data</var>: The private key data to be imported
34059 </p>
34060 <p><var>format</var>: The format of the private key
34061 </p>
34062 <p><var>keyid</var>: The key id to use (optional)
34063 </p>
34064 <p><var>password</var>: A password (optional)
34065 </p>
34066 <p>This function will import the given private key to the abstract
34067 <code>gnutls_privkey_t</code>  structure.
34068 </p>
34069 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34070 negative error value.
34071 </p>
34072 <p><strong>Since:</strong> 3.1.0
34073 </p></dd></dl>
34074
34075 <a name="gnutls_005fprivkey_005fimport_005fpkcs11-1"></a>
34076 <h4 class="subheading">gnutls_privkey_import_pkcs11</h4>
34077 <a name="gnutls_005fprivkey_005fimport_005fpkcs11"></a><dl>
34078 <dt><a name="index-gnutls_005fprivkey_005fimport_005fpkcs11"></a>Function: <em>int</em> <strong>gnutls_privkey_import_pkcs11</strong> <em>(gnutls_privkey_t <var>pkey</var>, gnutls_pkcs11_privkey_t <var>key</var>, unsigned int <var>flags</var>)</em></dt>
34079 <dd><p><var>pkey</var>: The private key
34080 </p>
34081 <p><var>key</var>: The private key to be imported
34082 </p>
34083 <p><var>flags</var>: Flags for the import
34084 </p>
34085 <p>This function will import the given private key to the abstract
34086 <code>gnutls_privkey_t</code>  structure.
34087 </p>
34088 <p>The <code>gnutls_pkcs11_privkey_t</code>  object must not be deallocated
34089 during the lifetime of this structure.
34090 </p>
34091 <p><code>flags</code> might be zero or one of <code>GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE</code>
34092 and <code>GNUTLS_PRIVKEY_IMPORT_COPY</code> .
34093 </p>
34094 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34095 negative error value.
34096 </p>
34097 <p><strong>Since:</strong> 2.12.0
34098 </p></dd></dl>
34099
34100 <a name="gnutls_005fprivkey_005fimport_005fpkcs11_005furl-1"></a>
34101 <h4 class="subheading">gnutls_privkey_import_pkcs11_url</h4>
34102 <a name="gnutls_005fprivkey_005fimport_005fpkcs11_005furl"></a><dl>
34103 <dt><a name="index-gnutls_005fprivkey_005fimport_005fpkcs11_005furl"></a>Function: <em>int</em> <strong>gnutls_privkey_import_pkcs11_url</strong> <em>(gnutls_privkey_t <var>key</var>, const char * <var>url</var>)</em></dt>
34104 <dd><p><var>key</var>: A key of type <code>gnutls_pubkey_t</code>
34105 </p>
34106 <p><var>url</var>: A PKCS 11 url
34107 </p>
34108 <p>This function will import a PKCS 11 private key to a <code>gnutls_private_key_t</code>
34109 structure.
34110 </p>
34111 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34112 negative error value.
34113 </p>
34114 <p><strong>Since:</strong> 3.1.0
34115 </p></dd></dl>
34116
34117 <a name="gnutls_005fprivkey_005fimport_005frsa_005fraw-1"></a>
34118 <h4 class="subheading">gnutls_privkey_import_rsa_raw</h4>
34119 <a name="gnutls_005fprivkey_005fimport_005frsa_005fraw"></a><dl>
34120 <dt><a name="index-gnutls_005fprivkey_005fimport_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_privkey_import_rsa_raw</strong> <em>(gnutls_privkey_t <var>key</var>, const gnutls_datum_t * <var>m</var>, const gnutls_datum_t * <var>e</var>, const gnutls_datum_t * <var>d</var>, const gnutls_datum_t * <var>p</var>, const gnutls_datum_t * <var>q</var>, const gnutls_datum_t * <var>u</var>, const gnutls_datum_t * <var>e1</var>, const gnutls_datum_t * <var>e2</var>)</em></dt>
34121 <dd><p><var>key</var>: The structure to store the parsed key
34122 </p>
34123 <p><var>m</var>: holds the modulus
34124 </p>
34125 <p><var>e</var>: holds the public exponent
34126 </p>
34127 <p><var>d</var>: holds the private exponent
34128 </p>
34129 <p><var>p</var>: holds the first prime (p)
34130 </p>
34131 <p><var>q</var>: holds the second prime (q)
34132 </p>
34133 <p><var>u</var>: holds the coefficient (optional)
34134 </p>
34135 <p><var>e1</var>: holds e1 = d mod (p-1) (optional)
34136 </p>
34137 <p><var>e2</var>: holds e2 = d mod (q-1) (optional)
34138 </p>
34139 <p>This function will convert the given RSA raw parameters to the
34140 native <code>gnutls_privkey_t</code>  format.  The output will be stored in
34141  <code>key</code> .
34142 </p>
34143 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34144 negative error value.
34145 </p></dd></dl>
34146
34147 <a name="gnutls_005fprivkey_005fimport_005ftpm_005fraw-1"></a>
34148 <h4 class="subheading">gnutls_privkey_import_tpm_raw</h4>
34149 <a name="gnutls_005fprivkey_005fimport_005ftpm_005fraw"></a><dl>
34150 <dt><a name="index-gnutls_005fprivkey_005fimport_005ftpm_005fraw"></a>Function: <em>int</em> <strong>gnutls_privkey_import_tpm_raw</strong> <em>(gnutls_privkey_t <var>pkey</var>, const gnutls_datum_t * <var>fdata</var>, gnutls_tpmkey_fmt_t <var>format</var>, const char * <var>srk_password</var>, const char * <var>key_password</var>, unsigned int <var>flags</var>)</em></dt>
34151 <dd><p><var>pkey</var>: The private key
34152 </p>
34153 <p><var>fdata</var>: The TPM key to be imported
34154 </p>
34155 <p><var>format</var>: The format of the private key
34156 </p>
34157 <p><var>srk_password</var>: The password for the SRK key (optional)
34158 </p>
34159 <p><var>key_password</var>: A password for the key (optional)
34160 </p>
34161 <p><var>flags</var>: should be zero
34162 </p>
34163 <p>This function will import the given private key to the abstract
34164 <code>gnutls_privkey_t</code>  structure.
34165 </p>
34166 <p>With respect to passwords the same as in <code>gnutls_privkey_import_tpm_url()</code>  apply.
34167 </p>
34168 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34169 negative error value.
34170 </p>
34171 <p><strong>Since:</strong> 3.1.0
34172 </p></dd></dl>
34173
34174 <a name="gnutls_005fprivkey_005fimport_005ftpm_005furl-1"></a>
34175 <h4 class="subheading">gnutls_privkey_import_tpm_url</h4>
34176 <a name="gnutls_005fprivkey_005fimport_005ftpm_005furl"></a><dl>
34177 <dt><a name="index-gnutls_005fprivkey_005fimport_005ftpm_005furl-1"></a>Function: <em>int</em> <strong>gnutls_privkey_import_tpm_url</strong> <em>(gnutls_privkey_t <var>pkey</var>, const char * <var>url</var>, const char * <var>srk_password</var>, const char * <var>key_password</var>, unsigned int <var>flags</var>)</em></dt>
34178 <dd><p><var>pkey</var>: The private key
34179 </p>
34180 <p><var>url</var>: The URL of the TPM key to be imported
34181 </p>
34182 <p><var>srk_password</var>: The password for the SRK key (optional)
34183 </p>
34184 <p><var>key_password</var>: A password for the key (optional)
34185 </p>
34186 <p><var>flags</var>: One of the GNUTLS_PRIVKEY_* flags
34187 </p>
34188 <p>This function will import the given private key to the abstract
34189 <code>gnutls_privkey_t</code>  structure.
34190 </p>
34191 <p>Note that unless <code>GNUTLS_PRIVKEY_DISABLE_CALLBACKS</code>
34192 is specified, if incorrect (or NULL) passwords are given
34193 the PKCS11 callback functions will be used to obtain the
34194 correct passwords. Otherwise if the SRK password is wrong
34195 <code>GNUTLS_E_TPM_SRK_PASSWORD_ERROR</code>  is returned and if the key password
34196 is wrong or not provided then <code>GNUTLS_E_TPM_KEY_PASSWORD_ERROR</code>
34197 is returned.
34198 </p>
34199 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34200 negative error value.
34201 </p>
34202 <p><strong>Since:</strong> 3.1.0
34203 </p></dd></dl>
34204
34205 <a name="gnutls_005fprivkey_005fimport_005furl-1"></a>
34206 <h4 class="subheading">gnutls_privkey_import_url</h4>
34207 <a name="gnutls_005fprivkey_005fimport_005furl"></a><dl>
34208 <dt><a name="index-gnutls_005fprivkey_005fimport_005furl-1"></a>Function: <em>int</em> <strong>gnutls_privkey_import_url</strong> <em>(gnutls_privkey_t <var>key</var>, const char * <var>url</var>, unsigned int <var>flags</var>)</em></dt>
34209 <dd><p><var>key</var>: A key of type <code>gnutls_privkey_t</code>
34210 </p>
34211 <p><var>url</var>: A PKCS 11 url
34212 </p>
34213 <p><var>flags</var>: should be zero
34214 </p>
34215 <p>This function will import a PKCS11 or TPM URL as a
34216 private key. The supported URL types can be checked
34217 using <code>gnutls_url_is_supported()</code> .
34218 </p>
34219 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34220 negative error value.
34221 </p>
34222 <p><strong>Since:</strong> 3.1.0
34223 </p></dd></dl>
34224
34225 <a name="gnutls_005fprivkey_005fimport_005fx509-1"></a>
34226 <h4 class="subheading">gnutls_privkey_import_x509</h4>
34227 <a name="gnutls_005fprivkey_005fimport_005fx509"></a><dl>
34228 <dt><a name="index-gnutls_005fprivkey_005fimport_005fx509"></a>Function: <em>int</em> <strong>gnutls_privkey_import_x509</strong> <em>(gnutls_privkey_t <var>pkey</var>, gnutls_x509_privkey_t <var>key</var>, unsigned int <var>flags</var>)</em></dt>
34229 <dd><p><var>pkey</var>: The private key
34230 </p>
34231 <p><var>key</var>: The private key to be imported
34232 </p>
34233 <p><var>flags</var>: Flags for the import
34234 </p>
34235 <p>This function will import the given private key to the abstract
34236 <code>gnutls_privkey_t</code>  structure.
34237 </p>
34238 <p>The <code>gnutls_x509_privkey_t</code>  object must not be deallocated
34239 during the lifetime of this structure.
34240 </p>
34241 <p><code>flags</code> might be zero or one of <code>GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE</code>
34242 and <code>GNUTLS_PRIVKEY_IMPORT_COPY</code> .
34243 </p>
34244 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34245 negative error value.
34246 </p>
34247 <p><strong>Since:</strong> 2.12.0
34248 </p></dd></dl>
34249
34250 <a name="gnutls_005fprivkey_005fimport_005fx509_005fraw-1"></a>
34251 <h4 class="subheading">gnutls_privkey_import_x509_raw</h4>
34252 <a name="gnutls_005fprivkey_005fimport_005fx509_005fraw"></a><dl>
34253 <dt><a name="index-gnutls_005fprivkey_005fimport_005fx509_005fraw-1"></a>Function: <em>int</em> <strong>gnutls_privkey_import_x509_raw</strong> <em>(gnutls_privkey_t <var>pkey</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, const char * <var>password</var>, unsigned int <var>flags</var>)</em></dt>
34254 <dd><p><var>pkey</var>: The private key
34255 </p>
34256 <p><var>data</var>: The private key data to be imported
34257 </p>
34258 <p><var>format</var>: The format of the private key
34259 </p>
34260 <p><var>password</var>: A password (optional)
34261 </p>
34262 <p><var>flags</var>: an ORed sequence of gnutls_pkcs_encrypt_flags_t
34263 </p>
34264 <p>This function will import the given private key to the abstract
34265 <code>gnutls_privkey_t</code>  structure.
34266 </p>
34267 <p>The supported formats are basic unencrypted key, PKCS8, PKCS12,
34268 and the openssl format.
34269 </p>
34270 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34271 negative error value.
34272 </p>
34273 <p><strong>Since:</strong> 3.1.0
34274 </p></dd></dl>
34275
34276 <a name="gnutls_005fprivkey_005finit-1"></a>
34277 <h4 class="subheading">gnutls_privkey_init</h4>
34278 <a name="gnutls_005fprivkey_005finit"></a><dl>
34279 <dt><a name="index-gnutls_005fprivkey_005finit"></a>Function: <em>int</em> <strong>gnutls_privkey_init</strong> <em>(gnutls_privkey_t * <var>key</var>)</em></dt>
34280 <dd><p><var>key</var>: The structure to be initialized
34281 </p>
34282 <p>This function will initialize an private key structure.
34283 </p>
34284 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34285 negative error value.
34286 </p>
34287 <p><strong>Since:</strong> 2.12.0
34288 </p></dd></dl>
34289
34290 <a name="gnutls_005fprivkey_005fset_005fpin_005ffunction-1"></a>
34291 <h4 class="subheading">gnutls_privkey_set_pin_function</h4>
34292 <a name="gnutls_005fprivkey_005fset_005fpin_005ffunction"></a><dl>
34293 <dt><a name="index-gnutls_005fprivkey_005fset_005fpin_005ffunction"></a>Function: <em>void</em> <strong>gnutls_privkey_set_pin_function</strong> <em>(gnutls_privkey_t <var>key</var>, gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</em></dt>
34294 <dd><p><var>key</var>: A key of type <code>gnutls_privkey_t</code>
34295 </p>
34296 <p><var>fn</var>: the callback
34297 </p>
34298 <p><var>userdata</var>: data associated with the callback
34299 </p>
34300 <p>This function will set a callback function to be used when
34301 required to access the object. This function overrides any other
34302 global PIN functions.
34303 </p>
34304 <p>Note that this function must be called right after initialization
34305 to have effect.
34306 </p>
34307 <p><strong>Since:</strong> 3.1.0
34308 </p></dd></dl>
34309
34310 <a name="gnutls_005fprivkey_005fsign_005fdata-1"></a>
34311 <h4 class="subheading">gnutls_privkey_sign_data</h4>
34312 <a name="gnutls_005fprivkey_005fsign_005fdata"></a><dl>
34313 <dt><a name="index-gnutls_005fprivkey_005fsign_005fdata-1"></a>Function: <em>int</em> <strong>gnutls_privkey_sign_data</strong> <em>(gnutls_privkey_t <var>signer</var>, gnutls_digest_algorithm_t <var>hash</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>data</var>, gnutls_datum_t * <var>signature</var>)</em></dt>
34314 <dd><p><var>signer</var>: Holds the key
34315 </p>
34316 <p><var>hash</var>: should be a digest algorithm
34317 </p>
34318 <p><var>flags</var>: Zero or one of <code>gnutls_privkey_flags_t</code>
34319 </p>
34320 <p><var>data</var>: holds the data to be signed
34321 </p>
34322 <p><var>signature</var>: will contain the signature allocate with <code>gnutls_malloc()</code>
34323 </p>
34324 <p>This function will sign the given data using a signature algorithm
34325 supported by the private key. Signature algorithms are always used
34326 together with a hash functions.  Different hash functions may be
34327 used for the RSA algorithm, but only the SHA family for the DSA keys.
34328 </p>
34329 <p>You may use <code>gnutls_pubkey_get_preferred_hash_algorithm()</code>  to determine
34330 the hash algorithm.
34331 </p>
34332 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34333 negative error value.
34334 </p>
34335 <p><strong>Since:</strong> 2.12.0
34336 </p></dd></dl>
34337
34338 <a name="gnutls_005fprivkey_005fsign_005fhash-1"></a>
34339 <h4 class="subheading">gnutls_privkey_sign_hash</h4>
34340 <a name="gnutls_005fprivkey_005fsign_005fhash"></a><dl>
34341 <dt><a name="index-gnutls_005fprivkey_005fsign_005fhash-1"></a>Function: <em>int</em> <strong>gnutls_privkey_sign_hash</strong> <em>(gnutls_privkey_t <var>signer</var>, gnutls_digest_algorithm_t <var>hash_algo</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>hash_data</var>, gnutls_datum_t * <var>signature</var>)</em></dt>
34342 <dd><p><var>signer</var>: Holds the signer&rsquo;s key
34343 </p>
34344 <p><var>hash_algo</var>: The hash algorithm used
34345 </p>
34346 <p><var>flags</var>: Zero or one of <code>gnutls_privkey_flags_t</code>
34347 </p>
34348 <p><var>hash_data</var>: holds the data to be signed
34349 </p>
34350 <p><var>signature</var>: will contain newly allocated signature
34351 </p>
34352 <p>This function will sign the given hashed data using a signature algorithm
34353 supported by the private key. Signature algorithms are always used
34354 together with a hash functions.  Different hash functions may be
34355 used for the RSA algorithm, but only SHA-XXX for the DSA keys.
34356 </p>
34357 <p>You may use <code>gnutls_pubkey_get_preferred_hash_algorithm()</code>  to determine
34358 the hash algorithm.
34359 </p>
34360 <p>Note that if <code>GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA</code>  flag is specified this function
34361 will ignore  <code>hash_algo</code> and perform a raw PKCS1 signature.
34362 </p>
34363 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34364 negative error value.
34365 </p>
34366 <p><strong>Since:</strong> 2.12.0
34367 </p></dd></dl>
34368
34369 <a name="gnutls_005fprivkey_005fstatus-1"></a>
34370 <h4 class="subheading">gnutls_privkey_status</h4>
34371 <a name="gnutls_005fprivkey_005fstatus"></a><dl>
34372 <dt><a name="index-gnutls_005fprivkey_005fstatus"></a>Function: <em>int</em> <strong>gnutls_privkey_status</strong> <em>(gnutls_privkey_t <var>key</var>)</em></dt>
34373 <dd><p><var>key</var>: Holds the key
34374 </p>
34375 <p>Checks the status of the private key token. This function
34376 is an actual wrapper over <code>gnutls_pkcs11_privkey_status()</code> , and
34377 if the private key is a PKCS <code>11</code>  token it will check whether
34378 it is inserted or not.
34379 </p>
34380 <p><strong>Returns:</strong> this function will return non-zero if the token
34381 holding the private key is still available (inserted), and zero otherwise.
34382 </p>
34383 <p><strong>Since:</strong> 3.1.10
34384 </p></dd></dl>
34385
34386 <a name="gnutls_005fprivkey_005fverify_005fparams-1"></a>
34387 <h4 class="subheading">gnutls_privkey_verify_params</h4>
34388 <a name="gnutls_005fprivkey_005fverify_005fparams"></a><dl>
34389 <dt><a name="index-gnutls_005fprivkey_005fverify_005fparams"></a>Function: <em>int</em> <strong>gnutls_privkey_verify_params</strong> <em>(gnutls_privkey_t <var>key</var>)</em></dt>
34390 <dd><p><var>key</var>: should contain a <code>gnutls_privkey_t</code>  structure
34391 </p>
34392 <p>This function will verify the private key parameters.
34393 </p>
34394 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34395 negative error value.
34396 </p>
34397 <p><strong>Since:</strong> 3.3.0
34398 </p></dd></dl>
34399
34400 <a name="gnutls_005fpubkey_005fdeinit-1"></a>
34401 <h4 class="subheading">gnutls_pubkey_deinit</h4>
34402 <a name="gnutls_005fpubkey_005fdeinit"></a><dl>
34403 <dt><a name="index-gnutls_005fpubkey_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_pubkey_deinit</strong> <em>(gnutls_pubkey_t <var>key</var>)</em></dt>
34404 <dd><p><var>key</var>: The structure to be deinitialized
34405 </p>
34406 <p>This function will deinitialize a public key structure.
34407 </p>
34408 <p><strong>Since:</strong> 2.12.0
34409 </p></dd></dl>
34410
34411 <a name="gnutls_005fpubkey_005fencrypt_005fdata-1"></a>
34412 <h4 class="subheading">gnutls_pubkey_encrypt_data</h4>
34413 <a name="gnutls_005fpubkey_005fencrypt_005fdata"></a><dl>
34414 <dt><a name="index-gnutls_005fpubkey_005fencrypt_005fdata-1"></a>Function: <em>int</em> <strong>gnutls_pubkey_encrypt_data</strong> <em>(gnutls_pubkey_t <var>key</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>plaintext</var>, gnutls_datum_t * <var>ciphertext</var>)</em></dt>
34415 <dd><p><var>key</var>: Holds the public key
34416 </p>
34417 <p><var>flags</var>: should be 0 for now
34418 </p>
34419 <p><var>plaintext</var>: The data to be encrypted
34420 </p>
34421 <p><var>ciphertext</var>: contains the encrypted data
34422 </p>
34423 <p>This function will encrypt the given data, using the public
34424 key.
34425 </p>
34426 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34427 negative error value.
34428 </p>
34429 <p><strong>Since:</strong> 3.0
34430 </p></dd></dl>
34431
34432 <a name="gnutls_005fpubkey_005fexport-1"></a>
34433 <h4 class="subheading">gnutls_pubkey_export</h4>
34434 <a name="gnutls_005fpubkey_005fexport"></a><dl>
34435 <dt><a name="index-gnutls_005fpubkey_005fexport"></a>Function: <em>int</em> <strong>gnutls_pubkey_export</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_x509_crt_fmt_t <var>format</var>, void * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
34436 <dd><p><var>key</var>: Holds the certificate
34437 </p>
34438 <p><var>format</var>: the format of output params. One of PEM or DER.
34439 </p>
34440 <p><var>output_data</var>: will contain a certificate PEM or DER encoded
34441 </p>
34442 <p><var>output_data_size</var>: holds the size of output_data (and will be
34443 replaced by the actual size of parameters)
34444 </p>
34445 <p>This function will export the public key to DER or PEM format.
34446 The contents of the exported data is the SubjectPublicKeyInfo
34447 X.509 structure.
34448 </p>
34449 <p>If the buffer provided is not long enough to hold the output, then
34450 *output_data_size is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  will
34451 be returned.
34452 </p>
34453 <p>If the structure is PEM encoded, it will have a header
34454 of &quot;BEGIN CERTIFICATE&quot;.
34455 </p>
34456 <p><strong>Returns:</strong> In case of failure a negative error code will be
34457 returned, and 0 on success.
34458 </p>
34459 <p><strong>Since:</strong> 2.12.0
34460 </p></dd></dl>
34461
34462 <a name="gnutls_005fpubkey_005fexport2-1"></a>
34463 <h4 class="subheading">gnutls_pubkey_export2</h4>
34464 <a name="gnutls_005fpubkey_005fexport2"></a><dl>
34465 <dt><a name="index-gnutls_005fpubkey_005fexport2-1"></a>Function: <em>int</em> <strong>gnutls_pubkey_export2</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_x509_crt_fmt_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
34466 <dd><p><var>key</var>: Holds the certificate
34467 </p>
34468 <p><var>format</var>: the format of output params. One of PEM or DER.
34469 </p>
34470 <p><var>out</var>: will contain a certificate PEM or DER encoded
34471 </p>
34472 <p>This function will export the public key to DER or PEM format.
34473 The contents of the exported data is the SubjectPublicKeyInfo
34474 X.509 structure.
34475 </p>
34476 <p>The output buffer will be allocated using <code>gnutls_malloc()</code> .
34477 </p>
34478 <p>If the structure is PEM encoded, it will have a header
34479 of &quot;BEGIN CERTIFICATE&quot;.
34480 </p>
34481 <p><strong>Returns:</strong> In case of failure a negative error code will be
34482 returned, and 0 on success.
34483 </p>
34484 <p><strong>Since:</strong> 3.1.3
34485 </p></dd></dl>
34486
34487 <a name="gnutls_005fpubkey_005fexport_005fdsa_005fraw-1"></a>
34488 <h4 class="subheading">gnutls_pubkey_export_dsa_raw</h4>
34489 <a name="gnutls_005fpubkey_005fexport_005fdsa_005fraw"></a><dl>
34490 <dt><a name="index-gnutls_005fpubkey_005fexport_005fdsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_pubkey_export_dsa_raw</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>g</var>, gnutls_datum_t * <var>y</var>)</em></dt>
34491 <dd><p><var>key</var>: Holds the public key
34492 </p>
34493 <p><var>p</var>: will hold the p
34494 </p>
34495 <p><var>q</var>: will hold the q
34496 </p>
34497 <p><var>g</var>: will hold the g
34498 </p>
34499 <p><var>y</var>: will hold the y
34500 </p>
34501 <p>This function will export the DSA public key&rsquo;s parameters found in
34502 the given certificate.  The new parameters will be allocated using
34503 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
34504 </p>
34505 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
34506 </p>
34507 <p><strong>Since:</strong> 3.3.0
34508 </p></dd></dl>
34509
34510 <a name="gnutls_005fpubkey_005fexport_005fecc_005fraw-1"></a>
34511 <h4 class="subheading">gnutls_pubkey_export_ecc_raw</h4>
34512 <a name="gnutls_005fpubkey_005fexport_005fecc_005fraw"></a><dl>
34513 <dt><a name="index-gnutls_005fpubkey_005fexport_005fecc_005fraw"></a>Function: <em>int</em> <strong>gnutls_pubkey_export_ecc_raw</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_ecc_curve_t * <var>curve</var>, gnutls_datum_t * <var>x</var>, gnutls_datum_t * <var>y</var>)</em></dt>
34514 <dd><p><var>key</var>: Holds the public key
34515 </p>
34516 <p><var>curve</var>: will hold the curve
34517 </p>
34518 <p><var>x</var>: will hold x
34519 </p>
34520 <p><var>y</var>: will hold y
34521 </p>
34522 <p>This function will export the ECC public key&rsquo;s parameters found in
34523 the given certificate.  The new parameters will be allocated using
34524 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
34525 </p>
34526 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
34527 </p>
34528 <p><strong>Since:</strong> 3.0
34529 </p></dd></dl>
34530
34531 <a name="gnutls_005fpubkey_005fexport_005fecc_005fx962-1"></a>
34532 <h4 class="subheading">gnutls_pubkey_export_ecc_x962</h4>
34533 <a name="gnutls_005fpubkey_005fexport_005fecc_005fx962"></a><dl>
34534 <dt><a name="index-gnutls_005fpubkey_005fexport_005fecc_005fx962"></a>Function: <em>int</em> <strong>gnutls_pubkey_export_ecc_x962</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_datum_t * <var>parameters</var>, gnutls_datum_t * <var>ecpoint</var>)</em></dt>
34535 <dd><p><var>key</var>: Holds the public key
34536 </p>
34537 <p><var>parameters</var>: DER encoding of an ANSI X9.62 parameters
34538 </p>
34539 <p><var>ecpoint</var>: DER encoding of ANSI X9.62 ECPoint
34540 </p>
34541 <p>This function will export the ECC public key&rsquo;s parameters found in
34542 the given certificate.  The new parameters will be allocated using
34543 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
34544 </p>
34545 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
34546 </p>
34547 <p><strong>Since:</strong> 3.3.0
34548 </p></dd></dl>
34549
34550 <a name="gnutls_005fpubkey_005fexport_005frsa_005fraw-1"></a>
34551 <h4 class="subheading">gnutls_pubkey_export_rsa_raw</h4>
34552 <a name="gnutls_005fpubkey_005fexport_005frsa_005fraw"></a><dl>
34553 <dt><a name="index-gnutls_005fpubkey_005fexport_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_pubkey_export_rsa_raw</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>)</em></dt>
34554 <dd><p><var>key</var>: Holds the certificate
34555 </p>
34556 <p><var>m</var>: will hold the modulus
34557 </p>
34558 <p><var>e</var>: will hold the public exponent
34559 </p>
34560 <p>This function will export the RSA public key&rsquo;s parameters found in
34561 the given structure.  The new parameters will be allocated using
34562 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
34563 </p>
34564 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
34565 </p>
34566 <p><strong>Since:</strong> 3.3.0
34567 </p></dd></dl>
34568
34569 <a name="gnutls_005fpubkey_005fget_005fkey_005fid-1"></a>
34570 <h4 class="subheading">gnutls_pubkey_get_key_id</h4>
34571 <a name="gnutls_005fpubkey_005fget_005fkey_005fid"></a><dl>
34572 <dt><a name="index-gnutls_005fpubkey_005fget_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_pubkey_get_key_id</strong> <em>(gnutls_pubkey_t <var>key</var>, unsigned int <var>flags</var>, unsigned char * <var>output_data</var>, size_t * <var>output_data_size</var>)</em></dt>
34573 <dd><p><var>key</var>: Holds the public key
34574 </p>
34575 <p><var>flags</var>: should be 0 for now
34576 </p>
34577 <p><var>output_data</var>: will contain the key ID
34578 </p>
34579 <p><var>output_data_size</var>: holds the size of output_data (and will be
34580 replaced by the actual size of parameters)
34581 </p>
34582 <p>This function will return a unique ID that depends on the public
34583 key parameters. This ID can be used in checking whether a
34584 certificate corresponds to the given public key.
34585 </p>
34586 <p>If the buffer provided is not long enough to hold the output, then
34587 *output_data_size is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  will
34588 be returned.  The output will normally be a SHA-1 hash output,
34589 which is 20 bytes.
34590 </p>
34591 <p><strong>Returns:</strong> In case of failure a negative error code will be
34592 returned, and 0 on success.
34593 </p>
34594 <p><strong>Since:</strong> 2.12.0
34595 </p></dd></dl>
34596
34597 <a name="gnutls_005fpubkey_005fget_005fkey_005fusage-1"></a>
34598 <h4 class="subheading">gnutls_pubkey_get_key_usage</h4>
34599 <a name="gnutls_005fpubkey_005fget_005fkey_005fusage"></a><dl>
34600 <dt><a name="index-gnutls_005fpubkey_005fget_005fkey_005fusage"></a>Function: <em>int</em> <strong>gnutls_pubkey_get_key_usage</strong> <em>(gnutls_pubkey_t <var>key</var>, unsigned int * <var>usage</var>)</em></dt>
34601 <dd><p><var>key</var>: should contain a <code>gnutls_pubkey_t</code>  structure
34602 </p>
34603 <p><var>usage</var>: If set will return the number of bits of the parameters (may be NULL)
34604 </p>
34605 <p>This function will return the key usage of the public key.
34606 </p>
34607 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34608 negative error value.
34609 </p>
34610 <p><strong>Since:</strong> 2.12.0
34611 </p></dd></dl>
34612
34613 <a name="gnutls_005fpubkey_005fget_005fopenpgp_005fkey_005fid-1"></a>
34614 <h4 class="subheading">gnutls_pubkey_get_openpgp_key_id</h4>
34615 <a name="gnutls_005fpubkey_005fget_005fopenpgp_005fkey_005fid"></a><dl>
34616 <dt><a name="index-gnutls_005fpubkey_005fget_005fopenpgp_005fkey_005fid"></a>Function: <em>int</em> <strong>gnutls_pubkey_get_openpgp_key_id</strong> <em>(gnutls_pubkey_t <var>key</var>, unsigned int <var>flags</var>, unsigned char * <var>output_data</var>, size_t * <var>output_data_size</var>, unsigned int * <var>subkey</var>)</em></dt>
34617 <dd><p><var>key</var>: Holds the public key
34618 </p>
34619 <p><var>flags</var>: should be 0 or <code>GNUTLS_PUBKEY_GET_OPENPGP_FINGERPRINT</code>
34620 </p>
34621 <p><var>output_data</var>: will contain the key ID
34622 </p>
34623 <p><var>output_data_size</var>: holds the size of output_data (and will be
34624 replaced by the actual size of parameters)
34625 </p>
34626 <p><var>subkey</var>: Will be non zero if the key ID corresponds to a subkey
34627 </p>
34628 <p>This function returns the OpenPGP key ID of the corresponding key.
34629 The key is a unique ID that depends on the public
34630 key parameters.
34631 </p>
34632 <p>If the flag <code>GNUTLS_PUBKEY_GET_OPENPGP_FINGERPRINT</code>  is specified
34633 this function returns the fingerprint of the master key.
34634 </p>
34635 <p>If the buffer provided is not long enough to hold the output, then
34636 *output_data_size is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  will
34637 be returned.  The output is <code>GNUTLS_OPENPGP_KEYID_SIZE</code>  bytes long.
34638 </p>
34639 <p><strong>Returns:</strong> In case of failure a negative error code will be
34640 returned, and 0 on success.
34641 </p>
34642 <p><strong>Since:</strong> 3.0
34643 </p></dd></dl>
34644
34645 <a name="gnutls_005fpubkey_005fget_005fpk_005falgorithm-1"></a>
34646 <h4 class="subheading">gnutls_pubkey_get_pk_algorithm</h4>
34647 <a name="gnutls_005fpubkey_005fget_005fpk_005falgorithm"></a><dl>
34648 <dt><a name="index-gnutls_005fpubkey_005fget_005fpk_005falgorithm"></a>Function: <em>int</em> <strong>gnutls_pubkey_get_pk_algorithm</strong> <em>(gnutls_pubkey_t <var>key</var>, unsigned int * <var>bits</var>)</em></dt>
34649 <dd><p><var>key</var>: should contain a <code>gnutls_pubkey_t</code>  structure
34650 </p>
34651 <p><var>bits</var>: If set will return the number of bits of the parameters (may be NULL)
34652 </p>
34653 <p>This function will return the public key algorithm of a public
34654 key and if possible will return a number of bits that indicates
34655 the security parameter of the key.
34656 </p>
34657 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code>  enumeration on
34658 success, or a negative error code on error.
34659 </p>
34660 <p><strong>Since:</strong> 2.12.0
34661 </p></dd></dl>
34662
34663 <a name="gnutls_005fpubkey_005fget_005fpreferred_005fhash_005falgorithm-1"></a>
34664 <h4 class="subheading">gnutls_pubkey_get_preferred_hash_algorithm</h4>
34665 <a name="gnutls_005fpubkey_005fget_005fpreferred_005fhash_005falgorithm"></a><dl>
34666 <dt><a name="index-gnutls_005fpubkey_005fget_005fpreferred_005fhash_005falgorithm"></a>Function: <em>int</em> <strong>gnutls_pubkey_get_preferred_hash_algorithm</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_digest_algorithm_t *         <var>hash</var>, unsigned int * <var>mand</var>)</em></dt>
34667 <dd><p><var>key</var>: Holds the certificate
34668 </p>
34669 <p><var>hash</var>: The result of the call with the hash algorithm used for signature
34670 </p>
34671 <p><var>mand</var>: If non zero it means that the algorithm MUST use this hash. May be NULL.
34672 </p>
34673 <p>This function will read the certifcate and return the appropriate digest
34674 algorithm to use for signing with this certificate. Some certificates (i.e.
34675 DSA might not be able to sign without the preferred algorithm).
34676 </p>
34677 <p>To get the signature algorithm instead of just the hash use <code>gnutls_pk_to_sign()</code>
34678 with the algorithm of the certificate/key and the provided  <code>hash</code> .
34679 </p>
34680 <p><strong>Returns:</strong> the 0 if the hash algorithm is found. A negative error code is
34681 returned on error.
34682 </p>
34683 <p><strong>Since:</strong> 2.12.0
34684 </p></dd></dl>
34685
34686 <a name="gnutls_005fpubkey_005fget_005fverify_005falgorithm-1"></a>
34687 <h4 class="subheading">gnutls_pubkey_get_verify_algorithm</h4>
34688 <a name="gnutls_005fpubkey_005fget_005fverify_005falgorithm"></a><dl>
34689 <dt><a name="index-gnutls_005fpubkey_005fget_005fverify_005falgorithm"></a>Function: <em>int</em> <strong>gnutls_pubkey_get_verify_algorithm</strong> <em>(gnutls_pubkey_t <var>key</var>, const gnutls_datum_t * <var>signature</var>, gnutls_digest_algorithm_t * <var>hash</var>)</em></dt>
34690 <dd><p><var>key</var>: Holds the certificate
34691 </p>
34692 <p><var>signature</var>: contains the signature
34693 </p>
34694 <p><var>hash</var>: The result of the call with the hash algorithm used for signature
34695 </p>
34696 <p>This function will read the certifcate and the signed data to
34697 determine the hash algorithm used to generate the signature.
34698 </p>
34699 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34700 negative error value.
34701 </p>
34702 <p><strong>Since:</strong> 2.12.0
34703 </p></dd></dl>
34704
34705 <a name="gnutls_005fpubkey_005fimport-1"></a>
34706 <h4 class="subheading">gnutls_pubkey_import</h4>
34707 <a name="gnutls_005fpubkey_005fimport"></a><dl>
34708 <dt><a name="index-gnutls_005fpubkey_005fimport"></a>Function: <em>int</em> <strong>gnutls_pubkey_import</strong> <em>(gnutls_pubkey_t <var>key</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>)</em></dt>
34709 <dd><p><var>key</var>: The structure to store the parsed public key.
34710 </p>
34711 <p><var>data</var>: The DER or PEM encoded certificate.
34712 </p>
34713 <p><var>format</var>: One of DER or PEM
34714 </p>
34715 <p>This function will import the provided public key in
34716 a SubjectPublicKeyInfo X.509 structure to a native
34717 <code>gnutls_pubkey_t</code>  structure. The output will be stored
34718 in  <code>key</code> . If the public key is PEM encoded it should have a header
34719 of &quot;PUBLIC KEY&quot;.
34720 </p>
34721 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34722 negative error value.
34723 </p>
34724 <p><strong>Since:</strong> 2.12.0
34725 </p></dd></dl>
34726
34727 <a name="gnutls_005fpubkey_005fimport_005fdsa_005fraw-1"></a>
34728 <h4 class="subheading">gnutls_pubkey_import_dsa_raw</h4>
34729 <a name="gnutls_005fpubkey_005fimport_005fdsa_005fraw"></a><dl>
34730 <dt><a name="index-gnutls_005fpubkey_005fimport_005fdsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_dsa_raw</strong> <em>(gnutls_pubkey_t <var>key</var>, const gnutls_datum_t * <var>p</var>, const gnutls_datum_t * <var>q</var>, const gnutls_datum_t * <var>g</var>, const gnutls_datum_t * <var>y</var>)</em></dt>
34731 <dd><p><var>key</var>: The structure to store the parsed key
34732 </p>
34733 <p><var>p</var>: holds the p
34734 </p>
34735 <p><var>q</var>: holds the q
34736 </p>
34737 <p><var>g</var>: holds the g
34738 </p>
34739 <p><var>y</var>: holds the y
34740 </p>
34741 <p>This function will convert the given DSA raw parameters to the
34742 native <code>gnutls_pubkey_t</code>  format.  The output will be stored
34743 in  <code>key</code> .
34744 </p>
34745 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34746 negative error value.
34747 </p>
34748 <p><strong>Since:</strong> 2.12.0
34749 </p></dd></dl>
34750
34751 <a name="gnutls_005fpubkey_005fimport_005fecc_005fraw-1"></a>
34752 <h4 class="subheading">gnutls_pubkey_import_ecc_raw</h4>
34753 <a name="gnutls_005fpubkey_005fimport_005fecc_005fraw"></a><dl>
34754 <dt><a name="index-gnutls_005fpubkey_005fimport_005fecc_005fraw"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_ecc_raw</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_ecc_curve_t <var>curve</var>, const gnutls_datum_t * <var>x</var>, const gnutls_datum_t * <var>y</var>)</em></dt>
34755 <dd><p><var>key</var>: The structure to store the parsed key
34756 </p>
34757 <p><var>curve</var>: holds the curve
34758 </p>
34759 <p><var>x</var>: holds the x
34760 </p>
34761 <p><var>y</var>: holds the y
34762 </p>
34763 <p>This function will convert the given elliptic curve parameters to a
34764 <code>gnutls_pubkey_t</code> .  The output will be stored in  <code>key</code> .
34765 </p>
34766 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34767 negative error value.
34768 </p>
34769 <p><strong>Since:</strong> 3.0
34770 </p></dd></dl>
34771
34772 <a name="gnutls_005fpubkey_005fimport_005fecc_005fx962-1"></a>
34773 <h4 class="subheading">gnutls_pubkey_import_ecc_x962</h4>
34774 <a name="gnutls_005fpubkey_005fimport_005fecc_005fx962"></a><dl>
34775 <dt><a name="index-gnutls_005fpubkey_005fimport_005fecc_005fx962"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_ecc_x962</strong> <em>(gnutls_pubkey_t <var>key</var>, const gnutls_datum_t * <var>parameters</var>, const gnutls_datum_t * <var>ecpoint</var>)</em></dt>
34776 <dd><p><var>key</var>: The structure to store the parsed key
34777 </p>
34778 <p><var>parameters</var>: DER encoding of an ANSI X9.62 parameters
34779 </p>
34780 <p><var>ecpoint</var>: DER encoding of ANSI X9.62 ECPoint
34781 </p>
34782 <p>This function will convert the given elliptic curve parameters to a
34783 <code>gnutls_pubkey_t</code> .  The output will be stored in  <code>key</code> .
34784 </p>
34785 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34786 negative error value.
34787 </p>
34788 <p><strong>Since:</strong> 3.0
34789 </p></dd></dl>
34790
34791 <a name="gnutls_005fpubkey_005fimport_005fopenpgp-1"></a>
34792 <h4 class="subheading">gnutls_pubkey_import_openpgp</h4>
34793 <a name="gnutls_005fpubkey_005fimport_005fopenpgp"></a><dl>
34794 <dt><a name="index-gnutls_005fpubkey_005fimport_005fopenpgp"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_openpgp</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_openpgp_crt_t <var>crt</var>, unsigned int <var>flags</var>)</em></dt>
34795 <dd><p><var>key</var>: The public key
34796 </p>
34797 <p><var>crt</var>: The certificate to be imported
34798 </p>
34799 <p><var>flags</var>: should be zero
34800 </p>
34801 <p>Imports a public key from an openpgp key. This function will import
34802 the given public key to the abstract <code>gnutls_pubkey_t</code>
34803 structure. The subkey set as preferred will be imported or the
34804 master key otherwise.
34805 </p>
34806 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34807 negative error value.
34808 </p>
34809 <p><strong>Since:</strong> 2.12.0
34810 </p></dd></dl>
34811
34812 <a name="gnutls_005fpubkey_005fimport_005fopenpgp_005fraw-1"></a>
34813 <h4 class="subheading">gnutls_pubkey_import_openpgp_raw</h4>
34814 <a name="gnutls_005fpubkey_005fimport_005fopenpgp_005fraw"></a><dl>
34815 <dt><a name="index-gnutls_005fpubkey_005fimport_005fopenpgp_005fraw"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_openpgp_raw</strong> <em>(gnutls_pubkey_t <var>pkey</var>, const gnutls_datum_t * <var>data</var>, gnutls_openpgp_crt_fmt_t <var>format</var>, const gnutls_openpgp_keyid_t <var>keyid</var>, unsigned int <var>flags</var>)</em></dt>
34816 <dd><p><var>pkey</var>: The public key
34817 </p>
34818 <p><var>data</var>: The public key data to be imported
34819 </p>
34820 <p><var>format</var>: The format of the public key
34821 </p>
34822 <p><var>keyid</var>: The key id to use (optional)
34823 </p>
34824 <p><var>flags</var>: Should be zero
34825 </p>
34826 <p>This function will import the given public key to the abstract
34827 <code>gnutls_pubkey_t</code>  structure.
34828 </p>
34829 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34830 negative error value.
34831 </p>
34832 <p><strong>Since:</strong> 3.1.3
34833 </p></dd></dl>
34834
34835 <a name="gnutls_005fpubkey_005fimport_005fpkcs11-1"></a>
34836 <h4 class="subheading">gnutls_pubkey_import_pkcs11</h4>
34837 <a name="gnutls_005fpubkey_005fimport_005fpkcs11"></a><dl>
34838 <dt><a name="index-gnutls_005fpubkey_005fimport_005fpkcs11"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_pkcs11</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_pkcs11_obj_t <var>obj</var>, unsigned int <var>flags</var>)</em></dt>
34839 <dd><p><var>key</var>: The public key
34840 </p>
34841 <p><var>obj</var>: The parameters to be imported
34842 </p>
34843 <p><var>flags</var>: should be zero
34844 </p>
34845 <p>Imports a public key from a pkcs11 key. This function will import
34846 the given public key to the abstract <code>gnutls_pubkey_t</code>  structure.
34847 </p>
34848 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34849 negative error value.
34850 </p>
34851 <p><strong>Since:</strong> 2.12.0
34852 </p></dd></dl>
34853
34854 <a name="gnutls_005fpubkey_005fimport_005fpkcs11_005furl-1"></a>
34855 <h4 class="subheading">gnutls_pubkey_import_pkcs11_url</h4>
34856 <a name="gnutls_005fpubkey_005fimport_005fpkcs11_005furl"></a><dl>
34857 <dt><a name="index-gnutls_005fpubkey_005fimport_005fpkcs11_005furl"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_pkcs11_url</strong> <em>(gnutls_pubkey_t <var>key</var>, const char * <var>url</var>, unsigned int <var>flags</var>)</em></dt>
34858 <dd><p><var>key</var>: A key of type <code>gnutls_pubkey_t</code>
34859 </p>
34860 <p><var>url</var>: A PKCS 11 url
34861 </p>
34862 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
34863 </p>
34864 <p>This function will import a PKCS 11 certificate to a <code>gnutls_pubkey_t</code>
34865 structure.
34866 </p>
34867 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34868 negative error value.
34869 </p>
34870 <p><strong>Since:</strong> 2.12.0
34871 </p></dd></dl>
34872
34873 <a name="gnutls_005fpubkey_005fimport_005fprivkey-1"></a>
34874 <h4 class="subheading">gnutls_pubkey_import_privkey</h4>
34875 <a name="gnutls_005fpubkey_005fimport_005fprivkey"></a><dl>
34876 <dt><a name="index-gnutls_005fpubkey_005fimport_005fprivkey"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_privkey</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_privkey_t <var>pkey</var>, unsigned int <var>usage</var>, unsigned int <var>flags</var>)</em></dt>
34877 <dd><p><var>key</var>: The public key
34878 </p>
34879 <p><var>pkey</var>: The private key
34880 </p>
34881 <p><var>usage</var>: GNUTLS_KEY_* key usage flags.
34882 </p>
34883 <p><var>flags</var>: should be zero
34884 </p>
34885 <p>Imports the public key from a private.  This function will import
34886 the given public key to the abstract <code>gnutls_pubkey_t</code>  structure.
34887 </p>
34888 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34889 negative error value.
34890 </p>
34891 <p><strong>Since:</strong> 2.12.0
34892 </p></dd></dl>
34893
34894 <a name="gnutls_005fpubkey_005fimport_005frsa_005fraw-1"></a>
34895 <h4 class="subheading">gnutls_pubkey_import_rsa_raw</h4>
34896 <a name="gnutls_005fpubkey_005fimport_005frsa_005fraw"></a><dl>
34897 <dt><a name="index-gnutls_005fpubkey_005fimport_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_rsa_raw</strong> <em>(gnutls_pubkey_t <var>key</var>, const gnutls_datum_t * <var>m</var>, const gnutls_datum_t * <var>e</var>)</em></dt>
34898 <dd><p><var>key</var>: Is a structure will hold the parameters
34899 </p>
34900 <p><var>m</var>: holds the modulus
34901 </p>
34902 <p><var>e</var>: holds the public exponent
34903 </p>
34904 <p>This function will replace the parameters in the given structure.
34905 The new parameters should be stored in the appropriate
34906 gnutls_datum.
34907 </p>
34908 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an negative error code.
34909 </p>
34910 <p><strong>Since:</strong> 2.12.0
34911 </p></dd></dl>
34912
34913 <a name="gnutls_005fpubkey_005fimport_005ftpm_005fraw-1"></a>
34914 <h4 class="subheading">gnutls_pubkey_import_tpm_raw</h4>
34915 <a name="gnutls_005fpubkey_005fimport_005ftpm_005fraw"></a><dl>
34916 <dt><a name="index-gnutls_005fpubkey_005fimport_005ftpm_005fraw"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_tpm_raw</strong> <em>(gnutls_pubkey_t <var>pkey</var>, const gnutls_datum_t * <var>fdata</var>, gnutls_tpmkey_fmt_t <var>format</var>, const char * <var>srk_password</var>, unsigned int <var>flags</var>)</em></dt>
34917 <dd><p><var>pkey</var>: The public key
34918 </p>
34919 <p><var>fdata</var>: The TPM key to be imported
34920 </p>
34921 <p><var>format</var>: The format of the private key
34922 </p>
34923 <p><var>srk_password</var>: The password for the SRK key (optional)
34924 </p>
34925 <p><var>flags</var>: One of the GNUTLS_PUBKEY_* flags
34926 </p>
34927 <p>This function will import the public key from the provided TPM key
34928 structure.
34929 </p>
34930 <p>With respect to passwords the same as in
34931 <code>gnutls_pubkey_import_tpm_url()</code>  apply.
34932 </p>
34933 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34934 negative error value.
34935 </p>
34936 <p><strong>Since:</strong> 3.1.0
34937 </p></dd></dl>
34938
34939 <a name="gnutls_005fpubkey_005fimport_005ftpm_005furl-1"></a>
34940 <h4 class="subheading">gnutls_pubkey_import_tpm_url</h4>
34941 <a name="gnutls_005fpubkey_005fimport_005ftpm_005furl"></a><dl>
34942 <dt><a name="index-gnutls_005fpubkey_005fimport_005ftpm_005furl-1"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_tpm_url</strong> <em>(gnutls_pubkey_t <var>pkey</var>, const char * <var>url</var>, const char * <var>srk_password</var>, unsigned int <var>flags</var>)</em></dt>
34943 <dd><p><var>pkey</var>: The public key
34944 </p>
34945 <p><var>url</var>: The URL of the TPM key to be imported
34946 </p>
34947 <p><var>srk_password</var>: The password for the SRK key (optional)
34948 </p>
34949 <p><var>flags</var>: should be zero
34950 </p>
34951 <p>This function will import the given private key to the abstract
34952 <code>gnutls_privkey_t</code>  structure.
34953 </p>
34954 <p>Note that unless <code>GNUTLS_PUBKEY_DISABLE_CALLBACKS</code>
34955 is specified, if incorrect (or NULL) passwords are given
34956 the PKCS11 callback functions will be used to obtain the
34957 correct passwords. Otherwise if the SRK password is wrong
34958 <code>GNUTLS_E_TPM_SRK_PASSWORD_ERROR</code>  is returned.
34959 </p>
34960 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34961 negative error value.
34962 </p>
34963 <p><strong>Since:</strong> 3.1.0
34964 </p></dd></dl>
34965
34966 <a name="gnutls_005fpubkey_005fimport_005furl-1"></a>
34967 <h4 class="subheading">gnutls_pubkey_import_url</h4>
34968 <a name="gnutls_005fpubkey_005fimport_005furl"></a><dl>
34969 <dt><a name="index-gnutls_005fpubkey_005fimport_005furl"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_url</strong> <em>(gnutls_pubkey_t <var>key</var>, const char * <var>url</var>, unsigned int <var>flags</var>)</em></dt>
34970 <dd><p><var>key</var>: A key of type <code>gnutls_pubkey_t</code>
34971 </p>
34972 <p><var>url</var>: A PKCS 11 url
34973 </p>
34974 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
34975 </p>
34976 <p>This function will import a PKCS11 certificate or a TPM key
34977 as a public key.
34978 </p>
34979 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34980 negative error value.
34981 </p>
34982 <p><strong>Since:</strong> 3.1.0
34983 </p></dd></dl>
34984
34985 <a name="gnutls_005fpubkey_005fimport_005fx509-1"></a>
34986 <h4 class="subheading">gnutls_pubkey_import_x509</h4>
34987 <a name="gnutls_005fpubkey_005fimport_005fx509"></a><dl>
34988 <dt><a name="index-gnutls_005fpubkey_005fimport_005fx509"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_x509</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_x509_crt_t <var>crt</var>, unsigned int <var>flags</var>)</em></dt>
34989 <dd><p><var>key</var>: The public key
34990 </p>
34991 <p><var>crt</var>: The certificate to be imported
34992 </p>
34993 <p><var>flags</var>: should be zero
34994 </p>
34995 <p>This function will import the given public key to the abstract
34996 <code>gnutls_pubkey_t</code>  structure.
34997 </p>
34998 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
34999 negative error value.
35000 </p>
35001 <p><strong>Since:</strong> 2.12.0
35002 </p></dd></dl>
35003
35004 <a name="gnutls_005fpubkey_005fimport_005fx509_005fcrq-1"></a>
35005 <h4 class="subheading">gnutls_pubkey_import_x509_crq</h4>
35006 <a name="gnutls_005fpubkey_005fimport_005fx509_005fcrq"></a><dl>
35007 <dt><a name="index-gnutls_005fpubkey_005fimport_005fx509_005fcrq"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_x509_crq</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_x509_crq_t <var>crq</var>, unsigned int <var>flags</var>)</em></dt>
35008 <dd><p><var>key</var>: The public key
35009 </p>
35010 <p><var>crq</var>: The certificate to be imported
35011 </p>
35012 <p><var>flags</var>: should be zero
35013 </p>
35014 <p>This function will import the given public key to the abstract
35015 <code>gnutls_pubkey_t</code>  structure.
35016 </p>
35017 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
35018 negative error value.
35019 </p>
35020 <p><strong>Since:</strong> 3.1.5
35021 </p></dd></dl>
35022
35023 <a name="gnutls_005fpubkey_005fimport_005fx509_005fraw-1"></a>
35024 <h4 class="subheading">gnutls_pubkey_import_x509_raw</h4>
35025 <a name="gnutls_005fpubkey_005fimport_005fx509_005fraw"></a><dl>
35026 <dt><a name="index-gnutls_005fpubkey_005fimport_005fx509_005fraw"></a>Function: <em>int</em> <strong>gnutls_pubkey_import_x509_raw</strong> <em>(gnutls_pubkey_t <var>pkey</var>, const gnutls_datum_t * <var>data</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned int <var>flags</var>)</em></dt>
35027 <dd><p><var>pkey</var>: The public key
35028 </p>
35029 <p><var>data</var>: The public key data to be imported
35030 </p>
35031 <p><var>format</var>: The format of the public key
35032 </p>
35033 <p><var>flags</var>: should be zero
35034 </p>
35035 <p>This function will import the given public key to the abstract
35036 <code>gnutls_pubkey_t</code>  structure.
35037 </p>
35038 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
35039 negative error value.
35040 </p>
35041 <p><strong>Since:</strong> 3.1.3
35042 </p></dd></dl>
35043
35044 <a name="gnutls_005fpubkey_005finit-1"></a>
35045 <h4 class="subheading">gnutls_pubkey_init</h4>
35046 <a name="gnutls_005fpubkey_005finit"></a><dl>
35047 <dt><a name="index-gnutls_005fpubkey_005finit"></a>Function: <em>int</em> <strong>gnutls_pubkey_init</strong> <em>(gnutls_pubkey_t * <var>key</var>)</em></dt>
35048 <dd><p><var>key</var>: The structure to be initialized
35049 </p>
35050 <p>This function will initialize an public key structure.
35051 </p>
35052 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
35053 negative error value.
35054 </p>
35055 <p><strong>Since:</strong> 2.12.0
35056 </p></dd></dl>
35057
35058 <a name="gnutls_005fpubkey_005fprint-1"></a>
35059 <h4 class="subheading">gnutls_pubkey_print</h4>
35060 <a name="gnutls_005fpubkey_005fprint"></a><dl>
35061 <dt><a name="index-gnutls_005fpubkey_005fprint"></a>Function: <em>int</em> <strong>gnutls_pubkey_print</strong> <em>(gnutls_pubkey_t <var>pubkey</var>, gnutls_certificate_print_formats_t <var>format</var>, gnutls_datum_t * <var>out</var>)</em></dt>
35062 <dd><p><var>pubkey</var>: The structure to be printed
35063 </p>
35064 <p><var>format</var>: Indicate the format to use
35065 </p>
35066 <p><var>out</var>: Newly allocated datum with null terminated string.
35067 </p>
35068 <p>This function will pretty print public key information, suitable for
35069 display to a human.
35070 </p>
35071 <p>Only <code>GNUTLS_CRT_PRINT_FULL</code>  and <code>GNUTLS_CRT_PRINT_FULL_NUMBERS</code>
35072 are implemented.
35073 </p>
35074 <p>The output  <code>out</code> needs to be deallocated using <code>gnutls_free()</code> .
35075 </p>
35076 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
35077 negative error value.
35078 </p>
35079 <p><strong>Since:</strong> 3.1.5
35080 </p></dd></dl>
35081
35082 <a name="gnutls_005fpubkey_005fset_005fkey_005fusage-1"></a>
35083 <h4 class="subheading">gnutls_pubkey_set_key_usage</h4>
35084 <a name="gnutls_005fpubkey_005fset_005fkey_005fusage"></a><dl>
35085 <dt><a name="index-gnutls_005fpubkey_005fset_005fkey_005fusage"></a>Function: <em>int</em> <strong>gnutls_pubkey_set_key_usage</strong> <em>(gnutls_pubkey_t <var>key</var>, unsigned int <var>usage</var>)</em></dt>
35086 <dd><p><var>key</var>: a certificate of type <code>gnutls_x509_crt_t</code>
35087 </p>
35088 <p><var>usage</var>: an ORed sequence of the GNUTLS_KEY_* elements.
35089 </p>
35090 <p>This function will set the key usage flags of the public key. This
35091 is only useful if the key is to be exported to a certificate or
35092 certificate request.
35093 </p>
35094 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
35095 negative error value.
35096 </p>
35097 <p><strong>Since:</strong> 2.12.0
35098 </p></dd></dl>
35099
35100 <a name="gnutls_005fpubkey_005fset_005fpin_005ffunction-1"></a>
35101 <h4 class="subheading">gnutls_pubkey_set_pin_function</h4>
35102 <a name="gnutls_005fpubkey_005fset_005fpin_005ffunction"></a><dl>
35103 <dt><a name="index-gnutls_005fpubkey_005fset_005fpin_005ffunction"></a>Function: <em>void</em> <strong>gnutls_pubkey_set_pin_function</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</em></dt>
35104 <dd><p><var>key</var>: A key of type <code>gnutls_pubkey_t</code>
35105 </p>
35106 <p><var>fn</var>: the callback
35107 </p>
35108 <p><var>userdata</var>: data associated with the callback
35109 </p>
35110 <p>This function will set a callback function to be used when
35111 required to access the object. This function overrides any other
35112 global PIN functions.
35113 </p>
35114 <p>Note that this function must be called right after initialization
35115 to have effect.
35116 </p>
35117 <p><strong>Since:</strong> 3.1.0
35118 </p></dd></dl>
35119
35120 <a name="gnutls_005fpubkey_005fverify_005fdata-1"></a>
35121 <h4 class="subheading">gnutls_pubkey_verify_data</h4>
35122 <a name="gnutls_005fpubkey_005fverify_005fdata"></a><dl>
35123 <dt><a name="index-gnutls_005fpubkey_005fverify_005fdata"></a>Function: <em>int</em> <strong>gnutls_pubkey_verify_data</strong> <em>(gnutls_pubkey_t <var>pubkey</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>data</var>, const gnutls_datum_t * <var>signature</var>)</em></dt>
35124 <dd><p><var>pubkey</var>: Holds the public key
35125 </p>
35126 <p><var>flags</var>: Zero or one of <code>gnutls_pubkey_flags_t</code>
35127 </p>
35128 <p><var>data</var>: holds the signed data
35129 </p>
35130 <p><var>signature</var>: contains the signature
35131 </p>
35132 <p>This function will verify the given signed data, using the
35133 parameters from the certificate.
35134 </p>
35135 <p>Deprecated. This function cannot be easily used securely.
35136 Use <code>gnutls_pubkey_verify_data2()</code>  instead.
35137 </p>
35138 <p><strong>Returns:</strong> In case of a verification failure <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
35139 is returned, and zero or positive code on success.
35140 </p>
35141 <p><strong>Since:</strong> 2.12.0
35142 </p></dd></dl>
35143
35144 <a name="gnutls_005fpubkey_005fverify_005fdata2-1"></a>
35145 <h4 class="subheading">gnutls_pubkey_verify_data2</h4>
35146 <a name="gnutls_005fpubkey_005fverify_005fdata2"></a><dl>
35147 <dt><a name="index-gnutls_005fpubkey_005fverify_005fdata2-1"></a>Function: <em>int</em> <strong>gnutls_pubkey_verify_data2</strong> <em>(gnutls_pubkey_t <var>pubkey</var>, gnutls_sign_algorithm_t <var>algo</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>data</var>, const gnutls_datum_t * <var>signature</var>)</em></dt>
35148 <dd><p><var>pubkey</var>: Holds the public key
35149 </p>
35150 <p><var>algo</var>: The signature algorithm used
35151 </p>
35152 <p><var>flags</var>: Zero or one of <code>gnutls_pubkey_flags_t</code>
35153 </p>
35154 <p><var>data</var>: holds the signed data
35155 </p>
35156 <p><var>signature</var>: contains the signature
35157 </p>
35158 <p>This function will verify the given signed data, using the
35159 parameters from the certificate.
35160 </p>
35161 <p><strong>Returns:</strong> In case of a verification failure <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
35162 is returned, and zero or positive code on success.
35163 </p>
35164 <p><strong>Since:</strong> 3.0
35165 </p></dd></dl>
35166
35167 <a name="gnutls_005fpubkey_005fverify_005fhash-1"></a>
35168 <h4 class="subheading">gnutls_pubkey_verify_hash</h4>
35169 <a name="gnutls_005fpubkey_005fverify_005fhash"></a><dl>
35170 <dt><a name="index-gnutls_005fpubkey_005fverify_005fhash"></a>Function: <em>int</em> <strong>gnutls_pubkey_verify_hash</strong> <em>(gnutls_pubkey_t <var>key</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>hash</var>, const gnutls_datum_t * <var>signature</var>)</em></dt>
35171 <dd><p><var>key</var>: Holds the public key
35172 </p>
35173 <p><var>flags</var>: Zero or one of <code>gnutls_pubkey_flags_t</code>
35174 </p>
35175 <p><var>hash</var>: holds the hash digest to be verified
35176 </p>
35177 <p><var>signature</var>: contains the signature
35178 </p>
35179 <p>This function will verify the given signed digest, using the
35180 parameters from the public key.
35181 </p>
35182 <p>Deprecated. This function cannot be easily used securely.
35183 Use <code>gnutls_pubkey_verify_hash2()</code>  instead.
35184 </p>
35185 <p><strong>Returns:</strong> In case of a verification failure <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
35186 is returned, and zero or positive code on success.
35187 </p>
35188 <p><strong>Since:</strong> 2.12.0
35189 </p></dd></dl>
35190
35191 <a name="gnutls_005fpubkey_005fverify_005fhash2-1"></a>
35192 <h4 class="subheading">gnutls_pubkey_verify_hash2</h4>
35193 <a name="gnutls_005fpubkey_005fverify_005fhash2"></a><dl>
35194 <dt><a name="index-gnutls_005fpubkey_005fverify_005fhash2-1"></a>Function: <em>int</em> <strong>gnutls_pubkey_verify_hash2</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_sign_algorithm_t <var>algo</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>hash</var>, const gnutls_datum_t * <var>signature</var>)</em></dt>
35195 <dd><p><var>key</var>: Holds the public key
35196 </p>
35197 <p><var>algo</var>: The signature algorithm used
35198 </p>
35199 <p><var>flags</var>: Zero or one of <code>gnutls_pubkey_flags_t</code>
35200 </p>
35201 <p><var>hash</var>: holds the hash digest to be verified
35202 </p>
35203 <p><var>signature</var>: contains the signature
35204 </p>
35205 <p>This function will verify the given signed digest, using the
35206 parameters from the public key. Note that unlike <code>gnutls_privkey_sign_hash()</code> ,
35207 this function accepts a signature algorithm instead of a digest algorithm.
35208 You can use <code>gnutls_pk_to_sign()</code>  to get the appropriate value.
35209 </p>
35210 <p><strong>Returns:</strong> In case of a verification failure <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
35211 is returned, and zero or positive code on success.
35212 </p>
35213 <p><strong>Since:</strong> 3.0
35214 </p></dd></dl>
35215
35216 <a name="gnutls_005fpubkey_005fverify_005fparams-1"></a>
35217 <h4 class="subheading">gnutls_pubkey_verify_params</h4>
35218 <a name="gnutls_005fpubkey_005fverify_005fparams"></a><dl>
35219 <dt><a name="index-gnutls_005fpubkey_005fverify_005fparams"></a>Function: <em>int</em> <strong>gnutls_pubkey_verify_params</strong> <em>(gnutls_pubkey_t <var>key</var>)</em></dt>
35220 <dd><p><var>key</var>: should contain a <code>gnutls_pubkey_t</code>  structure
35221 </p>
35222 <p>This function will verify the private key parameters.
35223 </p>
35224 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
35225 negative error value.
35226 </p>
35227 <p><strong>Since:</strong> 3.3.0
35228 </p></dd></dl>
35229
35230 <a name="gnutls_005fx509_005fcrl_005fprivkey_005fsign-1"></a>
35231 <h4 class="subheading">gnutls_x509_crl_privkey_sign</h4>
35232 <a name="gnutls_005fx509_005fcrl_005fprivkey_005fsign"></a><dl>
35233 <dt><a name="index-gnutls_005fx509_005fcrl_005fprivkey_005fsign-1"></a>Function: <em>int</em> <strong>gnutls_x509_crl_privkey_sign</strong> <em>(gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crt_t <var>issuer</var>, gnutls_privkey_t <var>issuer_key</var>, gnutls_digest_algorithm_t <var>dig</var>, unsigned int <var>flags</var>)</em></dt>
35234 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
35235 </p>
35236 <p><var>issuer</var>: is the certificate of the certificate issuer
35237 </p>
35238 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
35239 </p>
35240 <p><var>dig</var>: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you&rsquo;re doing.
35241 </p>
35242 <p><var>flags</var>: must be 0
35243 </p>
35244 <p>This function will sign the CRL with the issuer&rsquo;s private key, and
35245 will copy the issuer&rsquo;s information into the CRL.
35246 </p>
35247 <p>This must be the last step in a certificate CRL since all
35248 the previously set parameters are now signed.
35249 </p>
35250 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
35251 negative error value.
35252 </p>
35253 <p>Since 2.12.0
35254 </p></dd></dl>
35255
35256 <a name="gnutls_005fx509_005fcrq_005fprivkey_005fsign-1"></a>
35257 <h4 class="subheading">gnutls_x509_crq_privkey_sign</h4>
35258 <a name="gnutls_005fx509_005fcrq_005fprivkey_005fsign"></a><dl>
35259 <dt><a name="index-gnutls_005fx509_005fcrq_005fprivkey_005fsign"></a>Function: <em>int</em> <strong>gnutls_x509_crq_privkey_sign</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_privkey_t <var>key</var>, gnutls_digest_algorithm_t <var>dig</var>, unsigned int <var>flags</var>)</em></dt>
35260 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
35261 </p>
35262 <p><var>key</var>: holds a private key
35263 </p>
35264 <p><var>dig</var>: The message digest to use, i.e., <code>GNUTLS_DIG_SHA1</code>
35265 </p>
35266 <p><var>flags</var>: must be 0
35267 </p>
35268 <p>This function will sign the certificate request with a private key.
35269 This must be the same key as the one used in
35270 <code>gnutls_x509_crt_set_key()</code>  since a certificate request is self
35271 signed.
35272 </p>
35273 <p>This must be the last step in a certificate request generation
35274 since all the previously set parameters are now signed.
35275 </p>
35276 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, otherwise a negative error code.
35277 <code>GNUTLS_E_ASN1_VALUE_NOT_FOUND</code>  is returned if you didn&rsquo;t set all
35278 information in the certificate request (e.g., the version using
35279 <code>gnutls_x509_crq_set_version()</code> ).
35280 </p>
35281 <p><strong>Since:</strong> 2.12.0
35282 </p></dd></dl>
35283
35284 <a name="gnutls_005fx509_005fcrq_005fset_005fpubkey-1"></a>
35285 <h4 class="subheading">gnutls_x509_crq_set_pubkey</h4>
35286 <a name="gnutls_005fx509_005fcrq_005fset_005fpubkey"></a><dl>
35287 <dt><a name="index-gnutls_005fx509_005fcrq_005fset_005fpubkey-1"></a>Function: <em>int</em> <strong>gnutls_x509_crq_set_pubkey</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_pubkey_t <var>key</var>)</em></dt>
35288 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
35289 </p>
35290 <p><var>key</var>: holds a public key
35291 </p>
35292 <p>This function will set the public parameters from the given public
35293 key to the request.
35294 </p>
35295 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
35296 negative error value.
35297 </p>
35298 <p><strong>Since:</strong> 2.12.0
35299 </p></dd></dl>
35300
35301 <a name="gnutls_005fx509_005fcrt_005fprivkey_005fsign-1"></a>
35302 <h4 class="subheading">gnutls_x509_crt_privkey_sign</h4>
35303 <a name="gnutls_005fx509_005fcrt_005fprivkey_005fsign"></a><dl>
35304 <dt><a name="index-gnutls_005fx509_005fcrt_005fprivkey_005fsign"></a>Function: <em>int</em> <strong>gnutls_x509_crt_privkey_sign</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_x509_crt_t <var>issuer</var>, gnutls_privkey_t <var>issuer_key</var>, gnutls_digest_algorithm_t <var>dig</var>, unsigned int <var>flags</var>)</em></dt>
35305 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
35306 </p>
35307 <p><var>issuer</var>: is the certificate of the certificate issuer
35308 </p>
35309 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
35310 </p>
35311 <p><var>dig</var>: The message digest to use, <code>GNUTLS_DIG_SHA1</code>  is a safe choice
35312 </p>
35313 <p><var>flags</var>: must be 0
35314 </p>
35315 <p>This function will sign the certificate with the issuer&rsquo;s private key, and
35316 will copy the issuer&rsquo;s information into the certificate.
35317 </p>
35318 <p>This must be the last step in a certificate generation since all
35319 the previously set parameters are now signed.
35320 </p>
35321 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
35322 negative error value.
35323 </p></dd></dl>
35324
35325 <a name="gnutls_005fx509_005fcrt_005fset_005fpubkey-1"></a>
35326 <h4 class="subheading">gnutls_x509_crt_set_pubkey</h4>
35327 <a name="gnutls_005fx509_005fcrt_005fset_005fpubkey"></a><dl>
35328 <dt><a name="index-gnutls_005fx509_005fcrt_005fset_005fpubkey-1"></a>Function: <em>int</em> <strong>gnutls_x509_crt_set_pubkey</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_pubkey_t <var>key</var>)</em></dt>
35329 <dd><p><var>crt</var>: should contain a <code>gnutls_x509_crt_t</code>  structure
35330 </p>
35331 <p><var>key</var>: holds a public key
35332 </p>
35333 <p>This function will set the public parameters from the given public
35334 key to the request.
35335 </p>
35336 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
35337 negative error value.
35338 </p>
35339 <p><strong>Since:</strong> 2.12.0
35340 </p></dd></dl>
35341
35342
35343 <hr>
35344 <a name="DANE-API"></a>
35345 <div class="header">
35346 <p>
35347 Next: <a href="#Cryptographic-API" accesskey="n" rel="next">Cryptographic API</a>, Previous: <a href="#Abstract-key-API" accesskey="p" rel="prev">Abstract key API</a>, Up: <a href="#API-reference" accesskey="u" rel="up">API reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
35348 </div>
35349 <a name="DANE-API-1"></a>
35350 <h3 class="section">E.10 DANE API</h3>
35351
35352 <p>The following functions are to be used for DANE certificate verification.
35353 Their prototypes lie in <samp>gnutls/dane.h</samp>. Note that you need to link
35354 with the <code>libgnutls-dane</code> library to use them.
35355 </p>
35356
35357 <a name="dane_005fcert_005ftype_005fname-1"></a>
35358 <h4 class="subheading">dane_cert_type_name</h4>
35359 <a name="dane_005fcert_005ftype_005fname"></a><dl>
35360 <dt><a name="index-dane_005fcert_005ftype_005fname"></a>Function: <em>const char *</em> <strong>dane_cert_type_name</strong> <em>(dane_cert_type_t <var>type</var>)</em></dt>
35361 <dd><p><var>type</var>: is a DANE match type
35362 </p>
35363 <p>Convert a <code>dane_cert_type_t</code>  value to a string.
35364 </p>
35365 <p><strong>Returns:</strong> a string that contains the name of the specified
35366 type, or <code>NULL</code> .
35367 </p></dd></dl>
35368
35369 <a name="dane_005fcert_005fusage_005fname-1"></a>
35370 <h4 class="subheading">dane_cert_usage_name</h4>
35371 <a name="dane_005fcert_005fusage_005fname"></a><dl>
35372 <dt><a name="index-dane_005fcert_005fusage_005fname"></a>Function: <em>const char *</em> <strong>dane_cert_usage_name</strong> <em>(dane_cert_usage_t <var>usage</var>)</em></dt>
35373 <dd><p><var>usage</var>: &ndash; undescribed &ndash;
35374 </p>
35375 <p>Convert a <code>dane_cert_usage_t</code>  value to a string.
35376 </p>
35377 <p><strong>Returns:</strong> a string that contains the name of the specified
35378 type, or <code>NULL</code> .
35379 </p></dd></dl>
35380
35381 <a name="dane_005fmatch_005ftype_005fname-1"></a>
35382 <h4 class="subheading">dane_match_type_name</h4>
35383 <a name="dane_005fmatch_005ftype_005fname"></a><dl>
35384 <dt><a name="index-dane_005fmatch_005ftype_005fname"></a>Function: <em>const char *</em> <strong>dane_match_type_name</strong> <em>(dane_match_type_t <var>type</var>)</em></dt>
35385 <dd><p><var>type</var>: is a DANE match type
35386 </p>
35387 <p>Convert a <code>dane_match_type_t</code>  value to a string.
35388 </p>
35389 <p><strong>Returns:</strong> a string that contains the name of the specified
35390 type, or <code>NULL</code> .
35391 </p></dd></dl>
35392
35393 <a name="dane_005fquery_005fdata-1"></a>
35394 <h4 class="subheading">dane_query_data</h4>
35395 <a name="dane_005fquery_005fdata"></a><dl>
35396 <dt><a name="index-dane_005fquery_005fdata"></a>Function: <em>int</em> <strong>dane_query_data</strong> <em>(dane_query_t <var>q</var>, unsigned int <var>idx</var>, unsigned int * <var>usage</var>, unsigned int * <var>type</var>, unsigned int * <var>match</var>, gnutls_datum_t * <var>data</var>)</em></dt>
35397 <dd><p><var>q</var>: The query result structure
35398 </p>
35399 <p><var>idx</var>: The index of the query response.
35400 </p>
35401 <p><var>usage</var>: The certificate usage (see <code>dane_cert_usage_t</code> )
35402 </p>
35403 <p><var>type</var>: The certificate type (see <code>dane_cert_type_t</code> )
35404 </p>
35405 <p><var>match</var>: The DANE matching type (see <code>dane_match_type_t</code> )
35406 </p>
35407 <p><var>data</var>: The DANE data.
35408 </p>
35409 <p>This function will provide the DANE data from the query
35410 response.
35411 </p>
35412 <p><strong>Returns:</strong> On success, <code>DANE_E_SUCCESS</code>  (0) is returned, otherwise a
35413 negative error value.
35414 </p></dd></dl>
35415
35416 <a name="dane_005fquery_005fdeinit-1"></a>
35417 <h4 class="subheading">dane_query_deinit</h4>
35418 <a name="dane_005fquery_005fdeinit"></a><dl>
35419 <dt><a name="index-dane_005fquery_005fdeinit"></a>Function: <em>void</em> <strong>dane_query_deinit</strong> <em>(dane_query_t <var>q</var>)</em></dt>
35420 <dd><p><var>q</var>: The structure to be deinitialized
35421 </p>
35422 <p>This function will deinitialize a DANE query result structure.
35423 </p></dd></dl>
35424
35425 <a name="dane_005fquery_005fentries-1"></a>
35426 <h4 class="subheading">dane_query_entries</h4>
35427 <a name="dane_005fquery_005fentries"></a><dl>
35428 <dt><a name="index-dane_005fquery_005fentries"></a>Function: <em>unsigned int</em> <strong>dane_query_entries</strong> <em>(dane_query_t <var>q</var>)</em></dt>
35429 <dd><p><var>q</var>: The query result structure
35430 </p>
35431 <p>This function will return the number of entries in a query.
35432 </p>
35433 <p><strong>Returns:</strong> The number of entries.
35434 </p></dd></dl>
35435
35436 <a name="dane_005fquery_005fstatus-1"></a>
35437 <h4 class="subheading">dane_query_status</h4>
35438 <a name="dane_005fquery_005fstatus"></a><dl>
35439 <dt><a name="index-dane_005fquery_005fstatus"></a>Function: <em>dane_query_status_t</em> <strong>dane_query_status</strong> <em>(dane_query_t <var>q</var>)</em></dt>
35440 <dd><p><var>q</var>: The query result structure
35441 </p>
35442 <p>This function will return the status of the query response.
35443 See <code>dane_query_status_t</code>  for the possible types.
35444 </p>
35445 <p><strong>Returns:</strong> The status type.
35446 </p></dd></dl>
35447
35448 <a name="dane_005fquery_005ftlsa-1"></a>
35449 <h4 class="subheading">dane_query_tlsa</h4>
35450 <a name="dane_005fquery_005ftlsa"></a><dl>
35451 <dt><a name="index-dane_005fquery_005ftlsa"></a>Function: <em>int</em> <strong>dane_query_tlsa</strong> <em>(dane_state_t <var>s</var>, dane_query_t * <var>r</var>, const char * <var>host</var>, const char * <var>proto</var>, unsigned int <var>port</var>)</em></dt>
35452 <dd><p><var>s</var>: The DANE state structure
35453 </p>
35454 <p><var>r</var>: A structure to place the result
35455 </p>
35456 <p><var>host</var>: The host name to resolve.
35457 </p>
35458 <p><var>proto</var>: The protocol type (tcp, udp, etc.)
35459 </p>
35460 <p><var>port</var>: The service port number (eg. 443).
35461 </p>
35462 <p>This function will query the DNS server for the TLSA (DANE)
35463 data for the given host.
35464 </p>
35465 <p><strong>Returns:</strong> On success, <code>DANE_E_SUCCESS</code>  (0) is returned, otherwise a
35466 negative error value.
35467 </p></dd></dl>
35468
35469 <a name="dane_005fquery_005fto_005fraw_005ftlsa-1"></a>
35470 <h4 class="subheading">dane_query_to_raw_tlsa</h4>
35471 <a name="dane_005fquery_005fto_005fraw_005ftlsa"></a><dl>
35472 <dt><a name="index-dane_005fquery_005fto_005fraw_005ftlsa"></a>Function: <em>int</em> <strong>dane_query_to_raw_tlsa</strong> <em>(dane_query_t <var>q</var>, unsigned int * <var>data_entries</var>, char *** <var>dane_data</var>, int ** <var>dane_data_len</var>, int * <var>secure</var>, int * <var>bogus</var>)</em></dt>
35473 <dd><p><var>q</var>: The query result structure
35474 </p>
35475 <p><var>data_entries</var>: Pointer set to the number of entries in the query
35476 </p>
35477 <p><var>dane_data</var>: Pointer to contain an array of DNS rdata items, terminated with a NULL pointer;
35478 caller must guarantee that the referenced data remains
35479 valid until <code>dane_query_deinit()</code>  is called.
35480 </p>
35481 <p><var>dane_data_len</var>: Pointer to contain the length n bytes of the dane_data items
35482 </p>
35483 <p><var>secure</var>: Pointer set true if the result is validated securely, false if
35484 validation failed or the domain queried has no security info
35485 </p>
35486 <p><var>bogus</var>: Pointer set true if the result was not secure due to a security failure
35487 </p>
35488 <p>This function will provide the DANE data from the query
35489 response.
35490 </p>
35491 <p>The pointers dane_data and dane_data_len are allocated with <code>gnutls_malloc()</code>
35492 to contain the data from the query result structure (individual
35493  <code>dane_data</code> items simply point to the original data and are not allocated separately).
35494 The returned  <code>dane_data</code> are only valid during the lifetime of  <code>q</code> .
35495 </p>
35496 <p><strong>Returns:</strong> On success, <code>DANE_E_SUCCESS</code>  (0) is returned, otherwise a
35497 negative error value.
35498 </p></dd></dl>
35499
35500 <a name="dane_005fraw_005ftlsa-1"></a>
35501 <h4 class="subheading">dane_raw_tlsa</h4>
35502 <a name="dane_005fraw_005ftlsa"></a><dl>
35503 <dt><a name="index-dane_005fraw_005ftlsa"></a>Function: <em>int</em> <strong>dane_raw_tlsa</strong> <em>(dane_state_t <var>s</var>, dane_query_t * <var>r</var>, char *const * <var>dane_data</var>, const int * <var>dane_data_len</var>, int <var>secure</var>, int <var>bogus</var>)</em></dt>
35504 <dd><p><var>s</var>: The DANE state structure
35505 </p>
35506 <p><var>r</var>: A structure to place the result
35507 </p>
35508 <p><var>dane_data</var>: array of DNS rdata items, terminated with a NULL pointer;
35509 caller must guarantee that the referenced data remains
35510 valid until <code>dane_query_deinit()</code>  is called.
35511 </p>
35512 <p><var>dane_data_len</var>: the length n bytes of the dane_data items
35513 </p>
35514 <p><var>secure</var>: true if the result is validated securely, false if
35515 validation failed or the domain queried has no security info
35516 </p>
35517 <p><var>bogus</var>: if the result was not secure (secure = 0) due to a security failure,
35518 and the result is due to a security failure, bogus is true.
35519 </p>
35520 <p>This function will fill in the TLSA (DANE) structure from
35521 the given raw DNS record data. The  <code>dane_data</code> must be valid
35522 during the lifetime of the query.
35523 </p>
35524 <p><strong>Returns:</strong> On success, <code>DANE_E_SUCCESS</code>  (0) is returned, otherwise a
35525 negative error value.
35526 </p></dd></dl>
35527
35528 <a name="dane_005fstate_005fdeinit-1"></a>
35529 <h4 class="subheading">dane_state_deinit</h4>
35530 <a name="dane_005fstate_005fdeinit"></a><dl>
35531 <dt><a name="index-dane_005fstate_005fdeinit"></a>Function: <em>void</em> <strong>dane_state_deinit</strong> <em>(dane_state_t <var>s</var>)</em></dt>
35532 <dd><p><var>s</var>: The structure to be deinitialized
35533 </p>
35534 <p>This function will deinitialize a DANE query structure.
35535 </p></dd></dl>
35536
35537 <a name="dane_005fstate_005finit-1"></a>
35538 <h4 class="subheading">dane_state_init</h4>
35539 <a name="dane_005fstate_005finit"></a><dl>
35540 <dt><a name="index-dane_005fstate_005finit"></a>Function: <em>int</em> <strong>dane_state_init</strong> <em>(dane_state_t * <var>s</var>, unsigned int <var>flags</var>)</em></dt>
35541 <dd><p><var>s</var>: The structure to be initialized
35542 </p>
35543 <p><var>flags</var>: flags from the <code>dane_state_flags</code>  enumeration
35544 </p>
35545 <p>This function will initialize a DANE query structure.
35546 </p>
35547 <p><strong>Returns:</strong> On success, <code>DANE_E_SUCCESS</code>  (0) is returned, otherwise a
35548 negative error value.
35549 </p></dd></dl>
35550
35551 <a name="dane_005fstate_005fset_005fdlv_005ffile-1"></a>
35552 <h4 class="subheading">dane_state_set_dlv_file</h4>
35553 <a name="dane_005fstate_005fset_005fdlv_005ffile"></a><dl>
35554 <dt><a name="index-dane_005fstate_005fset_005fdlv_005ffile"></a>Function: <em>int</em> <strong>dane_state_set_dlv_file</strong> <em>(dane_state_t <var>s</var>, const char * <var>file</var>)</em></dt>
35555 <dd><p><var>s</var>: The structure to be deinitialized
35556 </p>
35557 <p><var>file</var>: The file holding the DLV keys.
35558 </p>
35559 <p>This function will set a file with trusted keys
35560 for DLV  (DNSSEC  Lookaside  Validation).
35561 </p></dd></dl>
35562
35563 <a name="dane_005fstrerror-1"></a>
35564 <h4 class="subheading">dane_strerror</h4>
35565 <a name="dane_005fstrerror"></a><dl>
35566 <dt><a name="index-dane_005fstrerror"></a>Function: <em>const char *</em> <strong>dane_strerror</strong> <em>(int <var>error</var>)</em></dt>
35567 <dd><p><var>error</var>: is a DANE error code, a negative error code
35568 </p>
35569 <p>This function is similar to strerror.  The difference is that it
35570 accepts an error number returned by a gnutls function; In case of
35571 an unknown error a descriptive string is sent instead of <code>NULL</code> .
35572 </p>
35573 <p>Error codes are always a negative error code.
35574 </p>
35575 <p><strong>Returns:</strong> A string explaining the DANE error message.
35576 </p></dd></dl>
35577
35578 <a name="dane_005fverification_005fstatus_005fprint-1"></a>
35579 <h4 class="subheading">dane_verification_status_print</h4>
35580 <a name="dane_005fverification_005fstatus_005fprint"></a><dl>
35581 <dt><a name="index-dane_005fverification_005fstatus_005fprint"></a>Function: <em>int</em> <strong>dane_verification_status_print</strong> <em>(unsigned int <var>status</var>, gnutls_datum_t * <var>out</var>, unsigned int <var>flags</var>)</em></dt>
35582 <dd><p><var>status</var>: The status flags to be printed
35583 </p>
35584 <p><var>out</var>: Newly allocated datum with (0) terminated string.
35585 </p>
35586 <p><var>flags</var>: should be zero
35587 </p>
35588 <p>This function will pretty print the status of a verification
35589 process &ndash; eg. the one obtained by <code>dane_verify_crt()</code> .
35590 </p>
35591 <p>The output  <code>out</code> needs to be deallocated using <code>gnutls_free()</code> .
35592 </p>
35593 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
35594 negative error value.
35595 </p></dd></dl>
35596
35597 <a name="dane_005fverify_005fcrt-1"></a>
35598 <h4 class="subheading">dane_verify_crt</h4>
35599 <a name="dane_005fverify_005fcrt"></a><dl>
35600 <dt><a name="index-dane_005fverify_005fcrt-1"></a>Function: <em>int</em> <strong>dane_verify_crt</strong> <em>(dane_state_t <var>s</var>, const gnutls_datum_t * <var>chain</var>, unsigned <var>chain_size</var>, gnutls_certificate_type_t <var>chain_type</var>, const char * <var>hostname</var>, const char * <var>proto</var>, unsigned int <var>port</var>, unsigned int <var>sflags</var>, unsigned int <var>vflags</var>, unsigned int * <var>verify</var>)</em></dt>
35601 <dd><p><var>s</var>: A DANE state structure (may be NULL)
35602 </p>
35603 <p><var>chain</var>: A certificate chain
35604 </p>
35605 <p><var>chain_size</var>: The size of the chain
35606 </p>
35607 <p><var>chain_type</var>: The type of the certificate chain
35608 </p>
35609 <p><var>hostname</var>: The hostname associated with the chain
35610 </p>
35611 <p><var>proto</var>: The protocol of the service connecting (e.g. tcp)
35612 </p>
35613 <p><var>port</var>: The port of the service connecting (e.g. 443)
35614 </p>
35615 <p><var>sflags</var>: Flags for the the initialization of  <code>s</code> (if NULL)
35616 </p>
35617 <p><var>vflags</var>: Verification flags; an OR&rsquo;ed list of <code>dane_verify_flags_t</code> .
35618 </p>
35619 <p><var>verify</var>: An OR&rsquo;ed list of <code>dane_verify_status_t</code> .
35620 </p>
35621 <p>This function will verify the given certificate chain against the
35622 CA constrains and/or the certificate available via DANE.
35623 If no information via DANE can be obtained the flag <code>DANE_VERIFY_NO_DANE_INFO</code>
35624 is set. If a DNSSEC signature is not available for the DANE
35625 record then the verify flag <code>DANE_VERIFY_NO_DNSSEC_DATA</code>  is set.
35626 </p>
35627 <p>Due to the many possible options of DANE, there is no single threat
35628 model countered. When notifying the user about DANE verification results
35629 it may be better to mention: DANE verification did not reject the certificate,
35630 rather than mentioning a successful DANE verication.
35631 </p>
35632 <p>Note that this function is designed to be run in addition to
35633 PKIX - certificate chain - verification. To be run independently
35634 the <code>DANE_VFLAG_ONLY_CHECK_EE_USAGE</code>  flag should be specified;
35635 then the function will check whether the key of the peer matches the
35636 key advertized in the DANE entry.
35637 </p>
35638 <p><strong>Returns:</strong> a negative error code on error and <code>DANE_E_SUCCESS</code>  (0)
35639 when the DANE entries were successfully parsed, irrespective of
35640 whether they were verified (see  <code>verify</code> for that information). If
35641 no usable entries were encountered <code>DANE_E_REQUESTED_DATA_NOT_AVAILABLE</code>
35642 will be returned.
35643 </p></dd></dl>
35644
35645 <a name="dane_005fverify_005fcrt_005fraw-1"></a>
35646 <h4 class="subheading">dane_verify_crt_raw</h4>
35647 <a name="dane_005fverify_005fcrt_005fraw"></a><dl>
35648 <dt><a name="index-dane_005fverify_005fcrt_005fraw"></a>Function: <em>int</em> <strong>dane_verify_crt_raw</strong> <em>(dane_state_t <var>s</var>, const gnutls_datum_t * <var>chain</var>, unsigned <var>chain_size</var>, gnutls_certificate_type_t <var>chain_type</var>, dane_query_t <var>r</var>, unsigned int <var>sflags</var>, unsigned int <var>vflags</var>, unsigned int * <var>verify</var>)</em></dt>
35649 <dd><p><var>s</var>: A DANE state structure (may be NULL)
35650 </p>
35651 <p><var>chain</var>: A certificate chain
35652 </p>
35653 <p><var>chain_size</var>: The size of the chain
35654 </p>
35655 <p><var>chain_type</var>: The type of the certificate chain
35656 </p>
35657 <p><var>r</var>: DANE data to check against
35658 </p>
35659 <p><var>sflags</var>: Flags for the the initialization of  <code>s</code> (if NULL)
35660 </p>
35661 <p><var>vflags</var>: Verification flags; an OR&rsquo;ed list of <code>dane_verify_flags_t</code> .
35662 </p>
35663 <p><var>verify</var>: An OR&rsquo;ed list of <code>dane_verify_status_t</code> .
35664 </p>
35665 <p>This function will verify the given certificate chain against the
35666 CA constrains and/or the certificate available via DANE.
35667 If no information via DANE can be obtained the flag <code>DANE_VERIFY_NO_DANE_INFO</code>
35668 is set. If a DNSSEC signature is not available for the DANE
35669 record then the verify flag <code>DANE_VERIFY_NO_DNSSEC_DATA</code>  is set.
35670 </p>
35671 <p>Due to the many possible options of DANE, there is no single threat
35672 model countered. When notifying the user about DANE verification results
35673 it may be better to mention: DANE verification did not reject the certificate,
35674 rather than mentioning a successful DANE verication.
35675 </p>
35676 <p>Note that this function is designed to be run in addition to
35677 PKIX - certificate chain - verification. To be run independently
35678 the <code>DANE_VFLAG_ONLY_CHECK_EE_USAGE</code>  flag should be specified;
35679 then the function will check whether the key of the peer matches the
35680 key advertized in the DANE entry.
35681 </p>
35682 <p>If the  <code>q</code> parameter is provided it will be used for caching entries.
35683 </p>
35684 <p><strong>Returns:</strong> a negative error code on error and <code>DANE_E_SUCCESS</code>  (0)
35685 when the DANE entries were successfully parsed, irrespective of
35686 whether they were verified (see  <code>verify</code> for that information). If
35687 no usable entries were encountered <code>DANE_E_REQUESTED_DATA_NOT_AVAILABLE</code>
35688 will be returned.
35689 </p></dd></dl>
35690
35691 <a name="dane_005fverify_005fsession_005fcrt-1"></a>
35692 <h4 class="subheading">dane_verify_session_crt</h4>
35693 <a name="dane_005fverify_005fsession_005fcrt"></a><dl>
35694 <dt><a name="index-dane_005fverify_005fsession_005fcrt"></a>Function: <em>int</em> <strong>dane_verify_session_crt</strong> <em>(dane_state_t <var>s</var>, gnutls_session_t <var>session</var>, const char * <var>hostname</var>, const char * <var>proto</var>, unsigned int <var>port</var>, unsigned int <var>sflags</var>, unsigned int <var>vflags</var>, unsigned int * <var>verify</var>)</em></dt>
35695 <dd><p><var>s</var>: A DANE state structure (may be NULL)
35696 </p>
35697 <p><var>session</var>: A gnutls session
35698 </p>
35699 <p><var>hostname</var>: The hostname associated with the chain
35700 </p>
35701 <p><var>proto</var>: The protocol of the service connecting (e.g. tcp)
35702 </p>
35703 <p><var>port</var>: The port of the service connecting (e.g. 443)
35704 </p>
35705 <p><var>sflags</var>: Flags for the the initialization of  <code>s</code> (if NULL)
35706 </p>
35707 <p><var>vflags</var>: Verification flags; an OR&rsquo;ed list of <code>dane_verify_flags_t</code> .
35708 </p>
35709 <p><var>verify</var>: An OR&rsquo;ed list of <code>dane_verify_status_t</code> .
35710 </p>
35711 <p>This function will verify session&rsquo;s certificate chain against the
35712 CA constrains and/or the certificate available via DANE.
35713 See <code>dane_verify_crt()</code>  for more information.
35714 </p>
35715 <p>This will not verify the chain for validity; unless the DANE
35716 verification is restricted to end certificates, this must be
35717 be performed separately using <code>gnutls_certificate_verify_peers3()</code> .
35718 </p>
35719 <p><strong>Returns:</strong> a negative error code on error and <code>DANE_E_SUCCESS</code>  (0)
35720 when the DANE entries were successfully parsed, irrespective of
35721 whether they were verified (see  <code>verify</code> for that information). If
35722 no usable entries were encountered <code>DANE_E_REQUESTED_DATA_NOT_AVAILABLE</code>
35723 will be returned.
35724 </p></dd></dl>
35725
35726
35727 <hr>
35728 <a name="Cryptographic-API"></a>
35729 <div class="header">
35730 <p>
35731 Next: <a href="#Compatibility-API" accesskey="n" rel="next">Compatibility API</a>, Previous: <a href="#DANE-API" accesskey="p" rel="prev">DANE API</a>, Up: <a href="#API-reference" accesskey="u" rel="up">API reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
35732 </div>
35733 <a name="Cryptographic-API-1"></a>
35734 <h3 class="section">E.11 Cryptographic API</h3>
35735
35736 <p>The following functions are to be used for low-level cryptographic operations.
35737 Their prototypes lie in <samp>gnutls/crypto.h</samp>.
35738 </p>
35739
35740 <a name="gnutls_005fcipher_005fadd_005fauth-1"></a>
35741 <h4 class="subheading">gnutls_cipher_add_auth</h4>
35742 <a name="gnutls_005fcipher_005fadd_005fauth"></a><dl>
35743 <dt><a name="index-gnutls_005fcipher_005fadd_005fauth"></a>Function: <em>int</em> <strong>gnutls_cipher_add_auth</strong> <em>(gnutls_cipher_hd_t <var>handle</var>, const void * <var>text</var>, size_t <var>text_size</var>)</em></dt>
35744 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code>  structure.
35745 </p>
35746 <p><var>text</var>: the data to be authenticated
35747 </p>
35748 <p><var>text_size</var>: The length of the data
35749 </p>
35750 <p>This function operates on authenticated encryption with
35751 associated data (AEAD) ciphers and authenticate the
35752 input data. This function can only be called once
35753 and before any encryption operations.
35754 </p>
35755 <p><strong>Returns:</strong> Zero or a negative error code on error.
35756 </p>
35757 <p><strong>Since:</strong> 3.0
35758 </p></dd></dl>
35759
35760 <a name="gnutls_005fcipher_005fdecrypt-1"></a>
35761 <h4 class="subheading">gnutls_cipher_decrypt</h4>
35762 <a name="gnutls_005fcipher_005fdecrypt"></a><dl>
35763 <dt><a name="index-gnutls_005fcipher_005fdecrypt"></a>Function: <em>int</em> <strong>gnutls_cipher_decrypt</strong> <em>(gnutls_cipher_hd_t <var>handle</var>, void * <var>ciphertext</var>, size_t <var>ciphertextlen</var>)</em></dt>
35764 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code>  structure.
35765 </p>
35766 <p><var>ciphertext</var>: the data to encrypt
35767 </p>
35768 <p><var>ciphertextlen</var>: The length of data to encrypt
35769 </p>
35770 <p>This function will decrypt the given data using the algorithm
35771 specified by the context.
35772 </p>
35773 <p>Note that in AEAD ciphers, this will not check the tag. You will
35774 need to compare the tag sent with the value returned from <code>gnutls_cipher_tag()</code> .
35775 </p>
35776 <p><strong>Returns:</strong> Zero or a negative error code on error.
35777 </p>
35778 <p><strong>Since:</strong> 2.10.0
35779 </p></dd></dl>
35780
35781 <a name="gnutls_005fcipher_005fdecrypt2-1"></a>
35782 <h4 class="subheading">gnutls_cipher_decrypt2</h4>
35783 <a name="gnutls_005fcipher_005fdecrypt2"></a><dl>
35784 <dt><a name="index-gnutls_005fcipher_005fdecrypt2"></a>Function: <em>int</em> <strong>gnutls_cipher_decrypt2</strong> <em>(gnutls_cipher_hd_t <var>handle</var>, const void * <var>ciphertext</var>, size_t <var>ciphertextlen</var>, void * <var>text</var>, size_t <var>textlen</var>)</em></dt>
35785 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code>  structure.
35786 </p>
35787 <p><var>ciphertext</var>: the data to encrypt
35788 </p>
35789 <p><var>ciphertextlen</var>: The length of data to encrypt
35790 </p>
35791 <p><var>text</var>: the decrypted data
35792 </p>
35793 <p><var>textlen</var>: The available length for decrypted data
35794 </p>
35795 <p>This function will decrypt the given data using the algorithm
35796 specified by the context.
35797 </p>
35798 <p>Note that in AEAD ciphers, this will not check the tag. You will
35799 need to compare the tag sent with the value returned from <code>gnutls_cipher_tag()</code> .
35800 </p>
35801 <p><strong>Returns:</strong> Zero or a negative error code on error.
35802 </p>
35803 <p><strong>Since:</strong> 2.12.0
35804 </p></dd></dl>
35805
35806 <a name="gnutls_005fcipher_005fdeinit-1"></a>
35807 <h4 class="subheading">gnutls_cipher_deinit</h4>
35808 <a name="gnutls_005fcipher_005fdeinit"></a><dl>
35809 <dt><a name="index-gnutls_005fcipher_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_cipher_deinit</strong> <em>(gnutls_cipher_hd_t <var>handle</var>)</em></dt>
35810 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code>  structure.
35811 </p>
35812 <p>This function will deinitialize all resources occupied by the given
35813 encryption context.
35814 </p>
35815 <p><strong>Since:</strong> 2.10.0
35816 </p></dd></dl>
35817
35818 <a name="gnutls_005fcipher_005fencrypt-1"></a>
35819 <h4 class="subheading">gnutls_cipher_encrypt</h4>
35820 <a name="gnutls_005fcipher_005fencrypt"></a><dl>
35821 <dt><a name="index-gnutls_005fcipher_005fencrypt"></a>Function: <em>int</em> <strong>gnutls_cipher_encrypt</strong> <em>(gnutls_cipher_hd_t <var>handle</var>, void * <var>text</var>, size_t <var>textlen</var>)</em></dt>
35822 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code>  structure.
35823 </p>
35824 <p><var>text</var>: the data to encrypt
35825 </p>
35826 <p><var>textlen</var>: The length of data to encrypt
35827 </p>
35828 <p>This function will encrypt the given data using the algorithm
35829 specified by the context.
35830 </p>
35831 <p><strong>Returns:</strong> Zero or a negative error code on error.
35832 </p>
35833 <p><strong>Since:</strong> 2.10.0
35834 </p></dd></dl>
35835
35836 <a name="gnutls_005fcipher_005fencrypt2-1"></a>
35837 <h4 class="subheading">gnutls_cipher_encrypt2</h4>
35838 <a name="gnutls_005fcipher_005fencrypt2"></a><dl>
35839 <dt><a name="index-gnutls_005fcipher_005fencrypt2"></a>Function: <em>int</em> <strong>gnutls_cipher_encrypt2</strong> <em>(gnutls_cipher_hd_t <var>handle</var>, const void * <var>text</var>, size_t <var>textlen</var>, void * <var>ciphertext</var>, size_t <var>ciphertextlen</var>)</em></dt>
35840 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code>  structure.
35841 </p>
35842 <p><var>text</var>: the data to encrypt
35843 </p>
35844 <p><var>textlen</var>: The length of data to encrypt
35845 </p>
35846 <p><var>ciphertext</var>: the encrypted data
35847 </p>
35848 <p><var>ciphertextlen</var>: The available length for encrypted data
35849 </p>
35850 <p>This function will encrypt the given data using the algorithm
35851 specified by the context.
35852 </p>
35853 <p><strong>Returns:</strong> Zero or a negative error code on error.
35854 </p>
35855 <p><strong>Since:</strong> 2.12.0
35856 </p></dd></dl>
35857
35858 <a name="gnutls_005fcipher_005fget_005fblock_005fsize-1"></a>
35859 <h4 class="subheading">gnutls_cipher_get_block_size</h4>
35860 <a name="gnutls_005fcipher_005fget_005fblock_005fsize"></a><dl>
35861 <dt><a name="index-gnutls_005fcipher_005fget_005fblock_005fsize"></a>Function: <em>int</em> <strong>gnutls_cipher_get_block_size</strong> <em>(gnutls_cipher_algorithm_t <var>algorithm</var>)</em></dt>
35862 <dd><p><var>algorithm</var>: is an encryption algorithm
35863 </p>
35864
35865 <p><strong>Returns:</strong> the block size of the encryption algorithm.
35866 </p>
35867 <p><strong>Since:</strong> 2.10.0
35868 </p></dd></dl>
35869
35870 <a name="gnutls_005fcipher_005fget_005fiv_005fsize-1"></a>
35871 <h4 class="subheading">gnutls_cipher_get_iv_size</h4>
35872 <a name="gnutls_005fcipher_005fget_005fiv_005fsize"></a><dl>
35873 <dt><a name="index-gnutls_005fcipher_005fget_005fiv_005fsize"></a>Function: <em>int</em> <strong>gnutls_cipher_get_iv_size</strong> <em>(gnutls_cipher_algorithm_t <var>algorithm</var>)</em></dt>
35874 <dd><p><var>algorithm</var>: is an encryption algorithm
35875 </p>
35876 <p>Get block size for encryption algorithm.
35877 </p>
35878 <p><strong>Returns:</strong> block size for encryption algorithm.
35879 </p>
35880 <p><strong>Since:</strong> 3.2.0
35881 </p></dd></dl>
35882
35883 <a name="gnutls_005fcipher_005fget_005ftag_005fsize-1"></a>
35884 <h4 class="subheading">gnutls_cipher_get_tag_size</h4>
35885 <a name="gnutls_005fcipher_005fget_005ftag_005fsize"></a><dl>
35886 <dt><a name="index-gnutls_005fcipher_005fget_005ftag_005fsize"></a>Function: <em>int</em> <strong>gnutls_cipher_get_tag_size</strong> <em>(gnutls_cipher_algorithm_t <var>algorithm</var>)</em></dt>
35887 <dd><p><var>algorithm</var>: is an encryption algorithm
35888 </p>
35889
35890 <p><strong>Returns:</strong> the tag size of the authenticated encryption algorithm.
35891 </p>
35892 <p><strong>Since:</strong> 3.2.2
35893 </p></dd></dl>
35894
35895 <a name="gnutls_005fcipher_005finit-1"></a>
35896 <h4 class="subheading">gnutls_cipher_init</h4>
35897 <a name="gnutls_005fcipher_005finit"></a><dl>
35898 <dt><a name="index-gnutls_005fcipher_005finit"></a>Function: <em>int</em> <strong>gnutls_cipher_init</strong> <em>(gnutls_cipher_hd_t * <var>handle</var>, gnutls_cipher_algorithm_t <var>cipher</var>, const gnutls_datum_t * <var>key</var>, const gnutls_datum_t * <var>iv</var>)</em></dt>
35899 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code>  structure.
35900 </p>
35901 <p><var>cipher</var>: the encryption algorithm to use
35902 </p>
35903 <p><var>key</var>: The key to be used for encryption
35904 </p>
35905 <p><var>iv</var>: The IV to use (if not applicable set NULL)
35906 </p>
35907 <p>This function will initialize an context that can be used for
35908 encryption/decryption of data. This will effectively use the
35909 current crypto backend in use by gnutls or the cryptographic
35910 accelerator in use.
35911 </p>
35912 <p><strong>Returns:</strong> Zero or a negative error code on error.
35913 </p>
35914 <p><strong>Since:</strong> 2.10.0
35915 </p></dd></dl>
35916
35917 <a name="gnutls_005fcipher_005fset_005fiv-1"></a>
35918 <h4 class="subheading">gnutls_cipher_set_iv</h4>
35919 <a name="gnutls_005fcipher_005fset_005fiv"></a><dl>
35920 <dt><a name="index-gnutls_005fcipher_005fset_005fiv"></a>Function: <em>void</em> <strong>gnutls_cipher_set_iv</strong> <em>(gnutls_cipher_hd_t <var>handle</var>, void * <var>iv</var>, size_t <var>ivlen</var>)</em></dt>
35921 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code>  structure.
35922 </p>
35923 <p><var>iv</var>: the IV to set
35924 </p>
35925 <p><var>ivlen</var>: The length of the IV
35926 </p>
35927 <p>This function will set the IV to be used for the next
35928 encryption block.
35929 </p>
35930 <p><strong>Since:</strong> 3.0
35931 </p></dd></dl>
35932
35933 <a name="gnutls_005fcipher_005ftag-1"></a>
35934 <h4 class="subheading">gnutls_cipher_tag</h4>
35935 <a name="gnutls_005fcipher_005ftag"></a><dl>
35936 <dt><a name="index-gnutls_005fcipher_005ftag"></a>Function: <em>int</em> <strong>gnutls_cipher_tag</strong> <em>(gnutls_cipher_hd_t <var>handle</var>, void * <var>tag</var>, size_t <var>tag_size</var>)</em></dt>
35937 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code>  structure.
35938 </p>
35939 <p><var>tag</var>: will hold the tag
35940 </p>
35941 <p><var>tag_size</var>: The length of the tag to return
35942 </p>
35943 <p>This function operates on authenticated encryption with
35944 associated data (AEAD) ciphers and will return the
35945 output tag.
35946 </p>
35947 <p><strong>Returns:</strong> Zero or a negative error code on error.
35948 </p>
35949 <p><strong>Since:</strong> 3.0
35950 </p></dd></dl>
35951
35952 <a name="gnutls_005fhash-1"></a>
35953 <h4 class="subheading">gnutls_hash</h4>
35954 <a name="gnutls_005fhash"></a><dl>
35955 <dt><a name="index-gnutls_005fhash"></a>Function: <em>int</em> <strong>gnutls_hash</strong> <em>(gnutls_hash_hd_t <var>handle</var>, const void * <var>text</var>, size_t <var>textlen</var>)</em></dt>
35956 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code>  structure.
35957 </p>
35958 <p><var>text</var>: the data to hash
35959 </p>
35960 <p><var>textlen</var>: The length of data to hash
35961 </p>
35962 <p>This function will hash the given data using the algorithm
35963 specified by the context.
35964 </p>
35965 <p><strong>Returns:</strong> Zero or a negative error code on error.
35966 </p>
35967 <p><strong>Since:</strong> 2.10.0
35968 </p></dd></dl>
35969
35970 <a name="gnutls_005fhash_005fdeinit-1"></a>
35971 <h4 class="subheading">gnutls_hash_deinit</h4>
35972 <a name="gnutls_005fhash_005fdeinit"></a><dl>
35973 <dt><a name="index-gnutls_005fhash_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_hash_deinit</strong> <em>(gnutls_hash_hd_t <var>handle</var>, void * <var>digest</var>)</em></dt>
35974 <dd><p><var>handle</var>: is a <code>gnutls_hash_hd_t</code>  structure.
35975 </p>
35976 <p><var>digest</var>: is the output value of the hash
35977 </p>
35978 <p>This function will deinitialize all resources occupied by
35979 the given hash context.
35980 </p>
35981 <p><strong>Since:</strong> 2.10.0
35982 </p></dd></dl>
35983
35984 <a name="gnutls_005fhash_005ffast-1"></a>
35985 <h4 class="subheading">gnutls_hash_fast</h4>
35986 <a name="gnutls_005fhash_005ffast"></a><dl>
35987 <dt><a name="index-gnutls_005fhash_005ffast"></a>Function: <em>int</em> <strong>gnutls_hash_fast</strong> <em>(gnutls_digest_algorithm_t <var>algorithm</var>, const void * <var>text</var>, size_t <var>textlen</var>, void * <var>digest</var>)</em></dt>
35988 <dd><p><var>algorithm</var>: the hash algorithm to use
35989 </p>
35990 <p><var>text</var>: the data to hash
35991 </p>
35992 <p><var>textlen</var>: The length of data to hash
35993 </p>
35994 <p><var>digest</var>: is the output value of the hash
35995 </p>
35996 <p>This convenience function will hash the given data and return output
35997 on a single call.
35998 </p>
35999 <p><strong>Returns:</strong> Zero or a negative error code on error.
36000 </p>
36001 <p><strong>Since:</strong> 2.10.0
36002 </p></dd></dl>
36003
36004 <a name="gnutls_005fhash_005fget_005flen-1"></a>
36005 <h4 class="subheading">gnutls_hash_get_len</h4>
36006 <a name="gnutls_005fhash_005fget_005flen"></a><dl>
36007 <dt><a name="index-gnutls_005fhash_005fget_005flen"></a>Function: <em>int</em> <strong>gnutls_hash_get_len</strong> <em>(gnutls_digest_algorithm_t <var>algorithm</var>)</em></dt>
36008 <dd><p><var>algorithm</var>: the hash algorithm to use
36009 </p>
36010 <p>This function will return the length of the output data
36011 of the given hash algorithm.
36012 </p>
36013 <p><strong>Returns:</strong> The length or zero on error.
36014 </p>
36015 <p><strong>Since:</strong> 2.10.0
36016 </p></dd></dl>
36017
36018 <a name="gnutls_005fhash_005finit-1"></a>
36019 <h4 class="subheading">gnutls_hash_init</h4>
36020 <a name="gnutls_005fhash_005finit"></a><dl>
36021 <dt><a name="index-gnutls_005fhash_005finit"></a>Function: <em>int</em> <strong>gnutls_hash_init</strong> <em>(gnutls_hash_hd_t * <var>dig</var>, gnutls_digest_algorithm_t <var>algorithm</var>)</em></dt>
36022 <dd><p><var>dig</var>: is a <code>gnutls_hash_hd_t</code>  structure.
36023 </p>
36024 <p><var>algorithm</var>: the hash algorithm to use
36025 </p>
36026 <p>This function will initialize an context that can be used to
36027 produce a Message Digest of data.  This will effectively use the
36028 current crypto backend in use by gnutls or the cryptographic
36029 accelerator in use.
36030 </p>
36031 <p><strong>Returns:</strong> Zero or a negative error code on error.
36032 </p>
36033 <p><strong>Since:</strong> 2.10.0
36034 </p></dd></dl>
36035
36036 <a name="gnutls_005fhash_005foutput-1"></a>
36037 <h4 class="subheading">gnutls_hash_output</h4>
36038 <a name="gnutls_005fhash_005foutput"></a><dl>
36039 <dt><a name="index-gnutls_005fhash_005foutput"></a>Function: <em>void</em> <strong>gnutls_hash_output</strong> <em>(gnutls_hash_hd_t <var>handle</var>, void * <var>digest</var>)</em></dt>
36040 <dd><p><var>handle</var>: is a <code>gnutls_hash_hd_t</code>  structure.
36041 </p>
36042 <p><var>digest</var>: is the output value of the hash
36043 </p>
36044 <p>This function will output the current hash value
36045 and reset the state of the hash.
36046 </p>
36047 <p><strong>Since:</strong> 2.10.0
36048 </p></dd></dl>
36049
36050 <a name="gnutls_005fhmac-1"></a>
36051 <h4 class="subheading">gnutls_hmac</h4>
36052 <a name="gnutls_005fhmac"></a><dl>
36053 <dt><a name="index-gnutls_005fhmac"></a>Function: <em>int</em> <strong>gnutls_hmac</strong> <em>(gnutls_hmac_hd_t <var>handle</var>, const void * <var>text</var>, size_t <var>textlen</var>)</em></dt>
36054 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code>  structure.
36055 </p>
36056 <p><var>text</var>: the data to hash
36057 </p>
36058 <p><var>textlen</var>: The length of data to hash
36059 </p>
36060 <p>This function will hash the given data using the algorithm
36061 specified by the context.
36062 </p>
36063 <p><strong>Returns:</strong> Zero or a negative error code on error.
36064 </p>
36065 <p><strong>Since:</strong> 2.10.0
36066 </p></dd></dl>
36067
36068 <a name="gnutls_005fhmac_005fdeinit-1"></a>
36069 <h4 class="subheading">gnutls_hmac_deinit</h4>
36070 <a name="gnutls_005fhmac_005fdeinit"></a><dl>
36071 <dt><a name="index-gnutls_005fhmac_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_hmac_deinit</strong> <em>(gnutls_hmac_hd_t <var>handle</var>, void * <var>digest</var>)</em></dt>
36072 <dd><p><var>handle</var>: is a <code>gnutls_hmac_hd_t</code>  structure.
36073 </p>
36074 <p><var>digest</var>: is the output value of the MAC
36075 </p>
36076 <p>This function will deinitialize all resources occupied by
36077 the given hmac context.
36078 </p>
36079 <p><strong>Since:</strong> 2.10.0
36080 </p></dd></dl>
36081
36082 <a name="gnutls_005fhmac_005ffast-1"></a>
36083 <h4 class="subheading">gnutls_hmac_fast</h4>
36084 <a name="gnutls_005fhmac_005ffast"></a><dl>
36085 <dt><a name="index-gnutls_005fhmac_005ffast"></a>Function: <em>int</em> <strong>gnutls_hmac_fast</strong> <em>(gnutls_mac_algorithm_t <var>algorithm</var>, const void * <var>key</var>, size_t <var>keylen</var>, const void * <var>text</var>, size_t <var>textlen</var>, void * <var>digest</var>)</em></dt>
36086 <dd><p><var>algorithm</var>: the hash algorithm to use
36087 </p>
36088 <p><var>key</var>: the key to use
36089 </p>
36090 <p><var>keylen</var>: The length of the key
36091 </p>
36092 <p><var>text</var>: the data to hash
36093 </p>
36094 <p><var>textlen</var>: The length of data to hash
36095 </p>
36096 <p><var>digest</var>: is the output value of the hash
36097 </p>
36098 <p>This convenience function will hash the given data and return output
36099 on a single call.
36100 </p>
36101 <p><strong>Returns:</strong> Zero or a negative error code on error.
36102 </p>
36103 <p><strong>Since:</strong> 2.10.0
36104 </p></dd></dl>
36105
36106 <a name="gnutls_005fhmac_005fget_005flen-1"></a>
36107 <h4 class="subheading">gnutls_hmac_get_len</h4>
36108 <a name="gnutls_005fhmac_005fget_005flen"></a><dl>
36109 <dt><a name="index-gnutls_005fhmac_005fget_005flen"></a>Function: <em>int</em> <strong>gnutls_hmac_get_len</strong> <em>(gnutls_mac_algorithm_t <var>algorithm</var>)</em></dt>
36110 <dd><p><var>algorithm</var>: the hmac algorithm to use
36111 </p>
36112 <p>This function will return the length of the output data
36113 of the given hmac algorithm.
36114 </p>
36115 <p><strong>Returns:</strong> The length or zero on error.
36116 </p>
36117 <p><strong>Since:</strong> 2.10.0
36118 </p></dd></dl>
36119
36120 <a name="gnutls_005fhmac_005finit-1"></a>
36121 <h4 class="subheading">gnutls_hmac_init</h4>
36122 <a name="gnutls_005fhmac_005finit"></a><dl>
36123 <dt><a name="index-gnutls_005fhmac_005finit"></a>Function: <em>int</em> <strong>gnutls_hmac_init</strong> <em>(gnutls_hmac_hd_t * <var>dig</var>, gnutls_mac_algorithm_t <var>algorithm</var>, const void * <var>key</var>, size_t <var>keylen</var>)</em></dt>
36124 <dd><p><var>dig</var>: is a <code>gnutls_hmac_hd_t</code>  structure.
36125 </p>
36126 <p><var>algorithm</var>: the HMAC algorithm to use
36127 </p>
36128 <p><var>key</var>: The key to be used for encryption
36129 </p>
36130 <p><var>keylen</var>: The length of the key
36131 </p>
36132 <p>This function will initialize an context that can be used to
36133 produce a Message Authentication Code (MAC) of data.  This will
36134 effectively use the current crypto backend in use by gnutls or the
36135 cryptographic accelerator in use.
36136 </p>
36137 <p>Note that despite the name of this function, it can be used
36138 for other MAC algorithms than HMAC.
36139 </p>
36140 <p><strong>Returns:</strong> Zero or a negative error code on error.
36141 </p>
36142 <p><strong>Since:</strong> 2.10.0
36143 </p></dd></dl>
36144
36145 <a name="gnutls_005fhmac_005foutput-1"></a>
36146 <h4 class="subheading">gnutls_hmac_output</h4>
36147 <a name="gnutls_005fhmac_005foutput"></a><dl>
36148 <dt><a name="index-gnutls_005fhmac_005foutput"></a>Function: <em>void</em> <strong>gnutls_hmac_output</strong> <em>(gnutls_hmac_hd_t <var>handle</var>, void * <var>digest</var>)</em></dt>
36149 <dd><p><var>handle</var>: is a <code>gnutls_hmac_hd_t</code>  structure.
36150 </p>
36151 <p><var>digest</var>: is the output value of the MAC
36152 </p>
36153 <p>This function will output the current MAC value
36154 and reset the state of the MAC.
36155 </p>
36156 <p><strong>Since:</strong> 2.10.0
36157 </p></dd></dl>
36158
36159 <a name="gnutls_005fhmac_005fset_005fnonce-1"></a>
36160 <h4 class="subheading">gnutls_hmac_set_nonce</h4>
36161 <a name="gnutls_005fhmac_005fset_005fnonce"></a><dl>
36162 <dt><a name="index-gnutls_005fhmac_005fset_005fnonce"></a>Function: <em>void</em> <strong>gnutls_hmac_set_nonce</strong> <em>(gnutls_hmac_hd_t <var>handle</var>, const void * <var>nonce</var>, size_t <var>nonce_len</var>)</em></dt>
36163 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code>  structure.
36164 </p>
36165 <p><var>nonce</var>: the data to set as nonce
36166 </p>
36167 <p><var>nonce_len</var>: The length of data
36168 </p>
36169 <p>This function will set the nonce in the MAC algorithm.
36170 </p>
36171 <p><strong>Since:</strong> 3.2.0
36172 </p></dd></dl>
36173
36174 <a name="gnutls_005fmac_005fget_005fnonce_005fsize-1"></a>
36175 <h4 class="subheading">gnutls_mac_get_nonce_size</h4>
36176 <a name="gnutls_005fmac_005fget_005fnonce_005fsize"></a><dl>
36177 <dt><a name="index-gnutls_005fmac_005fget_005fnonce_005fsize"></a>Function: <em>size_t</em> <strong>gnutls_mac_get_nonce_size</strong> <em>(gnutls_mac_algorithm_t <var>algorithm</var>)</em></dt>
36178 <dd><p><var>algorithm</var>: is an encryption algorithm
36179 </p>
36180 <p>Returns the size of the nonce used by the MAC in TLS.
36181 </p>
36182 <p><strong>Returns:</strong> length (in bytes) of the given MAC nonce size, or 0.
36183 </p>
36184 <p><strong>Since:</strong> 3.2.0
36185 </p></dd></dl>
36186
36187 <a name="gnutls_005frnd-1"></a>
36188 <h4 class="subheading">gnutls_rnd</h4>
36189 <a name="gnutls_005frnd"></a><dl>
36190 <dt><a name="index-gnutls_005frnd-1"></a>Function: <em>int</em> <strong>gnutls_rnd</strong> <em>(gnutls_rnd_level_t <var>level</var>, void * <var>data</var>, size_t <var>len</var>)</em></dt>
36191 <dd><p><var>level</var>: a security level
36192 </p>
36193 <p><var>data</var>: place to store random bytes
36194 </p>
36195 <p><var>len</var>: The requested size
36196 </p>
36197 <p>This function will generate random data and store it to output
36198 buffer.
36199 </p>
36200 <p>This function is thread-safe and also fork-safe.
36201 </p>
36202 <p><strong>Returns:</strong> Zero on success, or a negative error code on error.
36203 </p>
36204 <p><strong>Since:</strong> 2.12.0
36205 </p></dd></dl>
36206
36207 <a name="gnutls_005frnd_005frefresh-1"></a>
36208 <h4 class="subheading">gnutls_rnd_refresh</h4>
36209 <a name="gnutls_005frnd_005frefresh"></a><dl>
36210 <dt><a name="index-gnutls_005frnd_005frefresh"></a>Function: <em>void</em> <strong>gnutls_rnd_refresh</strong> <em>()</em></dt>
36211 <dd>
36212 <p>This function refreshes the random generator state.
36213 That is the current precise time, CPU usage, and
36214 other values are input into its state.
36215 </p>
36216 <p>On a slower rate input from /dev/urandom is mixed too.
36217 </p>
36218 <p><strong>Since:</strong> 3.1.7
36219 </p></dd></dl>
36220
36221
36222 <hr>
36223 <a name="Compatibility-API"></a>
36224 <div class="header">
36225 <p>
36226 Previous: <a href="#Cryptographic-API" accesskey="p" rel="prev">Cryptographic API</a>, Up: <a href="#API-reference" accesskey="u" rel="up">API reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
36227 </div>
36228 <a name="Compatibility-API-1"></a>
36229 <h3 class="section">E.12 Compatibility API</h3>
36230
36231 <p>The following functions are carried over from old GnuTLS released. They might be removed at a later version.
36232 Their prototypes lie in <samp>gnutls/compat.h</samp>.
36233 </p>
36234
36235 <a name="gnutls_005fcertificate_005fclient_005fset_005fretrieve_005ffunction-1"></a>
36236 <h4 class="subheading">gnutls_certificate_client_set_retrieve_function</h4>
36237 <a name="gnutls_005fcertificate_005fclient_005fset_005fretrieve_005ffunction"></a><dl>
36238 <dt><a name="index-gnutls_005fcertificate_005fclient_005fset_005fretrieve_005ffunction"></a>Function: <em>void</em> <strong>gnutls_certificate_client_set_retrieve_function</strong> <em>(gnutls_certificate_credentials_t <var>cred</var>, gnutls_certificate_client_retrieve_function * <var>func</var>)</em></dt>
36239 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
36240 </p>
36241 <p><var>func</var>: is the callback function
36242 </p>
36243 <p>This function sets a callback to be called in order to retrieve the
36244 certificate to be used in the handshake.
36245 You are advised to use <code>gnutls_certificate_set_retrieve_function2()</code>  because it
36246 is much more efficient in the processing it requires from gnutls.
36247 </p>
36248 <p>The callback&rsquo;s function prototype is:
36249 int (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int nreqs,
36250 const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length, gnutls_retr_st* st);
36251 </p>
36252 <p><code>req_ca_cert</code> is only used in X.509 certificates.
36253 Contains a list with the CA names that the server considers trusted.
36254 Normally we should send a certificate that is signed
36255 by one of these CAs. These names are DER encoded. To get a more
36256 meaningful value use the function <code>gnutls_x509_rdn_get()</code> .
36257 </p>
36258 <p><code>pk_algos</code> contains a list with server&rsquo;s acceptable signature algorithms.
36259 The certificate returned should support the server&rsquo;s given algorithms.
36260 </p>
36261 <p><code>st</code> should contain the certificates and private keys.
36262 </p>
36263 <p>If the callback function is provided then gnutls will call it, in the
36264 handshake, if a certificate is requested by the server (and after the
36265 certificate request message has been received).
36266 </p>
36267 <p>The callback function should set the certificate list to be sent,
36268 and return 0 on success. If no certificate was selected then the
36269 number of certificates should be set to zero. The value (-1)
36270 indicates error and the handshake will be terminated.
36271 </p></dd></dl>
36272
36273 <a name="gnutls_005fcertificate_005fserver_005fset_005fretrieve_005ffunction-1"></a>
36274 <h4 class="subheading">gnutls_certificate_server_set_retrieve_function</h4>
36275 <a name="gnutls_005fcertificate_005fserver_005fset_005fretrieve_005ffunction"></a><dl>
36276 <dt><a name="index-gnutls_005fcertificate_005fserver_005fset_005fretrieve_005ffunction"></a>Function: <em>void</em> <strong>gnutls_certificate_server_set_retrieve_function</strong> <em>(gnutls_certificate_credentials_t <var>cred</var>, gnutls_certificate_server_retrieve_function * <var>func</var>)</em></dt>
36277 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code>  structure.
36278 </p>
36279 <p><var>func</var>: is the callback function
36280 </p>
36281 <p>This function sets a callback to be called in order to retrieve the
36282 certificate to be used in the handshake.
36283 You are advised to use <code>gnutls_certificate_set_retrieve_function2()</code>  because it
36284 is much more efficient in the processing it requires from gnutls.
36285 </p>
36286 <p>The callback&rsquo;s function prototype is:
36287 int (*callback)(gnutls_session_t, gnutls_retr_st* st);
36288 </p>
36289 <p><code>st</code> should contain the certificates and private keys.
36290 </p>
36291 <p>If the callback function is provided then gnutls will call it, in the
36292 handshake, after the certificate request message has been received.
36293 </p>
36294 <p>The callback function should set the certificate list to be sent, and
36295 return 0 on success.  The value (-1) indicates error and the handshake
36296 will be terminated.
36297 </p></dd></dl>
36298
36299 <a name="gnutls_005fcertificate_005fset_005frsa_005fexport_005fparams-1"></a>
36300 <h4 class="subheading">gnutls_certificate_set_rsa_export_params</h4>
36301 <a name="gnutls_005fcertificate_005fset_005frsa_005fexport_005fparams"></a><dl>
36302 <dt><a name="index-gnutls_005fcertificate_005fset_005frsa_005fexport_005fparams"></a>Function: <em>void</em> <strong>gnutls_certificate_set_rsa_export_params</strong> <em>(gnutls_certificate_credentials_t       <var>res</var>, gnutls_rsa_params_t <var>rsa_params</var>)</em></dt>
36303 <dd><p><var>res</var>: is a gnutls_certificate_credentials_t structure
36304 </p>
36305 <p><var>rsa_params</var>: is a structure that holds temporary RSA parameters.
36306 </p>
36307 <p>This function will set the temporary RSA parameters for a
36308 certificate server to use.  These parameters will be used in
36309 RSA-EXPORT cipher suites.
36310 </p></dd></dl>
36311
36312 <a name="gnutls_005fcertificate_005ftype_005fset_005fpriority-1"></a>
36313 <h4 class="subheading">gnutls_certificate_type_set_priority</h4>
36314 <a name="gnutls_005fcertificate_005ftype_005fset_005fpriority"></a><dl>
36315 <dt><a name="index-gnutls_005fcertificate_005ftype_005fset_005fpriority"></a>Function: <em>int</em> <strong>gnutls_certificate_type_set_priority</strong> <em>(gnutls_session_t <var>session</var>, const int * <var>list</var>)</em></dt>
36316 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
36317 </p>
36318 <p><var>list</var>: is a 0 terminated list of gnutls_certificate_type_t elements.
36319 </p>
36320 <p>Sets the priority on the certificate types supported by gnutls.
36321 Priority is higher for elements specified before others.
36322 After specifying the types you want, you must append a 0.
36323 Note that the certificate type priority is set on the client.
36324 The server does not use the cert type priority except for disabling
36325 types that were not specified.
36326 </p>
36327 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
36328 </p></dd></dl>
36329
36330 <a name="gnutls_005fcipher_005fset_005fpriority-1"></a>
36331 <h4 class="subheading">gnutls_cipher_set_priority</h4>
36332 <a name="gnutls_005fcipher_005fset_005fpriority"></a><dl>
36333 <dt><a name="index-gnutls_005fcipher_005fset_005fpriority"></a>Function: <em>int</em> <strong>gnutls_cipher_set_priority</strong> <em>(gnutls_session_t <var>session</var>, const int * <var>list</var>)</em></dt>
36334 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
36335 </p>
36336 <p><var>list</var>: is a 0 terminated list of gnutls_cipher_algorithm_t elements.
36337 </p>
36338 <p>Sets the priority on the ciphers supported by gnutls.  Priority is
36339 higher for elements specified before others.  After specifying the
36340 ciphers you want, you must append a 0.  Note that the priority is
36341 set on the client. The server does not use the algorithm&rsquo;s
36342 priority except for disabling algorithms that were not specified.
36343 </p>
36344 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  (0) on success, or a negative error code.
36345 </p></dd></dl>
36346
36347 <a name="gnutls_005fcompression_005fset_005fpriority-1"></a>
36348 <h4 class="subheading">gnutls_compression_set_priority</h4>
36349 <a name="gnutls_005fcompression_005fset_005fpriority"></a><dl>
36350 <dt><a name="index-gnutls_005fcompression_005fset_005fpriority"></a>Function: <em>int</em> <strong>gnutls_compression_set_priority</strong> <em>(gnutls_session_t <var>session</var>, const int * <var>list</var>)</em></dt>
36351 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
36352 </p>
36353 <p><var>list</var>: is a 0 terminated list of gnutls_compression_method_t elements.
36354 </p>
36355 <p>Sets the priority on the compression algorithms supported by
36356 gnutls.  Priority is higher for elements specified before others.
36357 After specifying the algorithms you want, you must append a 0.
36358 Note that the priority is set on the client. The server does not
36359 use the algorithm&rsquo;s priority except for disabling algorithms that
36360 were not specified.
36361 </p>
36362 <p>TLS 1.0 does not define any compression algorithms except
36363 NULL. Other compression algorithms are to be considered as gnutls
36364 extensions.
36365 </p>
36366 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
36367 </p></dd></dl>
36368
36369 <a name="gnutls_005fglobal_005fset_005fmem_005ffunctions-1"></a>
36370 <h4 class="subheading">gnutls_global_set_mem_functions</h4>
36371 <a name="gnutls_005fglobal_005fset_005fmem_005ffunctions"></a><dl>
36372 <dt><a name="index-gnutls_005fglobal_005fset_005fmem_005ffunctions"></a>Function: <em>void</em> <strong>gnutls_global_set_mem_functions</strong> <em>(gnutls_alloc_function <var>alloc_func</var>, gnutls_alloc_function <var>secure_alloc_func</var>, gnutls_is_secure_function <var>is_secure_func</var>, gnutls_realloc_function <var>realloc_func</var>, gnutls_free_function <var>free_func</var>)</em></dt>
36373 <dd><p><var>alloc_func</var>: it&rsquo;s the default memory allocation function. Like <code>malloc()</code> .
36374 </p>
36375 <p><var>secure_alloc_func</var>: This is the memory allocation function that will be used for sensitive data.
36376 </p>
36377 <p><var>is_secure_func</var>: a function that returns 0 if the memory given is not secure. May be NULL.
36378 </p>
36379 <p><var>realloc_func</var>: A realloc function
36380 </p>
36381 <p><var>free_func</var>: The function that frees allocated data. Must accept a NULL pointer.
36382 </p>
36383
36384 <p><strong>Deprecated:</strong> since 3.3.0 it is no longer possible to replace the internally used
36385 memory allocation functions
36386 </p>
36387 <p>This is the function where you set the memory allocation functions
36388 gnutls is going to use. By default the libc&rsquo;s allocation functions
36389 (<code>malloc()</code> , <code>free()</code> ), are used by gnutls, to allocate both sensitive
36390 and not sensitive data.  This function is provided to set the
36391 memory allocation functions to something other than the defaults
36392 </p>
36393 <p>This function must be called before <code>gnutls_global_init()</code>  is called.
36394 This function is not thread safe.
36395 </p></dd></dl>
36396
36397 <a name="gnutls_005fkx_005fset_005fpriority-1"></a>
36398 <h4 class="subheading">gnutls_kx_set_priority</h4>
36399 <a name="gnutls_005fkx_005fset_005fpriority"></a><dl>
36400 <dt><a name="index-gnutls_005fkx_005fset_005fpriority"></a>Function: <em>int</em> <strong>gnutls_kx_set_priority</strong> <em>(gnutls_session_t <var>session</var>, const int * <var>list</var>)</em></dt>
36401 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
36402 </p>
36403 <p><var>list</var>: is a 0 terminated list of gnutls_kx_algorithm_t elements.
36404 </p>
36405 <p>Sets the priority on the key exchange algorithms supported by
36406 gnutls.  Priority is higher for elements specified before others.
36407 After specifying the algorithms you want, you must append a 0.
36408 Note that the priority is set on the client. The server does not
36409 use the algorithm&rsquo;s priority except for disabling algorithms that
36410 were not specified.
36411 </p>
36412 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
36413 </p></dd></dl>
36414
36415 <a name="gnutls_005fmac_005fset_005fpriority-1"></a>
36416 <h4 class="subheading">gnutls_mac_set_priority</h4>
36417 <a name="gnutls_005fmac_005fset_005fpriority"></a><dl>
36418 <dt><a name="index-gnutls_005fmac_005fset_005fpriority"></a>Function: <em>int</em> <strong>gnutls_mac_set_priority</strong> <em>(gnutls_session_t <var>session</var>, const int * <var>list</var>)</em></dt>
36419 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
36420 </p>
36421 <p><var>list</var>: is a 0 terminated list of gnutls_mac_algorithm_t elements.
36422 </p>
36423 <p>Sets the priority on the mac algorithms supported by gnutls.
36424 Priority is higher for elements specified before others.  After
36425 specifying the algorithms you want, you must append a 0.  Note
36426 that the priority is set on the client. The server does not use
36427 the algorithm&rsquo;s priority except for disabling algorithms that were
36428 not specified.
36429 </p>
36430 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
36431 </p></dd></dl>
36432
36433 <a name="gnutls_005fopenpgp_005fprivkey_005fsign_005fhash-1"></a>
36434 <h4 class="subheading">gnutls_openpgp_privkey_sign_hash</h4>
36435 <a name="gnutls_005fopenpgp_005fprivkey_005fsign_005fhash"></a><dl>
36436 <dt><a name="index-gnutls_005fopenpgp_005fprivkey_005fsign_005fhash"></a>Function: <em>int</em> <strong>gnutls_openpgp_privkey_sign_hash</strong> <em>(gnutls_openpgp_privkey_t <var>key</var>, const gnutls_datum_t * <var>hash</var>, gnutls_datum_t * <var>signature</var>)</em></dt>
36437 <dd><p><var>key</var>: Holds the key
36438 </p>
36439 <p><var>hash</var>: holds the data to be signed
36440 </p>
36441 <p><var>signature</var>: will contain newly allocated signature
36442 </p>
36443 <p>This function will sign the given hash using the private key.  You
36444 should use <code>gnutls_openpgp_privkey_set_preferred_key_id()</code>  before
36445 calling this function to set the subkey to use.
36446 </p>
36447 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
36448 negative error value.
36449 </p>
36450 <p><strong>Deprecated:</strong> Use <code>gnutls_privkey_sign_hash()</code>  instead.
36451 </p></dd></dl>
36452
36453 <a name="gnutls_005fprivkey_005fsign_005fraw_005fdata-1"></a>
36454 <h4 class="subheading">gnutls_privkey_sign_raw_data</h4>
36455 <a name="gnutls_005fprivkey_005fsign_005fraw_005fdata"></a><dl>
36456 <dt><a name="index-gnutls_005fprivkey_005fsign_005fraw_005fdata"></a>Function: <em>int</em> <strong>gnutls_privkey_sign_raw_data</strong> <em>(gnutls_privkey_t <var>key</var>, unsigned <var>flags</var>, const gnutls_datum_t * <var>data</var>, gnutls_datum_t * <var>signature</var>)</em></dt>
36457 <dd><p><var>key</var>: Holds the key
36458 </p>
36459 <p><var>flags</var>: should be zero
36460 </p>
36461 <p><var>data</var>: holds the data to be signed
36462 </p>
36463 <p><var>signature</var>: will contain the signature allocate with <code>gnutls_malloc()</code>
36464 </p>
36465 <p>This function will sign the given data using a signature algorithm
36466 supported by the private key. Note that this is a low-level function
36467 and does not apply any preprocessing or hash on the signed data.
36468 For example on an RSA key the input  <code>data</code> should be of the DigestInfo
36469 PKCS <code>1</code>  1.5 format. Use it only if you know what are you doing.
36470 </p>
36471 <p>Note this function is equivalent to using the <code>GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA</code>
36472 flag with <code>gnutls_privkey_sign_hash()</code> .
36473 </p>
36474 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
36475 negative error value.
36476 </p>
36477 <p><strong>Since:</strong> 3.1.10
36478 </p></dd></dl>
36479
36480 <a name="gnutls_005fprotocol_005fset_005fpriority-1"></a>
36481 <h4 class="subheading">gnutls_protocol_set_priority</h4>
36482 <a name="gnutls_005fprotocol_005fset_005fpriority"></a><dl>
36483 <dt><a name="index-gnutls_005fprotocol_005fset_005fpriority"></a>Function: <em>int</em> <strong>gnutls_protocol_set_priority</strong> <em>(gnutls_session_t <var>session</var>, const int * <var>list</var>)</em></dt>
36484 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
36485 </p>
36486 <p><var>list</var>: is a 0 terminated list of gnutls_protocol_t elements.
36487 </p>
36488 <p>Sets the priority on the protocol versions supported by gnutls.
36489 This function actually enables or disables protocols. Newer protocol
36490 versions always have highest priority.
36491 </p>
36492 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
36493 </p></dd></dl>
36494
36495 <a name="gnutls_005frsa_005fexport_005fget_005fmodulus_005fbits-1"></a>
36496 <h4 class="subheading">gnutls_rsa_export_get_modulus_bits</h4>
36497 <a name="gnutls_005frsa_005fexport_005fget_005fmodulus_005fbits"></a><dl>
36498 <dt><a name="index-gnutls_005frsa_005fexport_005fget_005fmodulus_005fbits"></a>Function: <em>int</em> <strong>gnutls_rsa_export_get_modulus_bits</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
36499 <dd><p><var>session</var>: is a gnutls session
36500 </p>
36501 <p>Get the export RSA parameter&rsquo;s modulus size.
36502 </p>
36503 <p><strong>Returns:</strong> The bits used in the last RSA-EXPORT key exchange with the
36504 peer, or a negative error code in case of error.
36505 </p></dd></dl>
36506
36507 <a name="gnutls_005frsa_005fexport_005fget_005fpubkey-1"></a>
36508 <h4 class="subheading">gnutls_rsa_export_get_pubkey</h4>
36509 <a name="gnutls_005frsa_005fexport_005fget_005fpubkey"></a><dl>
36510 <dt><a name="index-gnutls_005frsa_005fexport_005fget_005fpubkey"></a>Function: <em>int</em> <strong>gnutls_rsa_export_get_pubkey</strong> <em>(gnutls_session_t <var>session</var>, gnutls_datum_t * <var>exponent</var>, gnutls_datum_t * <var>modulus</var>)</em></dt>
36511 <dd><p><var>session</var>: is a gnutls session
36512 </p>
36513 <p><var>exponent</var>: will hold the exponent.
36514 </p>
36515 <p><var>modulus</var>: will hold the modulus.
36516 </p>
36517 <p>This function will return the peer&rsquo;s public key exponent and
36518 modulus used in the last RSA-EXPORT authentication.  The output
36519 parameters must be freed with <code>gnutls_free()</code> .
36520 </p>
36521 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise
36522 an error code is returned.
36523 </p></dd></dl>
36524
36525 <a name="gnutls_005frsa_005fparams_005fcpy-1"></a>
36526 <h4 class="subheading">gnutls_rsa_params_cpy</h4>
36527 <a name="gnutls_005frsa_005fparams_005fcpy"></a><dl>
36528 <dt><a name="index-gnutls_005frsa_005fparams_005fcpy"></a>Function: <em>int</em> <strong>gnutls_rsa_params_cpy</strong> <em>(gnutls_rsa_params_t <var>dst</var>, gnutls_rsa_params_t <var>src</var>)</em></dt>
36529 <dd><p><var>dst</var>: Is the destination structure, which should be initialized.
36530 </p>
36531 <p><var>src</var>: Is the source structure
36532 </p>
36533 <p>This function will copy the RSA parameters structure from source
36534 to destination.
36535 </p>
36536 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an negative error code.
36537 </p></dd></dl>
36538
36539 <a name="gnutls_005frsa_005fparams_005fdeinit-1"></a>
36540 <h4 class="subheading">gnutls_rsa_params_deinit</h4>
36541 <a name="gnutls_005frsa_005fparams_005fdeinit"></a><dl>
36542 <dt><a name="index-gnutls_005frsa_005fparams_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_rsa_params_deinit</strong> <em>(gnutls_rsa_params_t <var>rsa_params</var>)</em></dt>
36543 <dd><p><var>rsa_params</var>: Is a structure that holds the parameters
36544 </p>
36545 <p>This function will deinitialize the RSA parameters structure.
36546 </p></dd></dl>
36547
36548 <a name="gnutls_005frsa_005fparams_005fexport_005fpkcs1-1"></a>
36549 <h4 class="subheading">gnutls_rsa_params_export_pkcs1</h4>
36550 <a name="gnutls_005frsa_005fparams_005fexport_005fpkcs1"></a><dl>
36551 <dt><a name="index-gnutls_005frsa_005fparams_005fexport_005fpkcs1"></a>Function: <em>int</em> <strong>gnutls_rsa_params_export_pkcs1</strong> <em>(gnutls_rsa_params_t <var>params</var>, gnutls_x509_crt_fmt_t <var>format</var>, unsigned char * <var>params_data</var>, size_t * <var>params_data_size</var>)</em></dt>
36552 <dd><p><var>params</var>: Holds the RSA parameters
36553 </p>
36554 <p><var>format</var>: the format of output params. One of PEM or DER.
36555 </p>
36556 <p><var>params_data</var>: will contain a PKCS1 RSAPrivateKey structure PEM or DER encoded
36557 </p>
36558 <p><var>params_data_size</var>: holds the size of params_data (and will be replaced by the actual size of parameters)
36559 </p>
36560 <p>This function will export the given RSA parameters to a PKCS1
36561 RSAPrivateKey structure. If the buffer provided is not long enough to
36562 hold the output, then GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
36563 </p>
36564 <p>If the structure is PEM encoded, it will have a header
36565 of &quot;BEGIN RSA PRIVATE KEY&quot;.
36566 </p>
36567 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an negative error code.
36568 </p></dd></dl>
36569
36570 <a name="gnutls_005frsa_005fparams_005fexport_005fraw-1"></a>
36571 <h4 class="subheading">gnutls_rsa_params_export_raw</h4>
36572 <a name="gnutls_005frsa_005fparams_005fexport_005fraw"></a><dl>
36573 <dt><a name="index-gnutls_005frsa_005fparams_005fexport_005fraw"></a>Function: <em>int</em> <strong>gnutls_rsa_params_export_raw</strong> <em>(gnutls_rsa_params_t <var>rsa</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>, gnutls_datum_t * <var>d</var>, gnutls_datum_t * <var>p</var>, gnutls_datum_t * <var>q</var>, gnutls_datum_t * <var>u</var>, unsigned int * <var>bits</var>)</em></dt>
36574 <dd><p><var>rsa</var>: a structure that holds the rsa parameters
36575 </p>
36576 <p><var>m</var>: will hold the modulus
36577 </p>
36578 <p><var>e</var>: will hold the public exponent
36579 </p>
36580 <p><var>d</var>: will hold the private exponent
36581 </p>
36582 <p><var>p</var>: will hold the first prime (p)
36583 </p>
36584 <p><var>q</var>: will hold the second prime (q)
36585 </p>
36586 <p><var>u</var>: will hold the coefficient
36587 </p>
36588 <p><var>bits</var>: if non null will hold the prime&rsquo;s number of bits
36589 </p>
36590 <p>This function will export the RSA parameters found in the given
36591 structure. The new parameters will be allocated using
36592 <code>gnutls_malloc()</code>  and will be stored in the appropriate datum.
36593 </p>
36594 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an negative error code.
36595 </p></dd></dl>
36596
36597 <a name="gnutls_005frsa_005fparams_005fgenerate2-1"></a>
36598 <h4 class="subheading">gnutls_rsa_params_generate2</h4>
36599 <a name="gnutls_005frsa_005fparams_005fgenerate2"></a><dl>
36600 <dt><a name="index-gnutls_005frsa_005fparams_005fgenerate2"></a>Function: <em>int</em> <strong>gnutls_rsa_params_generate2</strong> <em>(gnutls_rsa_params_t <var>params</var>, unsigned int <var>bits</var>)</em></dt>
36601 <dd><p><var>params</var>: The structure where the parameters will be stored
36602 </p>
36603 <p><var>bits</var>: is the prime&rsquo;s number of bits
36604 </p>
36605 <p>This function will generate new temporary RSA parameters for use in
36606 RSA-EXPORT ciphersuites.  This function is normally slow.
36607 </p>
36608 <p>Note that if the parameters are to be used in export cipher suites the
36609 bits value should be 512 or less.
36610 Also note that the generation of new RSA parameters is only useful
36611 to servers. Clients use the parameters sent by the server, thus it&rsquo;s
36612 no use calling this in client side.
36613 </p>
36614 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an negative error code.
36615 </p></dd></dl>
36616
36617 <a name="gnutls_005frsa_005fparams_005fimport_005fpkcs1-1"></a>
36618 <h4 class="subheading">gnutls_rsa_params_import_pkcs1</h4>
36619 <a name="gnutls_005frsa_005fparams_005fimport_005fpkcs1"></a><dl>
36620 <dt><a name="index-gnutls_005frsa_005fparams_005fimport_005fpkcs1"></a>Function: <em>int</em> <strong>gnutls_rsa_params_import_pkcs1</strong> <em>(gnutls_rsa_params_t <var>params</var>, const gnutls_datum_t * <var>pkcs1_params</var>, gnutls_x509_crt_fmt_t <var>format</var>)</em></dt>
36621 <dd><p><var>params</var>: A structure where the parameters will be copied to
36622 </p>
36623 <p><var>pkcs1_params</var>: should contain a PKCS1 RSAPrivateKey structure PEM or DER encoded
36624 </p>
36625 <p><var>format</var>: the format of params. PEM or DER.
36626 </p>
36627 <p>This function will extract the RSAPrivateKey found in a PKCS1 formatted
36628 structure.
36629 </p>
36630 <p>If the structure is PEM encoded, it should have a header
36631 of &quot;BEGIN RSA PRIVATE KEY&quot;.
36632 </p>
36633 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an negative error code.
36634 </p></dd></dl>
36635
36636 <a name="gnutls_005frsa_005fparams_005fimport_005fraw-1"></a>
36637 <h4 class="subheading">gnutls_rsa_params_import_raw</h4>
36638 <a name="gnutls_005frsa_005fparams_005fimport_005fraw"></a><dl>
36639 <dt><a name="index-gnutls_005frsa_005fparams_005fimport_005fraw"></a>Function: <em>int</em> <strong>gnutls_rsa_params_import_raw</strong> <em>(gnutls_rsa_params_t <var>rsa_params</var>, const gnutls_datum_t * <var>m</var>, const gnutls_datum_t * <var>e</var>, const gnutls_datum_t * <var>d</var>, const gnutls_datum_t * <var>p</var>, const gnutls_datum_t * <var>q</var>, const gnutls_datum_t * <var>u</var>)</em></dt>
36640 <dd><p><var>rsa_params</var>: Is a structure will hold the parameters
36641 </p>
36642 <p><var>m</var>: holds the modulus
36643 </p>
36644 <p><var>e</var>: holds the public exponent
36645 </p>
36646 <p><var>d</var>: holds the private exponent
36647 </p>
36648 <p><var>p</var>: holds the first prime (p)
36649 </p>
36650 <p><var>q</var>: holds the second prime (q)
36651 </p>
36652 <p><var>u</var>: holds the coefficient
36653 </p>
36654 <p>This function will replace the parameters in the given structure.
36655 The new parameters should be stored in the appropriate
36656 gnutls_datum.
36657 </p>
36658 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an negative error code.
36659 </p></dd></dl>
36660
36661 <a name="gnutls_005frsa_005fparams_005finit-1"></a>
36662 <h4 class="subheading">gnutls_rsa_params_init</h4>
36663 <a name="gnutls_005frsa_005fparams_005finit"></a><dl>
36664 <dt><a name="index-gnutls_005frsa_005fparams_005finit"></a>Function: <em>int</em> <strong>gnutls_rsa_params_init</strong> <em>(gnutls_rsa_params_t * <var>rsa_params</var>)</em></dt>
36665 <dd><p><var>rsa_params</var>: Is a structure that will hold the parameters
36666 </p>
36667 <p>This function will initialize the temporary RSA parameters structure.
36668 </p>
36669 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an negative error code.
36670 </p></dd></dl>
36671
36672 <a name="gnutls_005fset_005fdefault_005fexport_005fpriority-1"></a>
36673 <h4 class="subheading">gnutls_set_default_export_priority</h4>
36674 <a name="gnutls_005fset_005fdefault_005fexport_005fpriority"></a><dl>
36675 <dt><a name="index-gnutls_005fset_005fdefault_005fexport_005fpriority"></a>Function: <em>int</em> <strong>gnutls_set_default_export_priority</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
36676 <dd><p><var>session</var>: is a <code>gnutls_session_t</code>  structure.
36677 </p>
36678 <p>Sets some default priority on the ciphers, key exchange methods, macs
36679 and compression methods.  This function also includes weak algorithms.
36680 </p>
36681 <p>This is the same as calling:
36682 </p>
36683 <p>gnutls_priority_set_direct (session, &quot;EXPORT&quot;, NULL);
36684 </p>
36685 <p>This function is kept around for backwards compatibility, but
36686 because of its wide use it is still fully supported.  If you wish
36687 to allow users to provide a string that specify which ciphers to
36688 use (which is recommended), you should use
36689 <code>gnutls_priority_set_direct()</code>  or <code>gnutls_priority_set()</code>  instead.
36690 </p>
36691 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code>  on success, or an error code.
36692 </p></dd></dl>
36693
36694 <a name="gnutls_005fsign_005fcallback_005fget-1"></a>
36695 <h4 class="subheading">gnutls_sign_callback_get</h4>
36696 <a name="gnutls_005fsign_005fcallback_005fget"></a><dl>
36697 <dt><a name="index-gnutls_005fsign_005fcallback_005fget"></a>Function: <em>gnutls_sign_func</em> <strong>gnutls_sign_callback_get</strong> <em>(gnutls_session_t <var>session</var>, void ** <var>userdata</var>)</em></dt>
36698 <dd><p><var>session</var>: is a gnutls session
36699 </p>
36700 <p><var>userdata</var>: if non-<code>NULL</code> , will be set to abstract callback pointer.
36701 </p>
36702 <p>Retrieve the callback function, and its userdata pointer.
36703 </p>
36704 <p><strong>Returns:</strong> The function pointer set by <code>gnutls_sign_callback_set()</code> , or
36705 if not set, <code>NULL</code> .
36706 </p>
36707 <p><strong>Deprecated:</strong> Use the PKCS 11 interfaces instead.
36708 </p></dd></dl>
36709
36710 <a name="gnutls_005fsign_005fcallback_005fset-1"></a>
36711 <h4 class="subheading">gnutls_sign_callback_set</h4>
36712 <a name="gnutls_005fsign_005fcallback_005fset"></a><dl>
36713 <dt><a name="index-gnutls_005fsign_005fcallback_005fset"></a>Function: <em>void</em> <strong>gnutls_sign_callback_set</strong> <em>(gnutls_session_t <var>session</var>, gnutls_sign_func <var>sign_func</var>, void * <var>userdata</var>)</em></dt>
36714 <dd><p><var>session</var>: is a gnutls session
36715 </p>
36716 <p><var>sign_func</var>: function pointer to application&rsquo;s sign callback.
36717 </p>
36718 <p><var>userdata</var>: void pointer that will be passed to sign callback.
36719 </p>
36720 <p>Set the callback function.  The function must have this prototype:
36721 </p>
36722 <p>typedef int (*gnutls_sign_func) (gnutls_session_t session,
36723 void *userdata,
36724 gnutls_certificate_type_t cert_type,
36725 const gnutls_datum_t * cert,
36726 const gnutls_datum_t * hash,
36727 gnutls_datum_t * signature);
36728 </p>
36729 <p>The  <code>userdata</code> parameter is passed to the  <code>sign_func</code> verbatim, and
36730 can be used to store application-specific data needed in the
36731 callback function.  See also <code>gnutls_sign_callback_get()</code> .
36732 </p>
36733 <p><strong>Deprecated:</strong> Use the PKCS 11 or <code>gnutls_privkey_t</code>  interfacess like <code>gnutls_privkey_import_ext()</code>  instead.
36734 </p></dd></dl>
36735
36736 <a name="gnutls_005fx509_005fcrl_005fsign-1"></a>
36737 <h4 class="subheading">gnutls_x509_crl_sign</h4>
36738 <a name="gnutls_005fx509_005fcrl_005fsign"></a><dl>
36739 <dt><a name="index-gnutls_005fx509_005fcrl_005fsign"></a>Function: <em>int</em> <strong>gnutls_x509_crl_sign</strong> <em>(gnutls_x509_crl_t <var>crl</var>, gnutls_x509_crt_t <var>issuer</var>, gnutls_x509_privkey_t <var>issuer_key</var>)</em></dt>
36740 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
36741 </p>
36742 <p><var>issuer</var>: is the certificate of the certificate issuer
36743 </p>
36744 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
36745 </p>
36746 <p>This function is the same a <code>gnutls_x509_crl_sign2()</code>  with no flags, and
36747 SHA1 as the hash algorithm.
36748 </p>
36749 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
36750 negative error value.
36751 </p>
36752 <p><strong>Deprecated:</strong> Use <code>gnutls_x509_crl_privkey_sign()</code> .
36753 </p></dd></dl>
36754
36755 <a name="gnutls_005fx509_005fcrq_005fsign-1"></a>
36756 <h4 class="subheading">gnutls_x509_crq_sign</h4>
36757 <a name="gnutls_005fx509_005fcrq_005fsign"></a><dl>
36758 <dt><a name="index-gnutls_005fx509_005fcrq_005fsign"></a>Function: <em>int</em> <strong>gnutls_x509_crq_sign</strong> <em>(gnutls_x509_crq_t <var>crq</var>, gnutls_x509_privkey_t <var>key</var>)</em></dt>
36759 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code>  structure
36760 </p>
36761 <p><var>key</var>: holds a private key
36762 </p>
36763 <p>This function is the same a <code>gnutls_x509_crq_sign2()</code>  with no flags,
36764 and SHA1 as the hash algorithm.
36765 </p>
36766 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
36767 negative error value.
36768 </p>
36769 <p><strong>Deprecated:</strong> Use <code>gnutls_x509_crq_privkey_sign()</code>  instead.
36770 </p></dd></dl>
36771
36772 <a name="gnutls_005fx509_005fcrt_005fget_005fpreferred_005fhash_005falgorithm-1"></a>
36773 <h4 class="subheading">gnutls_x509_crt_get_preferred_hash_algorithm</h4>
36774 <a name="gnutls_005fx509_005fcrt_005fget_005fpreferred_005fhash_005falgorithm"></a><dl>
36775 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fpreferred_005fhash_005falgorithm"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_preferred_hash_algorithm</strong> <em>(gnutls_x509_crt_t <var>crt</var>, gnutls_digest_algorithm_t *           <var>hash</var>, unsigned int * <var>mand</var>)</em></dt>
36776 <dd><p><var>crt</var>: Holds the certificate
36777 </p>
36778 <p><var>hash</var>: The result of the call with the hash algorithm used for signature
36779 </p>
36780 <p><var>mand</var>: If non-zero it means that the algorithm MUST use this hash. May be NULL.
36781 </p>
36782 <p>This function will read the certifcate and return the appropriate digest
36783 algorithm to use for signing with this certificate. Some certificates (i.e.
36784 DSA might not be able to sign without the preferred algorithm).
36785 </p>
36786 <p><strong>Deprecated:</strong> Please use <code>gnutls_pubkey_get_preferred_hash_algorithm()</code> .
36787 </p>
36788 <p><strong>Returns:</strong> the 0 if the hash algorithm is found. A negative error code is
36789 returned on error.
36790 </p>
36791 <p><strong>Since:</strong> 2.12.0
36792 </p></dd></dl>
36793
36794 <a name="gnutls_005fx509_005fcrt_005fget_005fverify_005falgorithm-1"></a>
36795 <h4 class="subheading">gnutls_x509_crt_get_verify_algorithm</h4>
36796 <a name="gnutls_005fx509_005fcrt_005fget_005fverify_005falgorithm"></a><dl>
36797 <dt><a name="index-gnutls_005fx509_005fcrt_005fget_005fverify_005falgorithm"></a>Function: <em>int</em> <strong>gnutls_x509_crt_get_verify_algorithm</strong> <em>(gnutls_x509_crt_t <var>crt</var>, const gnutls_datum_t * <var>signature</var>, gnutls_digest_algorithm_t * <var>hash</var>)</em></dt>
36798 <dd><p><var>crt</var>: Holds the certificate
36799 </p>
36800 <p><var>signature</var>: contains the signature
36801 </p>
36802 <p><var>hash</var>: The result of the call with the hash algorithm used for signature
36803 </p>
36804 <p>This function will read the certifcate and the signed data to
36805 determine the hash algorithm used to generate the signature.
36806 </p>
36807 <p><strong>Deprecated:</strong> Use <code>gnutls_pubkey_get_verify_algorithm()</code>  instead.
36808 </p>
36809 <p><strong>Returns:</strong> the 0 if the hash algorithm is found. A negative error code is
36810 returned on error.
36811 </p>
36812 <p><strong>Since:</strong> 2.8.0
36813 </p></dd></dl>
36814
36815 <a name="gnutls_005fx509_005fcrt_005fverify_005fdata-1"></a>
36816 <h4 class="subheading">gnutls_x509_crt_verify_data</h4>
36817 <a name="gnutls_005fx509_005fcrt_005fverify_005fdata"></a><dl>
36818 <dt><a name="index-gnutls_005fx509_005fcrt_005fverify_005fdata"></a>Function: <em>int</em> <strong>gnutls_x509_crt_verify_data</strong> <em>(gnutls_x509_crt_t <var>crt</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>data</var>, const gnutls_datum_t * <var>signature</var>)</em></dt>
36819 <dd><p><var>crt</var>: Holds the certificate
36820 </p>
36821 <p><var>flags</var>: should be 0 for now
36822 </p>
36823 <p><var>data</var>: holds the data to be signed
36824 </p>
36825 <p><var>signature</var>: contains the signature
36826 </p>
36827 <p>This function will verify the given signed data, using the
36828 parameters from the certificate.
36829 </p>
36830 <p>Deprecated. This function cannot be easily used securely.
36831 Use <code>gnutls_pubkey_verify_data2()</code>  instead.
36832 </p>
36833 <p><strong>Returns:</strong> In case of a verification failure <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
36834 is returned, and zero or positive code on success.
36835 </p></dd></dl>
36836
36837 <a name="gnutls_005fx509_005fcrt_005fverify_005fhash-1"></a>
36838 <h4 class="subheading">gnutls_x509_crt_verify_hash</h4>
36839 <a name="gnutls_005fx509_005fcrt_005fverify_005fhash"></a><dl>
36840 <dt><a name="index-gnutls_005fx509_005fcrt_005fverify_005fhash"></a>Function: <em>int</em> <strong>gnutls_x509_crt_verify_hash</strong> <em>(gnutls_x509_crt_t <var>crt</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>hash</var>, const gnutls_datum_t * <var>signature</var>)</em></dt>
36841 <dd><p><var>crt</var>: Holds the certificate
36842 </p>
36843 <p><var>flags</var>: should be 0 for now
36844 </p>
36845 <p><var>hash</var>: holds the hash digest to be verified
36846 </p>
36847 <p><var>signature</var>: contains the signature
36848 </p>
36849 <p>This function will verify the given signed digest, using the
36850 parameters from the certificate.
36851 </p>
36852 <p>Deprecated. This function cannot be easily used securely.
36853 Use <code>gnutls_pubkey_verify_hash2()</code>  instead.
36854 </p>
36855 <p><strong>Returns:</strong> In case of a verification failure <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
36856 is returned, and zero or positive code on success.
36857 </p></dd></dl>
36858
36859 <a name="gnutls_005fx509_005fprivkey_005fsign_005fdata-1"></a>
36860 <h4 class="subheading">gnutls_x509_privkey_sign_data</h4>
36861 <a name="gnutls_005fx509_005fprivkey_005fsign_005fdata"></a><dl>
36862 <dt><a name="index-gnutls_005fx509_005fprivkey_005fsign_005fdata"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_sign_data</strong> <em>(gnutls_x509_privkey_t <var>key</var>, gnutls_digest_algorithm_t <var>digest</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>data</var>, void * <var>signature</var>, size_t * <var>signature_size</var>)</em></dt>
36863 <dd><p><var>key</var>: Holds the key
36864 </p>
36865 <p><var>digest</var>: should be MD5 or SHA1
36866 </p>
36867 <p><var>flags</var>: should be 0 for now
36868 </p>
36869 <p><var>data</var>: holds the data to be signed
36870 </p>
36871 <p><var>signature</var>: will contain the signature
36872 </p>
36873 <p><var>signature_size</var>: holds the size of signature (and will be replaced
36874 by the new size)
36875 </p>
36876 <p>This function will sign the given data using a signature algorithm
36877 supported by the private key. Signature algorithms are always used
36878 together with a hash functions.  Different hash functions may be
36879 used for the RSA algorithm, but only SHA-1 for the DSA keys.
36880 </p>
36881 <p>If the buffer provided is not long enough to hold the output, then
36882 * <code>signature_size</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>  will
36883 be returned.
36884 </p>
36885 <p>Use <code>gnutls_x509_crt_get_preferred_hash_algorithm()</code>  to determine
36886 the hash algorithm.
36887 </p>
36888 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
36889 negative error value.
36890 </p>
36891 <p><strong>Deprecated:</strong> Use <code>gnutls_privkey_sign_data()</code> .
36892 </p></dd></dl>
36893
36894 <a name="gnutls_005fx509_005fprivkey_005fsign_005fhash-1"></a>
36895 <h4 class="subheading">gnutls_x509_privkey_sign_hash</h4>
36896 <a name="gnutls_005fx509_005fprivkey_005fsign_005fhash"></a><dl>
36897 <dt><a name="index-gnutls_005fx509_005fprivkey_005fsign_005fhash"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_sign_hash</strong> <em>(gnutls_x509_privkey_t <var>key</var>, const gnutls_datum_t * <var>hash</var>, gnutls_datum_t * <var>signature</var>)</em></dt>
36898 <dd><p><var>key</var>: Holds the key
36899 </p>
36900 <p><var>hash</var>: holds the data to be signed
36901 </p>
36902 <p><var>signature</var>: will contain newly allocated signature
36903 </p>
36904 <p>This function will sign the given hash using the private key. Do not
36905 use this function directly unless you know what it is. Typical signing
36906 requires the data to be hashed and stored in special formats
36907 (e.g. BER Digest-Info for RSA).
36908 </p>
36909 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code>  (0) is returned, otherwise a
36910 negative error value.
36911 </p>
36912 <p>Deprecated in: 2.12.0
36913 </p></dd></dl>
36914
36915
36916 <hr>
36917 <a name="Copying-Information"></a>
36918 <div class="header">
36919 <p>
36920 Next: <a href="#Bibliography" accesskey="n" rel="next">Bibliography</a>, Previous: <a href="#API-reference" accesskey="p" rel="prev">API reference</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
36921 </div>
36922 <a name="Copying-Information-1"></a>
36923 <h2 class="appendix">Appendix F Copying Information</h2>
36924 <a name="index-FDL_002c-GNU-Free-Documentation-License"></a>
36925
36926 <a name="GNU-Free-Documentation-License"></a>
36927 <h3 class="heading">GNU Free Documentation License</h3>
36928
36929 <div align="center">Version 1.3, 3 November 2008
36930 </div>
36931
36932 <div class="display">
36933 <pre class="display">Copyright &copy; 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
36934 <a href="http://fsf.org/">http://fsf.org/</a>
36935
36936 Everyone is permitted to copy and distribute verbatim copies
36937 of this license document, but changing it is not allowed.
36938 </pre></div>
36939
36940 <ol>
36941 <li> PREAMBLE
36942
36943 <p>The purpose of this License is to make a manual, textbook, or other
36944 functional and useful document <em>free</em> in the sense of freedom: to
36945 assure everyone the effective freedom to copy and redistribute it,
36946 with or without modifying it, either commercially or noncommercially.
36947 Secondarily, this License preserves for the author and publisher a way
36948 to get credit for their work, while not being considered responsible
36949 for modifications made by others.
36950 </p>
36951 <p>This License is a kind of &ldquo;copyleft&rdquo;, which means that derivative
36952 works of the document must themselves be free in the same sense.  It
36953 complements the GNU General Public License, which is a copyleft
36954 license designed for free software.
36955 </p>
36956 <p>We have designed this License in order to use it for manuals for free
36957 software, because free software needs free documentation: a free
36958 program should come with manuals providing the same freedoms that the
36959 software does.  But this License is not limited to software manuals;
36960 it can be used for any textual work, regardless of subject matter or
36961 whether it is published as a printed book.  We recommend this License
36962 principally for works whose purpose is instruction or reference.
36963 </p>
36964 </li><li> APPLICABILITY AND DEFINITIONS
36965
36966 <p>This License applies to any manual or other work, in any medium, that
36967 contains a notice placed by the copyright holder saying it can be
36968 distributed under the terms of this License.  Such a notice grants a
36969 world-wide, royalty-free license, unlimited in duration, to use that
36970 work under the conditions stated herein.  The &ldquo;Document&rdquo;, below,
36971 refers to any such manual or work.  Any member of the public is a
36972 licensee, and is addressed as &ldquo;you&rdquo;.  You accept the license if you
36973 copy, modify or distribute the work in a way requiring permission
36974 under copyright law.
36975 </p>
36976 <p>A &ldquo;Modified Version&rdquo; of the Document means any work containing the
36977 Document or a portion of it, either copied verbatim, or with
36978 modifications and/or translated into another language.
36979 </p>
36980 <p>A &ldquo;Secondary Section&rdquo; is a named appendix or a front-matter section
36981 of the Document that deals exclusively with the relationship of the
36982 publishers or authors of the Document to the Document&rsquo;s overall
36983 subject (or to related matters) and contains nothing that could fall
36984 directly within that overall subject.  (Thus, if the Document is in
36985 part a textbook of mathematics, a Secondary Section may not explain
36986 any mathematics.)  The relationship could be a matter of historical
36987 connection with the subject or with related matters, or of legal,
36988 commercial, philosophical, ethical or political position regarding
36989 them.
36990 </p>
36991 <p>The &ldquo;Invariant Sections&rdquo; are certain Secondary Sections whose titles
36992 are designated, as being those of Invariant Sections, in the notice
36993 that says that the Document is released under this License.  If a
36994 section does not fit the above definition of Secondary then it is not
36995 allowed to be designated as Invariant.  The Document may contain zero
36996 Invariant Sections.  If the Document does not identify any Invariant
36997 Sections then there are none.
36998 </p>
36999 <p>The &ldquo;Cover Texts&rdquo; are certain short passages of text that are listed,
37000 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
37001 the Document is released under this License.  A Front-Cover Text may
37002 be at most 5 words, and a Back-Cover Text may be at most 25 words.
37003 </p>
37004 <p>A &ldquo;Transparent&rdquo; copy of the Document means a machine-readable copy,
37005 represented in a format whose specification is available to the
37006 general public, that is suitable for revising the document
37007 straightforwardly with generic text editors or (for images composed of
37008 pixels) generic paint programs or (for drawings) some widely available
37009 drawing editor, and that is suitable for input to text formatters or
37010 for automatic translation to a variety of formats suitable for input
37011 to text formatters.  A copy made in an otherwise Transparent file
37012 format whose markup, or absence of markup, has been arranged to thwart
37013 or discourage subsequent modification by readers is not Transparent.
37014 An image format is not Transparent if used for any substantial amount
37015 of text.  A copy that is not &ldquo;Transparent&rdquo; is called &ldquo;Opaque&rdquo;.
37016 </p>
37017 <p>Examples of suitable formats for Transparent copies include plain
37018 ASCII without markup, Texinfo input format, LaTeX input
37019 format, SGML or XML using a publicly available
37020 DTD, and standard-conforming simple HTML,
37021 PostScript or PDF designed for human modification.  Examples
37022 of transparent image formats include PNG, XCF and
37023 JPG.  Opaque formats include proprietary formats that can be
37024 read and edited only by proprietary word processors, SGML or
37025 XML for which the DTD and/or processing tools are
37026 not generally available, and the machine-generated HTML,
37027 PostScript or PDF produced by some word processors for
37028 output purposes only.
37029 </p>
37030 <p>The &ldquo;Title Page&rdquo; means, for a printed book, the title page itself,
37031 plus such following pages as are needed to hold, legibly, the material
37032 this License requires to appear in the title page.  For works in
37033 formats which do not have any title page as such, &ldquo;Title Page&rdquo; means
37034 the text near the most prominent appearance of the work&rsquo;s title,
37035 preceding the beginning of the body of the text.
37036 </p>
37037 <p>The &ldquo;publisher&rdquo; means any person or entity that distributes copies
37038 of the Document to the public.
37039 </p>
37040 <p>A section &ldquo;Entitled XYZ&rdquo; means a named subunit of the Document whose
37041 title either is precisely XYZ or contains XYZ in parentheses following
37042 text that translates XYZ in another language.  (Here XYZ stands for a
37043 specific section name mentioned below, such as &ldquo;Acknowledgements&rdquo;,
37044 &ldquo;Dedications&rdquo;, &ldquo;Endorsements&rdquo;, or &ldquo;History&rdquo;.)  To &ldquo;Preserve the Title&rdquo;
37045 of such a section when you modify the Document means that it remains a
37046 section &ldquo;Entitled XYZ&rdquo; according to this definition.
37047 </p>
37048 <p>The Document may include Warranty Disclaimers next to the notice which
37049 states that this License applies to the Document.  These Warranty
37050 Disclaimers are considered to be included by reference in this
37051 License, but only as regards disclaiming warranties: any other
37052 implication that these Warranty Disclaimers may have is void and has
37053 no effect on the meaning of this License.
37054 </p>
37055 </li><li> VERBATIM COPYING
37056
37057 <p>You may copy and distribute the Document in any medium, either
37058 commercially or noncommercially, provided that this License, the
37059 copyright notices, and the license notice saying this License applies
37060 to the Document are reproduced in all copies, and that you add no other
37061 conditions whatsoever to those of this License.  You may not use
37062 technical measures to obstruct or control the reading or further
37063 copying of the copies you make or distribute.  However, you may accept
37064 compensation in exchange for copies.  If you distribute a large enough
37065 number of copies you must also follow the conditions in section 3.
37066 </p>
37067 <p>You may also lend copies, under the same conditions stated above, and
37068 you may publicly display copies.
37069 </p>
37070 </li><li> COPYING IN QUANTITY
37071
37072 <p>If you publish printed copies (or copies in media that commonly have
37073 printed covers) of the Document, numbering more than 100, and the
37074 Document&rsquo;s license notice requires Cover Texts, you must enclose the
37075 copies in covers that carry, clearly and legibly, all these Cover
37076 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
37077 the back cover.  Both covers must also clearly and legibly identify
37078 you as the publisher of these copies.  The front cover must present
37079 the full title with all words of the title equally prominent and
37080 visible.  You may add other material on the covers in addition.
37081 Copying with changes limited to the covers, as long as they preserve
37082 the title of the Document and satisfy these conditions, can be treated
37083 as verbatim copying in other respects.
37084 </p>
37085 <p>If the required texts for either cover are too voluminous to fit
37086 legibly, you should put the first ones listed (as many as fit
37087 reasonably) on the actual cover, and continue the rest onto adjacent
37088 pages.
37089 </p>
37090 <p>If you publish or distribute Opaque copies of the Document numbering
37091 more than 100, you must either include a machine-readable Transparent
37092 copy along with each Opaque copy, or state in or with each Opaque copy
37093 a computer-network location from which the general network-using
37094 public has access to download using public-standard network protocols
37095 a complete Transparent copy of the Document, free of added material.
37096 If you use the latter option, you must take reasonably prudent steps,
37097 when you begin distribution of Opaque copies in quantity, to ensure
37098 that this Transparent copy will remain thus accessible at the stated
37099 location until at least one year after the last time you distribute an
37100 Opaque copy (directly or through your agents or retailers) of that
37101 edition to the public.
37102 </p>
37103 <p>It is requested, but not required, that you contact the authors of the
37104 Document well before redistributing any large number of copies, to give
37105 them a chance to provide you with an updated version of the Document.
37106 </p>
37107 </li><li> MODIFICATIONS
37108
37109 <p>You may copy and distribute a Modified Version of the Document under
37110 the conditions of sections 2 and 3 above, provided that you release
37111 the Modified Version under precisely this License, with the Modified
37112 Version filling the role of the Document, thus licensing distribution
37113 and modification of the Modified Version to whoever possesses a copy
37114 of it.  In addition, you must do these things in the Modified Version:
37115 </p>
37116 <ol>
37117 <li> Use in the Title Page (and on the covers, if any) a title distinct
37118 from that of the Document, and from those of previous versions
37119 (which should, if there were any, be listed in the History section
37120 of the Document).  You may use the same title as a previous version
37121 if the original publisher of that version gives permission.
37122
37123 </li><li> List on the Title Page, as authors, one or more persons or entities
37124 responsible for authorship of the modifications in the Modified
37125 Version, together with at least five of the principal authors of the
37126 Document (all of its principal authors, if it has fewer than five),
37127 unless they release you from this requirement.
37128
37129 </li><li> State on the Title page the name of the publisher of the
37130 Modified Version, as the publisher.
37131
37132 </li><li> Preserve all the copyright notices of the Document.
37133
37134 </li><li> Add an appropriate copyright notice for your modifications
37135 adjacent to the other copyright notices.
37136
37137 </li><li> Include, immediately after the copyright notices, a license notice
37138 giving the public permission to use the Modified Version under the
37139 terms of this License, in the form shown in the Addendum below.
37140
37141 </li><li> Preserve in that license notice the full lists of Invariant Sections
37142 and required Cover Texts given in the Document&rsquo;s license notice.
37143
37144 </li><li> Include an unaltered copy of this License.
37145
37146 </li><li> Preserve the section Entitled &ldquo;History&rdquo;, Preserve its Title, and add
37147 to it an item stating at least the title, year, new authors, and
37148 publisher of the Modified Version as given on the Title Page.  If
37149 there is no section Entitled &ldquo;History&rdquo; in the Document, create one
37150 stating the title, year, authors, and publisher of the Document as
37151 given on its Title Page, then add an item describing the Modified
37152 Version as stated in the previous sentence.
37153
37154 </li><li> Preserve the network location, if any, given in the Document for
37155 public access to a Transparent copy of the Document, and likewise
37156 the network locations given in the Document for previous versions
37157 it was based on.  These may be placed in the &ldquo;History&rdquo; section.
37158 You may omit a network location for a work that was published at
37159 least four years before the Document itself, or if the original
37160 publisher of the version it refers to gives permission.
37161
37162 </li><li> For any section Entitled &ldquo;Acknowledgements&rdquo; or &ldquo;Dedications&rdquo;, Preserve
37163 the Title of the section, and preserve in the section all the
37164 substance and tone of each of the contributor acknowledgements and/or
37165 dedications given therein.
37166
37167 </li><li> Preserve all the Invariant Sections of the Document,
37168 unaltered in their text and in their titles.  Section numbers
37169 or the equivalent are not considered part of the section titles.
37170
37171 </li><li> Delete any section Entitled &ldquo;Endorsements&rdquo;.  Such a section
37172 may not be included in the Modified Version.
37173
37174 </li><li> Do not retitle any existing section to be Entitled &ldquo;Endorsements&rdquo; or
37175 to conflict in title with any Invariant Section.
37176
37177 </li><li> Preserve any Warranty Disclaimers.
37178 </li></ol>
37179
37180 <p>If the Modified Version includes new front-matter sections or
37181 appendices that qualify as Secondary Sections and contain no material
37182 copied from the Document, you may at your option designate some or all
37183 of these sections as invariant.  To do this, add their titles to the
37184 list of Invariant Sections in the Modified Version&rsquo;s license notice.
37185 These titles must be distinct from any other section titles.
37186 </p>
37187 <p>You may add a section Entitled &ldquo;Endorsements&rdquo;, provided it contains
37188 nothing but endorsements of your Modified Version by various
37189 parties&mdash;for example, statements of peer review or that the text has
37190 been approved by an organization as the authoritative definition of a
37191 standard.
37192 </p>
37193 <p>You may add a passage of up to five words as a Front-Cover Text, and a
37194 passage of up to 25 words as a Back-Cover Text, to the end of the list
37195 of Cover Texts in the Modified Version.  Only one passage of
37196 Front-Cover Text and one of Back-Cover Text may be added by (or
37197 through arrangements made by) any one entity.  If the Document already
37198 includes a cover text for the same cover, previously added by you or
37199 by arrangement made by the same entity you are acting on behalf of,
37200 you may not add another; but you may replace the old one, on explicit
37201 permission from the previous publisher that added the old one.
37202 </p>
37203 <p>The author(s) and publisher(s) of the Document do not by this License
37204 give permission to use their names for publicity for or to assert or
37205 imply endorsement of any Modified Version.
37206 </p>
37207 </li><li> COMBINING DOCUMENTS
37208
37209 <p>You may combine the Document with other documents released under this
37210 License, under the terms defined in section 4 above for modified
37211 versions, provided that you include in the combination all of the
37212 Invariant Sections of all of the original documents, unmodified, and
37213 list them all as Invariant Sections of your combined work in its
37214 license notice, and that you preserve all their Warranty Disclaimers.
37215 </p>
37216 <p>The combined work need only contain one copy of this License, and
37217 multiple identical Invariant Sections may be replaced with a single
37218 copy.  If there are multiple Invariant Sections with the same name but
37219 different contents, make the title of each such section unique by
37220 adding at the end of it, in parentheses, the name of the original
37221 author or publisher of that section if known, or else a unique number.
37222 Make the same adjustment to the section titles in the list of
37223 Invariant Sections in the license notice of the combined work.
37224 </p>
37225 <p>In the combination, you must combine any sections Entitled &ldquo;History&rdquo;
37226 in the various original documents, forming one section Entitled
37227 &ldquo;History&rdquo;; likewise combine any sections Entitled &ldquo;Acknowledgements&rdquo;,
37228 and any sections Entitled &ldquo;Dedications&rdquo;.  You must delete all
37229 sections Entitled &ldquo;Endorsements.&rdquo;
37230 </p>
37231 </li><li> COLLECTIONS OF DOCUMENTS
37232
37233 <p>You may make a collection consisting of the Document and other documents
37234 released under this License, and replace the individual copies of this
37235 License in the various documents with a single copy that is included in
37236 the collection, provided that you follow the rules of this License for
37237 verbatim copying of each of the documents in all other respects.
37238 </p>
37239 <p>You may extract a single document from such a collection, and distribute
37240 it individually under this License, provided you insert a copy of this
37241 License into the extracted document, and follow this License in all
37242 other respects regarding verbatim copying of that document.
37243 </p>
37244 </li><li> AGGREGATION WITH INDEPENDENT WORKS
37245
37246 <p>A compilation of the Document or its derivatives with other separate
37247 and independent documents or works, in or on a volume of a storage or
37248 distribution medium, is called an &ldquo;aggregate&rdquo; if the copyright
37249 resulting from the compilation is not used to limit the legal rights
37250 of the compilation&rsquo;s users beyond what the individual works permit.
37251 When the Document is included in an aggregate, this License does not
37252 apply to the other works in the aggregate which are not themselves
37253 derivative works of the Document.
37254 </p>
37255 <p>If the Cover Text requirement of section 3 is applicable to these
37256 copies of the Document, then if the Document is less than one half of
37257 the entire aggregate, the Document&rsquo;s Cover Texts may be placed on
37258 covers that bracket the Document within the aggregate, or the
37259 electronic equivalent of covers if the Document is in electronic form.
37260 Otherwise they must appear on printed covers that bracket the whole
37261 aggregate.
37262 </p>
37263 </li><li> TRANSLATION
37264
37265 <p>Translation is considered a kind of modification, so you may
37266 distribute translations of the Document under the terms of section 4.
37267 Replacing Invariant Sections with translations requires special
37268 permission from their copyright holders, but you may include
37269 translations of some or all Invariant Sections in addition to the
37270 original versions of these Invariant Sections.  You may include a
37271 translation of this License, and all the license notices in the
37272 Document, and any Warranty Disclaimers, provided that you also include
37273 the original English version of this License and the original versions
37274 of those notices and disclaimers.  In case of a disagreement between
37275 the translation and the original version of this License or a notice
37276 or disclaimer, the original version will prevail.
37277 </p>
37278 <p>If a section in the Document is Entitled &ldquo;Acknowledgements&rdquo;,
37279 &ldquo;Dedications&rdquo;, or &ldquo;History&rdquo;, the requirement (section 4) to Preserve
37280 its Title (section 1) will typically require changing the actual
37281 title.
37282 </p>
37283 </li><li> TERMINATION
37284
37285 <p>You may not copy, modify, sublicense, or distribute the Document
37286 except as expressly provided under this License.  Any attempt
37287 otherwise to copy, modify, sublicense, or distribute it is void, and
37288 will automatically terminate your rights under this License.
37289 </p>
37290 <p>However, if you cease all violation of this License, then your license
37291 from a particular copyright holder is reinstated (a) provisionally,
37292 unless and until the copyright holder explicitly and finally
37293 terminates your license, and (b) permanently, if the copyright holder
37294 fails to notify you of the violation by some reasonable means prior to
37295 60 days after the cessation.
37296 </p>
37297 <p>Moreover, your license from a particular copyright holder is
37298 reinstated permanently if the copyright holder notifies you of the
37299 violation by some reasonable means, this is the first time you have
37300 received notice of violation of this License (for any work) from that
37301 copyright holder, and you cure the violation prior to 30 days after
37302 your receipt of the notice.
37303 </p>
37304 <p>Termination of your rights under this section does not terminate the
37305 licenses of parties who have received copies or rights from you under
37306 this License.  If your rights have been terminated and not permanently
37307 reinstated, receipt of a copy of some or all of the same material does
37308 not give you any rights to use it.
37309 </p>
37310 </li><li> FUTURE REVISIONS OF THIS LICENSE
37311
37312 <p>The Free Software Foundation may publish new, revised versions
37313 of the GNU Free Documentation License from time to time.  Such new
37314 versions will be similar in spirit to the present version, but may
37315 differ in detail to address new problems or concerns.  See
37316 <a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>.
37317 </p>
37318 <p>Each version of the License is given a distinguishing version number.
37319 If the Document specifies that a particular numbered version of this
37320 License &ldquo;or any later version&rdquo; applies to it, you have the option of
37321 following the terms and conditions either of that specified version or
37322 of any later version that has been published (not as a draft) by the
37323 Free Software Foundation.  If the Document does not specify a version
37324 number of this License, you may choose any version ever published (not
37325 as a draft) by the Free Software Foundation.  If the Document
37326 specifies that a proxy can decide which future versions of this
37327 License can be used, that proxy&rsquo;s public statement of acceptance of a
37328 version permanently authorizes you to choose that version for the
37329 Document.
37330 </p>
37331 </li><li> RELICENSING
37332
37333 <p>&ldquo;Massive Multiauthor Collaboration Site&rdquo; (or &ldquo;MMC Site&rdquo;) means any
37334 World Wide Web server that publishes copyrightable works and also
37335 provides prominent facilities for anybody to edit those works.  A
37336 public wiki that anybody can edit is an example of such a server.  A
37337 &ldquo;Massive Multiauthor Collaboration&rdquo; (or &ldquo;MMC&rdquo;) contained in the
37338 site means any set of copyrightable works thus published on the MMC
37339 site.
37340 </p>
37341 <p>&ldquo;CC-BY-SA&rdquo; means the Creative Commons Attribution-Share Alike 3.0
37342 license published by Creative Commons Corporation, a not-for-profit
37343 corporation with a principal place of business in San Francisco,
37344 California, as well as future copyleft versions of that license
37345 published by that same organization.
37346 </p>
37347 <p>&ldquo;Incorporate&rdquo; means to publish or republish a Document, in whole or
37348 in part, as part of another Document.
37349 </p>
37350 <p>An MMC is &ldquo;eligible for relicensing&rdquo; if it is licensed under this
37351 License, and if all works that were first published under this License
37352 somewhere other than this MMC, and subsequently incorporated in whole
37353 or in part into the MMC, (1) had no cover texts or invariant sections,
37354 and (2) were thus incorporated prior to November 1, 2008.
37355 </p>
37356 <p>The operator of an MMC Site may republish an MMC contained in the site
37357 under CC-BY-SA on the same site at any time before August 1, 2009,
37358 provided the MMC is eligible for relicensing.
37359 </p>
37360 </li></ol>
37361
37362 <a name="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></a>
37363 <h3 class="heading">ADDENDUM: How to use this License for your documents</h3>
37364
37365 <p>To use this License in a document you have written, include a copy of
37366 the License in the document and put the following copyright and
37367 license notices just after the title page:
37368 </p>
37369 <div class="example">
37370 <pre class="example">  Copyright (C)  <var>year</var>  <var>your name</var>.
37371   Permission is granted to copy, distribute and/or modify this document
37372   under the terms of the GNU Free Documentation License, Version 1.3
37373   or any later version published by the Free Software Foundation;
37374   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
37375   Texts.  A copy of the license is included in the section entitled ``GNU
37376   Free Documentation License''.
37377 </pre></div>
37378
37379 <p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
37380 replace the &ldquo;with&hellip;Texts.&rdquo; line with this:
37381 </p>
37382 <div class="example">
37383 <pre class="example">    with the Invariant Sections being <var>list their titles</var>, with
37384     the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts
37385     being <var>list</var>.
37386 </pre></div>
37387
37388 <p>If you have Invariant Sections without Cover Texts, or some other
37389 combination of the three, merge those two alternatives to suit the
37390 situation.
37391 </p>
37392 <p>If your document contains nontrivial examples of program code, we
37393 recommend releasing these examples in parallel under your choice of
37394 free software license, such as the GNU General Public License,
37395 to permit their use in free software.
37396 </p>
37397
37398
37399
37400 <hr>
37401 <a name="Bibliography"></a>
37402 <div class="header">
37403 <p>
37404 Next: <a href="#Function-and-Data-Index" accesskey="n" rel="next">Function and Data Index</a>, Previous: <a href="#Copying-Information" accesskey="p" rel="prev">Copying Information</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
37405 </div>
37406 <a name="Bibliography-1"></a>
37407 <h2 class="unnumbered">Bibliography</h2>
37408
37409 <dl compact="compact">
37410 <dt><a name="CBCATT"></a>[CBCATT]</dt>
37411 <dd><p>Bodo Moeller, &quot;Security of CBC Ciphersuites in SSL/TLS: Problems and
37412 Countermeasures&quot;, 2002, available from
37413 <a href="http://www.openssl.org/~bodo/tls-cbc.txt">http://www.openssl.org/~bodo/tls-cbc.txt</a>.
37414 </p>
37415 </dd>
37416 <dt><a name="GPGH"></a>[GPGH]</dt>
37417 <dd><p>Mike Ashley, &quot;The GNU Privacy Handbook&quot;, 2002, available from
37418 <a href="http://www.gnupg.org/gph/en/manual.pdf">http://www.gnupg.org/gph/en/manual.pdf</a>.
37419 </p>
37420 </dd>
37421 <dt><a name="GUTPKI"></a>[GUTPKI]</dt>
37422 <dd><p>Peter Gutmann, &quot;Everything you never wanted to know about PKI but were
37423 forced to find out&quot;, Available from
37424 <a href="http://www.cs.auckland.ac.nz/~pgut001/">http://www.cs.auckland.ac.nz/~pgut001/</a>.
37425 </p>
37426 </dd>
37427 <dt><a name="KEYPIN"></a>[KEYPIN]</dt>
37428 <dd><p>Chris Evans and Chris Palmer, &quot;Public Key Pinning Extension for HTTP&quot;,
37429 Available from <a href="http://tools.ietf.org/html/draft-ietf-websec-key-pinning-01">http://tools.ietf.org/html/draft-ietf-websec-key-pinning-01</a>.
37430 </p>
37431 </dd>
37432 <dt><a name="NISTSP80057"></a>[NISTSP80057]</dt>
37433 <dd><p>NIST Special Publication 800-57, &quot;Recommendation for Key Management -
37434 Part 1: General (Revised)&quot;, March 2007, available from
37435 <a href="http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf">http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf</a>.
37436 </p>
37437 </dd>
37438 <dt><a name="RFC2246"></a>[RFC2246]</dt>
37439 <dd><p>Tim Dierks and Christopher Allen, &quot;The TLS Protocol Version 1.0&quot;,
37440 January 1999, Available from
37441 <a href="http://www.ietf.org/rfc/rfc2246.txt">http://www.ietf.org/rfc/rfc2246.txt</a>.
37442 </p>
37443 </dd>
37444 <dt><a name="RFC4418"></a>[RFC4418]</dt>
37445 <dd><p>Ted Krovetz, &quot;UMAC: Message Authentication Code using Universal Hashing&quot;,
37446 March 2006, Available from
37447 <a href="http://www.ietf.org/rfc/rfc4418.txt">http://www.ietf.org/rfc/rfc4418.txt</a>.
37448 </p>
37449 </dd>
37450 <dt><a name="RFC4680"></a>[RFC4680]</dt>
37451 <dd><p>S. Santesson, &quot;TLS Handshake Message for Supplemental Data&quot;,
37452 September 2006, Available from
37453 <a href="http://www.ietf.org/rfc/rfc4680.txt">http://www.ietf.org/rfc/rfc4680.txt</a>.
37454 </p>
37455 </dd>
37456 <dt><a name="RFC4514"></a>[RFC4514]</dt>
37457 <dd><p>Kurt D.  Zeilenga, &quot;Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names&quot;,
37458 June 2006, Available from
37459 <a href="http://www.ietf.org/rfc/rfc4513.txt">http://www.ietf.org/rfc/rfc4513.txt</a>.
37460 </p>
37461 </dd>
37462 <dt><a name="RFC4346"></a>[RFC4346]</dt>
37463 <dd><p>Tim Dierks and Eric Rescorla, &quot;The TLS Protocol Version 1.1&quot;, Match
37464 2006, Available from <a href="http://www.ietf.org/rfc/rfc4346.txt">http://www.ietf.org/rfc/rfc4346.txt</a>.
37465 </p>
37466 </dd>
37467 <dt><a name="RFC4347"></a>[RFC4347]</dt>
37468 <dd><p>Eric Rescorla and Nagendra Modadugu, &quot;Datagram Transport Layer Security&quot;, April
37469 2006, Available from <a href="http://www.ietf.org/rfc/rfc4347.txt">http://www.ietf.org/rfc/rfc4347.txt</a>.
37470 </p>
37471 </dd>
37472 <dt><a name="RFC5246"></a>[RFC5246]</dt>
37473 <dd><p>Tim Dierks and Eric Rescorla, &quot;The TLS Protocol Version 1.2&quot;, August
37474 2008, Available from <a href="http://www.ietf.org/rfc/rfc5246.txt">http://www.ietf.org/rfc/rfc5246.txt</a>.
37475 </p>
37476 </dd>
37477 <dt><a name="RFC2440"></a>[RFC2440]</dt>
37478 <dd><p>Jon Callas, Lutz Donnerhacke, Hal Finney and Rodney Thayer, &quot;OpenPGP
37479 Message Format&quot;, November 1998, Available from
37480 <a href="http://www.ietf.org/rfc/rfc2440.txt">http://www.ietf.org/rfc/rfc2440.txt</a>.
37481 </p>
37482 </dd>
37483 <dt><a name="RFC4880"></a>[RFC4880]</dt>
37484 <dd><p>Jon Callas, Lutz Donnerhacke, Hal Finney, David Shaw and Rodney
37485 Thayer, &quot;OpenPGP Message Format&quot;, November 2007, Available from
37486 <a href="http://www.ietf.org/rfc/rfc4880.txt">http://www.ietf.org/rfc/rfc4880.txt</a>.
37487 </p>
37488 </dd>
37489 <dt><a name="RFC4211"></a>[RFC4211]</dt>
37490 <dd><p>J. Schaad, &quot;Internet X.509 Public Key Infrastructure Certificate
37491 Request Message Format (CRMF)&quot;, September 2005, Available from
37492 <a href="http://www.ietf.org/rfc/rfc4211.txt">http://www.ietf.org/rfc/rfc4211.txt</a>.
37493 </p>
37494 </dd>
37495 <dt><a name="RFC2817"></a>[RFC2817]</dt>
37496 <dd><p>Rohit Khare and Scott Lawrence, &quot;Upgrading to TLS Within HTTP/1.1&quot;,
37497 May 2000, Available from <a href="http://www.ietf.org/rfc/rfc2817.txt">http://www.ietf.org/rfc/rfc2817.txt</a>
37498 </p>
37499 </dd>
37500 <dt><a name="RFC2818"></a>[RFC2818]</dt>
37501 <dd><p>Eric Rescorla, &quot;HTTP Over TLS&quot;, May 2000, Available from
37502 <a href="http://www.ietf/rfc/rfc2818.txt">http://www.ietf/rfc/rfc2818.txt</a>.
37503 </p>
37504 </dd>
37505 <dt><a name="RFC2945"></a>[RFC2945]</dt>
37506 <dd><p>Tom Wu, &quot;The SRP Authentication and Key Exchange System&quot;, September
37507 2000, Available from <a href="http://www.ietf.org/rfc/rfc2945.txt">http://www.ietf.org/rfc/rfc2945.txt</a>.
37508 </p>
37509 </dd>
37510 <dt><a name="RFC2986"></a>[RFC2986]</dt>
37511 <dd><p>Magnus Nystrom and Burt Kaliski, &quot;PKCS 10 v1.7: Certification Request
37512 Syntax Specification&quot;, November 2000, Available from
37513 <a href="http://www.ietf.org/rfc/rfc2986.txt">http://www.ietf.org/rfc/rfc2986.txt</a>.
37514 </p>
37515 </dd>
37516 <dt><a name="PKIX"></a>[PKIX]</dt>
37517 <dd><p>D. Cooper, S. Santesson, S. Farrel, S. Boeyen, R. Housley, W. Polk,
37518 &quot;Internet X.509 Public Key Infrastructure Certificate and Certificate
37519 Revocation List (CRL) Profile&quot;, May 2008, available from
37520 <a href="http://www.ietf.org/rfc/rfc5280.txt">http://www.ietf.org/rfc/rfc5280.txt</a>.
37521 </p>
37522 </dd>
37523 <dt><a name="RFC3749"></a>[RFC3749]</dt>
37524 <dd><p>Scott Hollenbeck, &quot;Transport Layer Security Protocol Compression
37525 Methods&quot;, May 2004, available from
37526 <a href="http://www.ietf.org/rfc/rfc3749.txt">http://www.ietf.org/rfc/rfc3749.txt</a>.
37527 </p>
37528 </dd>
37529 <dt><a name="RFC3820"></a>[RFC3820]</dt>
37530 <dd><p>Steven Tuecke, Von Welch, Doug Engert, Laura Pearlman, and Mary
37531 Thompson, &quot;Internet X.509 Public Key Infrastructure (PKI) Proxy
37532 Certificate Profile&quot;, June 2004, available from
37533 <a href="http://www.ietf.org/rfc/rfc3820">http://www.ietf.org/rfc/rfc3820</a>.
37534 </p>
37535 </dd>
37536 <dt><a name="RFC6520"></a>[RFC6520]</dt>
37537 <dd><p>R. Seggelmann, M. Tuexen, and M. Williams, &quot;Transport Layer Security (TLS) and
37538 Datagram Transport Layer Security (DTLS) Heartbeat Extension&quot;, February 2012, available from
37539 <a href="http://www.ietf.org/rfc/rfc6520">http://www.ietf.org/rfc/rfc6520</a>.
37540 </p>
37541
37542 </dd>
37543 <dt><a name="RFC5746"></a>[RFC5746]</dt>
37544 <dd><p>E. Rescorla, M. Ray, S. Dispensa, and N. Oskov, &quot;Transport Layer
37545 Security (TLS) Renegotiation Indication Extension&quot;, February 2010,
37546 available from <a href="http://www.ietf.org/rfc/rfc5746">http://www.ietf.org/rfc/rfc5746</a>.
37547 </p>
37548 </dd>
37549 <dt><a name="RFC5280"></a>[RFC5280]</dt>
37550 <dd><p>D. Cooper, S. Santesson, S. Farrell, S. Boeyen, R. Housley, and
37551 W. Polk, &quot;Internet X.509 Public Key Infrastructure Certificate and
37552 Certificate Revocation List (CRL) Profile&quot;, May 2008, available from
37553 <a href="http://www.ietf.org/rfc/rfc5280">http://www.ietf.org/rfc/rfc5280</a>.
37554 </p>
37555 </dd>
37556 <dt><a name="TLSTKT"></a>[TLSTKT]</dt>
37557 <dd><p>Joseph Salowey, Hao Zhou, Pasi Eronen, Hannes Tschofenig, &quot;Transport
37558 Layer Security (TLS) Session Resumption without Server-Side State&quot;,
37559 January 2008, available from <a href="http://www.ietf.org/rfc/rfc5077">http://www.ietf.org/rfc/rfc5077</a>.
37560 </p>
37561 </dd>
37562 <dt><a name="PKCS12"></a>[PKCS12]</dt>
37563 <dd><p>RSA Laboratories, &quot;PKCS 12 v1.0: Personal Information Exchange
37564 Syntax&quot;, June 1999, Available from <a href="http://www.rsa.com">http://www.rsa.com</a>.
37565 </p>
37566 </dd>
37567 <dt><a name="PKCS11"></a>[PKCS11]</dt>
37568 <dd><p>RSA Laboratories, &quot;PKCS #11 Base Functionality v2.30: Cryptoki â\80\93 Draft 4&quot;,
37569 July 2009, Available from <a href="http://www.rsa.com">http://www.rsa.com</a>.
37570 </p>
37571 </dd>
37572 <dt><a name="RESCORLA"></a>[RESCORLA]</dt>
37573 <dd><p>Eric Rescorla, &quot;SSL and TLS: Designing and Building Secure Systems&quot;,
37574 2001
37575 </p>
37576 </dd>
37577 <dt><a name="SELKEY"></a>[SELKEY]</dt>
37578 <dd><p>Arjen Lenstra and Eric Verheul, &quot;Selecting Cryptographic Key Sizes&quot;,
37579 2003, available from <a href="http://www.win.tue.nl/~klenstra/key.pdf">http://www.win.tue.nl/~klenstra/key.pdf</a>.
37580 </p>
37581 </dd>
37582 <dt><a name="SSL3"></a>[SSL3]</dt>
37583 <dd><p>Alan Freier, Philip Karlton and Paul Kocher, &quot;The Secure Sockets Layer (SSL) Protocol Version 3.0&quot;,
37584 August 2011, Available from <a href="http://www.ietf.org/rfc/rfc6101.txt">http://www.ietf.org/rfc/rfc6101.txt</a>.
37585 </p>
37586 </dd>
37587 <dt><a name="STEVENS"></a>[STEVENS]</dt>
37588 <dd><p>Richard Stevens, &quot;UNIX Network Programming, Volume 1&quot;, Prentice Hall
37589 PTR, January 1998
37590 </p>
37591 </dd>
37592 <dt><a name="TLSEXT"></a>[TLSEXT]</dt>
37593 <dd><p>Simon Blake-Wilson, Magnus Nystrom, David Hopwood, Jan Mikkelsen and
37594 Tim Wright, &quot;Transport Layer Security (TLS) Extensions&quot;, June 2003,
37595 Available from <a href="http://www.ietf.org/rfc/rfc3546.txt">http://www.ietf.org/rfc/rfc3546.txt</a>.
37596 </p>
37597 </dd>
37598 <dt><a name="TLSPGP"></a>[TLSPGP]</dt>
37599 <dd><p>Nikos Mavrogiannopoulos, &quot;Using OpenPGP keys for TLS authentication&quot;,
37600 January 2011. Available from
37601 <a href="http://www.ietf.org/rfc/rfc6091.txt">http://www.ietf.org/rfc/rfc6091.txt</a>.
37602 </p>
37603 </dd>
37604 <dt><a name="TLSSRP"></a>[TLSSRP]</dt>
37605 <dd><p>David Taylor, Trevor Perrin, Tom Wu and Nikos Mavrogiannopoulos,
37606 &quot;Using SRP for TLS Authentication&quot;, November 2007. Available from
37607 <a href="http://www.ietf.org/rfc/rfc5054.txt">http://www.ietf.org/rfc/rfc5054.txt</a>.
37608 </p>
37609 </dd>
37610 <dt><a name="TLSPSK"></a>[TLSPSK]</dt>
37611 <dd><p>Pasi Eronen and Hannes Tschofenig, &quot;Pre-shared key Ciphersuites for
37612 TLS&quot;, December 2005, Available from
37613 <a href="http://www.ietf.org/rfc/rfc4279.txt">http://www.ietf.org/rfc/rfc4279.txt</a>.
37614 </p>
37615 </dd>
37616 <dt><a name="TOMSRP"></a>[TOMSRP]</dt>
37617 <dd><p>Tom Wu, &quot;The Stanford SRP Authentication Project&quot;, Available at
37618 <a href="http://srp.stanford.edu/">http://srp.stanford.edu/</a>.
37619 </p>
37620 </dd>
37621 <dt><a name="WEGER"></a>[WEGER]</dt>
37622 <dd><p>Arjen Lenstra and Xiaoyun Wang and Benne de Weger, &quot;Colliding X.509
37623 Certificates&quot;, Cryptology ePrint Archive, Report 2005/067, Available
37624 at <a href="http://eprint.iacr.org/">http://eprint.iacr.org/</a>.
37625 </p>
37626 </dd>
37627 <dt><a name="ECRYPT"></a>[ECRYPT]</dt>
37628 <dd><p>European Network of Excellence in Cryptology II, &quot;ECRYPT II Yearly
37629 Report on Algorithms and Keysizes (2009-2010)&quot;, Available
37630 at <a href="http://www.ecrypt.eu.org/documents/D.SPA.13.pdf">http://www.ecrypt.eu.org/documents/D.SPA.13.pdf</a>.
37631 </p>
37632 </dd>
37633 <dt><a name="RFC5056"></a>[RFC5056]</dt>
37634 <dd><p>N. Williams, &quot;On the Use of Channel Bindings to Secure Channels&quot;,
37635 November 2007, available from <a href="http://www.ietf.org/rfc/rfc5056">http://www.ietf.org/rfc/rfc5056</a>.
37636 </p>
37637 </dd>
37638 <dt><a name="RFC5929"></a>[RFC5929]</dt>
37639 <dd><p>J. Altman, N. Williams, L. Zhu, &quot;Channel Bindings for TLS&quot;, July 2010,
37640 available from <a href="http://www.ietf.org/rfc/rfc5929">http://www.ietf.org/rfc/rfc5929</a>.
37641 </p>
37642 </dd>
37643 <dt><a name="PKCS11URI"></a>[PKCS11URI]</dt>
37644 <dd><p>J. Pechanec, D. Moffat, &quot;The PKCS#11 URI Scheme&quot;, September 2013,
37645 Work in progress, available from <a href="http://tools.ietf.org/html/draft-pechanec-pkcs11uri-13">http://tools.ietf.org/html/draft-pechanec-pkcs11uri-13</a>.
37646 </p>
37647 </dd>
37648 <dt><a name="TPMURI"></a>[TPMURI]</dt>
37649 <dd><p>C. Latze, N. Mavrogiannopoulos, &quot;The TPMKEY URI Scheme&quot;, January 2013,
37650 Work in progress, available from <a href="http://tools.ietf.org/html/draft-mavrogiannopoulos-tpmuri-01">http://tools.ietf.org/html/draft-mavrogiannopoulos-tpmuri-01</a>.
37651 </p>
37652 </dd>
37653 <dt><a name="ANDERSON"></a>[ANDERSON]</dt>
37654 <dd><p>R. J. Anderson, &quot;Security Engineering: A Guide to Building Dependable Distributed Systems&quot;,
37655 John Wiley \&amp; Sons, Inc., 2001.
37656 </p>
37657 </dd>
37658 <dt><a name="RFC4821"></a>[RFC4821]</dt>
37659 <dd><p>M. Mathis, J. Heffner, &quot;Packetization Layer Path MTU Discovery&quot;, March 2007,
37660 available from <a href="http://www.ietf.org/rfc/rfc4821.txt">http://www.ietf.org/rfc/rfc4821.txt</a>.
37661 </p>
37662 </dd>
37663 <dt><a name="RFC2560"></a>[RFC2560]</dt>
37664 <dd><p>M. Myers et al, &quot;X.509 Internet Public Key Infrastructure Online
37665 Certificate Status Protocol - OCSP&quot;, June 1999, Available from
37666 <a href="http://www.ietf.org/rfc/rfc2560.txt">http://www.ietf.org/rfc/rfc2560.txt</a>.
37667 </p>
37668 </dd>
37669 <dt><a name="RIVESTCRL"></a>[RIVESTCRL]</dt>
37670 <dd><p>R. L. Rivest, &quot;Can We Eliminate Certificate Revocation Lists?&quot;,
37671 Proceedings of Financial Cryptography &rsquo;98; Springer Lecture Notes in
37672 Computer Science No. 1465 (Rafael Hirschfeld, ed.), February 1998),
37673 pages 178&ndash;183, available from
37674 <a href="http://people.csail.mit.edu/rivest/Rivest-CanWeEliminateCertificateRevocationLists.pdf">http://people.csail.mit.edu/rivest/Rivest-CanWeEliminateCertificateRevocationLists.pdf</a>.
37675 </p>
37676 </dd>
37677 </dl>
37678
37679 <hr>
37680 <a name="Function-and-Data-Index"></a>
37681 <div class="header">
37682 <p>
37683 Next: <a href="#Concept-Index" accesskey="n" rel="next">Concept Index</a>, Previous: <a href="#Bibliography" accesskey="p" rel="prev">Bibliography</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
37684 </div>
37685 <a name="Function-and-Data-Index-1"></a>
37686 <h2 class="unnumbered">Function and Data Index</h2>
37687
37688 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Function-and-Data-Index_fn_letter-D"><b>D</b></a>
37689  &nbsp;
37690 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-G"><b>G</b></a>
37691  &nbsp;
37692 </td></tr></table>
37693 <table class="index-fn" border="0">
37694 <tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
37695 <tr><td colspan="4"> <hr></td></tr>
37696 <tr><th><a name="Function-and-Data-Index_fn_letter-D">D</a></th><td></td><td></td></tr>
37697 <tr><td></td><td valign="top"><a href="#index-dane_005fcert_005ftype_005fname"><code>dane_cert_type_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37698 <tr><td></td><td valign="top"><a href="#index-dane_005fcert_005fusage_005fname"><code>dane_cert_usage_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37699 <tr><td></td><td valign="top"><a href="#index-dane_005fmatch_005ftype_005fname"><code>dane_match_type_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37700 <tr><td></td><td valign="top"><a href="#index-dane_005fquery_005fdata"><code>dane_query_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37701 <tr><td></td><td valign="top"><a href="#index-dane_005fquery_005fdeinit"><code>dane_query_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37702 <tr><td></td><td valign="top"><a href="#index-dane_005fquery_005fentries"><code>dane_query_entries</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37703 <tr><td></td><td valign="top"><a href="#index-dane_005fquery_005fstatus"><code>dane_query_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37704 <tr><td></td><td valign="top"><a href="#index-dane_005fquery_005ftlsa"><code>dane_query_tlsa</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37705 <tr><td></td><td valign="top"><a href="#index-dane_005fquery_005fto_005fraw_005ftlsa"><code>dane_query_to_raw_tlsa</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37706 <tr><td></td><td valign="top"><a href="#index-dane_005fraw_005ftlsa"><code>dane_raw_tlsa</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37707 <tr><td></td><td valign="top"><a href="#index-dane_005fstate_005fdeinit"><code>dane_state_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37708 <tr><td></td><td valign="top"><a href="#index-dane_005fstate_005finit"><code>dane_state_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37709 <tr><td></td><td valign="top"><a href="#index-dane_005fstate_005fset_005fdlv_005ffile"><code>dane_state_set_dlv_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37710 <tr><td></td><td valign="top"><a href="#index-dane_005fstrerror"><code>dane_strerror</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37711 <tr><td></td><td valign="top"><a href="#index-dane_005fverification_005fstatus_005fprint"><code>dane_verification_status_print</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37712 <tr><td></td><td valign="top"><a href="#index-dane_005fverify_005fcrt"><code>dane_verify_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-verification">Certificate verification</a></td></tr>
37713 <tr><td></td><td valign="top"><a href="#index-dane_005fverify_005fcrt-1"><code>dane_verify_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37714 <tr><td></td><td valign="top"><a href="#index-dane_005fverify_005fcrt_005fraw"><code>dane_verify_crt_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37715 <tr><td></td><td valign="top"><a href="#index-dane_005fverify_005fsession_005fcrt"><code>dane_verify_session_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DANE-API">DANE API</a></td></tr>
37716 <tr><td colspan="4"> <hr></td></tr>
37717 <tr><th><a name="Function-and-Data-Index_fn_letter-G">G</a></th><td></td><td></td></tr>
37718 <tr><td></td><td valign="top"><a href="#index-gnutls_005falert_005fget"><code>gnutls_alert_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Handling-alerts">Handling alerts</a></td></tr>
37719 <tr><td></td><td valign="top"><a href="#index-gnutls_005falert_005fget-1"><code>gnutls_alert_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37720 <tr><td></td><td valign="top"><a href="#index-gnutls_005falert_005fget_005fname"><code>gnutls_alert_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Handling-alerts">Handling alerts</a></td></tr>
37721 <tr><td></td><td valign="top"><a href="#index-gnutls_005falert_005fget_005fname-1"><code>gnutls_alert_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37722 <tr><td></td><td valign="top"><a href="#index-gnutls_005falert_005fget_005fstrname"><code>gnutls_alert_get_strname</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37723 <tr><td></td><td valign="top"><a href="#index-gnutls_005falert_005fsend"><code>gnutls_alert_send</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Handling-alerts">Handling alerts</a></td></tr>
37724 <tr><td></td><td valign="top"><a href="#index-gnutls_005falert_005fsend-1"><code>gnutls_alert_send</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37725 <tr><td></td><td valign="top"><a href="#index-gnutls_005falert_005fsend_005fappropriate"><code>gnutls_alert_send_appropriate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37726 <tr><td></td><td valign="top"><a href="#index-gnutls_005falpn_005fget_005fselected_005fprotocol"><code>gnutls_alpn_get_selected_protocol</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37727 <tr><td></td><td valign="top"><a href="#index-gnutls_005falpn_005fset_005fprotocols"><code>gnutls_alpn_set_protocols</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37728 <tr><td></td><td valign="top"><a href="#index-gnutls_005fanon_005fallocate_005fclient_005fcredentials"><code>gnutls_anon_allocate_client_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37729 <tr><td></td><td valign="top"><a href="#index-gnutls_005fanon_005fallocate_005fserver_005fcredentials"><code>gnutls_anon_allocate_server_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37730 <tr><td></td><td valign="top"><a href="#index-gnutls_005fanon_005ffree_005fclient_005fcredentials"><code>gnutls_anon_free_client_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37731 <tr><td></td><td valign="top"><a href="#index-gnutls_005fanon_005ffree_005fserver_005fcredentials"><code>gnutls_anon_free_server_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37732 <tr><td></td><td valign="top"><a href="#index-gnutls_005fanon_005fset_005fparams_005ffunction"><code>gnutls_anon_set_params_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37733 <tr><td></td><td valign="top"><a href="#index-gnutls_005fanon_005fset_005fserver_005fdh_005fparams"><code>gnutls_anon_set_server_dh_params</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37734 <tr><td></td><td valign="top"><a href="#index-gnutls_005fanon_005fset_005fserver_005fparams_005ffunction"><code>gnutls_anon_set_server_params_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37735 <tr><td></td><td valign="top"><a href="#index-gnutls_005fauth_005fclient_005fget_005ftype"><code>gnutls_auth_client_get_type</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37736 <tr><td></td><td valign="top"><a href="#index-gnutls_005fauth_005fget_005ftype"><code>gnutls_auth_get_type</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37737 <tr><td></td><td valign="top"><a href="#index-gnutls_005fauth_005fserver_005fget_005ftype"><code>gnutls_auth_server_get_type</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37738 <tr><td></td><td valign="top"><a href="#index-gnutls_005fbye"><code>gnutls_bye</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Data-transfer-and-termination">Data transfer and termination</a></td></tr>
37739 <tr><td></td><td valign="top"><a href="#index-gnutls_005fbye-1"><code>gnutls_bye</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37740 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005factivation_005ftime_005fpeers"><code>gnutls_certificate_activation_time_peers</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37741 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fallocate_005fcredentials"><code>gnutls_certificate_allocate_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37742 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fclient_005fget_005frequest_005fstatus"><code>gnutls_certificate_client_get_request_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37743 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fclient_005fset_005fretrieve_005ffunction"><code>gnutls_certificate_client_set_retrieve_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
37744 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fexpiration_005ftime_005fpeers"><code>gnutls_certificate_expiration_time_peers</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37745 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005ffree_005fcas"><code>gnutls_certificate_free_cas</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37746 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005ffree_005fca_005fnames"><code>gnutls_certificate_free_ca_names</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37747 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005ffree_005fcredentials"><code>gnutls_certificate_free_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37748 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005ffree_005fcrls"><code>gnutls_certificate_free_crls</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37749 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005ffree_005fkeys"><code>gnutls_certificate_free_keys</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37750 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fget_005fcrt_005fraw"><code>gnutls_certificate_get_crt_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37751 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fget_005fissuer"><code>gnutls_certificate_get_issuer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37752 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fget_005fours"><code>gnutls_certificate_get_ours</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37753 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fget_005fpeers"><code>gnutls_certificate_get_peers</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37754 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fget_005fpeers_005fsubkey_005fid"><code>gnutls_certificate_get_peers_subkey_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37755 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fsend_005fx509_005frdn_005fsequence"><code>gnutls_certificate_send_x509_rdn_sequence</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-credentials">Certificate credentials</a></td></tr>
37756 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fsend_005fx509_005frdn_005fsequence-1"><code>gnutls_certificate_send_x509_rdn_sequence</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37757 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fserver_005fset_005frequest"><code>gnutls_certificate_server_set_request</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-credentials">Certificate credentials</a></td></tr>
37758 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fserver_005fset_005frequest-1"><code>gnutls_certificate_server_set_request</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37759 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fserver_005fset_005fretrieve_005ffunction"><code>gnutls_certificate_server_set_retrieve_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
37760 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fdh_005fparams"><code>gnutls_certificate_set_dh_params</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37761 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fkey"><code>gnutls_certificate_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-credentials">Certificate credentials</a></td></tr>
37762 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fkey-1"><code>gnutls_certificate_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
37763 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005focsp_005fstatus_005frequest_005ffile"><code>gnutls_certificate_set_ocsp_status_request_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37764 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005focsp_005fstatus_005frequest_005ffunction"><code>gnutls_certificate_set_ocsp_status_request_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37765 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fopenpgp_005fkey"><code>gnutls_certificate_set_openpgp_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37766 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005ffile"><code>gnutls_certificate_set_openpgp_keyring_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-certificates">OpenPGP certificates</a></td></tr>
37767 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005ffile-1"><code>gnutls_certificate_set_openpgp_keyring_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37768 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005fmem"><code>gnutls_certificate_set_openpgp_keyring_mem</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37769 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile"><code>gnutls_certificate_set_openpgp_key_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37770 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile2"><code>gnutls_certificate_set_openpgp_key_file2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37771 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005fmem"><code>gnutls_certificate_set_openpgp_key_mem</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37772 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005fmem2"><code>gnutls_certificate_set_openpgp_key_mem2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37773 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fparams_005ffunction"><code>gnutls_certificate_set_params_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Parameter-generation">Parameter generation</a></td></tr>
37774 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fparams_005ffunction-1"><code>gnutls_certificate_set_params_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37775 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fpin_005ffunction"><code>gnutls_certificate_set_pin_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-credentials">Certificate credentials</a></td></tr>
37776 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fpin_005ffunction-1"><code>gnutls_certificate_set_pin_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37777 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fretrieve_005ffunction"><code>gnutls_certificate_set_retrieve_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37778 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fretrieve_005ffunction2"><code>gnutls_certificate_set_retrieve_function2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
37779 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005frsa_005fexport_005fparams"><code>gnutls_certificate_set_rsa_export_params</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
37780 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005ftrust_005flist"><code>gnutls_certificate_set_trust_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
37781 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fverify_005fflags"><code>gnutls_certificate_set_verify_flags</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37782 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fverify_005ffunction"><code>gnutls_certificate_set_verify_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-credentials">Certificate credentials</a></td></tr>
37783 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fverify_005ffunction-1"><code>gnutls_certificate_set_verify_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37784 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fverify_005flimits"><code>gnutls_certificate_set_verify_limits</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37785 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005fcrl"><code>gnutls_certificate_set_x509_crl</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37786 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005fcrl_005ffile"><code>gnutls_certificate_set_x509_crl_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37787 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005fcrl_005fmem"><code>gnutls_certificate_set_x509_crl_mem</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37788 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005fkey"><code>gnutls_certificate_set_x509_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37789 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile"><code>gnutls_certificate_set_x509_key_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37790 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile2"><code>gnutls_certificate_set_x509_key_file2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37791 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005fkey_005fmem"><code>gnutls_certificate_set_x509_key_mem</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37792 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005fkey_005fmem2"><code>gnutls_certificate_set_x509_key_mem2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37793 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005fsimple_005fpkcs12_005ffile"><code>gnutls_certificate_set_x509_simple_pkcs12_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37794 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005fsimple_005fpkcs12_005fmem"><code>gnutls_certificate_set_x509_simple_pkcs12_mem</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37795 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005fsystem_005ftrust"><code>gnutls_certificate_set_x509_system_trust</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Using-a-PKCS11-token-with-TLS">Using a PKCS11 token with TLS</a></td></tr>
37796 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005fsystem_005ftrust-1"><code>gnutls_certificate_set_x509_system_trust</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37797 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005ftrust"><code>gnutls_certificate_set_x509_trust</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37798 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005ftrust_005fdir"><code>gnutls_certificate_set_x509_trust_dir</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37799 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005ftrust_005ffile"><code>gnutls_certificate_set_x509_trust_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37800 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fset_005fx509_005ftrust_005fmem"><code>gnutls_certificate_set_x509_trust_mem</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37801 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005ftype_005fget"><code>gnutls_certificate_type_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37802 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005ftype_005fget_005fid"><code>gnutls_certificate_type_get_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37803 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005ftype_005fget_005fname"><code>gnutls_certificate_type_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37804 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005ftype_005flist"><code>gnutls_certificate_type_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37805 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005ftype_005fset_005fpriority"><code>gnutls_certificate_type_set_priority</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
37806 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fverification_005fstatus_005fprint"><code>gnutls_certificate_verification_status_print</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37807 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fverify_005fflags"><code>gnutls_certificate_verify_flags</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-a-certificate-in-the-context-of-TLS-session">Verifying a certificate in the context of TLS session</a></td></tr>
37808 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fverify_005fflags-1"><code>gnutls_certificate_verify_flags</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-verification">Certificate verification</a></td></tr>
37809 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fverify_005fpeers"><code>gnutls_certificate_verify_peers</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37810 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fverify_005fpeers2"><code>gnutls_certificate_verify_peers2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37811 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fverify_005fpeers3"><code>gnutls_certificate_verify_peers3</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-credentials">Certificate credentials</a></td></tr>
37812 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fverify_005fpeers3-1"><code>gnutls_certificate_verify_peers3</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37813 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcheck_005fversion"><code>gnutls_check_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37814 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fadd_005fauth"><code>gnutls_cipher_add_auth</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37815 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fdecrypt"><code>gnutls_cipher_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37816 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fdecrypt2"><code>gnutls_cipher_decrypt2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37817 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fdeinit"><code>gnutls_cipher_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37818 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fencrypt"><code>gnutls_cipher_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37819 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fencrypt2"><code>gnutls_cipher_encrypt2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37820 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fget"><code>gnutls_cipher_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37821 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fget_005fblock_005fsize"><code>gnutls_cipher_get_block_size</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37822 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fget_005fid"><code>gnutls_cipher_get_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37823 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fget_005fiv_005fsize"><code>gnutls_cipher_get_iv_size</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37824 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fget_005fkey_005fsize"><code>gnutls_cipher_get_key_size</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37825 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fget_005fname"><code>gnutls_cipher_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37826 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fget_005ftag_005fsize"><code>gnutls_cipher_get_tag_size</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37827 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005finit"><code>gnutls_cipher_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37828 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005flist"><code>gnutls_cipher_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37829 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fset_005fiv"><code>gnutls_cipher_set_iv</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37830 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fset_005fpriority"><code>gnutls_cipher_set_priority</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
37831 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fsuite_005fget_005fname"><code>gnutls_cipher_suite_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37832 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005fsuite_005finfo"><code>gnutls_cipher_suite_info</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37833 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcipher_005ftag"><code>gnutls_cipher_tag</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37834 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcompression_005fget"><code>gnutls_compression_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37835 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcompression_005fget_005fid"><code>gnutls_compression_get_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37836 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcompression_005fget_005fname"><code>gnutls_compression_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37837 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcompression_005flist"><code>gnutls_compression_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37838 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcompression_005fset_005fpriority"><code>gnutls_compression_set_priority</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
37839 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcredentials_005fclear"><code>gnutls_credentials_clear</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37840 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcredentials_005fget"><code>gnutls_credentials_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37841 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcredentials_005fset"><code>gnutls_credentials_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Session-initialization">Session initialization</a></td></tr>
37842 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcredentials_005fset-1"><code>gnutls_credentials_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37843 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdb_005fcheck_005fentry"><code>gnutls_db_check_entry</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37844 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdb_005fcheck_005fentry_005ftime"><code>gnutls_db_check_entry_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37845 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdb_005fget_005fdefault_005fcache_005fexpiration"><code>gnutls_db_get_default_cache_expiration</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37846 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdb_005fget_005fptr"><code>gnutls_db_get_ptr</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37847 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdb_005fremove_005fsession"><code>gnutls_db_remove_session</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37848 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdb_005fset_005fcache_005fexpiration"><code>gnutls_db_set_cache_expiration</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37849 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdb_005fset_005fptr"><code>gnutls_db_set_ptr</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37850 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdb_005fset_005fremove_005ffunction"><code>gnutls_db_set_remove_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37851 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdb_005fset_005fretrieve_005ffunction"><code>gnutls_db_set_retrieve_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37852 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdb_005fset_005fstore_005ffunction"><code>gnutls_db_set_store_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37853 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdeinit"><code>gnutls_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Data-transfer-and-termination">Data transfer and termination</a></td></tr>
37854 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdeinit-1"><code>gnutls_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37855 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fget_005fgroup"><code>gnutls_dh_get_group</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37856 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fget_005fpeers_005fpublic_005fbits"><code>gnutls_dh_get_peers_public_bits</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37857 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fget_005fprime_005fbits"><code>gnutls_dh_get_prime_bits</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37858 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fget_005fpubkey"><code>gnutls_dh_get_pubkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37859 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fget_005fsecret_005fbits"><code>gnutls_dh_get_secret_bits</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37860 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fparams_005fcpy"><code>gnutls_dh_params_cpy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37861 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fparams_005fdeinit"><code>gnutls_dh_params_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37862 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fparams_005fexport2_005fpkcs3"><code>gnutls_dh_params_export2_pkcs3</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37863 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fparams_005fexport_005fpkcs3"><code>gnutls_dh_params_export_pkcs3</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37864 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fparams_005fexport_005fraw"><code>gnutls_dh_params_export_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37865 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fparams_005fgenerate2"><code>gnutls_dh_params_generate2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37866 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fparams_005fimport_005fpkcs3"><code>gnutls_dh_params_import_pkcs3</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37867 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fparams_005fimport_005fraw"><code>gnutls_dh_params_import_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37868 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fparams_005finit"><code>gnutls_dh_params_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37869 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdh_005fset_005fprime_005fbits"><code>gnutls_dh_set_prime_bits</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37870 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdigest_005fget_005fid"><code>gnutls_digest_get_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37871 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdigest_005fget_005fname"><code>gnutls_digest_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37872 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdigest_005flist"><code>gnutls_digest_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37873 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdtls_005fcookie_005fsend"><code>gnutls_dtls_cookie_send</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Datagram-TLS-API">Datagram TLS API</a></td></tr>
37874 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdtls_005fcookie_005fverify"><code>gnutls_dtls_cookie_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Datagram-TLS-API">Datagram TLS API</a></td></tr>
37875 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdtls_005fget_005fdata_005fmtu"><code>gnutls_dtls_get_data_mtu</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Datagram-TLS-API">Datagram TLS API</a></td></tr>
37876 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdtls_005fget_005fmtu"><code>gnutls_dtls_get_mtu</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Datagram-TLS-API">Datagram TLS API</a></td></tr>
37877 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdtls_005fget_005ftimeout"><code>gnutls_dtls_get_timeout</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Setting-up-the-transport-layer">Setting up the transport layer</a></td></tr>
37878 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdtls_005fget_005ftimeout-1"><code>gnutls_dtls_get_timeout</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Datagram-TLS-API">Datagram TLS API</a></td></tr>
37879 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdtls_005fprestate_005fset"><code>gnutls_dtls_prestate_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Datagram-TLS-API">Datagram TLS API</a></td></tr>
37880 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdtls_005fset_005fdata_005fmtu"><code>gnutls_dtls_set_data_mtu</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Datagram-TLS-API">Datagram TLS API</a></td></tr>
37881 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdtls_005fset_005fmtu"><code>gnutls_dtls_set_mtu</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Datagram-TLS-API">Datagram TLS API</a></td></tr>
37882 <tr><td></td><td valign="top"><a href="#index-gnutls_005fdtls_005fset_005ftimeouts"><code>gnutls_dtls_set_timeouts</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Datagram-TLS-API">Datagram TLS API</a></td></tr>
37883 <tr><td></td><td valign="top"><a href="#index-gnutls_005fecc_005fcurve_005fget"><code>gnutls_ecc_curve_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37884 <tr><td></td><td valign="top"><a href="#index-gnutls_005fecc_005fcurve_005fget_005fname"><code>gnutls_ecc_curve_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37885 <tr><td></td><td valign="top"><a href="#index-gnutls_005fecc_005fcurve_005fget_005fsize"><code>gnutls_ecc_curve_get_size</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37886 <tr><td></td><td valign="top"><a href="#index-gnutls_005fecc_005fcurve_005flist"><code>gnutls_ecc_curve_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37887 <tr><td></td><td valign="top"><a href="#index-gnutls_005ferror_005fis_005ffatal"><code>gnutls_error_is_fatal</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Data-transfer-and-termination">Data transfer and termination</a></td></tr>
37888 <tr><td></td><td valign="top"><a href="#index-gnutls_005ferror_005fis_005ffatal-1"><code>gnutls_error_is_fatal</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37889 <tr><td></td><td valign="top"><a href="#index-gnutls_005ferror_005fto_005falert"><code>gnutls_error_to_alert</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Handling-alerts">Handling alerts</a></td></tr>
37890 <tr><td></td><td valign="top"><a href="#index-gnutls_005ferror_005fto_005falert-1"><code>gnutls_error_to_alert</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37891 <tr><td></td><td valign="top"><a href="#index-gnutls_005fest_005frecord_005foverhead_005fsize"><code>gnutls_est_record_overhead_size</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37892 <tr><td></td><td valign="top"><a href="#index-gnutls_005ffingerprint"><code>gnutls_fingerprint</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37893 <tr><td></td><td valign="top"><a href="#index-gnutls_005ffips140_005fmode_005fenabled"><code>gnutls_fips140_mode_enabled</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37894 <tr><td></td><td valign="top"><a href="#index-gnutls_005fglobal_005fdeinit"><code>gnutls_global_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37895 <tr><td></td><td valign="top"><a href="#index-gnutls_005fglobal_005finit"><code>gnutls_global_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37896 <tr><td></td><td valign="top"><a href="#index-gnutls_005fglobal_005fset_005faudit_005flog_005ffunction"><code>gnutls_global_set_audit_log_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Debugging-and-auditing">Debugging and auditing</a></td></tr>
37897 <tr><td></td><td valign="top"><a href="#index-gnutls_005fglobal_005fset_005faudit_005flog_005ffunction-1"><code>gnutls_global_set_audit_log_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37898 <tr><td></td><td valign="top"><a href="#index-gnutls_005fglobal_005fset_005flog_005ffunction"><code>gnutls_global_set_log_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37899 <tr><td></td><td valign="top"><a href="#index-gnutls_005fglobal_005fset_005flog_005flevel"><code>gnutls_global_set_log_level</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37900 <tr><td></td><td valign="top"><a href="#index-gnutls_005fglobal_005fset_005fmem_005ffunctions"><code>gnutls_global_set_mem_functions</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
37901 <tr><td></td><td valign="top"><a href="#index-gnutls_005fglobal_005fset_005fmutex"><code>gnutls_global_set_mutex</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Thread-safety">Thread safety</a></td></tr>
37902 <tr><td></td><td valign="top"><a href="#index-gnutls_005fglobal_005fset_005fmutex-1"><code>gnutls_global_set_mutex</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37903 <tr><td></td><td valign="top"><a href="#index-gnutls_005fglobal_005fset_005ftime_005ffunction"><code>gnutls_global_set_time_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37904 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhandshake"><code>gnutls_handshake</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-handshake">TLS handshake</a></td></tr>
37905 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhandshake-1"><code>gnutls_handshake</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37906 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhandshake_005fdescription_005fget_005fname"><code>gnutls_handshake_description_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37907 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhandshake_005fget_005flast_005fin"><code>gnutls_handshake_get_last_in</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37908 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhandshake_005fget_005flast_005fout"><code>gnutls_handshake_get_last_out</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37909 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhandshake_005fset_005fhook_005ffunction"><code>gnutls_handshake_set_hook_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37910 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhandshake_005fset_005fmax_005fpacket_005flength"><code>gnutls_handshake_set_max_packet_length</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37911 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhandshake_005fset_005fpost_005fclient_005fhello_005ffunction"><code>gnutls_handshake_set_post_client_hello_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37912 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhandshake_005fset_005fprivate_005fextensions"><code>gnutls_handshake_set_private_extensions</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37913 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhandshake_005fset_005frandom"><code>gnutls_handshake_set_random</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37914 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhandshake_005fset_005ftimeout"><code>gnutls_handshake_set_timeout</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-handshake">TLS handshake</a></td></tr>
37915 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhandshake_005fset_005ftimeout-1"><code>gnutls_handshake_set_timeout</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37916 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhash"><code>gnutls_hash</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37917 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhash_005fdeinit"><code>gnutls_hash_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37918 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhash_005ffast"><code>gnutls_hash_fast</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37919 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhash_005fget_005flen"><code>gnutls_hash_get_len</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37920 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhash_005finit"><code>gnutls_hash_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37921 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhash_005foutput"><code>gnutls_hash_output</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37922 <tr><td></td><td valign="top"><a href="#index-gnutls_005fheartbeat_005fallowed"><code>gnutls_heartbeat_allowed</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37923 <tr><td></td><td valign="top"><a href="#index-gnutls_005fheartbeat_005fenable"><code>gnutls_heartbeat_enable</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37924 <tr><td></td><td valign="top"><a href="#index-gnutls_005fheartbeat_005fget_005ftimeout"><code>gnutls_heartbeat_get_timeout</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37925 <tr><td></td><td valign="top"><a href="#index-gnutls_005fheartbeat_005fping"><code>gnutls_heartbeat_ping</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37926 <tr><td></td><td valign="top"><a href="#index-gnutls_005fheartbeat_005fpong"><code>gnutls_heartbeat_pong</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37927 <tr><td></td><td valign="top"><a href="#index-gnutls_005fheartbeat_005fset_005ftimeouts"><code>gnutls_heartbeat_set_timeouts</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37928 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhex2bin"><code>gnutls_hex2bin</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37929 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhex_005fdecode"><code>gnutls_hex_decode</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37930 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhex_005fencode"><code>gnutls_hex_encode</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37931 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhmac"><code>gnutls_hmac</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37932 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhmac_005fdeinit"><code>gnutls_hmac_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37933 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhmac_005ffast"><code>gnutls_hmac_fast</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37934 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhmac_005fget_005flen"><code>gnutls_hmac_get_len</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37935 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhmac_005finit"><code>gnutls_hmac_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37936 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhmac_005foutput"><code>gnutls_hmac_output</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37937 <tr><td></td><td valign="top"><a href="#index-gnutls_005fhmac_005fset_005fnonce"><code>gnutls_hmac_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37938 <tr><td></td><td valign="top"><a href="#index-gnutls_005finit"><code>gnutls_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Session-initialization">Session initialization</a></td></tr>
37939 <tr><td></td><td valign="top"><a href="#index-gnutls_005finit-1"><code>gnutls_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37940 <tr><td></td><td valign="top"><a href="#index-gnutls_005fkey_005fgenerate"><code>gnutls_key_generate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37941 <tr><td></td><td valign="top"><a href="#index-gnutls_005fkx_005fget"><code>gnutls_kx_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37942 <tr><td></td><td valign="top"><a href="#index-gnutls_005fkx_005fget_005fid"><code>gnutls_kx_get_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37943 <tr><td></td><td valign="top"><a href="#index-gnutls_005fkx_005fget_005fname"><code>gnutls_kx_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37944 <tr><td></td><td valign="top"><a href="#index-gnutls_005fkx_005flist"><code>gnutls_kx_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37945 <tr><td></td><td valign="top"><a href="#index-gnutls_005fkx_005fset_005fpriority"><code>gnutls_kx_set_priority</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
37946 <tr><td></td><td valign="top"><a href="#index-gnutls_005fload_005ffile"><code>gnutls_load_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37947 <tr><td></td><td valign="top"><a href="#index-gnutls_005fmac_005fget"><code>gnutls_mac_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37948 <tr><td></td><td valign="top"><a href="#index-gnutls_005fmac_005fget_005fid"><code>gnutls_mac_get_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37949 <tr><td></td><td valign="top"><a href="#index-gnutls_005fmac_005fget_005fkey_005fsize"><code>gnutls_mac_get_key_size</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37950 <tr><td></td><td valign="top"><a href="#index-gnutls_005fmac_005fget_005fname"><code>gnutls_mac_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37951 <tr><td></td><td valign="top"><a href="#index-gnutls_005fmac_005fget_005fnonce_005fsize"><code>gnutls_mac_get_nonce_size</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
37952 <tr><td></td><td valign="top"><a href="#index-gnutls_005fmac_005flist"><code>gnutls_mac_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37953 <tr><td></td><td valign="top"><a href="#index-gnutls_005fmac_005fset_005fpriority"><code>gnutls_mac_set_priority</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
37954 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005fadd_005fcert"><code>gnutls_ocsp_req_add_cert</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37955 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005fadd_005fcert_005fid"><code>gnutls_ocsp_req_add_cert_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37956 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005fdeinit"><code>gnutls_ocsp_req_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37957 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005fexport"><code>gnutls_ocsp_req_export</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37958 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005fget_005fcert_005fid"><code>gnutls_ocsp_req_get_cert_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37959 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005fget_005fextension"><code>gnutls_ocsp_req_get_extension</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37960 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005fget_005fnonce"><code>gnutls_ocsp_req_get_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37961 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005fget_005fversion"><code>gnutls_ocsp_req_get_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37962 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005fimport"><code>gnutls_ocsp_req_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37963 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005finit"><code>gnutls_ocsp_req_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37964 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005fprint"><code>gnutls_ocsp_req_print</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37965 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005frandomize_005fnonce"><code>gnutls_ocsp_req_randomize_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37966 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005fset_005fextension"><code>gnutls_ocsp_req_set_extension</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37967 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005freq_005fset_005fnonce"><code>gnutls_ocsp_req_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37968 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fcheck_005fcrt"><code>gnutls_ocsp_resp_check_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37969 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fdeinit"><code>gnutls_ocsp_resp_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37970 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fexport"><code>gnutls_ocsp_resp_export</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37971 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fget_005fcerts"><code>gnutls_ocsp_resp_get_certs</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37972 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fget_005fextension"><code>gnutls_ocsp_resp_get_extension</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37973 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fget_005fnonce"><code>gnutls_ocsp_resp_get_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37974 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fget_005fproduced"><code>gnutls_ocsp_resp_get_produced</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37975 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fget_005fresponder"><code>gnutls_ocsp_resp_get_responder</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37976 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fget_005fresponse"><code>gnutls_ocsp_resp_get_response</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37977 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fget_005fsignature"><code>gnutls_ocsp_resp_get_signature</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37978 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fget_005fsignature_005falgorithm"><code>gnutls_ocsp_resp_get_signature_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37979 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fget_005fsingle"><code>gnutls_ocsp_resp_get_single</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-certificate-status-checking">OCSP certificate status checking</a></td></tr>
37980 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fget_005fsingle-1"><code>gnutls_ocsp_resp_get_single</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37981 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fget_005fstatus"><code>gnutls_ocsp_resp_get_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37982 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fget_005fversion"><code>gnutls_ocsp_resp_get_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37983 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fimport"><code>gnutls_ocsp_resp_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37984 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005finit"><code>gnutls_ocsp_resp_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37985 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fprint"><code>gnutls_ocsp_resp_print</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37986 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fverify"><code>gnutls_ocsp_resp_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37987 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fresp_005fverify_005fdirect"><code>gnutls_ocsp_resp_verify_direct</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
37988 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fstatus_005frequest_005fenable_005fclient"><code>gnutls_ocsp_status_request_enable_client</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37989 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fstatus_005frequest_005fget"><code>gnutls_ocsp_status_request_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37990 <tr><td></td><td valign="top"><a href="#index-gnutls_005focsp_005fstatus_005frequest_005fis_005fchecked"><code>gnutls_ocsp_status_request_is_checked</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
37991 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fcheck_005fhostname"><code>gnutls_openpgp_crt_check_hostname</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37992 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fcheck_005fhostname2"><code>gnutls_openpgp_crt_check_hostname2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37993 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fdeinit"><code>gnutls_openpgp_crt_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37994 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fexport"><code>gnutls_openpgp_crt_export</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37995 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fexport2"><code>gnutls_openpgp_crt_export2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37996 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fauth_005fsubkey"><code>gnutls_openpgp_crt_get_auth_subkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37997 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fcreation_005ftime"><code>gnutls_openpgp_crt_get_creation_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37998 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fexpiration_005ftime"><code>gnutls_openpgp_crt_get_expiration_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
37999 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005ffingerprint"><code>gnutls_openpgp_crt_get_fingerprint</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38000 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fkey_005fid"><code>gnutls_openpgp_crt_get_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38001 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fkey_005fusage"><code>gnutls_openpgp_crt_get_key_usage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38002 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fname"><code>gnutls_openpgp_crt_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38003 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fpk_005falgorithm"><code>gnutls_openpgp_crt_get_pk_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38004 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fpk_005fdsa_005fraw"><code>gnutls_openpgp_crt_get_pk_dsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38005 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fpk_005frsa_005fraw"><code>gnutls_openpgp_crt_get_pk_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38006 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fpreferred_005fkey_005fid"><code>gnutls_openpgp_crt_get_preferred_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38007 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005frevoked_005fstatus"><code>gnutls_openpgp_crt_get_revoked_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38008 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fcount"><code>gnutls_openpgp_crt_get_subkey_count</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38009 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fcreation_005ftime"><code>gnutls_openpgp_crt_get_subkey_creation_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38010 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fexpiration_005ftime"><code>gnutls_openpgp_crt_get_subkey_expiration_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38011 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005ffingerprint"><code>gnutls_openpgp_crt_get_subkey_fingerprint</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38012 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fid"><code>gnutls_openpgp_crt_get_subkey_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38013 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fidx"><code>gnutls_openpgp_crt_get_subkey_idx</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38014 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005falgorithm"><code>gnutls_openpgp_crt_get_subkey_pk_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38015 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005fdsa_005fraw"><code>gnutls_openpgp_crt_get_subkey_pk_dsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38016 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005frsa_005fraw"><code>gnutls_openpgp_crt_get_subkey_pk_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38017 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005frevoked_005fstatus"><code>gnutls_openpgp_crt_get_subkey_revoked_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38018 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fusage"><code>gnutls_openpgp_crt_get_subkey_usage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38019 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fget_005fversion"><code>gnutls_openpgp_crt_get_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38020 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fimport"><code>gnutls_openpgp_crt_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38021 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005finit"><code>gnutls_openpgp_crt_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38022 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fprint"><code>gnutls_openpgp_crt_print</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38023 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fset_005fpreferred_005fkey_005fid"><code>gnutls_openpgp_crt_set_preferred_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38024 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fverify_005fring"><code>gnutls_openpgp_crt_verify_ring</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-certificates">OpenPGP certificates</a></td></tr>
38025 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fverify_005fring-1"><code>gnutls_openpgp_crt_verify_ring</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38026 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fverify_005fself"><code>gnutls_openpgp_crt_verify_self</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-certificates">OpenPGP certificates</a></td></tr>
38027 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fcrt_005fverify_005fself-1"><code>gnutls_openpgp_crt_verify_self</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38028 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fkeyring_005fcheck_005fid"><code>gnutls_openpgp_keyring_check_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38029 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fkeyring_005fdeinit"><code>gnutls_openpgp_keyring_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38030 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fkeyring_005fget_005fcrt"><code>gnutls_openpgp_keyring_get_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38031 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fkeyring_005fget_005fcrt_005fcount"><code>gnutls_openpgp_keyring_get_crt_count</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38032 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fkeyring_005fimport"><code>gnutls_openpgp_keyring_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38033 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fkeyring_005finit"><code>gnutls_openpgp_keyring_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38034 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fdeinit"><code>gnutls_openpgp_privkey_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38035 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fexport"><code>gnutls_openpgp_privkey_export</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38036 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fexport2"><code>gnutls_openpgp_privkey_export2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38037 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fexport_005fdsa_005fraw"><code>gnutls_openpgp_privkey_export_dsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38038 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fexport_005frsa_005fraw"><code>gnutls_openpgp_privkey_export_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38039 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fexport_005fsubkey_005fdsa_005fraw"><code>gnutls_openpgp_privkey_export_subkey_dsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38040 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fexport_005fsubkey_005frsa_005fraw"><code>gnutls_openpgp_privkey_export_subkey_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38041 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fget_005ffingerprint"><code>gnutls_openpgp_privkey_get_fingerprint</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38042 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fget_005fkey_005fid"><code>gnutls_openpgp_privkey_get_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38043 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fget_005fpk_005falgorithm"><code>gnutls_openpgp_privkey_get_pk_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38044 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fget_005fpreferred_005fkey_005fid"><code>gnutls_openpgp_privkey_get_preferred_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38045 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fget_005frevoked_005fstatus"><code>gnutls_openpgp_privkey_get_revoked_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38046 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fcount"><code>gnutls_openpgp_privkey_get_subkey_count</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38047 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fcreation_005ftime"><code>gnutls_openpgp_privkey_get_subkey_creation_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38048 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fexpiration_005ftime"><code>gnutls_openpgp_privkey_get_subkey_expiration_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38049 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005ffingerprint"><code>gnutls_openpgp_privkey_get_subkey_fingerprint</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38050 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fid"><code>gnutls_openpgp_privkey_get_subkey_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38051 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fidx"><code>gnutls_openpgp_privkey_get_subkey_idx</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38052 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fpk_005falgorithm"><code>gnutls_openpgp_privkey_get_subkey_pk_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38053 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005frevoked_005fstatus"><code>gnutls_openpgp_privkey_get_subkey_revoked_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38054 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fimport"><code>gnutls_openpgp_privkey_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38055 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005finit"><code>gnutls_openpgp_privkey_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38056 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fsec_005fparam"><code>gnutls_openpgp_privkey_sec_param</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38057 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fset_005fpreferred_005fkey_005fid"><code>gnutls_openpgp_privkey_set_preferred_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38058 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fprivkey_005fsign_005fhash"><code>gnutls_openpgp_privkey_sign_hash</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38059 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fsend_005fcert"><code>gnutls_openpgp_send_cert</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38060 <tr><td></td><td valign="top"><a href="#index-gnutls_005fopenpgp_005fset_005frecv_005fkey_005ffunction"><code>gnutls_openpgp_set_recv_key_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38061 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpacket_005fdeinit"><code>gnutls_packet_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38062 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpacket_005fget"><code>gnutls_packet_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38063 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpcert_005fdeinit"><code>gnutls_pcert_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38064 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpcert_005fimport_005fopenpgp"><code>gnutls_pcert_import_openpgp</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38065 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpcert_005fimport_005fopenpgp_005fraw"><code>gnutls_pcert_import_openpgp_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38066 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpcert_005fimport_005fx509"><code>gnutls_pcert_import_x509</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38067 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpcert_005fimport_005fx509_005fraw"><code>gnutls_pcert_import_x509_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38068 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpcert_005flist_005fimport_005fx509_005fraw"><code>gnutls_pcert_list_import_x509_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38069 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpem_005fbase64_005fdecode"><code>gnutls_pem_base64_decode</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38070 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpem_005fbase64_005fdecode_005falloc"><code>gnutls_pem_base64_decode_alloc</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38071 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpem_005fbase64_005fencode"><code>gnutls_pem_base64_encode</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38072 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpem_005fbase64_005fencode_005falloc"><code>gnutls_pem_base64_encode_alloc</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38073 <tr><td></td><td valign="top"><a href="#index-gnutls_005fperror"><code>gnutls_perror</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38074 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fadd_005fprovider"><code>gnutls_pkcs11_add_provider</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38075 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fcopy_005fsecret_005fkey"><code>gnutls_pkcs11_copy_secret_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38076 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fcopy_005fx509_005fcrt"><code>gnutls_pkcs11_copy_x509_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Writing-objects">Writing objects</a></td></tr>
38077 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fcopy_005fx509_005fcrt-1"><code>gnutls_pkcs11_copy_x509_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38078 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fcopy_005fx509_005fcrt2"><code>gnutls_pkcs11_copy_x509_crt2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38079 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fcopy_005fx509_005fprivkey"><code>gnutls_pkcs11_copy_x509_privkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Writing-objects">Writing objects</a></td></tr>
38080 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fcopy_005fx509_005fprivkey-1"><code>gnutls_pkcs11_copy_x509_privkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38081 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fcopy_005fx509_005fprivkey2"><code>gnutls_pkcs11_copy_x509_privkey2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38082 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fcrt_005fis_005fknown"><code>gnutls_pkcs11_crt_is_known</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38083 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fdeinit"><code>gnutls_pkcs11_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38084 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fdelete_005furl"><code>gnutls_pkcs11_delete_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Writing-objects">Writing objects</a></td></tr>
38085 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fdelete_005furl-1"><code>gnutls_pkcs11_delete_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38086 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fget_005fpin_005ffunction"><code>gnutls_pkcs11_get_pin_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38087 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fget_005fraw_005fissuer"><code>gnutls_pkcs11_get_raw_issuer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38088 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005finit"><code>gnutls_pkcs11_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS11-Initialization">PKCS11 Initialization</a></td></tr>
38089 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005finit-1"><code>gnutls_pkcs11_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38090 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fdeinit"><code>gnutls_pkcs11_obj_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38091 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fexport"><code>gnutls_pkcs11_obj_export</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38092 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fexport2"><code>gnutls_pkcs11_obj_export2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38093 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fexport3"><code>gnutls_pkcs11_obj_export3</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38094 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fexport_005furl"><code>gnutls_pkcs11_obj_export_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38095 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fflags_005fget_005fstr"><code>gnutls_pkcs11_obj_flags_get_str</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38096 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fget_005fexts"><code>gnutls_pkcs11_obj_get_exts</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38097 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fget_005fflags"><code>gnutls_pkcs11_obj_get_flags</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38098 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fget_005finfo"><code>gnutls_pkcs11_obj_get_info</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reading-objects">Reading objects</a></td></tr>
38099 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fget_005finfo-1"><code>gnutls_pkcs11_obj_get_info</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38100 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fget_005ftype"><code>gnutls_pkcs11_obj_get_type</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38101 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fimport_005furl"><code>gnutls_pkcs11_obj_import_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38102 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005finit"><code>gnutls_pkcs11_obj_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38103 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005flist_005fimport_005furl"><code>gnutls_pkcs11_obj_list_import_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38104 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005flist_005fimport_005furl2"><code>gnutls_pkcs11_obj_list_import_url2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38105 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fset_005finfo"><code>gnutls_pkcs11_obj_set_info</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38106 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fobj_005fset_005fpin_005ffunction"><code>gnutls_pkcs11_obj_set_pin_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38107 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fprivkey_005fdeinit"><code>gnutls_pkcs11_privkey_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38108 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fprivkey_005fexport_005fpubkey"><code>gnutls_pkcs11_privkey_export_pubkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38109 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fprivkey_005fexport_005furl"><code>gnutls_pkcs11_privkey_export_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38110 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fprivkey_005fgenerate"><code>gnutls_pkcs11_privkey_generate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38111 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fprivkey_005fgenerate2"><code>gnutls_pkcs11_privkey_generate2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38112 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fprivkey_005fgenerate3"><code>gnutls_pkcs11_privkey_generate3</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38113 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fprivkey_005fget_005finfo"><code>gnutls_pkcs11_privkey_get_info</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38114 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fprivkey_005fget_005fpk_005falgorithm"><code>gnutls_pkcs11_privkey_get_pk_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38115 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fprivkey_005fimport_005furl"><code>gnutls_pkcs11_privkey_import_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38116 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fprivkey_005finit"><code>gnutls_pkcs11_privkey_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38117 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fprivkey_005fset_005fpin_005ffunction"><code>gnutls_pkcs11_privkey_set_pin_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38118 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fprivkey_005fstatus"><code>gnutls_pkcs11_privkey_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38119 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005freinit"><code>gnutls_pkcs11_reinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38120 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fset_005fpin_005ffunction"><code>gnutls_pkcs11_set_pin_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38121 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005fset_005ftoken_005ffunction"><code>gnutls_pkcs11_set_token_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38122 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005ftoken_005fget_005fflags"><code>gnutls_pkcs11_token_get_flags</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38123 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005ftoken_005fget_005finfo"><code>gnutls_pkcs11_token_get_info</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38124 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005ftoken_005fget_005fmechanism"><code>gnutls_pkcs11_token_get_mechanism</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38125 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005ftoken_005fget_005frandom"><code>gnutls_pkcs11_token_get_random</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38126 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005ftoken_005fget_005furl"><code>gnutls_pkcs11_token_get_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38127 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005ftoken_005finit"><code>gnutls_pkcs11_token_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38128 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005ftoken_005fset_005fpin"><code>gnutls_pkcs11_token_set_pin</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38129 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs11_005ftype_005fget_005fname"><code>gnutls_pkcs11_type_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38130 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005fdecrypt"><code>gnutls_pkcs12_bag_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38131 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005fdeinit"><code>gnutls_pkcs12_bag_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38132 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005fencrypt"><code>gnutls_pkcs12_bag_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38133 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005fget_005fcount"><code>gnutls_pkcs12_bag_get_count</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38134 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005fget_005fdata"><code>gnutls_pkcs12_bag_get_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38135 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005fget_005ffriendly_005fname"><code>gnutls_pkcs12_bag_get_friendly_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38136 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005fget_005fkey_005fid"><code>gnutls_pkcs12_bag_get_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38137 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005fget_005ftype"><code>gnutls_pkcs12_bag_get_type</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38138 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005finit"><code>gnutls_pkcs12_bag_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38139 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005fset_005fcrl"><code>gnutls_pkcs12_bag_set_crl</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38140 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005fset_005fcrt"><code>gnutls_pkcs12_bag_set_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38141 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005fset_005fdata"><code>gnutls_pkcs12_bag_set_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38142 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005fset_005ffriendly_005fname"><code>gnutls_pkcs12_bag_set_friendly_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38143 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fbag_005fset_005fkey_005fid"><code>gnutls_pkcs12_bag_set_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38144 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fdeinit"><code>gnutls_pkcs12_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38145 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fexport"><code>gnutls_pkcs12_export</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38146 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fexport2"><code>gnutls_pkcs12_export2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38147 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fgenerate_005fmac"><code>gnutls_pkcs12_generate_mac</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38148 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fget_005fbag"><code>gnutls_pkcs12_get_bag</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38149 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fimport"><code>gnutls_pkcs12_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38150 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005finit"><code>gnutls_pkcs12_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38151 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fset_005fbag"><code>gnutls_pkcs12_set_bag</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38152 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fsimple_005fparse"><code>gnutls_pkcs12_simple_parse</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Managing-encrypted-keys">Managing encrypted keys</a></td></tr>
38153 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fsimple_005fparse-1"><code>gnutls_pkcs12_simple_parse</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38154 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs12_005fverify_005fmac"><code>gnutls_pkcs12_verify_mac</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-12-API">PKCS 12 API</a></td></tr>
38155 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fdeinit"><code>gnutls_pkcs7_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38156 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fdelete_005fcrl"><code>gnutls_pkcs7_delete_crl</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38157 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fdelete_005fcrt"><code>gnutls_pkcs7_delete_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38158 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fexport"><code>gnutls_pkcs7_export</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38159 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fexport2"><code>gnutls_pkcs7_export2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38160 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fget_005fcrl_005fcount"><code>gnutls_pkcs7_get_crl_count</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38161 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fget_005fcrl_005fraw"><code>gnutls_pkcs7_get_crl_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38162 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fget_005fcrt_005fcount"><code>gnutls_pkcs7_get_crt_count</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38163 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fget_005fcrt_005fraw"><code>gnutls_pkcs7_get_crt_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38164 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fimport"><code>gnutls_pkcs7_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38165 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005finit"><code>gnutls_pkcs7_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38166 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fset_005fcrl"><code>gnutls_pkcs7_set_crl</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38167 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fset_005fcrl_005fraw"><code>gnutls_pkcs7_set_crl_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38168 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fset_005fcrt"><code>gnutls_pkcs7_set_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38169 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpkcs7_005fset_005fcrt_005fraw"><code>gnutls_pkcs7_set_crt_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38170 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpk_005falgorithm_005fget_005fname"><code>gnutls_pk_algorithm_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38171 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpk_005fbits_005fto_005fsec_005fparam"><code>gnutls_pk_bits_to_sec_param</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Selecting-cryptographic-key-sizes">Selecting cryptographic key sizes</a></td></tr>
38172 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpk_005fbits_005fto_005fsec_005fparam-1"><code>gnutls_pk_bits_to_sec_param</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38173 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpk_005fget_005fid"><code>gnutls_pk_get_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38174 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpk_005fget_005fname"><code>gnutls_pk_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38175 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpk_005flist"><code>gnutls_pk_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38176 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpk_005fto_005fsign"><code>gnutls_pk_to_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38177 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprf"><code>gnutls_prf</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38178 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprf_005fraw"><code>gnutls_prf_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38179 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpriority_005fcertificate_005ftype_005flist"><code>gnutls_priority_certificate_type_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38180 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpriority_005fcipher_005flist"><code>gnutls_priority_cipher_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38181 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpriority_005fcompression_005flist"><code>gnutls_priority_compression_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38182 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpriority_005fdeinit"><code>gnutls_priority_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38183 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpriority_005fecc_005fcurve_005flist"><code>gnutls_priority_ecc_curve_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38184 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpriority_005fget_005fcipher_005fsuite_005findex"><code>gnutls_priority_get_cipher_suite_index</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38185 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpriority_005finit"><code>gnutls_priority_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38186 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpriority_005fkx_005flist"><code>gnutls_priority_kx_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38187 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpriority_005fmac_005flist"><code>gnutls_priority_mac_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38188 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpriority_005fprotocol_005flist"><code>gnutls_priority_protocol_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38189 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpriority_005fset"><code>gnutls_priority_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38190 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpriority_005fset_005fdirect"><code>gnutls_priority_set_direct</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38191 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpriority_005fsign_005flist"><code>gnutls_priority_sign_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38192 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fdecrypt_005fdata"><code>gnutls_privkey_decrypt_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Operations">Operations</a></td></tr>
38193 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fdecrypt_005fdata-1"><code>gnutls_privkey_decrypt_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38194 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fdeinit"><code>gnutls_privkey_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38195 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fexport_005fdsa_005fraw"><code>gnutls_privkey_export_dsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38196 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fexport_005fecc_005fraw"><code>gnutls_privkey_export_ecc_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38197 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fexport_005frsa_005fraw"><code>gnutls_privkey_export_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38198 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fgenerate"><code>gnutls_privkey_generate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38199 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fget_005fpk_005falgorithm"><code>gnutls_privkey_get_pk_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38200 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fget_005ftype"><code>gnutls_privkey_get_type</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38201 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005fdsa_005fraw"><code>gnutls_privkey_import_dsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38202 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005fecc_005fraw"><code>gnutls_privkey_import_ecc_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38203 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005fext"><code>gnutls_privkey_import_ext</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38204 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005fext2"><code>gnutls_privkey_import_ext2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-private-keys">Abstract private keys</a></td></tr>
38205 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005fext2-1"><code>gnutls_privkey_import_ext2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38206 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005fopenpgp"><code>gnutls_privkey_import_openpgp</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38207 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005fopenpgp_005fraw"><code>gnutls_privkey_import_openpgp_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38208 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005fpkcs11"><code>gnutls_privkey_import_pkcs11</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38209 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005fpkcs11_005furl"><code>gnutls_privkey_import_pkcs11_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38210 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005frsa_005fraw"><code>gnutls_privkey_import_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38211 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005ftpm_005fraw"><code>gnutls_privkey_import_tpm_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38212 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005ftpm_005furl"><code>gnutls_privkey_import_tpm_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Using-keys">Using keys</a></td></tr>
38213 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005ftpm_005furl-1"><code>gnutls_privkey_import_tpm_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38214 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005furl"><code>gnutls_privkey_import_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-private-keys">Abstract private keys</a></td></tr>
38215 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005furl-1"><code>gnutls_privkey_import_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38216 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005fx509"><code>gnutls_privkey_import_x509</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38217 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005fx509_005fraw"><code>gnutls_privkey_import_x509_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Managing-encrypted-keys">Managing encrypted keys</a></td></tr>
38218 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fimport_005fx509_005fraw-1"><code>gnutls_privkey_import_x509_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38219 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005finit"><code>gnutls_privkey_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38220 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fset_005fpin_005ffunction"><code>gnutls_privkey_set_pin_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38221 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fsign_005fdata"><code>gnutls_privkey_sign_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Operations">Operations</a></td></tr>
38222 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fsign_005fdata-1"><code>gnutls_privkey_sign_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38223 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fsign_005fhash"><code>gnutls_privkey_sign_hash</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Operations">Operations</a></td></tr>
38224 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fsign_005fhash-1"><code>gnutls_privkey_sign_hash</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38225 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fsign_005fraw_005fdata"><code>gnutls_privkey_sign_raw_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38226 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fstatus"><code>gnutls_privkey_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38227 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprivkey_005fverify_005fparams"><code>gnutls_privkey_verify_params</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38228 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprotocol_005fget_005fid"><code>gnutls_protocol_get_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38229 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprotocol_005fget_005fname"><code>gnutls_protocol_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38230 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprotocol_005fget_005fversion"><code>gnutls_protocol_get_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38231 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprotocol_005flist"><code>gnutls_protocol_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38232 <tr><td></td><td valign="top"><a href="#index-gnutls_005fprotocol_005fset_005fpriority"><code>gnutls_protocol_set_priority</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38233 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fallocate_005fclient_005fcredentials"><code>gnutls_psk_allocate_client_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38234 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fallocate_005fserver_005fcredentials"><code>gnutls_psk_allocate_server_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38235 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fclient_005fget_005fhint"><code>gnutls_psk_client_get_hint</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38236 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005ffree_005fclient_005fcredentials"><code>gnutls_psk_free_client_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38237 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005ffree_005fserver_005fcredentials"><code>gnutls_psk_free_server_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38238 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fserver_005fget_005fusername"><code>gnutls_psk_server_get_username</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38239 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fset_005fclient_005fcredentials"><code>gnutls_psk_set_client_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38240 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fset_005fclient_005fcredentials_005ffunction"><code>gnutls_psk_set_client_credentials_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PSK-credentials">PSK credentials</a></td></tr>
38241 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fset_005fclient_005fcredentials_005ffunction-1"><code>gnutls_psk_set_client_credentials_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38242 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fset_005fparams_005ffunction"><code>gnutls_psk_set_params_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38243 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffile"><code>gnutls_psk_set_server_credentials_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PSK-credentials">PSK credentials</a></td></tr>
38244 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffile-1"><code>gnutls_psk_set_server_credentials_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38245 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffunction"><code>gnutls_psk_set_server_credentials_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38246 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fset_005fserver_005fcredentials_005fhint"><code>gnutls_psk_set_server_credentials_hint</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38247 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fset_005fserver_005fdh_005fparams"><code>gnutls_psk_set_server_dh_params</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38248 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fset_005fserver_005fparams_005ffunction"><code>gnutls_psk_set_server_params_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38249 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fdeinit"><code>gnutls_pubkey_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38250 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fencrypt_005fdata"><code>gnutls_pubkey_encrypt_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Operations">Operations</a></td></tr>
38251 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fencrypt_005fdata-1"><code>gnutls_pubkey_encrypt_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38252 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fexport"><code>gnutls_pubkey_export</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38253 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fexport2"><code>gnutls_pubkey_export2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-public-keys">Abstract public keys</a></td></tr>
38254 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fexport2-1"><code>gnutls_pubkey_export2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38255 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fexport_005fdsa_005fraw"><code>gnutls_pubkey_export_dsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38256 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fexport_005fecc_005fraw"><code>gnutls_pubkey_export_ecc_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38257 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fexport_005fecc_005fx962"><code>gnutls_pubkey_export_ecc_x962</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38258 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fexport_005frsa_005fraw"><code>gnutls_pubkey_export_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38259 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fget_005fkey_005fid"><code>gnutls_pubkey_get_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38260 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fget_005fkey_005fusage"><code>gnutls_pubkey_get_key_usage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38261 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fget_005fopenpgp_005fkey_005fid"><code>gnutls_pubkey_get_openpgp_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38262 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fget_005fpk_005falgorithm"><code>gnutls_pubkey_get_pk_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38263 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fget_005fpreferred_005fhash_005falgorithm"><code>gnutls_pubkey_get_preferred_hash_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38264 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fget_005fverify_005falgorithm"><code>gnutls_pubkey_get_verify_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38265 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport"><code>gnutls_pubkey_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38266 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005fdsa_005fraw"><code>gnutls_pubkey_import_dsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38267 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005fecc_005fraw"><code>gnutls_pubkey_import_ecc_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38268 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005fecc_005fx962"><code>gnutls_pubkey_import_ecc_x962</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38269 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005fopenpgp"><code>gnutls_pubkey_import_openpgp</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38270 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005fopenpgp_005fraw"><code>gnutls_pubkey_import_openpgp_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38271 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005fpkcs11"><code>gnutls_pubkey_import_pkcs11</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38272 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005fpkcs11_005furl"><code>gnutls_pubkey_import_pkcs11_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38273 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005fprivkey"><code>gnutls_pubkey_import_privkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38274 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005frsa_005fraw"><code>gnutls_pubkey_import_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38275 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005ftpm_005fraw"><code>gnutls_pubkey_import_tpm_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38276 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005ftpm_005furl"><code>gnutls_pubkey_import_tpm_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Using-keys">Using keys</a></td></tr>
38277 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005ftpm_005furl-1"><code>gnutls_pubkey_import_tpm_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38278 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005furl"><code>gnutls_pubkey_import_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38279 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005fx509"><code>gnutls_pubkey_import_x509</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38280 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005fx509_005fcrq"><code>gnutls_pubkey_import_x509_crq</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38281 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fimport_005fx509_005fraw"><code>gnutls_pubkey_import_x509_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38282 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005finit"><code>gnutls_pubkey_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38283 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fprint"><code>gnutls_pubkey_print</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38284 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fset_005fkey_005fusage"><code>gnutls_pubkey_set_key_usage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38285 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fset_005fpin_005ffunction"><code>gnutls_pubkey_set_pin_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38286 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fverify_005fdata"><code>gnutls_pubkey_verify_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38287 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fverify_005fdata2"><code>gnutls_pubkey_verify_data2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Operations">Operations</a></td></tr>
38288 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fverify_005fdata2-1"><code>gnutls_pubkey_verify_data2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38289 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fverify_005fhash"><code>gnutls_pubkey_verify_hash</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38290 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fverify_005fhash2"><code>gnutls_pubkey_verify_hash2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Operations">Operations</a></td></tr>
38291 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fverify_005fhash2-1"><code>gnutls_pubkey_verify_hash2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38292 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fverify_005fparams"><code>gnutls_pubkey_verify_params</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38293 <tr><td></td><td valign="top"><a href="#index-gnutls_005frandom_005fart"><code>gnutls_random_art</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38294 <tr><td></td><td valign="top"><a href="#index-gnutls_005frange_005fsplit"><code>gnutls_range_split</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38295 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fcan_005fuse_005flength_005fhiding"><code>gnutls_record_can_use_length_hiding</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38296 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fcheck_005fcorked"><code>gnutls_record_check_corked</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38297 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fcheck_005fpending"><code>gnutls_record_check_pending</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Data-transfer-and-termination">Data transfer and termination</a></td></tr>
38298 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fcheck_005fpending-1"><code>gnutls_record_check_pending</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38299 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fcork"><code>gnutls_record_cork</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Buffered-data-transfer">Buffered data transfer</a></td></tr>
38300 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fcork-1"><code>gnutls_record_cork</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38301 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fdisable_005fpadding"><code>gnutls_record_disable_padding</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38302 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fget_005fdirection"><code>gnutls_record_get_direction</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Asynchronous-operation">Asynchronous operation</a></td></tr>
38303 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fget_005fdirection-1"><code>gnutls_record_get_direction</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38304 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fget_005fdiscarded"><code>gnutls_record_get_discarded</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Datagram-TLS-API">Datagram TLS API</a></td></tr>
38305 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fget_005fmax_005fsize"><code>gnutls_record_get_max_size</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38306 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005foverhead_005fsize"><code>gnutls_record_overhead_size</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38307 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005frecv"><code>gnutls_record_recv</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Data-transfer-and-termination">Data transfer and termination</a></td></tr>
38308 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005frecv-1"><code>gnutls_record_recv</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38309 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005frecv_005fpacket"><code>gnutls_record_recv_packet</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38310 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005frecv_005fseq"><code>gnutls_record_recv_seq</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Data-transfer-and-termination">Data transfer and termination</a></td></tr>
38311 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005frecv_005fseq-1"><code>gnutls_record_recv_seq</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38312 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fsend"><code>gnutls_record_send</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Data-transfer-and-termination">Data transfer and termination</a></td></tr>
38313 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fsend-1"><code>gnutls_record_send</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38314 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fsend_005frange"><code>gnutls_record_send_range</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38315 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fset_005fmax_005fempty_005frecords"><code>gnutls_record_set_max_empty_records</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38316 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fset_005fmax_005fsize"><code>gnutls_record_set_max_size</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38317 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005fset_005ftimeout"><code>gnutls_record_set_timeout</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38318 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005funcork"><code>gnutls_record_uncork</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Buffered-data-transfer">Buffered data transfer</a></td></tr>
38319 <tr><td></td><td valign="top"><a href="#index-gnutls_005frecord_005funcork-1"><code>gnutls_record_uncork</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38320 <tr><td></td><td valign="top"><a href="#index-gnutls_005frehandshake"><code>gnutls_rehandshake</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38321 <tr><td></td><td valign="top"><a href="#index-gnutls_005frnd"><code>gnutls_rnd</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Random-number-generation">Random number generation</a></td></tr>
38322 <tr><td></td><td valign="top"><a href="#index-gnutls_005frnd-1"><code>gnutls_rnd</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
38323 <tr><td></td><td valign="top"><a href="#index-gnutls_005frnd_005frefresh"><code>gnutls_rnd_refresh</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cryptographic-API">Cryptographic API</a></td></tr>
38324 <tr><td></td><td valign="top"><a href="#index-gnutls_005frsa_005fexport_005fget_005fmodulus_005fbits"><code>gnutls_rsa_export_get_modulus_bits</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38325 <tr><td></td><td valign="top"><a href="#index-gnutls_005frsa_005fexport_005fget_005fpubkey"><code>gnutls_rsa_export_get_pubkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38326 <tr><td></td><td valign="top"><a href="#index-gnutls_005frsa_005fparams_005fcpy"><code>gnutls_rsa_params_cpy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38327 <tr><td></td><td valign="top"><a href="#index-gnutls_005frsa_005fparams_005fdeinit"><code>gnutls_rsa_params_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38328 <tr><td></td><td valign="top"><a href="#index-gnutls_005frsa_005fparams_005fexport_005fpkcs1"><code>gnutls_rsa_params_export_pkcs1</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38329 <tr><td></td><td valign="top"><a href="#index-gnutls_005frsa_005fparams_005fexport_005fraw"><code>gnutls_rsa_params_export_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38330 <tr><td></td><td valign="top"><a href="#index-gnutls_005frsa_005fparams_005fgenerate2"><code>gnutls_rsa_params_generate2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38331 <tr><td></td><td valign="top"><a href="#index-gnutls_005frsa_005fparams_005fimport_005fpkcs1"><code>gnutls_rsa_params_import_pkcs1</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38332 <tr><td></td><td valign="top"><a href="#index-gnutls_005frsa_005fparams_005fimport_005fraw"><code>gnutls_rsa_params_import_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38333 <tr><td></td><td valign="top"><a href="#index-gnutls_005frsa_005fparams_005finit"><code>gnutls_rsa_params_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38334 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsafe_005frenegotiation_005fstatus"><code>gnutls_safe_renegotiation_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38335 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsec_005fparam_005fget_005fname"><code>gnutls_sec_param_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38336 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsec_005fparam_005fto_005fpk_005fbits"><code>gnutls_sec_param_to_pk_bits</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Selecting-cryptographic-key-sizes">Selecting cryptographic key sizes</a></td></tr>
38337 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsec_005fparam_005fto_005fpk_005fbits-1"><code>gnutls_sec_param_to_pk_bits</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38338 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsec_005fparam_005fto_005fsymmetric_005fbits"><code>gnutls_sec_param_to_symmetric_bits</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38339 <tr><td></td><td valign="top"><a href="#index-gnutls_005fserver_005fname_005fget"><code>gnutls_server_name_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38340 <tr><td></td><td valign="top"><a href="#index-gnutls_005fserver_005fname_005fset"><code>gnutls_server_name_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38341 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fchannel_005fbinding"><code>gnutls_session_channel_binding</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38342 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fenable_005fcompatibility_005fmode"><code>gnutls_session_enable_compatibility_mode</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38343 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fforce_005fvalid"><code>gnutls_session_force_valid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38344 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fget_005fdata"><code>gnutls_session_get_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38345 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fget_005fdata2"><code>gnutls_session_get_data2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38346 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fget_005fdesc"><code>gnutls_session_get_desc</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38347 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fget_005fid"><code>gnutls_session_get_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38348 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fget_005fid2"><code>gnutls_session_get_id2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38349 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fget_005fptr"><code>gnutls_session_get_ptr</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38350 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fget_005frandom"><code>gnutls_session_get_random</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38351 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fis_005fresumed"><code>gnutls_session_is_resumed</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Session-resumption">Session resumption</a></td></tr>
38352 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fis_005fresumed-1"><code>gnutls_session_is_resumed</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38353 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fresumption_005frequested"><code>gnutls_session_resumption_requested</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Session-resumption">Session resumption</a></td></tr>
38354 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fresumption_005frequested-1"><code>gnutls_session_resumption_requested</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38355 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fset_005fdata"><code>gnutls_session_set_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38356 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fset_005fid"><code>gnutls_session_set_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38357 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fset_005fpremaster"><code>gnutls_session_set_premaster</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38358 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fset_005fptr"><code>gnutls_session_set_ptr</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38359 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fticket_005fenable_005fclient"><code>gnutls_session_ticket_enable_client</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38360 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fticket_005fenable_005fserver"><code>gnutls_session_ticket_enable_server</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Session-resumption">Session resumption</a></td></tr>
38361 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fticket_005fenable_005fserver-1"><code>gnutls_session_ticket_enable_server</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38362 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fticket_005fkey_005fgenerate"><code>gnutls_session_ticket_key_generate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Session-resumption">Session resumption</a></td></tr>
38363 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsession_005fticket_005fkey_005fgenerate-1"><code>gnutls_session_ticket_key_generate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38364 <tr><td></td><td valign="top"><a href="#index-gnutls_005fset_005fdefault_005fexport_005fpriority"><code>gnutls_set_default_export_priority</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38365 <tr><td></td><td valign="top"><a href="#index-gnutls_005fset_005fdefault_005fpriority"><code>gnutls_set_default_priority</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38366 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsign_005falgorithm_005fget"><code>gnutls_sign_algorithm_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38367 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsign_005falgorithm_005fget_005fclient"><code>gnutls_sign_algorithm_get_client</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38368 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsign_005falgorithm_005fget_005frequested"><code>gnutls_sign_algorithm_get_requested</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38369 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsign_005fcallback_005fget"><code>gnutls_sign_callback_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38370 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsign_005fcallback_005fset"><code>gnutls_sign_callback_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38371 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsign_005fget_005fhash_005falgorithm"><code>gnutls_sign_get_hash_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38372 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsign_005fget_005fid"><code>gnutls_sign_get_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38373 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsign_005fget_005fname"><code>gnutls_sign_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38374 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsign_005fget_005fpk_005falgorithm"><code>gnutls_sign_get_pk_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38375 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsign_005fis_005fsecure"><code>gnutls_sign_is_secure</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38376 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsign_005flist"><code>gnutls_sign_list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38377 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fallocate_005fclient_005fcredentials"><code>gnutls_srp_allocate_client_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38378 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fallocate_005fserver_005fcredentials"><code>gnutls_srp_allocate_server_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38379 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fbase64_005fdecode"><code>gnutls_srp_base64_decode</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38380 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fbase64_005fdecode_005falloc"><code>gnutls_srp_base64_decode_alloc</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38381 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fbase64_005fencode"><code>gnutls_srp_base64_encode</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38382 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fbase64_005fencode_005falloc"><code>gnutls_srp_base64_encode_alloc</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38383 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005ffree_005fclient_005fcredentials"><code>gnutls_srp_free_client_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38384 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005ffree_005fserver_005fcredentials"><code>gnutls_srp_free_server_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38385 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fserver_005fget_005fusername"><code>gnutls_srp_server_get_username</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38386 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fset_005fclient_005fcredentials"><code>gnutls_srp_set_client_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38387 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fset_005fclient_005fcredentials_005ffunction"><code>gnutls_srp_set_client_credentials_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#SRP-credentials">SRP credentials</a></td></tr>
38388 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fset_005fclient_005fcredentials_005ffunction-1"><code>gnutls_srp_set_client_credentials_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38389 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fset_005fprime_005fbits"><code>gnutls_srp_set_prime_bits</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38390 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffile"><code>gnutls_srp_set_server_credentials_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#SRP-credentials">SRP credentials</a></td></tr>
38391 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffile-1"><code>gnutls_srp_set_server_credentials_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38392 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffunction"><code>gnutls_srp_set_server_credentials_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#SRP-credentials">SRP credentials</a></td></tr>
38393 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffunction-1"><code>gnutls_srp_set_server_credentials_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38394 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fset_005fserver_005ffake_005fsalt_005fseed"><code>gnutls_srp_set_server_fake_salt_seed</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38395 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fverifier"><code>gnutls_srp_verifier</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Authentication-using-SRP">Authentication using SRP</a></td></tr>
38396 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrp_005fverifier-1"><code>gnutls_srp_verifier</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38397 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrtp_005fget_005fkeys"><code>gnutls_srtp_get_keys</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#SRTP">SRTP</a></td></tr>
38398 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrtp_005fget_005fkeys-1"><code>gnutls_srtp_get_keys</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38399 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrtp_005fget_005fmki"><code>gnutls_srtp_get_mki</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38400 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrtp_005fget_005fprofile_005fid"><code>gnutls_srtp_get_profile_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38401 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrtp_005fget_005fprofile_005fname"><code>gnutls_srtp_get_profile_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38402 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrtp_005fget_005fselected_005fprofile"><code>gnutls_srtp_get_selected_profile</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38403 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrtp_005fset_005fmki"><code>gnutls_srtp_set_mki</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38404 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrtp_005fset_005fprofile"><code>gnutls_srtp_set_profile</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38405 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsrtp_005fset_005fprofile_005fdirect"><code>gnutls_srtp_set_profile_direct</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38406 <tr><td></td><td valign="top"><a href="#index-gnutls_005fstore_005fcommitment"><code>gnutls_store_commitment</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-verification">Certificate verification</a></td></tr>
38407 <tr><td></td><td valign="top"><a href="#index-gnutls_005fstore_005fcommitment-1"><code>gnutls_store_commitment</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38408 <tr><td></td><td valign="top"><a href="#index-gnutls_005fstore_005fpubkey"><code>gnutls_store_pubkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-verification">Certificate verification</a></td></tr>
38409 <tr><td></td><td valign="top"><a href="#index-gnutls_005fstore_005fpubkey-1"><code>gnutls_store_pubkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38410 <tr><td></td><td valign="top"><a href="#index-gnutls_005fstrerror"><code>gnutls_strerror</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38411 <tr><td></td><td valign="top"><a href="#index-gnutls_005fstrerror_005fname"><code>gnutls_strerror_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38412 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsubject_005falt_005fnames_005fdeinit"><code>gnutls_subject_alt_names_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38413 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsubject_005falt_005fnames_005fget"><code>gnutls_subject_alt_names_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38414 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsubject_005falt_005fnames_005finit"><code>gnutls_subject_alt_names_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38415 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsubject_005falt_005fnames_005fset"><code>gnutls_subject_alt_names_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38416 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsupplemental_005fget_005fname"><code>gnutls_supplemental_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38417 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftdb_005fdeinit"><code>gnutls_tdb_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38418 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftdb_005finit"><code>gnutls_tdb_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38419 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftdb_005fset_005fstore_005fcommitment_005ffunc"><code>gnutls_tdb_set_store_commitment_func</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38420 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftdb_005fset_005fstore_005ffunc"><code>gnutls_tdb_set_store_func</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38421 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftdb_005fset_005fverify_005ffunc"><code>gnutls_tdb_set_verify_func</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38422 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftpm_005fget_005fregistered"><code>gnutls_tpm_get_registered</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TPM-API">TPM API</a></td></tr>
38423 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftpm_005fkey_005flist_005fdeinit"><code>gnutls_tpm_key_list_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TPM-API">TPM API</a></td></tr>
38424 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftpm_005fkey_005flist_005fget_005furl"><code>gnutls_tpm_key_list_get_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TPM-API">TPM API</a></td></tr>
38425 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftpm_005fprivkey_005fdelete"><code>gnutls_tpm_privkey_delete</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Key-generation">Key generation</a></td></tr>
38426 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftpm_005fprivkey_005fdelete-1"><code>gnutls_tpm_privkey_delete</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Using-keys">Using keys</a></td></tr>
38427 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftpm_005fprivkey_005fdelete-2"><code>gnutls_tpm_privkey_delete</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TPM-API">TPM API</a></td></tr>
38428 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftpm_005fprivkey_005fgenerate"><code>gnutls_tpm_privkey_generate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Key-generation">Key generation</a></td></tr>
38429 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftpm_005fprivkey_005fgenerate-1"><code>gnutls_tpm_privkey_generate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TPM-API">TPM API</a></td></tr>
38430 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fget_005fint"><code>gnutls_transport_get_int</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38431 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fget_005fint2"><code>gnutls_transport_get_int2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38432 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fget_005fptr"><code>gnutls_transport_get_ptr</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38433 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fget_005fptr2"><code>gnutls_transport_get_ptr2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38434 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005ferrno"><code>gnutls_transport_set_errno</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Setting-up-the-transport-layer">Setting up the transport layer</a></td></tr>
38435 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005ferrno-1"><code>gnutls_transport_set_errno</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38436 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005ferrno_005ffunction"><code>gnutls_transport_set_errno_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38437 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fint"><code>gnutls_transport_set_int</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38438 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fint2"><code>gnutls_transport_set_int2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38439 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fptr"><code>gnutls_transport_set_ptr</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38440 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fptr2"><code>gnutls_transport_set_ptr2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38441 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fpull_005ffunction"><code>gnutls_transport_set_pull_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Setting-up-the-transport-layer">Setting up the transport layer</a></td></tr>
38442 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fpull_005ffunction-1"><code>gnutls_transport_set_pull_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38443 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction"><code>gnutls_transport_set_pull_timeout_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Setting-up-the-transport-layer">Setting up the transport layer</a></td></tr>
38444 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction-1"><code>gnutls_transport_set_pull_timeout_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Setting-up-the-transport-layer">Setting up the transport layer</a></td></tr>
38445 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction-2"><code>gnutls_transport_set_pull_timeout_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38446 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fpush_005ffunction"><code>gnutls_transport_set_push_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Setting-up-the-transport-layer">Setting up the transport layer</a></td></tr>
38447 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fpush_005ffunction-1"><code>gnutls_transport_set_push_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38448 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fvec_005fpush_005ffunction"><code>gnutls_transport_set_vec_push_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Setting-up-the-transport-layer">Setting up the transport layer</a></td></tr>
38449 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fvec_005fpush_005ffunction-1"><code>gnutls_transport_set_vec_push_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38450 <tr><td></td><td valign="top"><a href="#index-gnutls_005furl_005fis_005fsupported"><code>gnutls_url_is_supported</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-public-keys">Abstract public keys</a></td></tr>
38451 <tr><td></td><td valign="top"><a href="#index-gnutls_005furl_005fis_005fsupported-1"><code>gnutls_url_is_supported</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38452 <tr><td></td><td valign="top"><a href="#index-gnutls_005fverify_005fstored_005fpubkey"><code>gnutls_verify_stored_pubkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-verification">Certificate verification</a></td></tr>
38453 <tr><td></td><td valign="top"><a href="#index-gnutls_005fverify_005fstored_005fpubkey-1"><code>gnutls_verify_stored_pubkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-TLS-API">Core TLS API</a></td></tr>
38454 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005faia_005fdeinit"><code>gnutls_x509_aia_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38455 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005faia_005fget"><code>gnutls_x509_aia_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38456 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005faia_005finit"><code>gnutls_x509_aia_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38457 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005faia_005fset"><code>gnutls_x509_aia_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38458 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005faki_005fdeinit"><code>gnutls_x509_aki_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38459 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005faki_005fget_005fcert_005fissuer"><code>gnutls_x509_aki_get_cert_issuer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38460 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005faki_005fget_005fid"><code>gnutls_x509_aki_get_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38461 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005faki_005finit"><code>gnutls_x509_aki_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38462 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005faki_005fset_005fcert_005fissuer"><code>gnutls_x509_aki_set_cert_issuer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38463 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005faki_005fset_005fid"><code>gnutls_x509_aki_set_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38464 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fcheck_005fissuer"><code>gnutls_x509_crl_check_issuer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38465 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fdeinit"><code>gnutls_x509_crl_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38466 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fdist_005fpoints_005fdeinit"><code>gnutls_x509_crl_dist_points_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38467 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fdist_005fpoints_005fget"><code>gnutls_x509_crl_dist_points_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38468 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fdist_005fpoints_005finit"><code>gnutls_x509_crl_dist_points_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38469 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fdist_005fpoints_005fset"><code>gnutls_x509_crl_dist_points_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38470 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fexport"><code>gnutls_x509_crl_export</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38471 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fexport2"><code>gnutls_x509_crl_export2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38472 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fauthority_005fkey_005fgn_005fserial"><code>gnutls_x509_crl_get_authority_key_gn_serial</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38473 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fauthority_005fkey_005fid"><code>gnutls_x509_crl_get_authority_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38474 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fcrt_005fcount"><code>gnutls_x509_crl_get_crt_count</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38475 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fcrt_005fserial"><code>gnutls_x509_crl_get_crt_serial</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKIX-certificate-revocation-lists">PKIX certificate revocation lists</a></td></tr>
38476 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fcrt_005fserial-1"><code>gnutls_x509_crl_get_crt_serial</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38477 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fdn_005foid"><code>gnutls_x509_crl_get_dn_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38478 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fextension_005fdata"><code>gnutls_x509_crl_get_extension_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38479 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fextension_005fdata2"><code>gnutls_x509_crl_get_extension_data2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38480 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fextension_005finfo"><code>gnutls_x509_crl_get_extension_info</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38481 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fextension_005foid"><code>gnutls_x509_crl_get_extension_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38482 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn"><code>gnutls_x509_crl_get_issuer_dn</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38483 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn2"><code>gnutls_x509_crl_get_issuer_dn2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38484 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn_005fby_005foid"><code>gnutls_x509_crl_get_issuer_dn_by_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38485 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fnext_005fupdate"><code>gnutls_x509_crl_get_next_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38486 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fnumber"><code>gnutls_x509_crl_get_number</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38487 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fraw_005fissuer_005fdn"><code>gnutls_x509_crl_get_raw_issuer_dn</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38488 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fsignature"><code>gnutls_x509_crl_get_signature</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38489 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fsignature_005falgorithm"><code>gnutls_x509_crl_get_signature_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38490 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fthis_005fupdate"><code>gnutls_x509_crl_get_this_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38491 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fget_005fversion"><code>gnutls_x509_crl_get_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38492 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fimport"><code>gnutls_x509_crl_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38493 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005finit"><code>gnutls_x509_crl_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38494 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fiter_005fcrt_005fserial"><code>gnutls_x509_crl_iter_crt_serial</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38495 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fiter_005fdeinit"><code>gnutls_x509_crl_iter_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38496 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005flist_005fimport"><code>gnutls_x509_crl_list_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38497 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005flist_005fimport2"><code>gnutls_x509_crl_list_import2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38498 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fprint"><code>gnutls_x509_crl_print</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38499 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fprivkey_005fsign"><code>gnutls_x509_crl_privkey_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKIX-certificate-revocation-lists">PKIX certificate revocation lists</a></td></tr>
38500 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fprivkey_005fsign-1"><code>gnutls_x509_crl_privkey_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38501 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fset_005fauthority_005fkey_005fid"><code>gnutls_x509_crl_set_authority_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38502 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fset_005fcrt"><code>gnutls_x509_crl_set_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38503 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fset_005fcrt_005fserial"><code>gnutls_x509_crl_set_crt_serial</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38504 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fset_005fnext_005fupdate"><code>gnutls_x509_crl_set_next_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38505 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fset_005fnumber"><code>gnutls_x509_crl_set_number</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38506 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fset_005fthis_005fupdate"><code>gnutls_x509_crl_set_this_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38507 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fset_005fversion"><code>gnutls_x509_crl_set_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38508 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fsign"><code>gnutls_x509_crl_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38509 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fsign2"><code>gnutls_x509_crl_sign2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKIX-certificate-revocation-lists">PKIX certificate revocation lists</a></td></tr>
38510 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fsign2-1"><code>gnutls_x509_crl_sign2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38511 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrl_005fverify"><code>gnutls_x509_crl_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38512 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fdeinit"><code>gnutls_x509_crq_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38513 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fexport"><code>gnutls_x509_crq_export</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38514 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fexport2"><code>gnutls_x509_crq_export2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38515 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fattribute_005fby_005foid"><code>gnutls_x509_crq_get_attribute_by_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38516 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fattribute_005fdata"><code>gnutls_x509_crq_get_attribute_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38517 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fattribute_005finfo"><code>gnutls_x509_crq_get_attribute_info</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38518 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fbasic_005fconstraints"><code>gnutls_x509_crq_get_basic_constraints</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38519 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fchallenge_005fpassword"><code>gnutls_x509_crq_get_challenge_password</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38520 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fdn"><code>gnutls_x509_crq_get_dn</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38521 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fdn2"><code>gnutls_x509_crq_get_dn2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38522 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fdn_005fby_005foid"><code>gnutls_x509_crq_get_dn_by_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38523 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fdn_005foid"><code>gnutls_x509_crq_get_dn_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38524 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fextension_005fby_005foid"><code>gnutls_x509_crq_get_extension_by_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38525 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fextension_005fby_005foid2"><code>gnutls_x509_crq_get_extension_by_oid2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38526 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fextension_005fdata"><code>gnutls_x509_crq_get_extension_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38527 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fextension_005fdata2"><code>gnutls_x509_crq_get_extension_data2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38528 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fextension_005finfo"><code>gnutls_x509_crq_get_extension_info</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38529 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fkey_005fid"><code>gnutls_x509_crq_get_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38530 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fkey_005fpurpose_005foid"><code>gnutls_x509_crq_get_key_purpose_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38531 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fkey_005frsa_005fraw"><code>gnutls_x509_crq_get_key_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38532 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fkey_005fusage"><code>gnutls_x509_crq_get_key_usage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38533 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fpk_005falgorithm"><code>gnutls_x509_crq_get_pk_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38534 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fprivate_005fkey_005fusage_005fperiod"><code>gnutls_x509_crq_get_private_key_usage_period</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38535 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fsubject_005falt_005fname"><code>gnutls_x509_crq_get_subject_alt_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38536 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fsubject_005falt_005fothername_005foid"><code>gnutls_x509_crq_get_subject_alt_othername_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38537 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fget_005fversion"><code>gnutls_x509_crq_get_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38538 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fimport"><code>gnutls_x509_crq_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38539 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005finit"><code>gnutls_x509_crq_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38540 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fprint"><code>gnutls_x509_crq_print</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38541 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fprivkey_005fsign"><code>gnutls_x509_crq_privkey_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38542 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fattribute_005fby_005foid"><code>gnutls_x509_crq_set_attribute_by_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38543 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fbasic_005fconstraints"><code>gnutls_x509_crq_set_basic_constraints</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38544 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fchallenge_005fpassword"><code>gnutls_x509_crq_set_challenge_password</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38545 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fdn"><code>gnutls_x509_crq_set_dn</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38546 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fdn_005fby_005foid"><code>gnutls_x509_crq_set_dn_by_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38547 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fkey"><code>gnutls_x509_crq_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-10-certificate-requests">PKCS 10 certificate requests</a></td></tr>
38548 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fkey-1"><code>gnutls_x509_crq_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38549 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fkey_005fpurpose_005foid"><code>gnutls_x509_crq_set_key_purpose_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38550 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fkey_005frsa_005fraw"><code>gnutls_x509_crq_set_key_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38551 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fkey_005fusage"><code>gnutls_x509_crq_set_key_usage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38552 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fprivate_005fkey_005fusage_005fperiod"><code>gnutls_x509_crq_set_private_key_usage_period</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38553 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fpubkey"><code>gnutls_x509_crq_set_pubkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Operations">Operations</a></td></tr>
38554 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fpubkey-1"><code>gnutls_x509_crq_set_pubkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38555 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fsubject_005falt_005fname"><code>gnutls_x509_crq_set_subject_alt_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38556 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fset_005fversion"><code>gnutls_x509_crq_set_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38557 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fsign"><code>gnutls_x509_crq_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38558 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fsign2"><code>gnutls_x509_crq_sign2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-10-certificate-requests">PKCS 10 certificate requests</a></td></tr>
38559 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fsign2-1"><code>gnutls_x509_crq_sign2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38560 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrq_005fverify"><code>gnutls_x509_crq_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38561 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fcheck_005fhostname"><code>gnutls_x509_crt_check_hostname</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38562 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fcheck_005fhostname2"><code>gnutls_x509_crt_check_hostname2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38563 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fcheck_005fissuer"><code>gnutls_x509_crt_check_issuer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38564 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fcheck_005frevocation"><code>gnutls_x509_crt_check_revocation</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38565 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fcpy_005fcrl_005fdist_005fpoints"><code>gnutls_x509_crt_cpy_crl_dist_points</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38566 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fdeinit"><code>gnutls_x509_crt_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38567 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fexport"><code>gnutls_x509_crt_export</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38568 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fexport2"><code>gnutls_x509_crt_export2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38569 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005factivation_005ftime"><code>gnutls_x509_crt_get_activation_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38570 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fauthority_005finfo_005faccess"><code>gnutls_x509_crt_get_authority_info_access</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38571 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fauthority_005fkey_005fgn_005fserial"><code>gnutls_x509_crt_get_authority_key_gn_serial</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38572 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fauthority_005fkey_005fid"><code>gnutls_x509_crt_get_authority_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38573 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fbasic_005fconstraints"><code>gnutls_x509_crt_get_basic_constraints</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38574 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fca_005fstatus"><code>gnutls_x509_crt_get_ca_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38575 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fcrl_005fdist_005fpoints"><code>gnutls_x509_crt_get_crl_dist_points</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38576 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fdn"><code>gnutls_x509_crt_get_dn</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38577 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fdn2"><code>gnutls_x509_crt_get_dn2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X_002e509-distinguished-names">X.509 distinguished names</a></td></tr>
38578 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fdn2-1"><code>gnutls_x509_crt_get_dn2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38579 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fdn_005fby_005foid"><code>gnutls_x509_crt_get_dn_by_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38580 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fdn_005foid"><code>gnutls_x509_crt_get_dn_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38581 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fexpiration_005ftime"><code>gnutls_x509_crt_get_expiration_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38582 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fextension_005fby_005foid"><code>gnutls_x509_crt_get_extension_by_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38583 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fextension_005fby_005foid2"><code>gnutls_x509_crt_get_extension_by_oid2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38584 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fextension_005fdata"><code>gnutls_x509_crt_get_extension_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38585 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fextension_005fdata2"><code>gnutls_x509_crt_get_extension_data2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38586 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fextension_005finfo"><code>gnutls_x509_crt_get_extension_info</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38587 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fextension_005foid"><code>gnutls_x509_crt_get_extension_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38588 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005ffingerprint"><code>gnutls_x509_crt_get_fingerprint</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38589 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fissuer"><code>gnutls_x509_crt_get_issuer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38590 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fname"><code>gnutls_x509_crt_get_issuer_alt_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38591 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fname2"><code>gnutls_x509_crt_get_issuer_alt_name2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38592 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fothername_005foid"><code>gnutls_x509_crt_get_issuer_alt_othername_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38593 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn"><code>gnutls_x509_crt_get_issuer_dn</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38594 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn2"><code>gnutls_x509_crt_get_issuer_dn2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38595 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005fby_005foid"><code>gnutls_x509_crt_get_issuer_dn_by_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38596 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005foid"><code>gnutls_x509_crt_get_issuer_dn_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38597 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fissuer_005funique_005fid"><code>gnutls_x509_crt_get_issuer_unique_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38598 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fkey_005fid"><code>gnutls_x509_crt_get_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X_002e509-public-and-private-keys">X.509 public and private keys</a></td></tr>
38599 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fkey_005fid-1"><code>gnutls_x509_crt_get_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38600 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fkey_005fpurpose_005foid"><code>gnutls_x509_crt_get_key_purpose_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38601 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fkey_005fusage"><code>gnutls_x509_crt_get_key_usage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38602 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fname_005fconstraints"><code>gnutls_x509_crt_get_name_constraints</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38603 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fpk_005falgorithm"><code>gnutls_x509_crt_get_pk_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38604 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fpk_005fdsa_005fraw"><code>gnutls_x509_crt_get_pk_dsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38605 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fpk_005frsa_005fraw"><code>gnutls_x509_crt_get_pk_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38606 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fpolicy"><code>gnutls_x509_crt_get_policy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38607 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fpreferred_005fhash_005falgorithm"><code>gnutls_x509_crt_get_preferred_hash_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38608 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fprivate_005fkey_005fusage_005fperiod"><code>gnutls_x509_crt_get_private_key_usage_period</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38609 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fproxy"><code>gnutls_x509_crt_get_proxy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38610 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fraw_005fdn"><code>gnutls_x509_crt_get_raw_dn</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38611 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fraw_005fissuer_005fdn"><code>gnutls_x509_crt_get_raw_issuer_dn</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38612 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fserial"><code>gnutls_x509_crt_get_serial</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38613 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fsignature"><code>gnutls_x509_crt_get_signature</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38614 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fsignature_005falgorithm"><code>gnutls_x509_crt_get_signature_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38615 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fsubject"><code>gnutls_x509_crt_get_subject</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38616 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fname"><code>gnutls_x509_crt_get_subject_alt_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38617 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fname2"><code>gnutls_x509_crt_get_subject_alt_name2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38618 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fothername_005foid"><code>gnutls_x509_crt_get_subject_alt_othername_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38619 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fsubject_005fkey_005fid"><code>gnutls_x509_crt_get_subject_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38620 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fsubject_005funique_005fid"><code>gnutls_x509_crt_get_subject_unique_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38621 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fverify_005falgorithm"><code>gnutls_x509_crt_get_verify_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38622 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fget_005fversion"><code>gnutls_x509_crt_get_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38623 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fimport"><code>gnutls_x509_crt_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38624 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fimport_005fpkcs11"><code>gnutls_x509_crt_import_pkcs11</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38625 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fimport_005fpkcs11_005furl"><code>gnutls_x509_crt_import_pkcs11_url</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38626 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005finit"><code>gnutls_x509_crt_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38627 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005flist_005fimport"><code>gnutls_x509_crt_list_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38628 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005flist_005fimport2"><code>gnutls_x509_crt_list_import2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38629 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005flist_005fimport_005fpkcs11"><code>gnutls_x509_crt_list_import_pkcs11</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-11-API">PKCS 11 API</a></td></tr>
38630 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005flist_005fverify"><code>gnutls_x509_crt_list_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38631 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fprint"><code>gnutls_x509_crt_print</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38632 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fprivkey_005fsign"><code>gnutls_x509_crt_privkey_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38633 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005factivation_005ftime"><code>gnutls_x509_crt_set_activation_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38634 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fauthority_005finfo_005faccess"><code>gnutls_x509_crt_set_authority_info_access</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38635 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fauthority_005fkey_005fid"><code>gnutls_x509_crt_set_authority_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38636 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fbasic_005fconstraints"><code>gnutls_x509_crt_set_basic_constraints</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38637 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fca_005fstatus"><code>gnutls_x509_crt_set_ca_status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38638 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fcrl_005fdist_005fpoints"><code>gnutls_x509_crt_set_crl_dist_points</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38639 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fcrl_005fdist_005fpoints2"><code>gnutls_x509_crt_set_crl_dist_points2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38640 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fcrq"><code>gnutls_x509_crt_set_crq</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38641 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fcrq_005fextensions"><code>gnutls_x509_crt_set_crq_extensions</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38642 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fdn"><code>gnutls_x509_crt_set_dn</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38643 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fdn_005fby_005foid"><code>gnutls_x509_crt_set_dn_by_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38644 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fexpiration_005ftime"><code>gnutls_x509_crt_set_expiration_time</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38645 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fextension_005fby_005foid"><code>gnutls_x509_crt_set_extension_by_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38646 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fissuer_005falt_005fname"><code>gnutls_x509_crt_set_issuer_alt_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38647 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fissuer_005fdn"><code>gnutls_x509_crt_set_issuer_dn</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38648 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fissuer_005fdn_005fby_005foid"><code>gnutls_x509_crt_set_issuer_dn_by_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38649 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fissuer_005funique_005fid"><code>gnutls_x509_crt_set_issuer_unique_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38650 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fkey"><code>gnutls_x509_crt_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38651 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fkey_005fpurpose_005foid"><code>gnutls_x509_crt_set_key_purpose_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38652 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fkey_005fusage"><code>gnutls_x509_crt_set_key_usage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38653 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fname_005fconstraints"><code>gnutls_x509_crt_set_name_constraints</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38654 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fpin_005ffunction"><code>gnutls_x509_crt_set_pin_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38655 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fpolicy"><code>gnutls_x509_crt_set_policy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38656 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fprivate_005fkey_005fusage_005fperiod"><code>gnutls_x509_crt_set_private_key_usage_period</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38657 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fproxy"><code>gnutls_x509_crt_set_proxy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38658 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fproxy_005fdn"><code>gnutls_x509_crt_set_proxy_dn</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38659 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fpubkey"><code>gnutls_x509_crt_set_pubkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Operations">Operations</a></td></tr>
38660 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fpubkey-1"><code>gnutls_x509_crt_set_pubkey</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-API">Abstract key API</a></td></tr>
38661 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fserial"><code>gnutls_x509_crt_set_serial</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38662 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fsubject_005falternative_005fname"><code>gnutls_x509_crt_set_subject_alternative_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38663 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fsubject_005falt_005fname"><code>gnutls_x509_crt_set_subject_alt_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38664 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fsubject_005fkey_005fid"><code>gnutls_x509_crt_set_subject_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38665 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fsubject_005funique_005fid"><code>gnutls_x509_crt_set_subject_unique_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38666 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fset_005fversion"><code>gnutls_x509_crt_set_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38667 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fsign"><code>gnutls_x509_crt_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38668 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fsign2"><code>gnutls_x509_crt_sign2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38669 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fverify"><code>gnutls_x509_crt_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38670 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fverify_005fdata"><code>gnutls_x509_crt_verify_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38671 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fcrt_005fverify_005fhash"><code>gnutls_x509_crt_verify_hash</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38672 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fdn_005fdeinit"><code>gnutls_x509_dn_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38673 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fdn_005fexport"><code>gnutls_x509_dn_export</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38674 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fdn_005fexport2"><code>gnutls_x509_dn_export2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38675 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fdn_005fget_005frdn_005fava"><code>gnutls_x509_dn_get_rdn_ava</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X_002e509-distinguished-names">X.509 distinguished names</a></td></tr>
38676 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fdn_005fget_005frdn_005fava-1"><code>gnutls_x509_dn_get_rdn_ava</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38677 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fdn_005fimport"><code>gnutls_x509_dn_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38678 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fdn_005finit"><code>gnutls_x509_dn_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38679 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fdn_005foid_005fknown"><code>gnutls_x509_dn_oid_known</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38680 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fdn_005foid_005fname"><code>gnutls_x509_dn_oid_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38681 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fdeinit"><code>gnutls_x509_ext_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38682 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fexport_005faia"><code>gnutls_x509_ext_export_aia</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38683 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fexport_005fauthority_005fkey_005fid"><code>gnutls_x509_ext_export_authority_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38684 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fexport_005fbasic_005fconstraints"><code>gnutls_x509_ext_export_basic_constraints</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38685 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fexport_005fcrl_005fdist_005fpoints"><code>gnutls_x509_ext_export_crl_dist_points</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38686 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fexport_005fkey_005fpurposes"><code>gnutls_x509_ext_export_key_purposes</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38687 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fexport_005fkey_005fusage"><code>gnutls_x509_ext_export_key_usage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38688 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fexport_005fname_005fconstraints"><code>gnutls_x509_ext_export_name_constraints</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38689 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fexport_005fpolicies"><code>gnutls_x509_ext_export_policies</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38690 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fexport_005fprivate_005fkey_005fusage_005fperiod"><code>gnutls_x509_ext_export_private_key_usage_period</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38691 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fexport_005fproxy"><code>gnutls_x509_ext_export_proxy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38692 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fexport_005fsubject_005falt_005fnames"><code>gnutls_x509_ext_export_subject_alt_names</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38693 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fexport_005fsubject_005fkey_005fid"><code>gnutls_x509_ext_export_subject_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38694 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fimport_005faia"><code>gnutls_x509_ext_import_aia</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38695 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fimport_005fauthority_005fkey_005fid"><code>gnutls_x509_ext_import_authority_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38696 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fimport_005fbasic_005fconstraints"><code>gnutls_x509_ext_import_basic_constraints</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38697 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fimport_005fcrl_005fdist_005fpoints"><code>gnutls_x509_ext_import_crl_dist_points</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38698 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fimport_005fkey_005fpurposes"><code>gnutls_x509_ext_import_key_purposes</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38699 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fimport_005fkey_005fusage"><code>gnutls_x509_ext_import_key_usage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38700 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fimport_005fname_005fconstraints"><code>gnutls_x509_ext_import_name_constraints</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38701 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fimport_005fpolicies"><code>gnutls_x509_ext_import_policies</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38702 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fimport_005fprivate_005fkey_005fusage_005fperiod"><code>gnutls_x509_ext_import_private_key_usage_period</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38703 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fimport_005fproxy"><code>gnutls_x509_ext_import_proxy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38704 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fimport_005fsubject_005falt_005fnames"><code>gnutls_x509_ext_import_subject_alt_names</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38705 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fimport_005fsubject_005fkey_005fid"><code>gnutls_x509_ext_import_subject_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38706 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fext_005fprint"><code>gnutls_x509_ext_print</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38707 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fkey_005fpurpose_005fdeinit"><code>gnutls_x509_key_purpose_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38708 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fkey_005fpurpose_005fget"><code>gnutls_x509_key_purpose_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38709 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fkey_005fpurpose_005finit"><code>gnutls_x509_key_purpose_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38710 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fkey_005fpurpose_005fset"><code>gnutls_x509_key_purpose_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38711 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fname_005fconstraints_005fadd_005fexcluded"><code>gnutls_x509_name_constraints_add_excluded</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38712 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fname_005fconstraints_005fadd_005fpermitted"><code>gnutls_x509_name_constraints_add_permitted</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38713 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fname_005fconstraints_005fcheck"><code>gnutls_x509_name_constraints_check</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38714 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fname_005fconstraints_005fcheck_005fcrt"><code>gnutls_x509_name_constraints_check_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38715 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fname_005fconstraints_005fdeinit"><code>gnutls_x509_name_constraints_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38716 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fname_005fconstraints_005fget_005fexcluded"><code>gnutls_x509_name_constraints_get_excluded</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38717 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fname_005fconstraints_005fget_005fpermitted"><code>gnutls_x509_name_constraints_get_permitted</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38718 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fname_005fconstraints_005finit"><code>gnutls_x509_name_constraints_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38719 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fothername_005fto_005fvirtual"><code>gnutls_x509_othername_to_virtual</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38720 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fpolicies_005fdeinit"><code>gnutls_x509_policies_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38721 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fpolicies_005fget"><code>gnutls_x509_policies_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38722 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fpolicies_005finit"><code>gnutls_x509_policies_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38723 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fpolicies_005fset"><code>gnutls_x509_policies_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38724 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fpolicy_005frelease"><code>gnutls_x509_policy_release</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38725 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fcpy"><code>gnutls_x509_privkey_cpy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38726 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fdeinit"><code>gnutls_x509_privkey_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38727 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fexport"><code>gnutls_x509_privkey_export</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38728 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fexport2"><code>gnutls_x509_privkey_export2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38729 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fexport2_005fpkcs8"><code>gnutls_x509_privkey_export2_pkcs8</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38730 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fexport_005fdsa_005fraw"><code>gnutls_x509_privkey_export_dsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38731 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fexport_005fecc_005fraw"><code>gnutls_x509_privkey_export_ecc_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38732 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fexport_005fpkcs8"><code>gnutls_x509_privkey_export_pkcs8</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38733 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fexport_005frsa_005fraw"><code>gnutls_x509_privkey_export_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38734 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fexport_005frsa_005fraw2"><code>gnutls_x509_privkey_export_rsa_raw2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38735 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005ffix"><code>gnutls_x509_privkey_fix</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38736 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fgenerate"><code>gnutls_x509_privkey_generate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38737 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fget_005fkey_005fid"><code>gnutls_x509_privkey_get_key_id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38738 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fget_005fpk_005falgorithm"><code>gnutls_x509_privkey_get_pk_algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38739 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fget_005fpk_005falgorithm2"><code>gnutls_x509_privkey_get_pk_algorithm2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38740 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fimport"><code>gnutls_x509_privkey_import</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38741 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fimport2"><code>gnutls_x509_privkey_import2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Managing-encrypted-keys">Managing encrypted keys</a></td></tr>
38742 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fimport2-1"><code>gnutls_x509_privkey_import2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38743 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fimport_005fdsa_005fraw"><code>gnutls_x509_privkey_import_dsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38744 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fimport_005fecc_005fraw"><code>gnutls_x509_privkey_import_ecc_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38745 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fimport_005fopenssl"><code>gnutls_x509_privkey_import_openssl</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Managing-encrypted-keys">Managing encrypted keys</a></td></tr>
38746 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fimport_005fopenssl-1"><code>gnutls_x509_privkey_import_openssl</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38747 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fimport_005fpkcs8"><code>gnutls_x509_privkey_import_pkcs8</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38748 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fimport_005frsa_005fraw"><code>gnutls_x509_privkey_import_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38749 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fimport_005frsa_005fraw2"><code>gnutls_x509_privkey_import_rsa_raw2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38750 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005finit"><code>gnutls_x509_privkey_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38751 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fsec_005fparam"><code>gnutls_x509_privkey_sec_param</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38752 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fsign_005fdata"><code>gnutls_x509_privkey_sign_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38753 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fsign_005fhash"><code>gnutls_x509_privkey_sign_hash</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-API">Compatibility API</a></td></tr>
38754 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fverify_005fparams"><code>gnutls_x509_privkey_verify_params</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38755 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005frdn_005fget"><code>gnutls_x509_rdn_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38756 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005frdn_005fget_005fby_005foid"><code>gnutls_x509_rdn_get_by_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38757 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005frdn_005fget_005foid"><code>gnutls_x509_rdn_get_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38758 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fadd_005fcas"><code>gnutls_x509_trust_list_add_cas</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-X_002e509-certificate-paths">Verifying X.509 certificate paths</a></td></tr>
38759 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fadd_005fcas-1"><code>gnutls_x509_trust_list_add_cas</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38760 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fadd_005fcrls"><code>gnutls_x509_trust_list_add_crls</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-X_002e509-certificate-paths">Verifying X.509 certificate paths</a></td></tr>
38761 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fadd_005fcrls-1"><code>gnutls_x509_trust_list_add_crls</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38762 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fadd_005fnamed_005fcrt"><code>gnutls_x509_trust_list_add_named_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-X_002e509-certificate-paths">Verifying X.509 certificate paths</a></td></tr>
38763 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fadd_005fnamed_005fcrt-1"><code>gnutls_x509_trust_list_add_named_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38764 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fadd_005fsystem_005ftrust"><code>gnutls_x509_trust_list_add_system_trust</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-X_002e509-certificate-paths">Verifying X.509 certificate paths</a></td></tr>
38765 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fadd_005fsystem_005ftrust-1"><code>gnutls_x509_trust_list_add_system_trust</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38766 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005fdir"><code>gnutls_x509_trust_list_add_trust_dir</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38767 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005ffile"><code>gnutls_x509_trust_list_add_trust_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-X_002e509-certificate-paths">Verifying X.509 certificate paths</a></td></tr>
38768 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005ffile-1"><code>gnutls_x509_trust_list_add_trust_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38769 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005fmem"><code>gnutls_x509_trust_list_add_trust_mem</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-X_002e509-certificate-paths">Verifying X.509 certificate paths</a></td></tr>
38770 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fadd_005ftrust_005fmem-1"><code>gnutls_x509_trust_list_add_trust_mem</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38771 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fdeinit"><code>gnutls_x509_trust_list_deinit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38772 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fget_005fissuer"><code>gnutls_x509_trust_list_get_issuer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38773 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005finit"><code>gnutls_x509_trust_list_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38774 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fremove_005fcas"><code>gnutls_x509_trust_list_remove_cas</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38775 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fremove_005ftrust_005ffile"><code>gnutls_x509_trust_list_remove_trust_file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38776 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fremove_005ftrust_005fmem"><code>gnutls_x509_trust_list_remove_trust_mem</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38777 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt"><code>gnutls_x509_trust_list_verify_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-X_002e509-certificate-paths">Verifying X.509 certificate paths</a></td></tr>
38778 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt-1"><code>gnutls_x509_trust_list_verify_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38779 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt2"><code>gnutls_x509_trust_list_verify_crt2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-X_002e509-certificate-paths">Verifying X.509 certificate paths</a></td></tr>
38780 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fverify_005fcrt2-1"><code>gnutls_x509_trust_list_verify_crt2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38781 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fverify_005fnamed_005fcrt"><code>gnutls_x509_trust_list_verify_named_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-X_002e509-certificate-paths">Verifying X.509 certificate paths</a></td></tr>
38782 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005ftrust_005flist_005fverify_005fnamed_005fcrt-1"><code>gnutls_x509_trust_list_verify_named_crt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
38783 <tr><td colspan="4"> <hr></td></tr>
38784 </table>
38785 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Function-and-Data-Index_fn_letter-D"><b>D</b></a>
38786  &nbsp;
38787 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-G"><b>G</b></a>
38788  &nbsp;
38789 </td></tr></table>
38790
38791 <hr>
38792 <a name="Concept-Index"></a>
38793 <div class="header">
38794 <p>
38795 Previous: <a href="#Function-and-Data-Index" accesskey="p" rel="prev">Function and Data Index</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
38796 </div>
38797 <a name="Concept-Index-1"></a>
38798 <h2 class="unnumbered">Concept Index</h2>
38799
38800 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a>
38801  &nbsp;
38802 <a class="summary-letter" href="#Concept-Index_cp_letter-B"><b>B</b></a>
38803  &nbsp;
38804 <a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a>
38805  &nbsp;
38806 <a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a>
38807  &nbsp;
38808 <a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a>
38809  &nbsp;
38810 <a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a>
38811  &nbsp;
38812 <a class="summary-letter" href="#Concept-Index_cp_letter-G"><b>G</b></a>
38813  &nbsp;
38814 <a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a>
38815  &nbsp;
38816 <a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a>
38817  &nbsp;
38818 <a class="summary-letter" href="#Concept-Index_cp_letter-K"><b>K</b></a>
38819  &nbsp;
38820 <a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a>
38821  &nbsp;
38822 <a class="summary-letter" href="#Concept-Index_cp_letter-O"><b>O</b></a>
38823  &nbsp;
38824 <a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a>
38825  &nbsp;
38826 <a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a>
38827  &nbsp;
38828 <a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a>
38829  &nbsp;
38830 <a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a>
38831  &nbsp;
38832 <a class="summary-letter" href="#Concept-Index_cp_letter-U"><b>U</b></a>
38833  &nbsp;
38834 <a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a>
38835  &nbsp;
38836 <a class="summary-letter" href="#Concept-Index_cp_letter-X"><b>X</b></a>
38837  &nbsp;
38838 </td></tr></table>
38839 <table class="index-cp" border="0">
38840 <tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
38841 <tr><td colspan="4"> <hr></td></tr>
38842 <tr><th><a name="Concept-Index_cp_letter-A">A</a></th><td></td><td></td></tr>
38843 <tr><td></td><td valign="top"><a href="#index-abstract-types">abstract types</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-key-types">Abstract key types</a></td></tr>
38844 <tr><td></td><td valign="top"><a href="#index-alert-protocol">alert protocol</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-TLS-Alert-Protocol">The TLS Alert Protocol</a></td></tr>
38845 <tr><td></td><td valign="top"><a href="#index-ALPN">ALPN</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Application-Layer-Protocol-Negotiation-_0028ALPN_0029">Application Layer Protocol Negotiation (ALPN)</a></td></tr>
38846 <tr><td></td><td valign="top"><a href="#index-anonymous-authentication">anonymous authentication</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Anonymous-authentication">Anonymous authentication</a></td></tr>
38847 <tr><td></td><td valign="top"><a href="#index-API-reference">API reference</a>:</td><td>&nbsp;</td><td valign="top"><a href="#API-reference">API reference</a></td></tr>
38848 <tr><td></td><td valign="top"><a href="#index-Application-Layer-Protocol-Negotiation">Application Layer Protocol Negotiation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Application-Layer-Protocol-Negotiation-_0028ALPN_0029">Application Layer Protocol Negotiation (ALPN)</a></td></tr>
38849 <tr><td></td><td valign="top"><a href="#index-authentication-methods">authentication methods</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Authentication-methods">Authentication methods</a></td></tr>
38850 <tr><td colspan="4"> <hr></td></tr>
38851 <tr><th><a name="Concept-Index_cp_letter-B">B</a></th><td></td><td></td></tr>
38852 <tr><td></td><td valign="top"><a href="#index-bad_005frecord_005fmac">bad_record_mac</a>:</td><td>&nbsp;</td><td valign="top"><a href="#On-Record-Padding">On Record Padding</a></td></tr>
38853 <tr><td colspan="4"> <hr></td></tr>
38854 <tr><th><a name="Concept-Index_cp_letter-C">C</a></th><td></td><td></td></tr>
38855 <tr><td></td><td valign="top"><a href="#index-callback-functions">callback functions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Callback-functions">Callback functions</a></td></tr>
38856 <tr><td></td><td valign="top"><a href="#index-certificate-authentication">certificate authentication</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-authentication">Certificate authentication</a></td></tr>
38857 <tr><td></td><td valign="top"><a href="#index-certificate-authentication-1">certificate authentication</a>:</td><td>&nbsp;</td><td valign="top"><a href="#More-on-certificate-authentication">More on certificate authentication</a></td></tr>
38858 <tr><td></td><td valign="top"><a href="#index-certificate-requests">certificate requests</a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-10-certificate-requests">PKCS 10 certificate requests</a></td></tr>
38859 <tr><td></td><td valign="top"><a href="#index-certificate-revocation-lists">certificate revocation lists</a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKIX-certificate-revocation-lists">PKIX certificate revocation lists</a></td></tr>
38860 <tr><td></td><td valign="top"><a href="#index-certificate-status">certificate status</a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-certificate-status-checking">OCSP certificate status checking</a></td></tr>
38861 <tr><td></td><td valign="top"><a href="#index-Certificate-status-request">Certificate status request</a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-status-request">OCSP status request</a></td></tr>
38862 <tr><td></td><td valign="top"><a href="#index-Certificate-verification">Certificate verification</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Advanced-certificate-verification">Advanced certificate verification</a></td></tr>
38863 <tr><td></td><td valign="top"><a href="#index-certification">certification</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certification">Certification</a></td></tr>
38864 <tr><td></td><td valign="top"><a href="#index-certtool"><code>certtool</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#certtool-Invocation">certtool Invocation</a></td></tr>
38865 <tr><td></td><td valign="top"><a href="#index-certtool-help">certtool help</a>:</td><td>&nbsp;</td><td valign="top"><a href="#certtool-Invocation">certtool Invocation</a></td></tr>
38866 <tr><td></td><td valign="top"><a href="#index-channel-bindings">channel bindings</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Channel-Bindings">Channel Bindings</a></td></tr>
38867 <tr><td></td><td valign="top"><a href="#index-ciphersuites">ciphersuites</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Supported-ciphersuites">Supported ciphersuites</a></td></tr>
38868 <tr><td></td><td valign="top"><a href="#index-client-certificate-authentication">client certificate authentication</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Client-Authentication">Client Authentication</a></td></tr>
38869 <tr><td></td><td valign="top"><a href="#index-compression-algorithms">compression algorithms</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compression-algorithms-used-in-the-record-layer">Compression algorithms used in the record layer</a></td></tr>
38870 <tr><td></td><td valign="top"><a href="#index-contributing">contributing</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Contributing">Contributing</a></td></tr>
38871 <tr><td></td><td valign="top"><a href="#index-CRL">CRL</a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKIX-certificate-revocation-lists">PKIX certificate revocation lists</a></td></tr>
38872 <tr><td colspan="4"> <hr></td></tr>
38873 <tr><th><a name="Concept-Index_cp_letter-D">D</a></th><td></td><td></td></tr>
38874 <tr><td></td><td valign="top"><a href="#index-DANE">DANE</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-a-certificate-using-DANE">Verifying a certificate using DANE</a></td></tr>
38875 <tr><td></td><td valign="top"><a href="#index-DANE-1">DANE</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-verification">Certificate verification</a></td></tr>
38876 <tr><td></td><td valign="top"><a href="#index-danetool"><code>danetool</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#danetool-Invocation">danetool Invocation</a></td></tr>
38877 <tr><td></td><td valign="top"><a href="#index-danetool-help">danetool help</a>:</td><td>&nbsp;</td><td valign="top"><a href="#danetool-Invocation">danetool Invocation</a></td></tr>
38878 <tr><td></td><td valign="top"><a href="#index-deriving-keys">deriving keys</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deriving-keys-for-other-applications_002fprotocols">Deriving keys for other applications/protocols</a></td></tr>
38879 <tr><td></td><td valign="top"><a href="#index-digital-signatures">digital signatures</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Digital-signatures">Digital signatures</a></td></tr>
38880 <tr><td></td><td valign="top"><a href="#index-DNSSEC">DNSSEC</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-a-certificate-using-DANE">Verifying a certificate using DANE</a></td></tr>
38881 <tr><td></td><td valign="top"><a href="#index-DNSSEC-1">DNSSEC</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-verification">Certificate verification</a></td></tr>
38882 <tr><td></td><td valign="top"><a href="#index-download">download</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Downloading-and-installing">Downloading and installing</a></td></tr>
38883 <tr><td colspan="4"> <hr></td></tr>
38884 <tr><th><a name="Concept-Index_cp_letter-E">E</a></th><td></td><td></td></tr>
38885 <tr><td></td><td valign="top"><a href="#index-Encrypted-keys">Encrypted keys</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Managing-encrypted-keys">Managing encrypted keys</a></td></tr>
38886 <tr><td></td><td valign="top"><a href="#index-error-codes">error codes</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Error-codes">Error codes</a></td></tr>
38887 <tr><td></td><td valign="top"><a href="#index-example-programs">example programs</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GnuTLS-application-examples">GnuTLS application examples</a></td></tr>
38888 <tr><td></td><td valign="top"><a href="#index-examples">examples</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GnuTLS-application-examples">GnuTLS application examples</a></td></tr>
38889 <tr><td></td><td valign="top"><a href="#index-exporting-keying-material">exporting keying material</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deriving-keys-for-other-applications_002fprotocols">Deriving keys for other applications/protocols</a></td></tr>
38890 <tr><td colspan="4"> <hr></td></tr>
38891 <tr><th><a name="Concept-Index_cp_letter-F">F</a></th><td></td><td></td></tr>
38892 <tr><td></td><td valign="top"><a href="#index-FDL_002c-GNU-Free-Documentation-License">FDL, GNU Free Documentation License</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Copying-Information">Copying Information</a></td></tr>
38893 <tr><td></td><td valign="top"><a href="#index-fork">fork</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Sessions-and-fork">Sessions and fork</a></td></tr>
38894 <tr><td colspan="4"> <hr></td></tr>
38895 <tr><th><a name="Concept-Index_cp_letter-G">G</a></th><td></td><td></td></tr>
38896 <tr><td></td><td valign="top"><a href="#index-generating-parameters">generating parameters</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Parameter-generation">Parameter generation</a></td></tr>
38897 <tr><td></td><td valign="top"><a href="#index-gnutls_002dcli"><code>gnutls-cli</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#gnutls_002dcli-Invocation">gnutls-cli Invocation</a></td></tr>
38898 <tr><td></td><td valign="top"><a href="#index-gnutls_002dcli-help">gnutls-cli help</a>:</td><td>&nbsp;</td><td valign="top"><a href="#gnutls_002dcli-Invocation">gnutls-cli Invocation</a></td></tr>
38899 <tr><td></td><td valign="top"><a href="#index-gnutls_002dcli_002ddebug"><code>gnutls-cli-debug</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#gnutls_002dcli_002ddebug-Invocation">gnutls-cli-debug Invocation</a></td></tr>
38900 <tr><td></td><td valign="top"><a href="#index-gnutls_002dcli_002ddebug-help">gnutls-cli-debug help</a>:</td><td>&nbsp;</td><td valign="top"><a href="#gnutls_002dcli_002ddebug-Invocation">gnutls-cli-debug Invocation</a></td></tr>
38901 <tr><td></td><td valign="top"><a href="#index-gnutls_002dserv"><code>gnutls-serv</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#gnutls_002dserv-Invocation">gnutls-serv Invocation</a></td></tr>
38902 <tr><td></td><td valign="top"><a href="#index-gnutls_002dserv-help">gnutls-serv help</a>:</td><td>&nbsp;</td><td valign="top"><a href="#gnutls_002dserv-Invocation">gnutls-serv Invocation</a></td></tr>
38903 <tr><td colspan="4"> <hr></td></tr>
38904 <tr><th><a name="Concept-Index_cp_letter-H">H</a></th><td></td><td></td></tr>
38905 <tr><td></td><td valign="top"><a href="#index-hacking">hacking</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Contributing">Contributing</a></td></tr>
38906 <tr><td></td><td valign="top"><a href="#index-handshake-protocol">handshake protocol</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-TLS-Handshake-Protocol">The TLS Handshake Protocol</a></td></tr>
38907 <tr><td></td><td valign="top"><a href="#index-hardware-security-modules">hardware security modules</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Smart-cards-and-HSMs">Smart cards and HSMs</a></td></tr>
38908 <tr><td></td><td valign="top"><a href="#index-hardware-tokens">hardware tokens</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Smart-cards-and-HSMs">Smart cards and HSMs</a></td></tr>
38909 <tr><td></td><td valign="top"><a href="#index-hash-functions">hash functions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Hash-and-HMAC-functions">Hash and HMAC functions</a></td></tr>
38910 <tr><td></td><td valign="top"><a href="#index-heartbeat">heartbeat</a>:</td><td>&nbsp;</td><td valign="top"><a href="#HeartBeat">HeartBeat</a></td></tr>
38911 <tr><td></td><td valign="top"><a href="#index-HMAC-functions">HMAC functions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Hash-and-HMAC-functions">Hash and HMAC functions</a></td></tr>
38912 <tr><td colspan="4"> <hr></td></tr>
38913 <tr><th><a name="Concept-Index_cp_letter-I">I</a></th><td></td><td></td></tr>
38914 <tr><td></td><td valign="top"><a href="#index-installation">installation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Downloading-and-installing">Downloading and installing</a></td></tr>
38915 <tr><td></td><td valign="top"><a href="#index-internal-architecture">internal architecture</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Internal-architecture-of-GnuTLS">Internal architecture of GnuTLS</a></td></tr>
38916 <tr><td colspan="4"> <hr></td></tr>
38917 <tr><th><a name="Concept-Index_cp_letter-K">K</a></th><td></td><td></td></tr>
38918 <tr><td></td><td valign="top"><a href="#index-key-extraction">key extraction</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deriving-keys-for-other-applications_002fprotocols">Deriving keys for other applications/protocols</a></td></tr>
38919 <tr><td></td><td valign="top"><a href="#index-Key-pinning">Key pinning</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-a-certificate-using-trust-on-first-use-authentication">Verifying a certificate using trust on first use authentication</a></td></tr>
38920 <tr><td></td><td valign="top"><a href="#index-Key-pinning-1">Key pinning</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-verification">Certificate verification</a></td></tr>
38921 <tr><td></td><td valign="top"><a href="#index-key-sizes">key sizes</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Selecting-cryptographic-key-sizes">Selecting cryptographic key sizes</a></td></tr>
38922 <tr><td></td><td valign="top"><a href="#index-keying-material-exporters">keying material exporters</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deriving-keys-for-other-applications_002fprotocols">Deriving keys for other applications/protocols</a></td></tr>
38923 <tr><td colspan="4"> <hr></td></tr>
38924 <tr><th><a name="Concept-Index_cp_letter-M">M</a></th><td></td><td></td></tr>
38925 <tr><td></td><td valign="top"><a href="#index-maximum-fragment-length">maximum fragment length</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Maximum-fragment-length-negotiation">Maximum fragment length negotiation</a></td></tr>
38926 <tr><td colspan="4"> <hr></td></tr>
38927 <tr><th><a name="Concept-Index_cp_letter-O">O</a></th><td></td><td></td></tr>
38928 <tr><td></td><td valign="top"><a href="#index-OCSP">OCSP</a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-certificate-status-checking">OCSP certificate status checking</a></td></tr>
38929 <tr><td></td><td valign="top"><a href="#index-OCSP-Functions">OCSP Functions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-API">OCSP API</a></td></tr>
38930 <tr><td></td><td valign="top"><a href="#index-OCSP-status-request">OCSP status request</a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-status-request">OCSP status request</a></td></tr>
38931 <tr><td></td><td valign="top"><a href="#index-ocsptool"><code>ocsptool</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ocsptool-Invocation">ocsptool Invocation</a></td></tr>
38932 <tr><td></td><td valign="top"><a href="#index-ocsptool-help">ocsptool help</a>:</td><td>&nbsp;</td><td valign="top"><a href="#ocsptool-Invocation">ocsptool Invocation</a></td></tr>
38933 <tr><td></td><td valign="top"><a href="#index-Online-Certificate-Status-Protocol">Online Certificate Status Protocol</a>:</td><td>&nbsp;</td><td valign="top"><a href="#OCSP-certificate-status-checking">OCSP certificate status checking</a></td></tr>
38934 <tr><td></td><td valign="top"><a href="#index-OpenPGP-API">OpenPGP API</a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-API">OpenPGP API</a></td></tr>
38935 <tr><td></td><td valign="top"><a href="#index-OpenPGP-certificates">OpenPGP certificates</a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-certificates">OpenPGP certificates</a></td></tr>
38936 <tr><td></td><td valign="top"><a href="#index-OpenPGP-server">OpenPGP server</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Echo-server-with-OpenPGP-authentication">Echo server with OpenPGP authentication</a></td></tr>
38937 <tr><td></td><td valign="top"><a href="#index-OpenSSL">OpenSSL</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compatibility-with-the-OpenSSL-library">Compatibility with the OpenSSL library</a></td></tr>
38938 <tr><td></td><td valign="top"><a href="#index-OpenSSL-encrypted-keys">OpenSSL encrypted keys</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Managing-encrypted-keys">Managing encrypted keys</a></td></tr>
38939 <tr><td colspan="4"> <hr></td></tr>
38940 <tr><th><a name="Concept-Index_cp_letter-P">P</a></th><td></td><td></td></tr>
38941 <tr><td></td><td valign="top"><a href="#index-p11tool"><code>p11tool</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#p11tool-Invocation">p11tool Invocation</a></td></tr>
38942 <tr><td></td><td valign="top"><a href="#index-p11tool-help">p11tool help</a>:</td><td>&nbsp;</td><td valign="top"><a href="#p11tool-Invocation">p11tool Invocation</a></td></tr>
38943 <tr><td></td><td valign="top"><a href="#index-parameter-generation">parameter generation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Parameter-generation">Parameter generation</a></td></tr>
38944 <tr><td></td><td valign="top"><a href="#index-PCT">PCT</a>:</td><td>&nbsp;</td><td valign="top"><a href="#On-SSL-2-and-older-protocols">On SSL 2 and older protocols</a></td></tr>
38945 <tr><td></td><td valign="top"><a href="#index-PKCS-_002310">PKCS #10</a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-10-certificate-requests">PKCS 10 certificate requests</a></td></tr>
38946 <tr><td></td><td valign="top"><a href="#index-PKCS-_002311-tokens">PKCS #11 tokens</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Smart-cards-and-HSMs">Smart cards and HSMs</a></td></tr>
38947 <tr><td></td><td valign="top"><a href="#index-PKCS-_002312">PKCS #12</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Managing-encrypted-keys">Managing encrypted keys</a></td></tr>
38948 <tr><td></td><td valign="top"><a href="#index-PKCS-_00238">PKCS #8</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Managing-encrypted-keys">Managing encrypted keys</a></td></tr>
38949 <tr><td></td><td valign="top"><a href="#index-Priority-strings">Priority strings</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Priority-Strings">Priority Strings</a></td></tr>
38950 <tr><td></td><td valign="top"><a href="#index-PSK-authentication">PSK authentication</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Authentication-using-PSK">Authentication using PSK</a></td></tr>
38951 <tr><td></td><td valign="top"><a href="#index-psktool"><code>psktool</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#psktool-Invocation">psktool Invocation</a></td></tr>
38952 <tr><td></td><td valign="top"><a href="#index-psktool-help">psktool help</a>:</td><td>&nbsp;</td><td valign="top"><a href="#psktool-Invocation">psktool Invocation</a></td></tr>
38953 <tr><td></td><td valign="top"><a href="#index-public-key-algorithms">public key algorithms</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Public-key-algorithms">Public key algorithms</a></td></tr>
38954 <tr><td colspan="4"> <hr></td></tr>
38955 <tr><th><a name="Concept-Index_cp_letter-R">R</a></th><td></td><td></td></tr>
38956 <tr><td></td><td valign="top"><a href="#index-random-numbers">random numbers</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Random-number-generation">Random number generation</a></td></tr>
38957 <tr><td></td><td valign="top"><a href="#index-record-padding">record padding</a>:</td><td>&nbsp;</td><td valign="top"><a href="#On-Record-Padding">On Record Padding</a></td></tr>
38958 <tr><td></td><td valign="top"><a href="#index-record-protocol">record protocol</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-TLS-record-protocol">The TLS record protocol</a></td></tr>
38959 <tr><td></td><td valign="top"><a href="#index-renegotiation">renegotiation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Safe-renegotiation">Safe renegotiation</a></td></tr>
38960 <tr><td></td><td valign="top"><a href="#index-reporting-bugs">reporting bugs</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Bug-Reports">Bug Reports</a></td></tr>
38961 <tr><td></td><td valign="top"><a href="#index-resuming-sessions">resuming sessions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Resuming-Sessions">Resuming Sessions</a></td></tr>
38962 <tr><td></td><td valign="top"><a href="#index-resuming-sessions-1">resuming sessions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Session-resumption">Session resumption</a></td></tr>
38963 <tr><td colspan="4"> <hr></td></tr>
38964 <tr><th><a name="Concept-Index_cp_letter-S">S</a></th><td></td><td></td></tr>
38965 <tr><td></td><td valign="top"><a href="#index-safe-renegotiation">safe renegotiation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Safe-renegotiation">Safe renegotiation</a></td></tr>
38966 <tr><td></td><td valign="top"><a href="#index-Secure-RTP">Secure RTP</a>:</td><td>&nbsp;</td><td valign="top"><a href="#SRTP">SRTP</a></td></tr>
38967 <tr><td></td><td valign="top"><a href="#index-server-name-indication">server name indication</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Server-name-indication">Server name indication</a></td></tr>
38968 <tr><td></td><td valign="top"><a href="#index-session-resumption">session resumption</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Resuming-Sessions">Resuming Sessions</a></td></tr>
38969 <tr><td></td><td valign="top"><a href="#index-session-resumption-1">session resumption</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Session-resumption">Session resumption</a></td></tr>
38970 <tr><td></td><td valign="top"><a href="#index-session-tickets">session tickets</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Session-tickets">Session tickets</a></td></tr>
38971 <tr><td></td><td valign="top"><a href="#index-Smart-card-example">Smart card example</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Client-using-a-smart-card-with-TLS">Client using a smart card with TLS</a></td></tr>
38972 <tr><td></td><td valign="top"><a href="#index-smart-cards">smart cards</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Smart-cards-and-HSMs">Smart cards and HSMs</a></td></tr>
38973 <tr><td></td><td valign="top"><a href="#index-SRP-authentication">SRP authentication</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Authentication-using-SRP">Authentication using SRP</a></td></tr>
38974 <tr><td></td><td valign="top"><a href="#index-srptool"><code>srptool</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#srptool-Invocation">srptool Invocation</a></td></tr>
38975 <tr><td></td><td valign="top"><a href="#index-srptool-help">srptool help</a>:</td><td>&nbsp;</td><td valign="top"><a href="#srptool-Invocation">srptool Invocation</a></td></tr>
38976 <tr><td></td><td valign="top"><a href="#index-SRTP">SRTP</a>:</td><td>&nbsp;</td><td valign="top"><a href="#SRTP">SRTP</a></td></tr>
38977 <tr><td></td><td valign="top"><a href="#index-SSH_002dstyle-authentication">SSH-style authentication</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-a-certificate-using-trust-on-first-use-authentication">Verifying a certificate using trust on first use authentication</a></td></tr>
38978 <tr><td></td><td valign="top"><a href="#index-SSH_002dstyle-authentication-1">SSH-style authentication</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-verification">Certificate verification</a></td></tr>
38979 <tr><td></td><td valign="top"><a href="#index-SSL-2">SSL 2</a>:</td><td>&nbsp;</td><td valign="top"><a href="#On-SSL-2-and-older-protocols">On SSL 2 and older protocols</a></td></tr>
38980 <tr><td></td><td valign="top"><a href="#index-symmetric-algorithms">symmetric algorithms</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Symmetric-algorithms">Symmetric algorithms</a></td></tr>
38981 <tr><td></td><td valign="top"><a href="#index-symmetric-cryptography">symmetric cryptography</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Symmetric-algorithms">Symmetric algorithms</a></td></tr>
38982 <tr><td></td><td valign="top"><a href="#index-symmetric-encryption-algorithms">symmetric encryption algorithms</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Encryption-algorithms-used-in-the-record-layer">Encryption algorithms used in the record layer</a></td></tr>
38983 <tr><td colspan="4"> <hr></td></tr>
38984 <tr><th><a name="Concept-Index_cp_letter-T">T</a></th><td></td><td></td></tr>
38985 <tr><td></td><td valign="top"><a href="#index-thread-safety">thread safety</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Thread-safety">Thread safety</a></td></tr>
38986 <tr><td></td><td valign="top"><a href="#index-tickets">tickets</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Session-tickets">Session tickets</a></td></tr>
38987 <tr><td></td><td valign="top"><a href="#index-TLS-extensions">TLS extensions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Extensions">TLS Extensions</a></td></tr>
38988 <tr><td></td><td valign="top"><a href="#index-TLS-extensions-1">TLS extensions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Maximum-fragment-length-negotiation">Maximum fragment length negotiation</a></td></tr>
38989 <tr><td></td><td valign="top"><a href="#index-TLS-extensions-2">TLS extensions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Server-name-indication">Server name indication</a></td></tr>
38990 <tr><td></td><td valign="top"><a href="#index-TLS-extensions-3">TLS extensions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Session-tickets">Session tickets</a></td></tr>
38991 <tr><td></td><td valign="top"><a href="#index-TLS-extensions-4">TLS extensions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#HeartBeat">HeartBeat</a></td></tr>
38992 <tr><td></td><td valign="top"><a href="#index-TLS-layers">TLS layers</a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-layers">TLS layers</a></td></tr>
38993 <tr><td></td><td valign="top"><a href="#index-TPM">TPM</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Trusted-Platform-Module">Trusted Platform Module</a></td></tr>
38994 <tr><td></td><td valign="top"><a href="#index-tpmtool"><code>tpmtool</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#tpmtool-Invocation">tpmtool Invocation</a></td></tr>
38995 <tr><td></td><td valign="top"><a href="#index-tpmtool-help">tpmtool help</a>:</td><td>&nbsp;</td><td valign="top"><a href="#tpmtool-Invocation">tpmtool Invocation</a></td></tr>
38996 <tr><td></td><td valign="top"><a href="#index-transport-layer">transport layer</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-transport-layer">The transport layer</a></td></tr>
38997 <tr><td></td><td valign="top"><a href="#index-transport-protocol">transport protocol</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-transport-layer">The transport layer</a></td></tr>
38998 <tr><td></td><td valign="top"><a href="#index-Trust-on-first-use">Trust on first use</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-a-certificate-using-trust-on-first-use-authentication">Verifying a certificate using trust on first use authentication</a></td></tr>
38999 <tr><td></td><td valign="top"><a href="#index-Trust-on-first-use-1">Trust on first use</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-verification">Certificate verification</a></td></tr>
39000 <tr><td></td><td valign="top"><a href="#index-trusted-platform-module">trusted platform module</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Trusted-Platform-Module">Trusted Platform Module</a></td></tr>
39001 <tr><td colspan="4"> <hr></td></tr>
39002 <tr><th><a name="Concept-Index_cp_letter-U">U</a></th><td></td><td></td></tr>
39003 <tr><td></td><td valign="top"><a href="#index-upgrading">upgrading</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Upgrading-from-previous-versions">Upgrading from previous versions</a></td></tr>
39004 <tr><td colspan="4"> <hr></td></tr>
39005 <tr><th><a name="Concept-Index_cp_letter-V">V</a></th><td></td><td></td></tr>
39006 <tr><td></td><td valign="top"><a href="#index-verifying-certificate-paths">verifying certificate paths</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-X_002e509-certificate-paths">Verifying X.509 certificate paths</a></td></tr>
39007 <tr><td></td><td valign="top"><a href="#index-verifying-certificate-paths-1">verifying certificate paths</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-a-certificate-in-the-context-of-TLS-session">Verifying a certificate in the context of TLS session</a></td></tr>
39008 <tr><td></td><td valign="top"><a href="#index-verifying-certificate-paths-2">verifying certificate paths</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-a-certificate-using-trust-on-first-use-authentication">Verifying a certificate using trust on first use authentication</a></td></tr>
39009 <tr><td></td><td valign="top"><a href="#index-verifying-certificate-paths-3">verifying certificate paths</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verifying-a-certificate-using-DANE">Verifying a certificate using DANE</a></td></tr>
39010 <tr><td></td><td valign="top"><a href="#index-verifying-certificate-with-pkcs11">verifying certificate with pkcs11</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Verification-using-PKCS11">Verification using PKCS11</a></td></tr>
39011 <tr><td colspan="4"> <hr></td></tr>
39012 <tr><th><a name="Concept-Index_cp_letter-X">X</a></th><td></td><td></td></tr>
39013 <tr><td></td><td valign="top"><a href="#index-X_002e509-certificates">X.509 certificates</a>:</td><td>&nbsp;</td><td valign="top"><a href="#X_002e509-certificates">X.509 certificates</a></td></tr>
39014 <tr><td></td><td valign="top"><a href="#index-X_002e509-distinguished-name">X.509 distinguished name</a>:</td><td>&nbsp;</td><td valign="top"><a href="#X_002e509-distinguished-names">X.509 distinguished names</a></td></tr>
39015 <tr><td></td><td valign="top"><a href="#index-X_002e509-extensions">X.509 extensions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#X_002e509-extensions">X.509 extensions</a></td></tr>
39016 <tr><td></td><td valign="top"><a href="#index-X_002e509-Functions">X.509 Functions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#X509-certificate-API">X509 certificate API</a></td></tr>
39017 <tr><td colspan="4"> <hr></td></tr>
39018 </table>
39019 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a>
39020  &nbsp;
39021 <a class="summary-letter" href="#Concept-Index_cp_letter-B"><b>B</b></a>
39022  &nbsp;
39023 <a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a>
39024  &nbsp;
39025 <a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a>
39026  &nbsp;
39027 <a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a>
39028  &nbsp;
39029 <a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a>
39030  &nbsp;
39031 <a class="summary-letter" href="#Concept-Index_cp_letter-G"><b>G</b></a>
39032  &nbsp;
39033 <a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a>
39034  &nbsp;
39035 <a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a>
39036  &nbsp;
39037 <a class="summary-letter" href="#Concept-Index_cp_letter-K"><b>K</b></a>
39038  &nbsp;
39039 <a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a>
39040  &nbsp;
39041 <a class="summary-letter" href="#Concept-Index_cp_letter-O"><b>O</b></a>
39042  &nbsp;
39043 <a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a>
39044  &nbsp;
39045 <a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a>
39046  &nbsp;
39047 <a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a>
39048  &nbsp;
39049 <a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a>
39050  &nbsp;
39051 <a class="summary-letter" href="#Concept-Index_cp_letter-U"><b>U</b></a>
39052  &nbsp;
39053 <a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a>
39054  &nbsp;
39055 <a class="summary-letter" href="#Concept-Index_cp_letter-X"><b>X</b></a>
39056  &nbsp;
39057 </td></tr></table>
39058
39059 <div class="footnote">
39060 <hr>
39061 <h4 class="footnotes-heading">Footnotes</h4>
39062
39063 <h3><a name="FOOT1" href="#DOCF1">(1)</a></h3>
39064 <p>IETF, or Internet Engineering Task Force,
39065 is a large open international community of network designers,
39066 operators, vendors, and researchers concerned with the evolution of
39067 the Internet architecture and the smooth operation of the Internet.
39068 It is open to any interested individual.</p>
39069 <h3><a name="FOOT2" href="#DOCF2">(2)</a></h3>
39070 <p>If this is not possible then please consult <a href="#Interoperability">Interoperability</a>.</p>
39071 <h3><a name="FOOT3" href="#DOCF3">(3)</a></h3>
39072 <p>MAC stands for Message Authentication Code. It can be described as a keyed hash algorithm. See RFC2104.</p>
39073 <h3><a name="FOOT4" href="#DOCF4">(4)</a></h3>
39074 <p>See also the Server Name Indication extension on
39075 <a href="#serverind">serverind</a>.</p>
39076 <h3><a name="FOOT5" href="#DOCF5">(5)</a></h3>
39077 <p>See LDAP, IMAP etc.</p>
39078 <h3><a name="FOOT6" href="#DOCF6">(6)</a></h3>
39079 <p>see <a href="http://p11-glue.freedesktop.org/trust-module.html">http://p11-glue.freedesktop.org/trust-module.html</a>.</p>
39080 <h3><a name="FOOT7" href="#DOCF7">(7)</a></h3>
39081 <p><a href="http://www.gnupg.org/related_software/gpgme/">http://www.gnupg.org/related_software/gpgme/</a></p>
39082 <h3><a name="FOOT8" href="#DOCF8">(8)</a></h3>
39083 <p><a href="http://www.opensc-project.org">http://www.opensc-project.org</a></p>
39084 <h3><a name="FOOT9" href="#DOCF9">(9)</a></h3>
39085 <p><a href="http://p11-glue.freedesktop.org/trust-module.html">http://p11-glue.freedesktop.org/trust-module.html</a></p>
39086 <h3><a name="FOOT10" href="#DOCF10">(10)</a></h3>
39087 <p><a href="http://p11-glue.freedesktop.org/">http://p11-glue.freedesktop.org/</a></p>
39088 <h3><a name="FOOT11" href="#DOCF11">(11)</a></h3>
39089 <p>The first message in a <acronym>TLS</acronym> handshake</p>
39090 <h3><a name="FOOT12" href="#DOCF12">(12)</a></h3>
39091 <p>The original behavior of requiring explicit initialization can obtained by setting the
39092 GNUTLS_NO_EXPLICIT_INIT environment variable to 1, or by using the macro GNUTLS_SKIP_GLOBAL_INIT
39093 in a global section of your program.</p>
39094 <h3><a name="FOOT13" href="#DOCF13">(13)</a></h3>
39095 <p>A key of 128 bits or 16 bytes should be sufficient for this purpose.</p>
39096 <h3><a name="FOOT14" href="#DOCF14">(14)</a></h3>
39097 <p>The default is <code>/etc/gnutls/default-priorities</code>.</p>
39098 <h3><a name="FOOT15" href="#DOCF15">(15)</a></h3>
39099 <p>It depends on the group used.  Primes with
39100 lesser bits are always faster, but also easier to break.  See <a href="#Selecting-cryptographic-key-sizes">Selecting cryptographic key sizes</a>
39101 for the acceptable security levels.</p>
39102 <h3><a name="FOOT16" href="#DOCF16">(16)</a></h3>
39103 <p>See <a href="http://www.lysator.liu.se/~nisse/nettle/">http://www.lysator.liu.se/~nisse/nettle/</a>.</p>
39104 <h3><a name="FOOT17" href="#DOCF17">(17)</a></h3>
39105 <p>such as the
39106 <code>gnutls_certificate_credentials_t</code> structures</p>
39107 <h3><a name="FOOT18" href="#DOCF18">(18)</a></h3>
39108 <p>See
39109 <a href="http://lists.gnu.org/archive/html/gnutls-devel/2011-02/msg00079.html">http://lists.gnu.org/archive/html/gnutls-devel/2011-02/msg00079.html</a>.</p>
39110 <h3><a name="FOOT19" href="#DOCF19">(19)</a></h3>
39111 <p>Check <a href="http://home.gna.org/cryptodev-linux/">http://home.gna.org/cryptodev-linux/</a>
39112 for the Linux kernel implementation of <code>/dev/crypto</code>.</p>
39113 </div>
39114 <hr>
39115
39116
39117
39118 </body>
39119 </html>