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 6 January 2012 for version
   4 2.12.20 of GnuTLS.
   5
   6 Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
   7
   8 Permission is granted to copy, distribute and/or modify this document
   9 under the terms of the GNU Free Documentation License, Version 1.3 or
  10 any later version published by the Free Software Foundation; with no
  11 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
  12 copy of the license is included in the section entitled "GNU Free
  13 Documentation License". -->
  14 <!-- Created by GNU Texinfo 4.13.90, http://www.gnu.org/software/texinfo/ -->
  15 <head>
  16 <title>GnuTLS 2.12.20</title>
  17
  18 <meta name="description" content="GnuTLS 2.12.20">
  19 <meta name="keywords" content="GnuTLS 2.12.20">
  20 <meta name="resource-type" content="document">
  21 <meta name="distribution" content="global">
  22 <meta name="Generator" content="makeinfo">
  23 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  24 <link href="#Top" rel="start" title="Top">
  25 <link href="#Function-and-Data-Index" rel="index" title="Function and Data Index">
  26 <link href="#SEC_Contents" rel="contents" title="Table of Contents">
  27 <link href="dir.html#Top" rel="up" title="(dir)">
  28 <style type="text/css">
  29 <!--
  30 a.summary-letter {text-decoration: none}
  31 blockquote.smallquotation {font-size: smaller}
  32 div.display {margin-left: 3.2em}
  33 div.example {margin-left: 3.2em}
  34 div.lisp {margin-left: 3.2em}
  35 div.smalldisplay {margin-left: 3.2em}
  36 div.smallexample {margin-left: 3.2em}
  37 div.smalllisp {margin-left: 3.2em}
  38 pre.display {font-family: serif}
  39 pre.format {font-family: serif}
  40 pre.menu-comment {font-family: serif}
  41 pre.menu-preformatted {font-family: serif}
  42 pre.smalldisplay {font-family: serif; font-size: smaller}
  43 pre.smallexample {font-size: smaller}
  44 pre.smallformat {font-family: serif; font-size: smaller}
  45 pre.smalllisp {font-size: smaller}
  46 span.nocodebreak {white-space:pre}
  47 span.nolinebreak {white-space:pre}
  48 span.roman {font-family:serif; font-weight:normal}
  49 span.sansserif {font-family:sans-serif; font-weight:normal}
  50 ul.no-bullet {list-style: none}
  51 body {
  52         margin: 2%;
  53         padding: 0 5%;
  54         background: #ffffff;
  55 }
  56 h1,h2,h3,h4,h5 {
  57     font-weight: bold;
  58     padding: 5px 5px 5px 5px;
  59     background-color: #c2e0ff;
  60     color: #336699;
  61 }
  62 h1 {
  63     padding: 2em 2em 2em 5%;
  64     color: white;
  65     background: #336699;
  66     text-align: center;
  67     letter-spacing: 3px;
  68 }
  69 h2 { text-decoration: underline; }
  70 pre {
  71   margin: 0 5%;
  72   padding: 0.5em;
  73 }
  74 pre.example {
  75   border: solid 1px;
  76   background: #eeeeff;
  77   padding-bottom: 1em;
  78 }
  79 pre.verbatim {
  80   border: solid 1px gray;
  81   background: white;
  82   padding-bottom: 1em;
  83 }
  84 div.node {
  85   margin: 0 -5% 0 -2%;
  86   padding: 0.5em 0.5em;
  87   margin-top: 0.5em;
  88   margin-bottom: 0.5em;
  89   font-weight: bold;
  90 }
  91 dd, li {
  92   padding-top: 0.1em;
  93   padding-bottom: 0.1em;
  94 }
  95
  96 -->
  97 </style>
  98
  99
 100 </head>
 101
 102 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
 103 <h1 class="settitle" align="center">GnuTLS 2.12.20</h1>
 104
 105
 106
 107
 108
 109
 110
 111
 112 <a name="SEC_Contents"></a>
 113 <h2 class="contents-heading">Table of Contents</h2>
 114
 115 <div class="contents">
 116
 117 <ul class="no-bullet">
 118   <li><a name="toc-Preface-1" href="#Preface">1 Preface</a>
 119   <ul class="no-bullet">
 120     <li><a name="toc-Getting-Help" href="#Getting-help">1.1 Getting Help</a></li>
 121     <li><a name="toc-Commercial-Support-1" href="#Commercial-Support">1.2 Commercial Support</a></li>
 122     <li><a name="toc-Downloading-and-Installing-1" href="#Downloading-and-Installing">1.3 Downloading and Installing</a></li>
 123     <li><a name="toc-Bug-Reports-1" href="#Bug-Reports">1.4 Bug Reports</a></li>
 124     <li><a name="toc-Contributing-1" href="#Contributing">1.5 Contributing</a></li>
 125   </ul></li>
 126   <li><a name="toc-The-Library-1" href="#The-Library">2 The Library</a>
 127   <ul class="no-bullet">
 128     <li><a name="toc-General-Idea-1" href="#General-Idea">2.1 General Idea</a></li>
 129     <li><a name="toc-Error-Handling" href="#Error-handling">2.2 Error Handling</a></li>
 130     <li><a name="toc-Memory-Handling" href="#Memory-handling">2.3 Memory Handling</a></li>
 131     <li><a name="toc-Callback-Functions" href="#Callback-functions">2.4 Callback Functions</a></li>
 132   </ul></li>
 133   <li><a name="toc-Introduction-to-TLS-1" href="#Introduction-to-TLS">3 Introduction to <acronym>TLS</acronym></a>
 134   <ul class="no-bullet">
 135     <li><a name="toc-TLS-Layers" href="#TLS-layers">3.1 TLS Layers</a></li>
 136     <li><a name="toc-The-Transport-Layer" href="#The-transport-layer">3.2 The Transport Layer</a></li>
 137     <li><a name="toc-The-TLS-Record-Protocol" href="#The-TLS-record-protocol">3.3 The TLS Record Protocol</a>
 138     <ul class="no-bullet">
 139       <li><a name="toc-Encryption-Algorithms-Used-in-the-Record-Layer" href="#Encryption-algorithms-used-in-the-record-layer">3.3.1 Encryption Algorithms Used in the Record Layer</a></li>
 140       <li><a name="toc-Compression-Algorithms-Used-in-the-Record-Layer" href="#Compression-algorithms-used-in-the-record-layer">3.3.2 Compression Algorithms Used in the Record Layer</a></li>
 141       <li><a name="toc-Weaknesses-and-Countermeasures" href="#Weaknesses-and-countermeasures">3.3.3 Weaknesses and Countermeasures</a></li>
 142       <li><a name="toc-On-Record-Padding-1" href="#On-Record-Padding">3.3.4 On Record Padding</a></li>
 143     </ul></li>
 144     <li><a name="toc-The-TLS-Alert-Protocol-1" href="#The-TLS-Alert-Protocol">3.4 The TLS Alert Protocol</a></li>
 145     <li><a name="toc-The-TLS-Handshake-Protocol-1" href="#The-TLS-Handshake-Protocol">3.5 The TLS Handshake Protocol</a>
 146     <ul class="no-bullet">
 147       <li><a name="toc-TLS-Cipher-Suites-1" href="#TLS-Cipher-Suites">3.5.1 TLS Cipher Suites</a></li>
 148       <li><a name="toc-Priority-Strings-1" href="#Priority-Strings">3.5.2 Priority Strings</a></li>
 149       <li><a name="toc-Client-Authentication-1" href="#Client-Authentication">3.5.3 Client Authentication</a></li>
 150       <li><a name="toc-Resuming-Sessions-1" href="#Resuming-Sessions">3.5.4 Resuming Sessions</a></li>
 151       <li><a name="toc-Resuming-Internals-1" href="#Resuming-Internals">3.5.5 Resuming Internals</a></li>
 152       <li><a name="toc-Interoperability-1" href="#Interoperability">3.5.6 Interoperability</a></li>
 153     </ul></li>
 154     <li><a name="toc-TLS-Extensions-1" href="#TLS-Extensions">3.6 TLS Extensions</a>
 155     <ul class="no-bullet">
 156       <li><a name="toc-Maximum-Fragment-Length-Negotiation" href="#Maximum-Fragment-Length-Negotiation">3.6.1 Maximum Fragment Length Negotiation</a></li>
 157       <li><a name="toc-Server-Name-Indication" href="#Server-Name-Indication">3.6.2 Server Name Indication</a></li>
 158       <li><a name="toc-Session-Tickets" href="#Session-Tickets">3.6.3 Session Tickets</a></li>
 159       <li><a name="toc-Safe-Renegotiation" href="#Safe-Renegotiation">3.6.4 Safe Renegotiation</a></li>
 160     </ul></li>
 161     <li><a name="toc-Selecting-Cryptographic-Key-Sizes" href="#Selecting-cryptographic-key-sizes">3.7 Selecting Cryptographic Key Sizes</a></li>
 162     <li><a name="toc-On-SSL-2-and-Older-Protocols" href="#On-SSL-2-and-older-protocols">3.8 On SSL 2 and Older Protocols</a></li>
 163   </ul></li>
 164   <li><a name="toc-Authentication-Methods" href="#Authentication-methods">4 Authentication Methods</a>
 165   <ul class="no-bullet">
 166     <li><a name="toc-Certificate-Authentication-1" href="#Certificate-authentication">4.1 Certificate Authentication</a>
 167     <ul class="no-bullet">
 168       <li><a name="toc-Authentication-Using-X_002e509-Certificates" href="#Authentication-Using-X_002e509-Certificates">4.1.1 Authentication Using <acronym>X.509</acronym> Certificates</a></li>
 169       <li><a name="toc-Authentication-Using-OpenPGP-Keys" href="#Authentication-Using-OpenPGP-Keys">4.1.2 Authentication Using <acronym>OpenPGP</acronym> Keys</a></li>
 170       <li><a name="toc-Using-Certificate-Authentication" href="#Using-Certificate-Authentication">4.1.3 Using Certificate Authentication</a></li>
 171     </ul></li>
 172     <li><a name="toc-Anonymous-Authentication" href="#Anonymous-authentication">4.2 Anonymous Authentication</a></li>
 173     <li><a name="toc-Authentication-using-SRP-1" href="#Authentication-using-SRP">4.3 Authentication using <acronym>SRP</acronym></a></li>
 174     <li><a name="toc-Authentication-using-PSK-1" href="#Authentication-using-PSK">4.4 Authentication using <acronym>PSK</acronym></a></li>
 175     <li><a name="toc-Authentication-and-Credentials" href="#Authentication-and-credentials">4.5 Authentication and Credentials</a></li>
 176     <li><a name="toc-Parameters-Stored-in-Credentials" href="#Parameters-stored-in-credentials">4.6 Parameters Stored in Credentials</a></li>
 177   </ul></li>
 178   <li><a name="toc-More-on-Certificate-Authentication" href="#More-on-certificate-authentication">5 More on Certificate Authentication</a>
 179   <ul class="no-bullet">
 180     <li><a name="toc-The-X_002e509-Trust-Model" href="#The-X_002e509-trust-model">5.1 The <acronym>X.509</acronym> Trust Model</a>
 181     <ul class="no-bullet">
 182       <li><a name="toc-X_002e509-Certificates" href="#X_002e509-certificates">5.1.1 <acronym>X.509</acronym> Certificates</a></li>
 183       <li><a name="toc-Verifying-X_002e509-Certificate-Paths" href="#Verifying-X_002e509-certificate-paths">5.1.2 Verifying <acronym>X.509</acronym> Certificate Paths</a></li>
 184       <li><a name="toc-PKCS-_002310-Certificate-Requests" href="#PKCS-_002310-certificate-requests">5.1.3 <acronym>PKCS</acronym> #10 Certificate Requests</a></li>
 185       <li><a name="toc-PKCS-_002312-Structures" href="#PKCS-_002312-structures">5.1.4 <acronym>PKCS</acronym> #12 Structures</a></li>
 186     </ul></li>
 187     <li><a name="toc-The-OpenPGP-Trust-Model" href="#The-OpenPGP-trust-model">5.2 The <acronym>OpenPGP</acronym> Trust Model</a>
 188     <ul class="no-bullet">
 189       <li><a name="toc-OpenPGP-Keys" href="#OpenPGP-Keys">5.2.1 <acronym>OpenPGP</acronym> Keys</a></li>
 190       <li><a name="toc-Verifying-an-OpenPGP-Key" href="#Verifying-an-OpenPGP-Key">5.2.2 Verifying an <acronym>OpenPGP</acronym> Key</a></li>
 191     </ul></li>
 192     <li><a name="toc-PKCS-_002311-tokens-1" href="#PKCS-_002311-tokens">5.3 <acronym>PKCS #11</acronym> tokens</a>
 193     <ul class="no-bullet">
 194       <li><a name="toc-Introduction" href="#Introduction">5.3.1 Introduction</a></li>
 195       <li><a name="toc-Initialization-1" href="#Initialization-1">5.3.2 Initialization</a></li>
 196       <li><a name="toc-Reading-Objects" href="#Reading-Objects">5.3.3 Reading Objects</a></li>
 197       <li><a name="toc-Writing-Objects" href="#Writing-Objects">5.3.4 Writing Objects</a></li>
 198       <li><a name="toc-Using-a-PKCS-_002311-token-with-TLS" href="#Using-a-PKCS-_002311-token-with-TLS">5.3.5 Using a <acronym>PKCS #11</acronym> token with TLS</a></li>
 199     </ul></li>
 200     <li><a name="toc-Abstract-data-types-1" href="#Abstract-data-types">5.4 Abstract data types</a></li>
 201     <li><a name="toc-Digital-Signatures" href="#Digital-signatures">5.5 Digital Signatures</a>
 202     <ul class="no-bullet">
 203       <li><a name="toc-Trading-Security-for-Interoperability" href="#Trading-Security-for-Interoperability">5.5.1 Trading Security for Interoperability</a></li>
 204     </ul></li>
 205   </ul></li>
 206   <li><a name="toc-How-To-Use-TLS-in-Application-Protocols" href="#How-to-use-TLS-in-application-protocols">6 How To Use <acronym>TLS</acronym> in Application Protocols</a>
 207   <ul class="no-bullet">
 208     <li><a name="toc-Separate-Ports" href="#Separate-ports">6.1 Separate Ports</a></li>
 209     <li><a name="toc-Upward-Negotiation" href="#Upward-negotiation">6.2 Upward Negotiation</a></li>
 210   </ul></li>
 211   <li><a name="toc-How-To-Use-GnuTLS-in-Applications" href="#How-to-use-GnuTLS-in-applications">7 How To Use <acronym>GnuTLS</acronym> in Applications</a>
 212   <ul class="no-bullet">
 213     <li><a name="toc-Preparation-1" href="#Preparation">7.1 Preparation</a>
 214     <ul class="no-bullet">
 215       <li><a name="toc-Headers-1" href="#Headers">7.1.1 Headers</a></li>
 216       <li><a name="toc-Initialization-2" href="#Initialization">7.1.2 Initialization</a></li>
 217       <li><a name="toc-Version-Check" href="#Version-check">7.1.3 Version Check</a></li>
 218       <li><a name="toc-Debugging-1" href="#Debugging">7.1.4 Debugging</a></li>
 219       <li><a name="toc-Building-the-Source" href="#Building-the-source">7.1.5 Building the Source</a></li>
 220     </ul></li>
 221     <li><a name="toc-Multi_002dThreaded-Applications" href="#Multi_002dthreaded-applications">7.2 Multi-Threaded Applications</a></li>
 222     <li><a name="toc-Client-Examples" href="#Client-examples">7.3 Client Examples</a>
 223     <ul class="no-bullet">
 224       <li><a name="toc-Simple-Client-Example-with-Anonymous-Authentication" href="#Simple-client-example-with-anonymous-authentication">7.3.1 Simple Client Example with Anonymous Authentication</a></li>
 225       <li><a name="toc-Simple-Client-Example-with-X_002e509-Certificate-Support" href="#Simple-client-example-with-X_002e509-certificate-support">7.3.2 Simple Client Example with <acronym>X.509</acronym> Certificate Support</a></li>
 226       <li><a name="toc-Obtaining-Session-Information" href="#Obtaining-session-information">7.3.3 Obtaining Session Information</a></li>
 227       <li><a name="toc-Verifying-Peer_0027s-Certificate" href="#Verifying-peer_0027s-certificate">7.3.4 Verifying Peer&rsquo;s Certificate</a></li>
 228       <li><a name="toc-Using-a-Callback-to-Select-the-Certificate-to-Use" href="#Using-a-callback-to-select-the-certificate-to-use">7.3.5 Using a Callback to Select the Certificate to Use</a></li>
 229       <li><a name="toc-Using-a-PKCS-_002311-token-with-TLS-1" href="#Client-using-a-PKCS-_002311-token-with-TLS">7.3.6 Using a <acronym>PKCS #11</acronym> token with TLS</a></li>
 230       <li><a name="toc-Client-with-Resume-Capability-Example" href="#Client-with-Resume-capability-example">7.3.7 Client with Resume Capability Example</a></li>
 231       <li><a name="toc-Simple-Client-Example-with-SRP-Authentication" href="#Simple-client-example-with-SRP-authentication">7.3.8 Simple Client Example with <acronym>SRP</acronym> Authentication</a></li>
 232       <li><a name="toc-Simple-Client-Example-using-the-C_002b_002b-API" href="#Simple-client-example-in-C_002b_002b">7.3.9 Simple Client Example using the C++ API</a></li>
 233       <li><a name="toc-Helper-Function-for-TCP-Connections" href="#Helper-function-for-TCP-connections">7.3.10 Helper Function for TCP Connections</a></li>
 234     </ul></li>
 235     <li><a name="toc-Server-Examples" href="#Server-examples">7.4 Server Examples</a>
 236     <ul class="no-bullet">
 237       <li><a name="toc-Echo-Server-with-X_002e509-Authentication" href="#Echo-Server-with-X_002e509-authentication">7.4.1 Echo Server with <acronym>X.509</acronym> Authentication</a></li>
 238       <li><a name="toc-Echo-Server-with-OpenPGP-Authentication" href="#Echo-Server-with-OpenPGP-authentication">7.4.2 Echo Server with <acronym>OpenPGP</acronym> Authentication</a></li>
 239       <li><a name="toc-Echo-Server-with-SRP-Authentication" href="#Echo-Server-with-SRP-authentication">7.4.3 Echo Server with <acronym>SRP</acronym> Authentication</a></li>
 240       <li><a name="toc-Echo-Server-with-Anonymous-Authentication" href="#Echo-Server-with-anonymous-authentication">7.4.4 Echo Server with Anonymous Authentication</a></li>
 241     </ul></li>
 242     <li><a name="toc-Miscellaneous-Examples" href="#Miscellaneous-examples">7.5 Miscellaneous Examples</a>
 243     <ul class="no-bullet">
 244       <li><a name="toc-Checking-for-an-Alert" href="#Checking-for-an-alert">7.5.1 Checking for an Alert</a></li>
 245       <li><a name="toc-X_002e509-Certificate-Parsing-Example" href="#X_002e509-certificate-parsing-example">7.5.2 <acronym>X.509</acronym> Certificate Parsing Example</a></li>
 246       <li><a name="toc-Certificate-Request-Generation" href="#Certificate-request-generation">7.5.3 Certificate Request Generation</a></li>
 247       <li><a name="toc-PKCS-_002312-Structure-Generation" href="#PKCS-_002312-structure-generation">7.5.4 <acronym>PKCS</acronym> #12 Structure Generation</a></li>
 248     </ul></li>
 249     <li><a name="toc-Parameter-generation-1" href="#Parameter-generation">7.6 Parameter generation</a></li>
 250     <li><a name="toc-Keying-Material-Exporters-1" href="#Keying-Material-Exporters">7.7 Keying Material Exporters</a></li>
 251     <li><a name="toc-Channel-Bindings-1" href="#Channel-Bindings">7.8 Channel Bindings</a></li>
 252     <li><a name="toc-Compatibility-with-the-OpenSSL-Library" href="#Compatibility-with-the-OpenSSL-library">7.9 Compatibility with the OpenSSL Library</a></li>
 253   </ul></li>
 254   <li><a name="toc-Included-Programs" href="#Included-programs">8 Included Programs</a>
 255   <ul class="no-bullet">
 256     <li><a name="toc-Invoking-certtool-1" href="#Invoking-certtool">8.1 Invoking certtool</a></li>
 257     <li><a name="toc-Invoking-gnutls_002dcli-1" href="#Invoking-gnutls_002dcli">8.2 Invoking gnutls-cli</a>
 258     <ul class="no-bullet">
 259       <li><a name="toc-Example-client-PSK-connection-1" href="#Example-client-PSK-connection">8.2.1 Example client PSK connection</a></li>
 260     </ul></li>
 261     <li><a name="toc-Invoking-gnutls_002dcli_002ddebug-1" href="#Invoking-gnutls_002dcli_002ddebug">8.3 Invoking gnutls-cli-debug</a></li>
 262     <li><a name="toc-Invoking-gnutls_002dserv-1" href="#Invoking-gnutls_002dserv">8.4 Invoking gnutls-serv</a>
 263     <ul class="no-bullet">
 264       <li><a name="toc-Setting-Up-a-Test-HTTPS-Server" href="#Setting-Up-a-Test-HTTPS-Server">8.4.1 Setting Up a Test HTTPS Server</a></li>
 265       <li><a name="toc-Example-server-PSK-connection-1" href="#Example-server-PSK-connection">8.4.2 Example server PSK connection</a></li>
 266     </ul></li>
 267     <li><a name="toc-Invoking-psktool-1" href="#Invoking-psktool">8.5 Invoking psktool</a></li>
 268     <li><a name="toc-Invoking-srptool-1" href="#Invoking-srptool">8.6 Invoking srptool</a></li>
 269     <li><a name="toc-Invoking-p11tool-1" href="#Invoking-p11tool">8.7 Invoking p11tool</a></li>
 270   </ul></li>
 271   <li><a name="toc-Function-Reference" href="#Function-reference">9 Function Reference</a>
 272   <ul class="no-bullet">
 273     <li><a name="toc-Core-Functions" href="#Core-functions">9.1 Core Functions</a></li>
 274     <li><a name="toc-X_002e509-Certificate-Functions" href="#X_002e509-certificate-functions">9.2 <acronym>X.509</acronym> Certificate Functions</a></li>
 275     <li><a name="toc-GnuTLS_002dextra-Functions" href="#GnuTLS_002dextra-functions">9.3 <acronym>GnuTLS-extra</acronym> Functions</a></li>
 276     <li><a name="toc-OpenPGP-Functions" href="#OpenPGP-functions">9.4 <acronym>OpenPGP</acronym> Functions</a></li>
 277     <li><a name="toc-TLS-Inner-Application-_0028TLS_002fIA_0029-Functions" href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">9.5 <acronym>TLS</acronym> Inner Application (<acronym>TLS/IA</acronym>) Functions</a></li>
 278     <li><a name="toc-Error-Codes-and-Descriptions" href="#Error-codes-and-descriptions">9.6 Error Codes and Descriptions</a></li>
 279   </ul></li>
 280   <li><a name="toc-All-the-Supported-Ciphersuites-in-GnuTLS" href="#All-the-supported-ciphersuites-in-GnuTLS">10 All the Supported Ciphersuites in <acronym>GnuTLS</acronym></a></li>
 281   <li><a name="toc-Guile-Bindings-1" href="#Guile-Bindings">11 Guile Bindings</a>
 282   <ul class="no-bullet">
 283     <li><a name="toc-Guile-Preparations-1" href="#Guile-Preparations">11.1 Guile Preparations</a></li>
 284     <li><a name="toc-Guile-API-Conventions-1" href="#Guile-API-Conventions">11.2 Guile API Conventions</a>
 285     <ul class="no-bullet">
 286       <li><a name="toc-Enumerates-and-Constants-1" href="#Enumerates-and-Constants">11.2.1 Enumerates and Constants</a></li>
 287       <li><a name="toc-Procedure-Names-1" href="#Procedure-Names">11.2.2 Procedure Names</a></li>
 288       <li><a name="toc-Representation-of-Binary-Data-1" href="#Representation-of-Binary-Data">11.2.3 Representation of Binary Data</a></li>
 289       <li><a name="toc-Input-and-Output-1" href="#Input-and-Output">11.2.4 Input and Output</a></li>
 290       <li><a name="toc-Exception-Handling-1" href="#Exception-Handling">11.2.5 Exception Handling</a></li>
 291     </ul></li>
 292     <li><a name="toc-Guile-Examples-1" href="#Guile-Examples">11.3 Guile Examples</a>
 293     <ul class="no-bullet">
 294       <li><a name="toc-Anonymous-Authentication-Guile-Example-1" href="#Anonymous-Authentication-Guile-Example">11.3.1 Anonymous Authentication Guile Example</a></li>
 295       <li><a name="toc-OpenPGP-Authentication-Guile-Example-1" href="#OpenPGP-Authentication-Guile-Example">11.3.2 OpenPGP Authentication Guile Example</a></li>
 296       <li><a name="toc-Importing-OpenPGP-Keys-Guile-Example-1" href="#Importing-OpenPGP-Keys-Guile-Example">11.3.3 Importing OpenPGP Keys Guile Example</a></li>
 297     </ul></li>
 298     <li><a name="toc-Guile-Reference-1" href="#Guile-Reference">11.4 Guile Reference</a>
 299     <ul class="no-bullet">
 300       <li><a name="toc-Core-Interface-1" href="#Core-Interface">11.4.1 Core Interface</a></li>
 301       <li><a name="toc-Extra-Interface-1" href="#Extra-Interface">11.4.2 Extra Interface</a></li>
 302     </ul></li>
 303   </ul></li>
 304   <li><a name="toc-Internal-Architecture-of-GnuTLS" href="#Internal-architecture-of-GnuTLS">12 Internal Architecture of GnuTLS</a>
 305   <ul class="no-bullet">
 306     <li><a name="toc-The-TLS-Protocol-1" href="#The-TLS-Protocol">12.1 The TLS Protocol</a></li>
 307     <li><a name="toc-TLS-Handshake-Protocol-1" href="#TLS-Handshake-Protocol">12.2 TLS Handshake Protocol</a></li>
 308     <li><a name="toc-TLS-Authentication-Methods-1" href="#TLS-Authentication-Methods">12.3 TLS Authentication Methods</a></li>
 309     <li><a name="toc-TLS-Extension-Handling-1" href="#TLS-Extension-Handling">12.4 TLS Extension Handling</a>
 310     <ul class="no-bullet">
 311       <li><a name="toc-Adding-a-New-TLS-Extension" href="#Adding-a-New-TLS-Extension">12.4.1 Adding a New TLS Extension</a></li>
 312     </ul></li>
 313     <li><a name="toc-Certificate-Handling-1" href="#Certificate-Handling">12.5 Certificate Handling</a></li>
 314     <li><a name="toc-Cryptographic-Backend-1" href="#Cryptographic-Backend">12.6 Cryptographic Backend</a>
 315     <ul class="no-bullet">
 316       <li><a name="toc-Cryptographic-Library-layer" href="#Cryptographic-Library-layer">12.6.1 Cryptographic Library layer</a></li>
 317       <li><a name="toc-External-cryptography-provider" href="#External-cryptography-provider">12.6.2 External cryptography provider</a>
 318       <ul class="no-bullet">
 319         <li><a name="toc-Override-specific-algorithms" href="#Override-specific-algorithms">12.6.2.1 Override specific algorithms</a></li>
 320         <li><a name="toc-Override-parts-of-the-backend" href="#Override-parts-of-the-backend">12.6.2.2 Override parts of the backend</a></li>
 321       </ul></li>
 322     </ul></li>
 323   </ul></li>
 324   <li><a name="toc-Copying-Information-1" href="#Copying-Information">Appendix A Copying Information</a>
 325   <ul class="no-bullet">
 326     <li><a name="toc-GNU-Free-Documentation-License-1" href="#GNU-Free-Documentation-License">A.1 GNU Free Documentation License</a></li>
 327     <li><a name="toc-GNU-Lesser-General-Public-License" href="#GNU-LGPL">A.2 GNU Lesser General Public License</a></li>
 328     <li><a name="toc-GNU-General-Public-License" href="#GNU-GPL">A.3 GNU General Public License</a></li>
 329   </ul></li>
 330   <li><a name="toc-Bibliography-1" href="#Bibliography">Bibliography</a></li>
 331   <li><a name="toc-Function-and-Data-Index-1" href="#Function-and-Data-Index">Function and Data Index</a></li>
 332   <li><a name="toc-Concept-Index-1" href="#Concept-Index">Concept Index</a></li>
 333 </ul>
 334 </div>
 335
 336
 337 <a name="Top"></a>
 338 <div class="header">
 339 <p>
 340 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>
 341 </div>
 342 <a name="GnuTLS"></a>
 343 <h1 class="top">GnuTLS</h1>
 344
 345 <p>This manual is last updated 6 January 2012 for version
 346 2.12.20 of GnuTLS.
 347 </p>
 348 <p>Copyright &copy; 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
 349 </p>
 350 <blockquote>
 351 <p>Permission is granted to copy, distribute and/or modify this document
 352 under the terms of the GNU Free Documentation License, Version 1.3 or
 353 any later version published by the Free Software Foundation; with no
 354 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
 355 copy of the license is included in the section entitled &ldquo;GNU Free
 356 Documentation License&rdquo;.
 357 </p></blockquote>
 358
 359
 360 <table class="menu" border="0" cellspacing="0">
 361 <tr><td align="left" valign="top">&bull; <a href="#Preface" accesskey="1">Preface</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 362 </td></tr>
 363 <tr><td align="left" valign="top">&bull; <a href="#The-Library" accesskey="2">The Library</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 364 </td></tr>
 365 <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">
 366 </td></tr>
 367 <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">
 368 </td></tr>
 369 <tr><td align="left" valign="top">&bull; <a href="#More-on-certificate-authentication" accesskey="5">More on certificate authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 370 </td></tr>
 371 <tr><td align="left" valign="top">&bull; <a href="#How-to-use-TLS-in-application-protocols" accesskey="6">How to use TLS in application protocols</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 372 </td></tr>
 373 <tr><td align="left" valign="top">&bull; <a href="#How-to-use-GnuTLS-in-applications" accesskey="7">How to use GnuTLS in applications</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 374 </td></tr>
 375 <tr><td align="left" valign="top">&bull; <a href="#Included-programs" accesskey="8">Included programs</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 376 </td></tr>
 377 <tr><td align="left" valign="top">&bull; <a href="#Function-reference" accesskey="9">Function reference</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 378 </td></tr>
 379 <tr><td align="left" valign="top">&bull; <a href="#All-the-supported-ciphersuites-in-GnuTLS">All the supported ciphersuites in GnuTLS</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 380 </td></tr>
 381 <tr><td align="left" valign="top">&bull; <a href="#Guile-Bindings">Guile Bindings</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 382 </td></tr>
 383 <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">
 384 </td></tr>
 385 <tr><td align="left" valign="top">&bull; <a href="#Copying-Information">Copying Information</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 386 </td></tr>
 387 <tr><td align="left" valign="top">&bull; <a href="#Concept-Index">Concept Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 388 </td></tr>
 389 <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">
 390 </td></tr>
 391 <tr><td align="left" valign="top">&bull; <a href="#Bibliography">Bibliography</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 392 </td></tr>
 393 </table>
 394
 395 <hr>
 396 <a name="Preface"></a>
 397 <div class="header">
 398 <p>
 399 Next: <a href="#The-Library" accesskey="n" rel="next">The Library</a>, Previous: <a href="#Top" accesskey="p" rel="previous">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>
 400 </div>
 401 <a name="Preface-1"></a>
 402 <h2 class="chapter">1 Preface</h2>
 403
 404 <p>This document tries to demonstrate and explain the <acronym>GnuTLS</acronym>
 405 library API.  A brief introduction to the protocols and the technology
 406 involved, is also included so that an application programmer can
 407 better understand the <acronym>GnuTLS</acronym> purpose and actual offerings.
 408 Even if <acronym>GnuTLS</acronym> is a typical library software, it operates
 409 over several security and cryptographic protocols, which require the
 410 programmer to make careful and correct usage of them, otherwise he
 411 risks to offer just a false sense of security. Security and the
 412 network security terms are very general terms even for computer
 413 software thus cannot be easily restricted to a single cryptographic
 414 library.  For that reason, do not consider a program secure just
 415 because it uses <acronym>GnuTLS</acronym>; there are several ways to compromise
 416 a program or a communication line and <acronym>GnuTLS</acronym> only helps with
 417 some of them.
 418 </p>
 419 <p>Although this document tries to be self contained, basic network
 420 programming and PKI knowlegde is assumed in most of it. A good
 421 introduction to networking can be found in [STEVENS] (see <a href="#Bibliography">Bibliography</a>) and for
 422 Public Key Infrastructure in [GUTPKI] (see <a href="#Bibliography">Bibliography</a>).
 423 </p>
 424 <a name="Availability"></a>
 425 <p>Updated versions of the <acronym>GnuTLS</acronym> software and this document
 426 will be available from <a href="http://www.gnutls.org/">http://www.gnutls.org/</a> and
 427 <a href="http://www.gnu.org/software/gnutls/">http://www.gnu.org/software/gnutls/</a>.
 428 </p>
 429 <table class="menu" border="0" cellspacing="0">
 430 <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">
 431 </td></tr>
 432 <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">
 433 </td></tr>
 434 <tr><td align="left" valign="top">&bull; <a href="#Downloading-and-Installing" accesskey="3">Downloading and Installing</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 435 </td></tr>
 436 <tr><td align="left" valign="top">&bull; <a href="#Bug-Reports" accesskey="4">Bug Reports</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 437 </td></tr>
 438 <tr><td align="left" valign="top">&bull; <a href="#Contributing" accesskey="5">Contributing</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 439 </td></tr>
 440 </table>
 441
 442 <hr>
 443 <a name="Getting-help"></a>
 444 <div class="header">
 445 <p>
 446 Next: <a href="#Commercial-Support" accesskey="n" rel="next">Commercial Support</a>, Up: <a href="#Preface" accesskey="u" rel="up">Preface</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>
 447 </div>
 448 <a name="Getting-Help"></a>
 449 <h3 class="section">1.1 Getting Help</h3>
 450
 451 <p>A mailing list where users may help each other exists, and you can
 452 reach it by sending e-mail to <a href="mailto:help-gnutls@gnu.org">help-gnutls@gnu.org</a>.  Archives
 453 of the mailing list discussions, and an interface to manage
 454 subscriptions, is available through the World Wide Web at
 455 <a href="http://lists.gnu.org/mailman/listinfo/help-gnutls">http://lists.gnu.org/mailman/listinfo/help-gnutls</a>.
 456 </p>
 457 <p>A mailing list for developers are also available, see
 458 <a href="http://www.gnu.org/software/gnutls/lists.html">http://www.gnu.org/software/gnutls/lists.html</a>.
 459 </p>
 460 <p>Bug reports should be sent to <a href="mailto:bug-gnutls@gnu.org">bug-gnutls@gnu.org</a>, see
 461 See <a href="#Bug-Reports">Bug Reports</a>.
 462 </p>
 463 <hr>
 464 <a name="Commercial-Support"></a>
 465 <div class="header">
 466 <p>
 467 Next: <a href="#Downloading-and-Installing" accesskey="n" rel="next">Downloading and Installing</a>, Previous: <a href="#Getting-help" accesskey="p" rel="previous">Getting help</a>, Up: <a href="#Preface" accesskey="u" rel="up">Preface</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>
 468 </div>
 469 <a name="Commercial-Support-1"></a>
 470 <h3 class="section">1.2 Commercial Support</h3>
 471
 472 <p>Commercial support is available for users of GnuTLS.  The kind of
 473 support that can be purchased may include:
 474 </p>
 475 <ul>
 476 <li> Implement new features.
 477 Such as a new TLS extension.
 478
 479 </li><li> Port GnuTLS to new platforms.
 480 This could include porting to an embedded platforms that may need
 481 memory or size optimization.
 482
 483 </li><li> Integrating TLS as a security environment in your existing project.
 484
 485 </li><li> System design of components related to TLS.
 486
 487 </li></ul>
 488
 489 <p>If you are interested, please write to:
 490 </p>
 491 <pre class="verbatim">Simon Josefsson Datakonsult
 492 Hagagatan 24
 493 113 47 Stockholm
 494 Sweden
 495
 496 E-mail: simon@josefsson.org
 497 </pre>
 498 <p>If your company provides support related to GnuTLS and would like to
 499 be mentioned here, contact the author (see <a href="#Bug-Reports">Bug Reports</a>).
 500 </p>
 501 <hr>
 502 <a name="Downloading-and-Installing"></a>
 503 <div class="header">
 504 <p>
 505 Next: <a href="#Bug-Reports" accesskey="n" rel="next">Bug Reports</a>, Previous: <a href="#Commercial-Support" accesskey="p" rel="previous">Commercial Support</a>, Up: <a href="#Preface" accesskey="u" rel="up">Preface</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="Downloading-and-Installing-1"></a>
 508 <h3 class="section">1.3 Downloading and Installing</h3>
 509 <a name="index-Installation"></a>
 510 <a name="index-Download"></a>
 511
 512 <p>GnuTLS is available for download from the following URL:
 513 </p>
 514 <p><a href="http://www.gnutls.org/download.html">http://www.gnutls.org/download.html</a>
 515 </p>
 516 <p>The latest version is stored in a file, e.g.,
 517 &lsquo;<samp>gnutls-2.12.20.tar.gz</samp>&rsquo; where the &lsquo;<samp>2.12.20</samp>&rsquo;
 518 value is the highest version number in the directory.
 519 </p>
 520 <p>GnuTLS uses a Linux-like development cycle: even minor version numbers
 521 indicate a stable release and a odd minor version number indicates a
 522 development release.  For example, GnuTLS 1.6.3 denote a stable
 523 release since 6 is even, and GnuTLS 1.7.11 denote a development
 524 release since 7 is odd.
 525 </p>
 526 <p>GnuTLS depends on Libgcrypt,
 527 and you will need to install Libgcrypt
 528 before installing GnuTLS.  Libgcrypt is available from
 529 <a href="ftp://ftp.gnupg.org/gcrypt/libgcrypt">ftp://ftp.gnupg.org/gcrypt/libgcrypt</a>.  Libgcrypt needs another
 530 library, libgpg-error, and you need to install libgpg-error before
 531 installing Libgcrypt.  Libgpg-error is available from
 532 <a href="ftp://ftp.gnupg.org/gcrypt/libgpg-error">ftp://ftp.gnupg.org/gcrypt/libgpg-error</a>.
 533 </p>
 534 <p>Don&rsquo;t forget to verify the cryptographic signature after downloading
 535 source code packages.
 536 </p>
 537 <p>The package is then extracted, configured and built like many other
 538 packages that use Autoconf.  For detailed information on configuring
 539 and building it, refer to the &lsquo;<tt>INSTALL</tt>&rsquo; file that is part of the
 540 distribution archive.  Typically you invoke <code>./configure</code> and
 541 then <code>make check install</code>.  There are a number of compile-time
 542 parameters, as discussed below.
 543 </p>
 544 <p>The compression libraries (libz and lzo) are optional dependencies.
 545 You can get libz from <a href="http://www.zlib.net/">http://www.zlib.net/</a>.  You can get lzo
 546 from <a href="http://www.oberhumer.com/opensource/lzo/">http://www.oberhumer.com/opensource/lzo/</a>.
 547 </p>
 548 <p>The X.509 part of GnuTLS needs ASN.1 functionality, from a library
 549 called libtasn1.  A copy of libtasn1 is included in GnuTLS.  If you
 550 want to install it separately (e.g., to make it possibly to use
 551 libtasn1 in other programs), you can get it from
 552 <a href="http://www.gnu.org/software/gnutls/download.html">http://www.gnu.org/software/gnutls/download.html</a>.
 553 </p>
 554 <p>The OpenPGP part of GnuTLS uses a stripped down version of OpenCDK for
 555 parsing OpenPGP packets.  It is included GnuTLS.  Use parameter
 556 <code>--disable-openpgp-authentication</code> to disable the OpenPGP
 557 functionality in GnuTLS.  Unfortunately, we didn&rsquo;t have resources to
 558 maintain the code in a separate library.
 559 </p>
 560 <p>Regarding the Guile bindings, there are additional installation
 561 considerations, see See <a href="#Guile-Preparations">Guile Preparations</a>.
 562 </p>
 563 <p>A few <code>configure</code> options may be relevant, summarized in the
 564 table.
 565 </p>
 566 <dl compact="compact">
 567 <dt><code>--disable-srp-authentication</code></dt>
 568 <dt><code>--disable-psk-authentication</code></dt>
 569 <dt><code>--disable-anon-authentication</code></dt>
 570 <dt><code>--disable-extra-pki</code></dt>
 571 <dt><code>--disable-openpgp-authentication</code></dt>
 572 <dt><code>--disable-openssl-compatibility</code></dt>
 573 <dd><p>Disable or enable particular features.  Generally not recommended.
 574 </p>
 575 </dd>
 576 </dl>
 577
 578 <p>For the complete list, refer to the output from <code>configure
 579 --help</code>.
 580 </p>
 581 <hr>
 582 <a name="Bug-Reports"></a>
 583 <div class="header">
 584 <p>
 585 Next: <a href="#Contributing" accesskey="n" rel="next">Contributing</a>, Previous: <a href="#Downloading-and-Installing" accesskey="p" rel="previous">Downloading and Installing</a>, Up: <a href="#Preface" accesskey="u" rel="up">Preface</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>
 586 </div>
 587 <a name="Bug-Reports-1"></a>
 588 <h3 class="section">1.4 Bug Reports</h3>
 589 <a name="index-Reporting-Bugs"></a>
 590
 591 <p>If you think you have found a bug in GnuTLS, please investigate it and
 592 report it.
 593 </p>
 594 <ul>
 595 <li> Please make sure that the bug is really in GnuTLS, and
 596 preferably also check that it hasn&rsquo;t already been fixed in the latest
 597 version.
 598
 599 </li><li> You have to send us a test case that makes it possible for us to
 600 reproduce the bug.
 601
 602 </li><li> You also have to explain what is wrong; if you get a crash, or
 603 if the results printed are not good and in that case, in what way.
 604 Make sure that the bug report includes all information you would need
 605 to fix this kind of bug for someone else.
 606
 607 </li></ul>
 608
 609 <p>Please make an effort to produce a self-contained report, with
 610 something definite that can be tested or debugged.  Vague queries or
 611 piecemeal messages are difficult to act on and don&rsquo;t help the
 612 development effort.
 613 </p>
 614 <p>If your bug report is good, we will do our best to help you to get a
 615 corrected version of the software; if the bug report is poor, we won&rsquo;t
 616 do anything about it (apart from asking you to send better bug
 617 reports).
 618 </p>
 619 <p>If you think something in this manual is unclear, or downright
 620 incorrect, or if the language needs to be improved, please also send a
 621 note.
 622 </p>
 623 <p>Send your bug report to:
 624 </p>
 625 <div align="center">&lsquo;<samp>bug-gnutls@gnu.org</samp>&rsquo;
 626 </div>
 627 <hr>
 628 <a name="Contributing"></a>
 629 <div class="header">
 630 <p>
 631 Previous: <a href="#Bug-Reports" accesskey="p" rel="previous">Bug Reports</a>, Up: <a href="#Preface" accesskey="u" rel="up">Preface</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>
 632 </div>
 633 <a name="Contributing-1"></a>
 634 <h3 class="section">1.5 Contributing</h3>
 635 <a name="index-Contributing"></a>
 636 <a name="index-Hacking"></a>
 637
 638 <p>If you want to submit a patch for inclusion &ndash; from solve a typo you
 639 discovered, up to adding support for a new feature &ndash; you should
 640 submit it as a bug report (see <a href="#Bug-Reports">Bug Reports</a>).  There are some
 641 things that you can do to increase the chances for it to be included
 642 in the official package.
 643 </p>
 644 <p>Unless your patch is very small (say, under 10 lines) we require that
 645 you assign the copyright of your work to the Free Software Foundation.
 646 This is to protect the freedom of the project.  If you have not
 647 already signed papers, we will send you the necessary information when
 648 you submit your contribution.
 649 </p>
 650 <p>For contributions that doesn&rsquo;t consist of actual programming code, the
 651 only guidelines are common sense.  Use it.
 652 </p>
 653 <p>For code contributions, a number of style guides will help you:
 654 </p>
 655 <ul>
 656 <li> Coding Style.
 657 Follow the GNU Standards document.
 658
 659 <p>If you normally code using another coding standard, there is no
 660 problem, but you should use &lsquo;<samp>indent</samp>&rsquo; to reformat the code
 661 before submitting your work.
 662 </p>
 663 </li><li> Use the unified diff format &lsquo;<samp>diff -u</samp>&rsquo;.
 664
 665 </li><li> Return errors.
 666 No reason whatsoever should abort the execution of the library.  Even
 667 memory allocation errors, e.g. when malloc return NULL, should work
 668 although result in an error code.
 669
 670 </li><li> Design with thread safety in mind.
 671 Don&rsquo;t use global variables.  Don&rsquo;t even write to per-handle global
 672 variables unless the documented behaviour of the function you write is
 673 to write to the per-handle global variable.
 674
 675 </li><li> Avoid using the C math library.
 676 It causes problems for embedded implementations, and in most
 677 situations it is very easy to avoid using it.
 678
 679 </li><li> Document your functions.
 680 Use comments before each function headers, that, if properly
 681 formatted, are extracted into Texinfo manuals and GTK-DOC web pages.
 682
 683 </li><li> Supply a ChangeLog and NEWS entries, where appropriate.
 684
 685 </li></ul>
 686
 687 <hr>
 688 <a name="The-Library"></a>
 689 <div class="header">
 690 <p>
 691 Next: <a href="#Introduction-to-TLS" accesskey="n" rel="next">Introduction to TLS</a>, Previous: <a href="#Preface" accesskey="p" rel="previous">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>
 692 </div>
 693 <a name="The-Library-1"></a>
 694 <h2 class="chapter">2 The Library</h2>
 695
 696 <p>In brief <acronym>GnuTLS</acronym> can be described as a library which offers an API
 697 to access secure communication protocols. These protocols provide
 698 privacy over insecure lines, and were designed to prevent
 699 eavesdropping, tampering, or message forgery.
 700 </p>
 701 <p>Technically <acronym>GnuTLS</acronym> is a portable ANSI C based library which
 702 implements the protocols ranging from SSL 3.0 to TLS 1.2 (See <a href="#Introduction-to-TLS">Introduction to
 703 TLS</a>, for a more detailed description of the protocols), accompanied
 704 with the required framework for authentication and public key
 705 infrastructure.  Important features of the <acronym>GnuTLS</acronym> library
 706 include:
 707 </p>
 708 <ul>
 709 <li> Support for TLS 1.2, TLS 1.1, TLS 1.0 and SSL 3.0 protocols.
 710
 711 </li><li> Support for both <acronym>X.509</acronym> and <acronym>OpenPGP</acronym> certificates.
 712
 713 </li><li> Support for handling and verification of certificates.
 714
 715 </li><li> Support for <acronym>SRP</acronym> for TLS authentication.
 716
 717 </li><li> Support for <acronym>PSK</acronym> for TLS authentication.
 718
 719 </li><li> Support for TLS Extension mechanism.
 720
 721 </li><li> Support for TLS Compression Methods.
 722
 723 </li></ul>
 724
 725 <p>Additionally <acronym>GnuTLS</acronym> provides a limited emulation API for the
 726 widely used OpenSSL<a name="DOCF1" href="#FOOT1">(1)</a> library,
 727 to ease integration with existing applications.
 728 </p>
 729 <p><acronym>GnuTLS</acronym> consists of three independent parts, namely the &ldquo;TLS
 730 protocol part&rdquo;, the &ldquo;Certificate part&rdquo;, and the &ldquo;Cryptographic
 731 backend&rdquo; part.  The &lsquo;TLS protocol part&rsquo; is the actual protocol
 732 implementation, and is entirely implemented within the
 733 <acronym>GnuTLS</acronym> library.  The &lsquo;Certificate part&rsquo; consists of the
 734 certificate parsing, and verification functions which is partially
 735 implemented in the <acronym>GnuTLS</acronym> library.  The
 736 <acronym>Libtasn1</acronym><a name="DOCF2" href="#FOOT2">(2)</a>,
 737 a library which offers <acronym>ASN.1</acronym> parsing capabilities, is used
 738 for the <acronym>X.509</acronym> certificate parsing functions.  A smaller
 739 version of
 740 <acronym>OpenCDK</acronym><a name="DOCF3" href="#FOOT3">(3)</a>
 741 is used for the <acronym>OpenPGP</acronym> key support in <acronym>GnuTLS</acronym>.
 742 The &ldquo;Cryptographic backend&rdquo; is provided by the
 743 <acronym>Libgcrypt</acronym><a name="DOCF4" href="#FOOT4">(4)</a>
 744 library<a name="DOCF5" href="#FOOT5">(5)</a>.
 745 </p>
 746 <p>In order to ease integration in embedded systems, parts of the
 747 <acronym>GnuTLS</acronym> library can be disabled at compile time. That way a
 748 small library, with the required features, can be generated.
 749 </p>
 750 <table class="menu" border="0" cellspacing="0">
 751 <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">
 752 </td></tr>
 753 <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">
 754 </td></tr>
 755 <tr><td align="left" valign="top">&bull; <a href="#Memory-handling" accesskey="3">Memory handling</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 756 </td></tr>
 757 <tr><td align="left" valign="top">&bull; <a href="#Callback-functions" accesskey="4">Callback functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 758 </td></tr>
 759 </table>
 760
 761 <hr>
 762 <a name="General-Idea"></a>
 763 <div class="header">
 764 <p>
 765 Next: <a href="#Error-handling" accesskey="n" rel="next">Error handling</a>, Up: <a href="#The-Library" accesskey="u" rel="up">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>
 766 </div>
 767 <a name="General-Idea-1"></a>
 768 <h3 class="section">2.1 General Idea</h3>
 769
 770 <p>A brief description of how <acronym>GnuTLS</acronym> works internally is shown
 771 at the figure below. This section may be easier to understand after
 772 having seen the examples (see <a href="#examples">examples</a>).
 773 </p>
 774 <img src="gnutls-internals.png" alt="gnutls-internals">
 775
 776 <p>As shown in the figure, there is a read-only global state that is
 777 initialized once by the global initialization function.  This global
 778 structure, among others, contains the memory allocation functions
 779 used, and some structures needed for the <acronym>ASN.1</acronym> parser.  This
 780 structure is never modified by any <acronym>GnuTLS</acronym> function, except
 781 for the deinitialization function which frees all memory allocated in
 782 the global structure and is called after the program has permanently
 783 finished using <acronym>GnuTLS</acronym>.
 784 </p>
 785 <p>The credentials structure is used by some authentication methods, such
 786 as certificate authentication (see <a href="#Certificate-Authentication">Certificate Authentication</a>).  A
 787 credentials structure may contain certificates, private keys,
 788 temporary parameters for Diffie-Hellman or RSA key exchange, and other
 789 stuff that may be shared between several TLS sessions.
 790 </p>
 791 <p>This structure should be initialized using the appropriate
 792 initialization functions. For example an application which uses
 793 certificate authentication would probably initialize the credentials,
 794 using the appropriate functions, and put its trusted certificates in
 795 this structure. The next step is to associate the credentials
 796 structure with each <acronym>TLS</acronym> session.
 797 </p>
 798 <p>A <acronym>GnuTLS</acronym> session contains all the required stuff for a
 799 session to handle one secure connection. This session calls directly
 800 to the transport layer functions, in order to communicate with the
 801 peer.  Every session has a unique session ID shared with the peer.
 802 </p>
 803 <p>Since TLS sessions can be resumed, servers would probably need a
 804 database backend to hold the session&rsquo;s parameters.  Every
 805 <acronym>GnuTLS</acronym> session after a successful handshake calls the
 806 appropriate backend function (See <a href="#resume">resume</a>, for information on
 807 initialization) to store the newly negotiated session. The session
 808 database is examined by the server just after having received the
 809 client hello<a name="DOCF6" href="#FOOT6">(6)</a>,
 810 and if the session ID sent by the client, matches a stored session,
 811 the stored session will be retrieved, and the new session will be a
 812 resumed one, and will share the same session ID with the previous one.
 813 </p>
 814 <hr>
 815 <a name="Error-handling"></a>
 816 <div class="header">
 817 <p>
 818 Next: <a href="#Memory-handling" accesskey="n" rel="next">Memory handling</a>, Previous: <a href="#General-Idea" accesskey="p" rel="previous">General Idea</a>, Up: <a href="#The-Library" accesskey="u" rel="up">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>
 819 </div>
 820 <a name="Error-Handling"></a>
 821 <h3 class="section">2.2 Error Handling</h3>
 822
 823 <p>In <acronym>GnuTLS</acronym> most functions return an integer type as a result.
 824 In almost all cases a zero or a positive number means success, and a
 825 negative number indicates failure, or a situation that some action has
 826 to be taken. Thus negative error codes may be fatal or not.
 827 </p>
 828 <p>Fatal errors terminate the connection immediately and further sends
 829 and receives will be disallowed. An example of a fatal error code is
 830 <code>GNUTLS_E_DECRYPTION_FAILED</code>. Non-fatal errors may warn about
 831 something, i.e., a warning alert was received, or indicate the some
 832 action has to be taken. This is the case with the error code
 833 <code>GNUTLS_E_REHANDSHAKE</code> returned by <a href="#gnutls_005frecord_005frecv">gnutls_record_recv</a>.
 834 This error code indicates that the server requests a re-handshake. The
 835 client may ignore this request, or may reply with an alert.  You can
 836 test if an error code is a fatal one by using the
 837 <a href="#gnutls_005ferror_005fis_005ffatal">gnutls_error_is_fatal</a>.
 838 </p>
 839 <p>If any non fatal errors, that require an action, are to be returned by
 840 a function, these error codes will be documented in the function&rsquo;s
 841 reference.  See <a href="#Error-Codes">Error Codes</a>, for all the error codes.
 842 </p>
 843 <hr>
 844 <a name="Memory-handling"></a>
 845 <div class="header">
 846 <p>
 847 Next: <a href="#Callback-functions" accesskey="n" rel="next">Callback functions</a>, Previous: <a href="#Error-handling" accesskey="p" rel="previous">Error handling</a>, Up: <a href="#The-Library" accesskey="u" rel="up">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>
 848 </div>
 849 <a name="Memory-Handling"></a>
 850 <h3 class="section">2.3 Memory Handling</h3>
 851
 852 <p><acronym>GnuTLS</acronym> internally handles heap allocated objects
 853 differently, depending on the sensitivity of the data they
 854 contain. However for performance reasons, the default memory functions
 855 do not overwrite sensitive data from memory, nor protect such objects
 856 from being written to the swap.  In order to change the default
 857 behavior the <a href="#gnutls_005fglobal_005fset_005fmem_005ffunctions">gnutls_global_set_mem_functions</a> function is
 858 available which can be used to set other memory handlers than the
 859 defaults.
 860 </p>
 861 <p>The <acronym>Libgcrypt</acronym> library on which <acronym>GnuTLS</acronym> depends, has
 862 such secure memory allocation functions available. These should be
 863 used in cases where even the system&rsquo;s swap memory is not considered
 864 secure. See the documentation of <acronym>Libgcrypt</acronym> for more
 865 information.
 866 </p>
 867 <hr>
 868 <a name="Callback-functions"></a>
 869 <div class="header">
 870 <p>
 871 Previous: <a href="#Memory-handling" accesskey="p" rel="previous">Memory handling</a>, Up: <a href="#The-Library" accesskey="u" rel="up">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>
 872 </div>
 873 <a name="Callback-Functions"></a>
 874 <h3 class="section">2.4 Callback Functions</h3>
 875 <a name="index-Callback-functions"></a>
 876
 877 <p>There are several cases where <acronym>GnuTLS</acronym> may need some out of
 878 band input from your program. This is now implemented using some
 879 callback functions, which your program is expected to register.
 880 </p>
 881 <p>An example of this type of functions are the push and pull callbacks
 882 which are used to specify the functions that will retrieve and send
 883 data to the transport layer.
 884 </p>
 885 <ul>
 886 <li> <a href="#gnutls_005ftransport_005fset_005fpush_005ffunction">gnutls_transport_set_push_function</a>
 887
 888 </li><li> <a href="#gnutls_005ftransport_005fset_005fpull_005ffunction">gnutls_transport_set_pull_function</a>
 889
 890 </li></ul>
 891
 892 <p>Other callback functions such as the one set by
 893 <a href="#gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffunction">gnutls_srp_set_server_credentials_function</a>, may require more
 894 complicated input, including data to be allocated.  These callbacks
 895 should allocate and free memory using the functions shown below.
 896 </p>
 897 <ul>
 898 <li> <a href="#gnutls_005fmalloc">gnutls_malloc</a>
 899
 900 </li><li> <a href="#gnutls_005ffree">gnutls_free</a>
 901
 902 </li></ul>
 903
 904 <hr>
 905 <a name="Introduction-to-TLS"></a>
 906 <div class="header">
 907 <p>
 908 Next: <a href="#Authentication-methods" accesskey="n" rel="next">Authentication methods</a>, Previous: <a href="#The-Library" accesskey="p" rel="previous">The 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>
 909 </div>
 910 <a name="Introduction-to-TLS-1"></a>
 911 <h2 class="chapter">3 Introduction to <acronym>TLS</acronym></h2>
 912
 913 <p><acronym>TLS</acronym> stands for &ldquo;Transport Layer Security&rdquo; and is the
 914 successor of SSL, the Secure Sockets Layer protocol [SSL3] (see <a href="#Bibliography">Bibliography</a>)
 915 designed by Netscape.  <acronym>TLS</acronym> is an Internet protocol, defined
 916 by <acronym>IETF</acronym><a name="DOCF7" href="#FOOT7">(7)</a>, described in <acronym>RFC</acronym>
 917 4346 and also in [RESCORLA] (see <a href="#Bibliography">Bibliography</a>).  The protocol provides
 918 confidentiality, and authentication layers over any reliable transport
 919 layer.  The description, below, refers to <acronym>TLS</acronym> 1.0 but also
 920 applies to <acronym>TLS</acronym> 1.1 [RFC4346] (see <a href="#Bibliography">Bibliography</a>) and <acronym>SSL</acronym> 3.0,
 921 since the differences of these protocols are minor.  Older protocols
 922 such as <acronym>SSL</acronym> 2.0 are not discussed nor implemented in
 923 <acronym>GnuTLS</acronym> since they are not considered secure today.  GnuTLS
 924 also supports <acronym>X.509</acronym> and <acronym>OpenPGP</acronym> [RFC4880] (see <a href="#Bibliography">Bibliography</a>).
 925 </p>
 926 <table class="menu" border="0" cellspacing="0">
 927 <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">
 928 </td></tr>
 929 <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">
 930 </td></tr>
 931 <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">
 932 </td></tr>
 933 <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">
 934 </td></tr>
 935 <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">
 936 </td></tr>
 937 <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">
 938 </td></tr>
 939 <tr><td align="left" valign="top">&bull; <a href="#Selecting-cryptographic-key-sizes" accesskey="7">Selecting cryptographic key sizes</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 940 </td></tr>
 941 <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">
 942 </td></tr>
 943 </table>
 944
 945 <hr>
 946 <a name="TLS-layers"></a>
 947 <div class="header">
 948 <p>
 949 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>
 950 </div>
 951 <a name="TLS-Layers"></a>
 952 <h3 class="section">3.1 TLS Layers</h3>
 953 <a name="index-TLS-Layers"></a>
 954
 955 <p><acronym>TLS</acronym> is a layered protocol, and consists of the Record
 956 Protocol, the Handshake Protocol and the Alert Protocol. The Record
 957 Protocol is to serve all other protocols and is above the transport
 958 layer.  The Record protocol offers symmetric encryption, data
 959 authenticity, and optionally compression.
 960 </p>
 961 <p>The Alert protocol offers some signaling to the other protocols. It
 962 can help informing the peer for the cause of failures and other error
 963 conditions.  See <a href="#The-Alert-Protocol">The Alert Protocol</a>, for more information.  The
 964 alert protocol is above the record protocol.
 965 </p>
 966 <p>The Handshake protocol is responsible for the security parameters&rsquo;
 967 negotiation, the initial key exchange and authentication.  See <a href="#The-Handshake-Protocol">The
 968 Handshake Protocol</a>, for more information about the handshake
 969 protocol.  The protocol layering in TLS is shown in the figure below.
 970 </p>
 971 <img src="gnutls-layers.png" alt="gnutls-layers">
 972
 973 <hr>
 974 <a name="The-transport-layer"></a>
 975 <div class="header">
 976 <p>
 977 Next: <a href="#The-TLS-record-protocol" accesskey="n" rel="next">The TLS record protocol</a>, Previous: <a href="#TLS-layers" accesskey="p" rel="previous">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>
 978 </div>
 979 <a name="The-Transport-Layer"></a>
 980 <h3 class="section">3.2 The Transport Layer</h3>
 981 <a name="index-Transport-protocol"></a>
 982
 983 <p><acronym>TLS</acronym> is not limited to one transport layer, it can be used
 984 above any transport layer, as long as it is a reliable one.  A set of
 985 functions is provided and their purpose is to load to <acronym>GnuTLS</acronym> the
 986 required callbacks to access the transport layer.
 987 </p>
 988 <ul>
 989 <li> <a href="#gnutls_005ftransport_005fset_005fpush_005ffunction">gnutls_transport_set_push_function</a>
 990 </li><li> <a href="#gnutls_005ftransport_005fset_005fvec_005fpush_005ffunction">gnutls_transport_set_vec_push_function</a>
 991 </li><li> <a href="#gnutls_005ftransport_005fset_005fpull_005ffunction">gnutls_transport_set_pull_function</a>
 992 </li><li> <a href="#gnutls_005ftransport_005fset_005fptr">gnutls_transport_set_ptr</a>
 993 </li><li> <a href="#gnutls_005ftransport_005fset_005flowat">gnutls_transport_set_lowat</a>
 994 </li><li> <a href="#gnutls_005ftransport_005fset_005ferrno">gnutls_transport_set_errno</a>
 995 </li></ul>
 996
 997 <p>These functions accept a callback function as a parameter.  The
 998 callback functions should return the number of bytes written, or -1 on
 999 error and should set <code>errno</code> appropriately.
1000 </p>
1001 <p>In some environments, setting <code>errno</code> is unreliable, for example
1002 Windows have several errno variables in different CRTs, or it may be
1003 that errno is not a thread-local variable.  If this is a concern to
1004 you, call <code>gnutls_transport_set_errno</code> with the intended errno
1005 value instead of setting <code>errno</code> directly.
1006 </p>
1007 <p><acronym>GnuTLS</acronym> currently only interprets the EINTR and EAGAIN errno
1008 values and returns the corresponding <acronym>GnuTLS</acronym> error codes
1009 <code>GNUTLS_E_INTERRUPTED</code> and <code>GNUTLS_E_AGAIN</code>.  These values
1010 are usually returned by interrupted system calls, or when non blocking
1011 IO is used.  All <acronym>GnuTLS</acronym> functions can be resumed (called
1012 again), if any of these error codes is returned.  The error codes
1013 above refer to the system call, not the <acronym>GnuTLS</acronym> function,
1014 since signals do not interrupt <acronym>GnuTLS</acronym>&rsquo; functions.
1015 </p>
1016 <p>For non blocking sockets or other custom made pull/push functions
1017 the <a href="#gnutls_005ftransport_005fset_005flowat">gnutls_transport_set_lowat</a> must be called, with a zero
1018 low water mark value.
1019 </p>
1020 <p>By default, if the transport functions are not set, <acronym>GnuTLS</acronym>
1021 will use the Berkeley Sockets functions.
1022 </p>
1023 <hr>
1024 <a name="The-TLS-record-protocol"></a>
1025 <div class="header">
1026 <p>
1027 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="previous">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>
1028 </div>
1029 <a name="The-TLS-Record-Protocol"></a>
1030 <h3 class="section">3.3 The TLS Record Protocol</h3>
1031 <a name="index-Record-protocol"></a>
1032
1033 <p>The Record protocol is the secure communications provider. Its purpose
1034 is to encrypt, authenticate and &mdash;optionally&mdash; compress packets.
1035 The following functions are available:
1036 </p>
1037 <dl compact="compact">
1038 <dt><a href="#gnutls_005frecord_005fsend">gnutls_record_send</a>:</dt>
1039 <dd><p>To send a record packet (with application data).
1040 </p>
1041 </dd>
1042 <dt><a href="#gnutls_005frecord_005frecv">gnutls_record_recv</a>:</dt>
1043 <dd><p>To receive a record packet (with application data).
1044 </p>
1045 </dd>
1046 <dt><a href="#gnutls_005frecord_005fget_005fdirection">gnutls_record_get_direction</a>:</dt>
1047 <dd><p>To get the direction of the last interrupted function call.
1048 </p></dd>
1049 </dl>
1050
1051 <p>As you may have already noticed, the functions which access the Record
1052 protocol, are quite limited, given the importance of this protocol in
1053 <acronym>TLS</acronym>.  This is because the Record protocol&rsquo;s parameters are
1054 all set by the Handshake protocol.
1055 </p>
1056 <p>The Record protocol initially starts with NULL parameters, which means
1057 no encryption, and no MAC is used. Encryption and authentication begin
1058 just after the handshake protocol has finished.
1059 </p>
1060 <table class="menu" border="0" cellspacing="0">
1061 <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">
1062 </td></tr>
1063 <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">
1064 </td></tr>
1065 <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">
1066 </td></tr>
1067 <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">
1068 </td></tr>
1069 </table>
1070
1071 <hr>
1072 <a name="Encryption-algorithms-used-in-the-record-layer"></a>
1073 <div class="header">
1074 <p>
1075 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>
1076 </div>
1077 <a name="Encryption-Algorithms-Used-in-the-Record-Layer"></a>
1078 <h4 class="subsection">3.3.1 Encryption Algorithms Used in the Record Layer</h4>
1079 <a name="index-Symmetric-encryption-algorithms"></a>
1080
1081 <p>Confidentiality in the record layer is achieved by using symmetric
1082 block encryption algorithms like <code>3DES</code>, <code>AES</code><a name="DOCF8" href="#FOOT8">(8)</a>, or stream algorithms like
1083 <code>ARCFOUR_128</code><a name="DOCF9" href="#FOOT9">(9)</a>. Ciphers are encryption algorithms that use a single, secret,
1084 key to encrypt and decrypt data. Block algorithms in TLS also provide
1085 protection against statistical analysis of the data.  Thus, if you&rsquo;re
1086 using the <acronym>TLS</acronym> protocol, a random number of blocks will be
1087 appended to data, to prevent eavesdroppers from guessing the actual
1088 data size.
1089 </p>
1090 <p>Supported cipher algorithms:
1091 </p>
1092 <dl compact="compact">
1093 <dt><code>3DES_CBC</code></dt>
1094 <dd><p><code>3DES_CBC</code> is the DES block cipher algorithm used with triple
1095 encryption (EDE). Has 64 bits block size and is used in CBC mode.
1096 </p>
1097 </dd>
1098 <dt><code>ARCFOUR_128</code></dt>
1099 <dd><p>ARCFOUR is a fast stream cipher.
1100 </p>
1101 </dd>
1102 <dt><code>ARCFOUR_40</code></dt>
1103 <dd><p>This is the ARCFOUR cipher that is fed with a 40 bit key,
1104 which is considered weak.
1105 </p>
1106 </dd>
1107 <dt><code>AES_CBC</code></dt>
1108 <dd><p>AES or RIJNDAEL is the block cipher algorithm that replaces the old
1109 DES algorithm.  Has 128 bits block size and is used in CBC mode.
1110 </p></dd>
1111 </dl>
1112
1113 <p>Supported MAC algorithms:
1114 </p>
1115 <dl compact="compact">
1116 <dt><code>MAC_MD5</code></dt>
1117 <dd><p>MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs
1118 128 bits of data.
1119 </p>
1120 </dd>
1121 <dt><code>MAC_SHA</code></dt>
1122 <dd><p>SHA is a cryptographic hash algorithm designed by NSA. Outputs 160
1123 bits of data.
1124 </p>
1125 </dd>
1126 </dl>
1127
1128 <hr>
1129 <a name="Compression-algorithms-used-in-the-record-layer"></a>
1130 <div class="header">
1131 <p>
1132 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="previous">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>
1133 </div>
1134 <a name="Compression-Algorithms-Used-in-the-Record-Layer"></a>
1135 <h4 class="subsection">3.3.2 Compression Algorithms Used in the Record Layer</h4>
1136 <a name="index-Compression-algorithms"></a>
1137
1138 <p>The TLS record layer also supports compression.  The algorithms
1139 implemented in <acronym>GnuTLS</acronym> can be found in the table below.
1140 All the algorithms except for DEFLATE which is
1141 referenced in [RFC3749] (see <a href="#Bibliography">Bibliography</a>), should be considered as
1142 <acronym>GnuTLS</acronym>&rsquo; extensions<a name="DOCF10" href="#FOOT10">(10)</a>, and should be advertised only when the peer is known to
1143 have a compliant client, to avoid interoperability problems.
1144 </p>
1145 <p>The included algorithms perform really good when text, or other
1146 compressible data are to be transfered, but offer nothing on already
1147 compressed data, such as compressed images, zipped archives etc.
1148 These compression algorithms, may be useful in high bandwidth TLS
1149 tunnels, and in cases where network usage has to be minimized. As a
1150 drawback, compression increases latency.
1151 </p>
1152 <p>The record layer compression in <acronym>GnuTLS</acronym> is implemented based
1153 on the proposal [RFC3749] (see <a href="#Bibliography">Bibliography</a>).
1154 The supported compression algorithms are:
1155 </p>
1156 <dl compact="compact">
1157 <dt><code>DEFLATE</code></dt>
1158 <dd><p>Zlib compression, using the deflate algorithm.
1159 </p>
1160 </dd>
1161 <dt><code>LZO</code></dt>
1162 <dd><p>LZO is a very fast compression algorithm.  This algorithm is only
1163 available if the <acronym>GnuTLS-extra</acronym> library has been initialized
1164 and the private extensions are enabled, and if GnuTLS was built with
1165 LZO support.
1166 </p>
1167 </dd>
1168 </dl>
1169
1170 <hr>
1171 <a name="Weaknesses-and-countermeasures"></a>
1172 <div class="header">
1173 <p>
1174 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="previous">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>
1175 </div>
1176 <a name="Weaknesses-and-Countermeasures"></a>
1177 <h4 class="subsection">3.3.3 Weaknesses and Countermeasures</h4>
1178
1179 <p>Some weaknesses that may affect the security of the Record layer have
1180 been found in <acronym>TLS</acronym> 1.0 protocol. These weaknesses can be
1181 exploited by active attackers, and exploit the facts that
1182 </p>
1183 <ol>
1184 <li> <acronym>TLS</acronym> has separate alerts for &ldquo;decryption_failed&rdquo; and
1185 &ldquo;bad_record_mac&rdquo;
1186
1187 </li><li> The decryption failure reason can be detected by timing the response
1188 time.
1189
1190 </li><li> The IV for CBC encrypted packets is the last block of the previous
1191 encrypted packet.
1192
1193 </li></ol>
1194
1195 <p>Those weaknesses were solved in <acronym>TLS</acronym> 1.1 [RFC4346] (see <a href="#Bibliography">Bibliography</a>)
1196 which is implemented in <acronym>GnuTLS</acronym>. For a detailed discussion
1197 see the archives of the TLS Working Group mailing list and the paper
1198 [CBCATT] (see <a href="#Bibliography">Bibliography</a>).
1199 </p>
1200 <hr>
1201 <a name="On-Record-Padding"></a>
1202 <div class="header">
1203 <p>
1204 Previous: <a href="#Weaknesses-and-countermeasures" accesskey="p" rel="previous">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>
1205 </div>
1206 <a name="On-Record-Padding-1"></a>
1207 <h4 class="subsection">3.3.4 On Record Padding</h4>
1208 <a name="index-Record-padding"></a>
1209 <a name="index-Bad-record-MAC"></a>
1210
1211 <p>The TLS protocol allows for random padding of records, to make it more
1212 difficult to perform analysis on the length of exchanged messages (RFC 5246 6.2.3.2).
1213 GnuTLS appears to be one of few implementation that take advantage of this text,
1214 and pad records by a random length.
1215 </p>
1216 <p>The TLS implementation in the Symbian operating system, frequently
1217 used by Nokia and Sony-Ericsson mobile phones, cannot handle
1218 non-minimal record padding.  What happens when one of these clients
1219 handshake with a GnuTLS server is that the client will fail to compute
1220 the correct MAC for the record.  The client sends a TLS alert
1221 (<code>bad_record_mac</code>) and disconnects.  Typically this will result
1222 in error messages such as &rsquo;A TLS fatal alert has been received&rsquo;, &rsquo;Bad
1223 record MAC&rsquo;, or both, on the GnuTLS server side.
1224 </p>
1225 <p>GnuTLS implements a work around for this problem.  However, it has to
1226 be enabled specifically.  It can be enabled by using
1227 <a href="#gnutls_005frecord_005fdisable_005fpadding">gnutls_record_disable_padding</a>, or <a href="#gnutls_005fpriority_005fset">gnutls_priority_set</a> with
1228 the <code>%COMPAT</code> priority string.
1229 </p>
1230 <p>If you implement an application that have a configuration file, we
1231 recommend that you make it possible for users or administrators to
1232 specify a GnuTLS protocol priority string, which is used by your
1233 application via <a href="#gnutls_005fpriority_005fset">gnutls_priority_set</a>.  To allow the best
1234 flexibility, make it possible to have a different priority string for
1235 different incoming IP addresses.
1236 </p>
1237 <p>To enable the workaround in the <code>gnutls-cli</code> client or the
1238 <code>gnutls-serv</code> server, for testing of other implementations, use
1239 the following parameter: <code>--priority &quot;NORMAL:%COMPAT&quot;</code>.
1240 </p>
1241
1242 <hr>
1243 <a name="The-TLS-Alert-Protocol"></a>
1244 <div class="header">
1245 <p>
1246 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="previous">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>
1247 </div>
1248 <a name="The-TLS-Alert-Protocol-1"></a>
1249 <h3 class="section">3.4 The TLS Alert Protocol</h3>
1250 <a name="The-Alert-Protocol"></a><a name="index-Alert-protocol"></a>
1251
1252 <p>The Alert protocol is there to allow signals to be sent between peers.
1253 These signals are mostly used to inform the peer about the cause of a
1254 protocol failure. Some of these signals are used internally by the
1255 protocol and the application protocol does not have to cope with them
1256 (see <code>GNUTLS_A_CLOSE_NOTIFY</code>), and others refer to the
1257 application protocol solely (see <code>GNUTLS_A_USER_CANCELLED</code>).  An
1258 alert signal includes a level indication which may be either fatal or
1259 warning. Fatal alerts always terminate the current connection, and
1260 prevent future renegotiations using the current session ID.
1261 </p>
1262 <p>The alert messages are protected by the record protocol, thus the
1263 information that is included does not leak. You must take extreme care
1264 for the alert information not to leak to a possible attacker, via
1265 public log files etc.
1266 </p>
1267 <dl compact="compact">
1268 <dt><a href="#gnutls_005falert_005fsend">gnutls_alert_send</a>:</dt>
1269 <dd><p>To send an alert signal.
1270 </p>
1271 </dd>
1272 <dt><a href="#gnutls_005ferror_005fto_005falert">gnutls_error_to_alert</a>:</dt>
1273 <dd><p>To map a gnutls error number to an alert signal.
1274 </p>
1275 </dd>
1276 <dt><a href="#gnutls_005falert_005fget">gnutls_alert_get</a>:</dt>
1277 <dd><p>Returns the last received alert.
1278 </p>
1279 </dd>
1280 <dt><a href="#gnutls_005falert_005fget_005fname">gnutls_alert_get_name</a>:</dt>
1281 <dd><p>Returns the name, in a character array, of the given alert.
1282 </p>
1283 </dd>
1284 </dl>
1285
1286 <hr>
1287 <a name="The-TLS-Handshake-Protocol"></a>
1288 <div class="header">
1289 <p>
1290 Next: <a href="#TLS-Extensions" accesskey="n" rel="next">TLS Extensions</a>, Previous: <a href="#The-TLS-Alert-Protocol" accesskey="p" rel="previous">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>
1291 </div>
1292 <a name="The-TLS-Handshake-Protocol-1"></a>
1293 <h3 class="section">3.5 The TLS Handshake Protocol</h3>
1294 <a name="The-Handshake-Protocol"></a><a name="index-Handshake-protocol"></a>
1295
1296 <p>The Handshake protocol is responsible for the ciphersuite negotiation,
1297 the initial key exchange, and the authentication of the two peers.
1298 This is fully controlled by the application layer, thus your program
1299 has to set up the required parameters. Available functions to control
1300 the handshake protocol include:
1301 </p>
1302 <dl compact="compact">
1303 <dt><a href="#gnutls_005fpriority_005finit">gnutls_priority_init</a>:</dt>
1304 <dd><p>To initialize a priority set of ciphers.
1305 </p>
1306 </dd>
1307 <dt><a href="#gnutls_005fpriority_005fdeinit">gnutls_priority_deinit</a>:</dt>
1308 <dd><p>To deinitialize a priority set of ciphers.
1309 </p>
1310 </dd>
1311 <dt><a href="#gnutls_005fpriority_005fset">gnutls_priority_set</a>:</dt>
1312 <dd><p>To associate a priority set with a <acronym>TLS</acronym> session.
1313 </p>
1314 </dd>
1315 <dt><a href="#gnutls_005fpriority_005fset_005fdirect">gnutls_priority_set_direct</a>:</dt>
1316 <dd><p>To directly associate a session with a given priority string.
1317 </p>
1318 </dd>
1319 <dt><a href="#gnutls_005fcredentials_005fset">gnutls_credentials_set</a>:</dt>
1320 <dd><p>To set the appropriate credentials structures.
1321 </p>
1322 </dd>
1323 <dt><a href="#gnutls_005fcertificate_005fserver_005fset_005frequest">gnutls_certificate_server_set_request</a>:</dt>
1324 <dd><p>To set whether client certificate is required or not.
1325 </p>
1326 </dd>
1327 <dt><a href="#gnutls_005fhandshake">gnutls_handshake</a>:</dt>
1328 <dd><p>To initiate the handshake.
1329 </p></dd>
1330 </dl>
1331
1332 <table class="menu" border="0" cellspacing="0">
1333 <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.
1334 </td></tr>
1335 <tr><td align="left" valign="top">&bull; <a href="#Priority-Strings" accesskey="2">Priority Strings</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Defining how parameters are negotiated.
1336 </td></tr>
1337 <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.
1338 </td></tr>
1339 <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.
1340 </td></tr>
1341 <tr><td align="left" valign="top">&bull; <a href="#Resuming-Internals" accesskey="5">Resuming Internals</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">More information on reusing previously established keys.
1342 </td></tr>
1343 <tr><td align="left" valign="top">&bull; <a href="#Interoperability" accesskey="6">Interoperability</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">About interoperability with other implementations.
1344 </td></tr>
1345 </table>
1346
1347 <hr>
1348 <a name="TLS-Cipher-Suites"></a>
1349 <div class="header">
1350 <p>
1351 Next: <a href="#Priority-Strings" accesskey="n" rel="next">Priority Strings</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>
1352 </div>
1353 <a name="TLS-Cipher-Suites-1"></a>
1354 <h4 class="subsection">3.5.1 TLS Cipher Suites</h4>
1355
1356 <p>The Handshake Protocol of <acronym>TLS</acronym> negotiates cipher suites of
1357 the form <code>TLS_DHE_RSA_WITH_3DES_CBC_SHA</code>.  The usual cipher
1358 suites contain these parameters:
1359 </p>
1360 <ul>
1361 <li> The key exchange algorithm.
1362 <code>DHE_RSA</code> in the example.
1363
1364 </li><li> The Symmetric encryption algorithm and mode
1365 <code>3DES_CBC</code> in this example.
1366
1367 </li><li> The MAC<a name="DOCF11" href="#FOOT11">(11)</a> algorithm used for authentication.
1368 <code>MAC_SHA</code> is used in the above example.
1369
1370 </li></ul>
1371
1372 <p>The cipher suite negotiated in the handshake protocol will affect the
1373 Record Protocol, by enabling encryption and data authentication.  Note
1374 that you should not over rely on <acronym>TLS</acronym> to negotiate the
1375 strongest available cipher suite. Do not enable ciphers and algorithms
1376 that you consider weak.
1377 </p>
1378 <p>All the supported ciphersuites are shown in <a href="#ciphersuites">ciphersuites</a>.
1379 </p>
1380 <hr>
1381 <a name="Priority-Strings"></a>
1382 <div class="header">
1383 <p>
1384 Next: <a href="#Client-Authentication" accesskey="n" rel="next">Client Authentication</a>, Previous: <a href="#TLS-Cipher-Suites" accesskey="p" rel="previous">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>
1385 </div>
1386 <a name="Priority-Strings-1"></a>
1387 <h4 class="subsection">3.5.2 Priority Strings</h4>
1388
1389 <p>In order to specify cipher suite preferences, the
1390 previously shown priority functions accept a string
1391 that specifies the algorithms to be enabled in a TLS handshake.
1392 That string may contain some high level keyword such as:
1393 </p>
1394 <dl compact="compact">
1395 <dt>PERFORMANCE:</dt>
1396 <dd><p>All the &quot;secure&quot; ciphersuites are enabled,
1397 limited to 128 bit ciphers and sorted by terms of speed
1398 performance.
1399 </p>
1400 </dd>
1401 <dt>NORMAL:</dt>
1402 <dd><p>Means all &quot;secure&quot; ciphersuites. The 256-bit ciphers are
1403 included as a fallback only.  The ciphers are sorted by security
1404 margin.
1405 </p>
1406 </dd>
1407 <dt>SECURE128:</dt>
1408 <dd><p>Means all &quot;secure&quot; ciphersuites with ciphers up to 128
1409 bits, sorted by security margin.
1410 </p>
1411 </dd>
1412 <dt>SECURE256:</dt>
1413 <dd><p>Means all &quot;secure&quot; ciphersuites including the 256 bit
1414 ciphers, sorted by security margin.
1415 </p>
1416 </dd>
1417 <dt>EXPORT:</dt>
1418 <dd><p>Means all ciphersuites are enabled, including the
1419 low-security 40 bit ciphers.
1420 </p>
1421 </dd>
1422 <dt>NONE:</dt>
1423 <dd><p>Means nothing is enabled.  This disables even protocols and
1424 compression methods. It should be followed by the
1425 algorithms to be enabled.
1426 </p>
1427 </dd>
1428 </dl>
1429
1430 <p>or it might contain special keywords, that will be explained
1431 later on.
1432 </p>
1433 <p>Unless the first keyword is &quot;NONE&quot; the defaults (in preference
1434 order) are for TLS protocols TLS 1.2, TLS1.1, TLS1.0, SSL3.0; for
1435 compression NULL; for certificate types X.509, OpenPGP.
1436 For key exchange algorithms when in NORMAL or SECURE levels the
1437 perfect forward secrecy algorithms take precedence of the other
1438 protocols.  In all cases all the supported key exchange algorithms
1439  are enabled (except for the RSA-EXPORT which is only enabled in
1440 EXPORT level).
1441 </p>
1442 <p>The NONE keyword is followed by the algorithms to be enabled,
1443 and is used to provide the exact list of requested algorithms<a name="DOCF12" href="#FOOT12">(12)</a>. The order with which every algorithm
1444 is specified is significant. Similar algorithms specified before others
1445 will take precedence.
1446 </p>
1447 <p>Keywords prepended to individual algorithms:
1448 </p><dl compact="compact">
1449 <dt>&rsquo;!&rsquo; or &rsquo;-&rsquo;</dt>
1450 <dd><p>appended with an algorithm will remove this algorithm.
1451 </p>
1452 </dd>
1453 <dt>&quot;+&quot;</dt>
1454 <dd><p>appended with an algorithm will add this algorithm.
1455 </p>
1456 </dd>
1457 </dl>
1458
1459 <p>Individual algorithms:
1460 </p><dl compact="compact">
1461 <dt>Ciphers:</dt>
1462 <dd><p>AES-128-CBC, AES-256-CBC, CAMELLIA-128-CBC,
1463 CAMELLIA-256-CBC, ARCFOUR-128, 3DES-CBC ARCFOUR-40. Catch all
1464 name is CIPHER-ALL which will add all the algorithms from NORMAL
1465 priority.
1466 </p>
1467 </dd>
1468 <dt>Key exchange:</dt>
1469 <dd><p>RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS,
1470 PSK, DHE-PSK, ANON-DH, RSA-EXPORT. The
1471 key exchange methods do not have a catch all.
1472 </p>
1473 </dd>
1474 <dt>MAC:</dt>
1475 <dd><p>MD5, SHA1, SHA256. All algorithms from NORMAL priority can be accessed with MAC-ALL.
1476 </p>
1477 </dd>
1478 <dt>Compression algorithms:</dt>
1479 <dd><p>COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.
1480 </p>
1481 </dd>
1482 <dt>TLS versions:</dt>
1483 <dd><p>VERS-SSL3.0, VERS-TLS1.0, VERS-TLS1.1,
1484 VERS-TLS1.2. Catch all is VERS-TLS-ALL.
1485 </p>
1486 </dd>
1487 <dt>Signature algorithms:</dt>
1488 <dd><p>SIGN-RSA-SHA1, SIGN-RSA-SHA224,
1489 SIGN-RSA-SHA256, SIGN-RSA-SHA384, SIGN-RSA-SHA512, SIGN-DSA-SHA1,
1490 SIGN-DSA-SHA224, SIGN-DSA-SHA256, SIGN-RSA-MD5. Catch all
1491 is SIGN-ALL. This is only valid for TLS 1.2 and later.
1492 </p>
1493 </dd>
1494 </dl>
1495
1496
1497 <p>Special keywords:
1498 </p><dl compact="compact">
1499 <dt>%COMPAT:</dt>
1500 <dd><p>will enable compatibility mode. It might mean that violations
1501 of the protocols are allowed as long as maximum compatibility with
1502 problematic clients and servers is achieved.
1503 </p>
1504 </dd>
1505 <dt>%DISABLE_SAFE_RENEGOTIATION:</dt>
1506 <dd><p>will disable safe renegotiation
1507 completely.  Do not use unless you know what you are doing.
1508 Testing purposes only.
1509 </p>
1510 </dd>
1511 <dt>%UNSAFE_RENEGOTIATION:</dt>
1512 <dd><p>will allow handshakes and rehandshakes
1513 without the safe renegotiation extension.  Note that for clients
1514 this mode is insecure (you may be under attack), and for servers it
1515 will allow insecure clients to connect (which could be fooled by an
1516 attacker).  Do not use unless you know what you are doing and want
1517 maximum compatibility.
1518 </p>
1519 </dd>
1520 <dt>%PARTIAL_RENEGOTIATION:</dt>
1521 <dd><p>will allow initial handshakes to proceed,
1522 but not rehandshakes.  This leaves the client vulnerable to attack,
1523 and servers will be compatible with non-upgraded clients for
1524 initial handshakes.  This is currently the default for clients and
1525 servers, for compatibility reasons.
1526 </p>
1527 </dd>
1528 <dt>%SAFE_RENEGOTIATION:</dt>
1529 <dd><p>will enforce safe renegotiation.  Clients and
1530 servers will refuse to talk to an insecure peer.  Currently this
1531 causes operability problems, but is required for full protection.
1532 </p>
1533 </dd>
1534 <dt>%SSL3_RECORD_VERSION:</dt>
1535 <dd><p>will use SSL3.0 record version in client hello.
1536 This is the default.
1537 </p>
1538 </dd>
1539 <dt>%LATEST_RECORD_VERSION:</dt>
1540 <dd><p>will use the latest TLS version record version in client hello.
1541 </p>
1542 </dd>
1543 <dt>%VERIFY_ALLOW_SIGN_RSA_MD5:</dt>
1544 <dd><p>will allow RSA-MD5 signatures in certificate chains.
1545 </p>
1546 </dd>
1547 <dt>%VERIFY_ALLOW_X509_V1_CA_CRT:</dt>
1548 <dd><p>will allow V1 CAs in chains.
1549 </p>
1550 </dd>
1551 </dl>
1552
1553 <hr>
1554 <a name="Client-Authentication"></a>
1555 <div class="header">
1556 <p>
1557 Next: <a href="#Resuming-Sessions" accesskey="n" rel="next">Resuming Sessions</a>, Previous: <a href="#Priority-Strings" accesskey="p" rel="previous">Priority Strings</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>
1558 </div>
1559 <a name="Client-Authentication-1"></a>
1560 <h4 class="subsection">3.5.3 Client Authentication</h4>
1561 <a name="index-Client-Certificate-authentication"></a>
1562
1563 <p>In the case of ciphersuites that use certificate authentication, the
1564 authentication of the client is optional in <acronym>TLS</acronym>.  A server
1565 may request a certificate from the client &mdash; using the
1566 <a href="#gnutls_005fcertificate_005fserver_005fset_005frequest">gnutls_certificate_server_set_request</a> function. If a certificate
1567 is to be requested from the client during the handshake, the server
1568 will send a certificate request message that contains a list of
1569 acceptable certificate signers. In <acronym>GnuTLS</acronym> the certificate
1570 signers list is constructed using the trusted Certificate Authorities
1571 by the server. That is the ones set using
1572 </p><ul>
1573 <li> <a href="#gnutls_005fcertificate_005fset_005fx509_005ftrust_005ffile">gnutls_certificate_set_x509_trust_file</a>
1574 </li><li> <a href="#gnutls_005fcertificate_005fset_005fx509_005ftrust_005fmem">gnutls_certificate_set_x509_trust_mem</a>
1575 </li></ul>
1576
1577 <p>Sending of the names of the CAs can be controlled using
1578 <a href="#gnutls_005fcertificate_005fsend_005fx509_005frdn_005fsequence">gnutls_certificate_send_x509_rdn_sequence</a>. The client, then, may
1579 send a certificate, signed by one of the server&rsquo;s acceptable signers.
1580 </p>
1581 <hr>
1582 <a name="Resuming-Sessions"></a>
1583 <div class="header">
1584 <p>
1585 Next: <a href="#Resuming-Internals" accesskey="n" rel="next">Resuming Internals</a>, Previous: <a href="#Client-Authentication" accesskey="p" rel="previous">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>
1586 </div>
1587 <a name="Resuming-Sessions-1"></a>
1588 <h4 class="subsection">3.5.4 Resuming Sessions</h4>
1589 <a name="resume"></a><a name="index-Resuming-sessions"></a>
1590
1591 <p>The <a href="#gnutls_005fhandshake">gnutls_handshake</a> function, is expensive since a lot of
1592 calculations are performed. In order to support many fast connections
1593 to the same server a client may use session resuming. <strong>Session
1594 resuming</strong> is a feature of the <acronym>TLS</acronym> protocol which allows a
1595 client to connect to a server, after a successful handshake, without
1596 the expensive calculations.  This is achieved by using the previously
1597 established keys. <acronym>GnuTLS</acronym> supports this feature, and the
1598 example (see <a href="#ex_003aresume_002dclient">ex:resume-client</a>) illustrates a typical use of it.
1599 </p>
1600 <p>Keep in mind that sessions are expired after some time, for security
1601 reasons, thus it may be normal for a server not to resume a session
1602 even if you requested that.  Also note that you must enable, using the
1603 priority functions, at least the algorithms used in the last session.
1604 </p>
1605 <hr>
1606 <a name="Resuming-Internals"></a>
1607 <div class="header">
1608 <p>
1609 Next: <a href="#Interoperability" accesskey="n" rel="next">Interoperability</a>, Previous: <a href="#Resuming-Sessions" accesskey="p" rel="previous">Resuming Sessions</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>
1610 </div>
1611 <a name="Resuming-Internals-1"></a>
1612 <h4 class="subsection">3.5.5 Resuming Internals</h4>
1613
1614 <p>The resuming capability, mostly in the server side, is one of the
1615 problems of a thread-safe TLS implementations. The problem is that all
1616 threads must share information in order to be able to resume
1617 sessions. The gnutls approach is, in case of a client, to leave all
1618 the burden of resuming to the client. I.e., copy and keep the
1619 necessary parameters. See the functions:
1620 </p>
1621 <ul>
1622 <li> <a href="#gnutls_005fsession_005fget_005fdata">gnutls_session_get_data</a>
1623
1624 </li><li> <a href="#gnutls_005fsession_005fget_005fid">gnutls_session_get_id</a>
1625
1626 </li><li> <a href="#gnutls_005fsession_005fset_005fdata">gnutls_session_set_data</a>
1627
1628 </li></ul>
1629
1630 <p>The server side is different. A server has to specify some callback
1631 functions which store, retrieve and delete session data. These can be
1632 registered with:
1633 </p>
1634 <ul>
1635 <li> <a href="#gnutls_005fdb_005fset_005fremove_005ffunction">gnutls_db_set_remove_function</a>
1636
1637 </li><li> <a href="#gnutls_005fdb_005fset_005fstore_005ffunction">gnutls_db_set_store_function</a>
1638
1639 </li><li> <a href="#gnutls_005fdb_005fset_005fretrieve_005ffunction">gnutls_db_set_retrieve_function</a>
1640
1641 </li><li> <a href="#gnutls_005fdb_005fset_005fptr">gnutls_db_set_ptr</a>
1642
1643 </li></ul>
1644
1645 <p>It might also be useful to be able to check for expired sessions in
1646 order to remove them, and save space. The function
1647 <a href="#gnutls_005fdb_005fcheck_005fentry">gnutls_db_check_entry</a> is provided for that reason.
1648 </p>
1649 <hr>
1650 <a name="Interoperability"></a>
1651 <div class="header">
1652 <p>
1653 Previous: <a href="#Resuming-Internals" accesskey="p" rel="previous">Resuming Internals</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>
1654 </div>
1655 <a name="Interoperability-1"></a>
1656 <h4 class="subsection">3.5.6 Interoperability</h4>
1657
1658 <p>The <acronym>TLS</acronym> handshake is a complex procedure that negotiates all
1659 required parameters for a secure session. <acronym>GnuTLS</acronym> supports
1660 several <acronym>TLS</acronym> extensions, as well as the latest <acronym>TLS</acronym> protocol
1661 version 1.2. However few implementations are not able to
1662 properly interoperate once faced with extensions or version protocols
1663 they do not support and understand. The <acronym>TLS</acronym> protocol allows for a
1664 graceful downgrade to the commonly supported options, but practice shows
1665 it is not always implemented correctly.
1666 </p>
1667 <p>Because there is no way to achieve maximum interoperability with broken peers
1668 without sacrificing security, <acronym>GnuTLS</acronym> ignores such peers by default.
1669 This might not be acceptable in cases where maximum compatibility
1670 is required. Thus we allow enabling compatibility with broken peers using
1671 priority strings (see <a href="#Priority-Strings">Priority Strings</a>). An example priority string that
1672 is known to provide wide compatibility even with broken peers
1673 is shown below:
1674 </p><div class="example">
1675 <pre class="example">NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:%COMPAT
1676 </pre></div>
1677 <p>This priority string will only enable SSL 3.0 and TLS 1.0 as protocols and
1678 will disable, via the <code>%COMPAT</code> keyword, several <acronym>TLS</acronym> protocol
1679 options that are known to cause compatibility problems.
1680 We suggest however only to use this mode if compatibility issues occur.
1681 </p>
1682 <hr>
1683 <a name="TLS-Extensions"></a>
1684 <div class="header">
1685 <p>
1686 Next: <a href="#Selecting-cryptographic-key-sizes" accesskey="n" rel="next">Selecting cryptographic key sizes</a>, Previous: <a href="#The-TLS-Handshake-Protocol" accesskey="p" rel="previous">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>
1687 </div>
1688 <a name="TLS-Extensions-1"></a>
1689 <h3 class="section">3.6 TLS Extensions</h3>
1690 <a name="index-TLS-Extensions"></a>
1691
1692 <p>A number of extensions to the <acronym>TLS</acronym> protocol have been
1693 proposed mainly in [TLSEXT] (see <a href="#Bibliography">Bibliography</a>). The extensions supported
1694 in <acronym>GnuTLS</acronym> are:
1695 </p>
1696 <ul>
1697 <li> Maximum fragment length negotiation
1698 </li><li> Server name indication
1699 </li><li> Session tickets
1700 </li><li> Safe Renegotiation
1701 </li></ul>
1702
1703 <p>and they will be discussed in the subsections that follow.
1704 </p>
1705 <a name="Maximum-Fragment-Length-Negotiation"></a>
1706 <h4 class="subsection">3.6.1 Maximum Fragment Length Negotiation</h4>
1707 <a name="index-TLS-Extensions-1"></a>
1708 <a name="index-Maximum-fragment-length"></a>
1709
1710 <p>This extension allows a <acronym>TLS</acronym> implementation to negotiate a
1711 smaller value for record packet maximum length. This extension may be
1712 useful to clients with constrained capabilities. See the
1713 <a href="#gnutls_005frecord_005fset_005fmax_005fsize">gnutls_record_set_max_size</a> and the
1714 <a href="#gnutls_005frecord_005fget_005fmax_005fsize">gnutls_record_get_max_size</a> functions.
1715 </p>
1716 <a name="Server-Name-Indication"></a>
1717 <h4 class="subsection">3.6.2 Server Name Indication</h4>
1718 <a name="serverind"></a><a name="index-TLS-Extensions-2"></a>
1719 <a name="index-Server-name-indication"></a>
1720
1721 <p>A common problem in <acronym>HTTPS</acronym> servers is the fact that the
1722 <acronym>TLS</acronym> protocol is not aware of the hostname that a client
1723 connects to, when the handshake procedure begins. For that reason the
1724 <acronym>TLS</acronym> server has no way to know which certificate to send.
1725 </p>
1726 <p>This extension solves that problem within the <acronym>TLS</acronym> protocol,
1727 and allows a client to send the HTTP hostname before the handshake
1728 begins within the first handshake packet.  The functions
1729 <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
1730 used to enable this extension, or to retrieve the name sent by a
1731 client.
1732 </p>
1733 <a name="Session-Tickets"></a>
1734 <h4 class="subsection">3.6.3 Session Tickets</h4>
1735 <a name="index-TLS-Extensions-3"></a>
1736 <a name="index-Session-Tickets"></a>
1737 <a name="index-Ticket"></a>
1738
1739 <p>To resume a TLS session the server normally store some state.  This
1740 complicates deployment, and typical situations the client can cache
1741 information and send it to the server instead.  The Session Ticket
1742 extension implements this idea, and it is documented in
1743 RFC 5077 [TLSTKT] (see <a href="#Bibliography">Bibliography</a>).
1744 </p>
1745 <p>Clients can enable support for TLS tickets with
1746 <a href="#gnutls_005fsession_005fticket_005fenable_005fclient">gnutls_session_ticket_enable_client</a> and servers use
1747 <a href="#gnutls_005fsession_005fticket_005fkey_005fgenerate">gnutls_session_ticket_key_generate</a> to generate a key and
1748 <a href="#gnutls_005fsession_005fticket_005fenable_005fserver">gnutls_session_ticket_enable_server</a> to enable the extension.
1749 Clients resume sessions using the ticket using the normal session
1750 resume functions, <a href="#resume">resume</a>.
1751 </p>
1752 <a name="Safe-Renegotiation"></a>
1753 <h4 class="subsection">3.6.4 Safe Renegotiation</h4>
1754 <a name="index-renegotiation"></a>
1755
1756 <p>TLS gives the option to two communicating parties to renegotiate
1757 and update their security parameters. One useful example of this feature
1758 was for a client to initially connect using anonymous negotiation to a
1759 server, and the renegotiate using some authenticated ciphersuite. This occured
1760 to avoid having the client sending its credentials in the clear.
1761 </p>
1762 <p>However this renegotiation, as initially designed would not ensure that
1763 the party one is renegotiating is the same as the one in the initial negotiation.
1764 For example one server could forward all renegotiation traffic to an other
1765 server who will see this traffic as an initial negotiation attempt.
1766 </p>
1767 <p>This might be seen as a valid design decision, but it seems it was
1768 not widely known or understood, thus today some application protocols the TLS
1769 renegotiation feature in a manner that enables a malicious server to insert
1770 content of his choice in the beginning of a TLS session.
1771 </p>
1772 <p>The most prominent vulnerability was with HTTPS. There servers request
1773 a renegotiation to enforce an anonymous user to use a certificate in order
1774 to access certain parts of a web site.  The
1775 attack works by having the attacker simulate a client and connect to a
1776 server, with server-only authentication, and send some data intended
1777 to cause harm.  The server will then require renegotiation from him
1778 in order to perform the request.
1779 When the proper client attempts to contact the server,
1780 the attacker hijacks that connection and forwards traffic to
1781 the initial server that requested renegotiation.  The
1782 attacker will not be able to read the data exchanged between the
1783 client and the server.  However, the server will (incorrectly) assume
1784 that the initial request sent by the attacker was sent by the now authenticated
1785 client.  The result is a prefix plain-text injection attack.
1786 </p>
1787 <p>The above is just one example.  Other vulnerabilities exists that do
1788 not rely on the TLS renegotiation to change the client&rsquo;s authenticated
1789 status (either TLS or application layer).
1790 </p>
1791 <p>While fixing these application protocols and implementations would be
1792 one natural reaction, an extension to TLS has been designed that
1793 cryptographically binds together any renegotiated handshakes with the
1794 initial negotiation.  When the extension is used, the attack is
1795 detected and the session can be terminated.  The extension is
1796 specified in [RFC5746] (see <a href="#Bibliography">Bibliography</a>).
1797 </p>
1798 <p>GnuTLS supports the safe renegotiation extension.  The default
1799 behavior is as follows.  Clients will attempt to negotiate the safe
1800 renegotiation extension when talking to servers.  Servers will accept
1801 the extension when presented by clients.  Clients and servers will
1802 permit an initial handshake to complete even when the other side does
1803 not support the safe renegotiation extension.  Clients and servers
1804 will refuse renegotiation attempts when the extension has not been
1805 negotiated.
1806 </p>
1807 <p>Note that permitting clients to connect to servers when the safe
1808 renegotiation extension is not enabled, is open up for attacks.
1809 Changing this default behaviour would prevent interoperability against
1810 the majority of deployed servers out there.  We will reconsider this
1811 default behaviour in the future when more servers have been upgraded.
1812 Note that it is easy to configure clients to always require the safe
1813 renegotiation extension from servers (see below on the
1814 <code>%SAFE_RENEGOTIATION</code> priority string).
1815 </p>
1816 <p>To modify the default behaviour, we have introduced some new priority
1817 strings.  The priority strings can be used by applications
1818 (see <a href="#gnutls_005fpriority_005fset">gnutls_priority_set</a>) and end users (e.g., <code>--priority</code>
1819 parameter to <code>gnutls-cli</code> and <code>gnutls-serv</code>).
1820 </p>
1821 <p>The <code>%UNSAFE_RENEGOTIATION</code> priority string permits
1822 (re-)handshakes even when the safe renegotiation extension was not
1823 negotiated. The default behavior is <code>%PARTIAL_RENEGOTIATION</code> that will
1824 prevent renegotiation with clients and servers not supporting the
1825 extension. This is secure for servers but leaves clients vulnerable
1826 to some attacks, but this is a tradeoff between security and compatibility
1827 with old servers. The <code>%SAFE_RENEGOTIATION</code> priority string makes
1828 clients and servers require the extension for every handshake. The latter
1829 is the most secure option for clients, at the cost of not being able
1830 to connect to legacy servers. Servers will also deny clients that
1831 do not support the extension from connecting.
1832 </p>
1833 <p>It is possible to disable use of the extension completely, in both
1834 clients and servers, by using the <code>%DISABLE_SAFE_RENEGOTIATION</code>
1835 priority string however we strongly recommend you to only do this for
1836 debugging and test purposes.
1837 </p>
1838 <p>The default values if the flags above are not specified are:
1839 </p><dl compact="compact">
1840 <dt><code>Server:</code></dt>
1841 <dd><p>%PARTIAL_RENEGOTIATION
1842 </p>
1843 </dd>
1844 <dt><code>Client:</code></dt>
1845 <dd><p>%PARTIAL_RENEGOTIATION
1846 </p>
1847 </dd>
1848 </dl>
1849
1850 <p>For applications we have introduced a new API related to safe
1851 renegotiation.  The <a href="#gnutls_005fsafe_005frenegotiation_005fstatus">gnutls_safe_renegotiation_status</a> function is
1852 used to check if the extension has been negotiated on a session, and
1853 can be used both by clients and servers.
1854 </p>
1855 <hr>
1856 <a name="Selecting-cryptographic-key-sizes"></a>
1857 <div class="header">
1858 <p>
1859 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="previous">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>
1860 </div>
1861 <a name="Selecting-Cryptographic-Key-Sizes"></a>
1862 <h3 class="section">3.7 Selecting Cryptographic Key Sizes</h3>
1863 <a name="index-key-sizes"></a>
1864
1865 <p>In TLS, since a lot of algorithms are involved, it is not easy to set
1866 a consistent security level.  For this reason this section will
1867 present some correspondance between key sizes of symmetric algorithms
1868 and public key algorithms based on the &ldquo;ECRYPT II Yearly Report on Algorithms and Keysizes (2009-2010)&rdquo;
1869 in [ECRYPT] (see <a href="#Bibliography">Bibliography</a>).  Those can be used to generate certificates with
1870 appropriate key sizes as well as parameters for Diffie-Hellman and SRP
1871 authentication.
1872 </p>
1873 <table>
1874 <tr><td width="10%">Security bits</td><td width="15%">RSA, DH and SRP parameter size</td><td width="10%">ECC key size</td><td width="20%"><code>gnutls_sec_param_t</code></td><td width="35%">Description</td></tr>
1875 <tr><td width="10%">64</td><td width="15%">816</td><td width="10%">128</td><td width="20%"><code>WEAK</code></td><td width="35%">Very short term protection against small organizations</td></tr>
1876 <tr><td width="10%">80</td><td width="15%">1248</td><td width="10%">160</td><td width="20%"><code>LOW</code></td><td width="35%">Very short term protection against agencies</td></tr>
1877 <tr><td width="10%">112</td><td width="15%">2432</td><td width="10%">224</td><td width="20%"><code>NORMAL</code></td><td width="35%">Medium-term protection</td></tr>
1878 <tr><td width="10%">128</td><td width="15%">3248</td><td width="10%">256</td><td width="20%"><code>HIGH</code></td><td width="35%">Long term protection</td></tr>
1879 <tr><td width="10%">256</td><td width="15%">15424</td><td width="10%">512</td><td width="20%"><code>ULTRA</code></td><td width="35%">Foreseeable future</td></tr>
1880 </table>
1881
1882 <p>The first column provides a security parameter in a number of bits. This
1883 gives an indication of the number of combinations to be tried by an adversary
1884 to brute force a key. For example to test all possible keys in a 112 bit security parameter
1885 <em>2^{112}</em> combinations have to be tried. For today&rsquo;s technology this is infeasible.
1886 The next two columns correlate the security
1887 parameter with actual bit sizes of parameters for DH, RSA, SRP and ECC algorithms.
1888 A mapping to <code>gnutls_sec_param_t</code> value is given for each security parameter, on
1889 the next column, and finally a brief description of the level.
1890 </p>
1891 <p>Note however that the values suggested here are nothing more than an
1892 educated guess that is valid today. There are no guarrantees that an
1893 algorithm will remain unbreakable or that these values will remain
1894 constant in time. There could be scientific breakthroughs that cannot
1895 be predicted or total failure of the current public key systems by
1896 quantum computers. On the other hand though the cryptosystems used in
1897 TLS are selected in a conservative way and such catastrophic
1898 breakthroughs or failures are believed to be unlikely.
1899 </p>
1900 <p>NIST publication SP 800-57 [NISTSP80057] (see <a href="#Bibliography">Bibliography</a>) contains a similar
1901 table.
1902 </p>
1903 <p>When using <acronym>GnuTLS</acronym> and a decision on bit sizes for a public
1904 key algorithm is required, use of the following functions is
1905 recommended:
1906 </p><ul>
1907 <li> <a href="#gnutls_005fpk_005fbits_005fto_005fsec_005fparam">gnutls_pk_bits_to_sec_param</a>
1908
1909 </li><li> <a href="#gnutls_005fsec_005fparam_005fto_005fpk_005fbits">gnutls_sec_param_to_pk_bits</a>
1910
1911 </li></ul>
1912 <p>Those functions will convert a human understandable security parameter
1913 of <code>gnutls_sec_param_t</code> type, to a number of bits suitable for a public
1914 key algorithm.
1915 </p>
1916 <hr>
1917 <a name="On-SSL-2-and-older-protocols"></a>
1918 <div class="header">
1919 <p>
1920 Previous: <a href="#Selecting-cryptographic-key-sizes" accesskey="p" rel="previous">Selecting cryptographic key sizes</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>
1921 </div>
1922 <a name="On-SSL-2-and-Older-Protocols"></a>
1923 <h3 class="section">3.8 On SSL 2 and Older Protocols</h3>
1924 <a name="index-SSL-2"></a>
1925
1926 <p>One of the initial decisions in the <acronym>GnuTLS</acronym> development was
1927 to implement the known security protocols for the transport layer.
1928 Initially <acronym>TLS</acronym> 1.0 was implemented since it was the latest at
1929 that time, and was considered to be the most advanced in security
1930 properties.  Later the <acronym>SSL</acronym> 3.0 protocol was implemented
1931 since it is still the only protocol supported by several servers and
1932 there are no serious security vulnerabilities known.
1933 </p>
1934 <p>One question that may arise is why we didn&rsquo;t implement <acronym>SSL</acronym>
1935 2.0 in the library.  There are several reasons, most important being
1936 that it has serious security flaws, unacceptable for a modern security
1937 library.  Other than that, this protocol is barely used by anyone
1938 these days since it has been deprecated since 1996.  The security
1939 problems in <acronym>SSL</acronym> 2.0 include:
1940 </p>
1941 <ul>
1942 <li> Message integrity compromised.
1943 The <acronym>SSLv2</acronym> message authentication uses the MD5 function, and
1944 is insecure.
1945
1946 </li><li> Man-in-the-middle attack.
1947 There is no protection of the handshake in <acronym>SSLv2</acronym>, which
1948 permits a man-in-the-middle attack.
1949
1950 </li><li> Truncation attack.
1951 <acronym>SSLv2</acronym> relies on TCP FIN to close the session, so the
1952 attacker can forge a TCP FIN, and the peer cannot tell if it was a
1953 legitimate end of data or not.
1954
1955 </li><li> Weak message integrity for export ciphers.
1956 The cryptographic keys in <acronym>SSLv2</acronym> are used for both message
1957 authentication and encryption, so if weak encryption schemes are
1958 negotiated (say 40-bit keys) the message authentication code use the
1959 same weak key, which isn&rsquo;t necessary.
1960
1961 </li></ul>
1962
1963 <a name="index-PCT"></a>
1964 <p>Other protocols such as Microsoft&rsquo;s <acronym>PCT</acronym> 1 and <acronym>PCT</acronym>
1965 2 were not implemented because they were also abandoned and deprecated
1966 by <acronym>SSL</acronym> 3.0 and later <acronym>TLS</acronym> 1.0.
1967 </p>
1968
1969
1970 <hr>
1971 <a name="Authentication-methods"></a>
1972 <div class="header">
1973 <p>
1974 Next: <a href="#More-on-certificate-authentication" accesskey="n" rel="next">More on certificate authentication</a>, Previous: <a href="#Introduction-to-TLS" accesskey="p" rel="previous">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>
1975 </div>
1976 <a name="Authentication-Methods"></a>
1977 <h2 class="chapter">4 Authentication Methods</h2>
1978
1979 <p>The <acronym>TLS</acronym> protocol provides confidentiality and encryption,
1980 but also offers authentication, which is a prerequisite for a secure
1981 connection. The available authentication methods in <acronym>GnuTLS</acronym>
1982 are:
1983 </p>
1984 <ul>
1985 <li> Certificate authentication
1986
1987 </li><li> Anonymous authentication
1988
1989 </li><li> <acronym>SRP</acronym> authentication
1990
1991 </li><li> <acronym>PSK</acronym> authentication
1992
1993 </li></ul>
1994
1995 <table class="menu" border="0" cellspacing="0">
1996 <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">
1997 </td></tr>
1998 <tr><td align="left" valign="top">&bull; <a href="#Anonymous-authentication" accesskey="2">Anonymous authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
1999 </td></tr>
2000 <tr><td align="left" valign="top">&bull; <a href="#Authentication-using-SRP" accesskey="3">Authentication using SRP</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2001 </td></tr>
2002 <tr><td align="left" valign="top">&bull; <a href="#Authentication-using-PSK" accesskey="4">Authentication using PSK</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2003 </td></tr>
2004 <tr><td align="left" valign="top">&bull; <a href="#Authentication-and-credentials" accesskey="5">Authentication and credentials</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2005 </td></tr>
2006 <tr><td align="left" valign="top">&bull; <a href="#Parameters-stored-in-credentials" accesskey="6">Parameters stored in credentials</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2007 </td></tr>
2008 </table>
2009
2010 <hr>
2011 <a name="Certificate-authentication"></a>
2012 <div class="header">
2013 <p>
2014 Next: <a href="#Anonymous-authentication" accesskey="n" rel="next">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>
2015 </div>
2016 <a name="Certificate-Authentication-1"></a>
2017 <h3 class="section">4.1 Certificate Authentication</h3>
2018
2019 <a name="Authentication-Using-X_002e509-Certificates"></a>
2020 <h4 class="subsection">4.1.1 Authentication Using <acronym>X.509</acronym> Certificates</h4>
2021 <a name="index-X_002e509-certificates"></a>
2022
2023 <p><acronym>X.509</acronym> certificates contain the public parameters, of a
2024 public key algorithm, and an authority&rsquo;s signature, which proves the
2025 authenticity of the parameters.  See <a href="#The-X_002e509-trust-model">The X.509 trust model</a>, for
2026 more information on <acronym>X.509</acronym> protocols.
2027 </p>
2028 <a name="Authentication-Using-OpenPGP-Keys"></a>
2029 <h4 class="subsection">4.1.2 Authentication Using <acronym>OpenPGP</acronym> Keys</h4>
2030 <a name="index-OpenPGP-Keys"></a>
2031
2032 <p><acronym>OpenPGP</acronym> keys also contain public parameters of a public key
2033 algorithm, and signatures from several other parties. Depending on
2034 whether a signer is trusted the key is considered trusted or not.
2035 <acronym>GnuTLS</acronym>&rsquo;s <acronym>OpenPGP</acronym> authentication implementation is
2036 based on the [TLSPGP] (see <a href="#Bibliography">Bibliography</a>) proposal.
2037 </p>
2038 <p>See <a href="#The-OpenPGP-trust-model">The OpenPGP trust model</a>, for more information about the
2039 <acronym>OpenPGP</acronym> trust model.  For a more detailed introduction to
2040 <acronym>OpenPGP</acronym> and <acronym>GnuPG</acronym> see [GPGH] (see <a href="#Bibliography">Bibliography</a>).
2041 </p>
2042 <a name="Using-Certificate-Authentication"></a>
2043 <h4 class="subsection">4.1.3 Using Certificate Authentication</h4>
2044
2045 <p>In <acronym>GnuTLS</acronym> both the <acronym>OpenPGP</acronym> and <acronym>X.509</acronym>
2046 certificates are part of the certificate authentication and thus are
2047 handled using a common API.
2048 </p>
2049 <p>When using certificates the server is required to have at least one
2050 certificate and private key pair. A client may or may not have such a
2051 pair. The certificate and key pair should be loaded, before any
2052 <acronym>TLS</acronym> session is initialized, in a certificate credentials
2053 structure. This should be done by using
2054 <a href="#gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile">gnutls_certificate_set_x509_key_file</a> or
2055 <a href="#gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile">gnutls_certificate_set_openpgp_key_file</a> depending on the
2056 certificate type.  In the <acronym>X.509</acronym> case, the functions will
2057 also accept and use a certificate list that leads to a trusted
2058 authority. The certificate list must be ordered in such way that every
2059 certificate certifies the one before it. The trusted authority&rsquo;s
2060 certificate need not to be included, since the peer should possess it
2061 already.
2062 </p>
2063 <p>As an alternative, a callback may be used so the server or the client
2064 specify the certificate and the key at the handshake time.  That
2065 callback can be set using the functions:
2066 </p>
2067 <ul>
2068 <li> <a href="#gnutls_005fcertificate_005fserver_005fset_005fretrieve_005ffunction">gnutls_certificate_server_set_retrieve_function</a>
2069
2070 </li><li> <a href="#gnutls_005fcertificate_005fclient_005fset_005fretrieve_005ffunction">gnutls_certificate_client_set_retrieve_function</a>
2071
2072 </li></ul>
2073
2074 <p>Clients and servers that will select certificates using callback
2075 functions should select a certificate according the peer&rsquo;s signature
2076 algorithm preferences. To get those preferences use
2077 <a href="#gnutls_005fsign_005falgorithm_005fget_005frequested">gnutls_sign_algorithm_get_requested</a>.
2078 </p>
2079 <p>Certificate verification is possible by loading the trusted
2080 authorities into the credentials structure by using
2081 <a href="#gnutls_005fcertificate_005fset_005fx509_005ftrust_005ffile">gnutls_certificate_set_x509_trust_file</a> or
2082 <a href="#gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005ffile">gnutls_certificate_set_openpgp_keyring_file</a> for openpgp
2083 keys. Note however that the peer&rsquo;s certificate is not automatically
2084 verified, you should call <a href="#gnutls_005fcertificate_005fverify_005fpeers2">gnutls_certificate_verify_peers2</a>,
2085 after a successful handshake, to verify the signatures of the
2086 certificate.  An alternative way, which reports a more detailed
2087 verification output, is to use <a href="#gnutls_005fcertificate_005fget_005fpeers">gnutls_certificate_get_peers</a> to
2088 obtain the raw certificate of the peer and verify it using the
2089 functions discussed in <a href="#The-X_002e509-trust-model">The X.509 trust model</a>.
2090 </p>
2091 <p>In a handshake, the negotiated cipher suite depends on the
2092 certificate&rsquo;s parameters, so not all key exchange methods will be
2093 available with some certificates. <acronym>GnuTLS</acronym> will disable
2094 ciphersuites that are not compatible with the key, or the enabled
2095 authentication methods.  For example keys marked as sign-only, will
2096 not be able to access the plain RSA ciphersuites, but only the
2097 <code>DHE_RSA</code> ones. It is recommended not to use RSA keys for both
2098 signing and encryption. If possible use the same key for the
2099 <code>DHE_RSA</code> and <code>RSA_EXPORT</code> ciphersuites, which use signing,
2100 and a different key for the plain RSA ciphersuites, which use
2101 encryption.  All the key exchange methods shown below are available in
2102 certificate authentication.
2103 </p>
2104 <p>Note that the DHE key exchange methods are generally
2105 slower<a name="DOCF13" href="#FOOT13">(13)</a> than plain RSA and require Diffie
2106 Hellman parameters to be generated and associated with a credentials
2107 structure, by the server.  The <code>RSA-EXPORT</code> method also requires
2108 512 bit RSA parameters, that should also be generated and associated
2109 with the credentials structure.  See the functions:
2110 </p>
2111 <ul>
2112 <li> <a href="#gnutls_005fdh_005fparams_005fgenerate2">gnutls_dh_params_generate2</a>
2113
2114 </li><li> <a href="#gnutls_005fcertificate_005fset_005fdh_005fparams">gnutls_certificate_set_dh_params</a>
2115
2116 </li><li> <a href="#gnutls_005frsa_005fparams_005fgenerate2">gnutls_rsa_params_generate2</a>
2117
2118 </li><li> <a href="#gnutls_005fcertificate_005fset_005frsa_005fexport_005fparams">gnutls_certificate_set_rsa_export_params</a>
2119
2120 </li></ul>
2121
2122 <p>Sometimes in order to avoid bottlenecks in programs it is useful to
2123 store and read parameters from formats that can be generated by
2124 external programs such as <code>certtool</code>. This is possible with
2125 <acronym>GnuTLS</acronym> by using the following functions:
2126 </p>
2127 <ul>
2128 <li> <a href="#gnutls_005fdh_005fparams_005fimport_005fpkcs3">gnutls_dh_params_import_pkcs3</a>
2129
2130 </li><li> <a href="#gnutls_005frsa_005fparams_005fimport_005fpkcs1">gnutls_rsa_params_import_pkcs1</a>
2131
2132 </li><li> <a href="#gnutls_005fdh_005fparams_005fexport_005fpkcs3">gnutls_dh_params_export_pkcs3</a>
2133
2134 </li><li> <a href="#gnutls_005frsa_005fparams_005fexport_005fpkcs1">gnutls_rsa_params_export_pkcs1</a>
2135
2136 </li></ul>
2137
2138 <p>Key exchange algorithms for <acronym>OpenPGP</acronym> and <acronym>X.509</acronym>
2139 certificates:
2140 </p>
2141 <dl compact="compact">
2142 <dt><code>RSA:</code></dt>
2143 <dd><p>The RSA algorithm is used to encrypt a key and send it to the peer.
2144 The certificate must allow the key to be used for encryption.
2145 </p>
2146 </dd>
2147 <dt><code>RSA_EXPORT:</code></dt>
2148 <dd><p>The RSA algorithm is used to encrypt a key and send it to the peer.
2149 In the EXPORT algorithm, the server signs temporary RSA parameters of
2150 512 bits &mdash; which are considered weak &mdash; and sends them to the
2151 client.
2152 </p>
2153 </dd>
2154 <dt><code>DHE_RSA:</code></dt>
2155 <dd><p>The RSA algorithm is used to sign Ephemeral Diffie-Hellman parameters
2156 which are sent to the peer. The key in the certificate must allow the
2157 key to be used for signing. Note that key exchange algorithms which
2158 use Ephemeral Diffie-Hellman parameters, offer perfect forward
2159 secrecy. That means that even if the private key used for signing is
2160 compromised, it cannot be used to reveal past session data.
2161 </p>
2162 </dd>
2163 <dt><code>DHE_DSS:</code></dt>
2164 <dd><p>The DSS algorithm is used to sign Ephemeral Diffie-Hellman parameters
2165 which are sent to the peer. The certificate must contain DSA
2166 parameters to use this key exchange algorithm. DSS stands for Digital
2167 Signature Standard.
2168 </p>
2169 </dd>
2170 </dl>
2171
2172 <hr>
2173 <a name="Anonymous-authentication"></a>
2174 <div class="header">
2175 <p>
2176 Next: <a href="#Authentication-using-SRP" accesskey="n" rel="next">Authentication using SRP</a>, Previous: <a href="#Certificate-authentication" accesskey="p" rel="previous">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>
2177 </div>
2178 <a name="Anonymous-Authentication"></a>
2179 <h3 class="section">4.2 Anonymous Authentication</h3>
2180 <a name="index-Anonymous-authentication"></a>
2181
2182 <p>The anonymous key exchange performs encryption but there is no
2183 indication of the identity of the peer.  This kind of authentication
2184 is vulnerable to a man in the middle attack, but this protocol can be
2185 used even if there is no prior communication and trusted parties with
2186 the peer, or when full anonymity is required.  Unless really required,
2187 do not use anonymous authentication.  Available key exchange methods
2188 are shown below.
2189 </p>
2190 <p>Note that the key exchange methods for anonymous authentication
2191 require Diffie-Hellman parameters to be generated by the server and
2192 associated with an anonymous credentials structure.
2193 </p>
2194 <p>Supported anonymous key exchange algorithms:
2195 </p>
2196 <dl compact="compact">
2197 <dt><code>ANON_DH:</code></dt>
2198 <dd><p>This algorithm exchanges Diffie-Hellman parameters.
2199 </p>
2200 </dd>
2201 </dl>
2202
2203 <hr>
2204 <a name="Authentication-using-SRP"></a>
2205 <div class="header">
2206 <p>
2207 Next: <a href="#Authentication-using-PSK" accesskey="n" rel="next">Authentication using PSK</a>, Previous: <a href="#Anonymous-authentication" accesskey="p" rel="previous">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>
2208 </div>
2209 <a name="Authentication-using-SRP-1"></a>
2210 <h3 class="section">4.3 Authentication using <acronym>SRP</acronym></h3>
2211 <a name="index-SRP-authentication"></a>
2212
2213 <p>Authentication via the Secure Remote Password protocol,
2214 <acronym>SRP</acronym><a name="DOCF14" href="#FOOT14">(14)</a>,
2215 is supported.  The <acronym>SRP</acronym> key exchange is an extension to the
2216 <acronym>TLS</acronym> protocol, and it is a password based authentication
2217 (unlike <acronym>X.509</acronym> or <acronym>OpenPGP</acronym> that use certificates).
2218 The two peers can be identified using a single password, or there can
2219 be combinations where the client is authenticated using <acronym>SRP</acronym>
2220 and the server using a certificate.
2221 </p>
2222 <p>The advantage of <acronym>SRP</acronym> authentication, over other proposed
2223 secure password authentication schemes, is that <acronym>SRP</acronym> does not
2224 require the server to hold the user&rsquo;s password.  This kind of
2225 protection is similar to the one used traditionally in the <em>UNIX</em>
2226 &lsquo;<tt>/etc/passwd</tt>&rsquo; file, where the contents of this file did not cause
2227 harm to the system security if they were revealed.  The <acronym>SRP</acronym>
2228 needs instead of the plain password something called a verifier, which
2229 is calculated using the user&rsquo;s password, and if stolen cannot be used
2230 to impersonate the user. Check [TOMSRP] (see <a href="#Bibliography">Bibliography</a>) for a detailed
2231 description of the <acronym>SRP</acronym> protocol and the Stanford
2232 <acronym>SRP</acronym> libraries, which includes a PAM module that synchronizes
2233 the system&rsquo;s users passwords with the <acronym>SRP</acronym> password
2234 files. That way <acronym>SRP</acronym> authentication could be used for all the
2235 system&rsquo;s users.
2236 </p>
2237 <p>The implementation in <acronym>GnuTLS</acronym> is based on paper
2238 [TLSSRP] (see <a href="#Bibliography">Bibliography</a>).  The supported <acronym>SRP</acronym> key exchange methods are:
2239 </p>
2240 <dl compact="compact">
2241 <dt><code>SRP:</code></dt>
2242 <dd><p>Authentication using the <acronym>SRP</acronym> protocol.
2243 </p>
2244 </dd>
2245 <dt><code>SRP_DSS:</code></dt>
2246 <dd><p>Client authentication using the <acronym>SRP</acronym> protocol. Server is
2247 authenticated using a certificate with DSA parameters.
2248 </p>
2249 </dd>
2250 <dt><code>SRP_RSA:</code></dt>
2251 <dd><p>Client authentication using the <acronym>SRP</acronym> protocol. Server is
2252 authenticated using a certificate with RSA parameters.
2253 </p>
2254 </dd>
2255 </dl>
2256
2257 <p>If clients supporting <acronym>SRP</acronym> know the username and password
2258 before the connection, should initialize the client credentials and
2259 call the function <a href="#gnutls_005fsrp_005fset_005fclient_005fcredentials">gnutls_srp_set_client_credentials</a>.
2260 Alternatively they could specify a callback function by using the
2261 function <a href="#gnutls_005fsrp_005fset_005fclient_005fcredentials_005ffunction">gnutls_srp_set_client_credentials_function</a>.  This has
2262 the advantage that allows probing the server for <acronym>SRP</acronym>
2263 support.  In that case the callback function will be called twice per
2264 handshake.  The first time is before the ciphersuite is negotiated,
2265 and if the callback returns a negative error code, the callback will
2266 be called again if <acronym>SRP</acronym> has been negotiated.  This uses a
2267 special <acronym>TLS</acronym>-<acronym>SRP</acronym> handshake idiom in order to avoid,
2268 in interactive applications, to ask the user for <acronym>SRP</acronym>
2269 password and username if the server does not negotiate an
2270 <acronym>SRP</acronym> ciphersuite.
2271 </p>
2272 <p>In server side the default behaviour of <acronym>GnuTLS</acronym> is to read
2273 the usernames and <acronym>SRP</acronym> verifiers from password files. These
2274 password files are the ones used by the <em>Stanford srp libraries</em>
2275 and can be specified using the
2276 <a href="#gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffile">gnutls_srp_set_server_credentials_file</a>.  If a different
2277 password file format is to be used, then the function
2278 <a href="#gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffunction">gnutls_srp_set_server_credentials_function</a>, should be called,
2279 in order to set an appropriate callback.
2280 </p>
2281 <p>Some helper functions such as
2282 </p>
2283 <ul>
2284 <li> <a href="#gnutls_005fsrp_005fverifier">gnutls_srp_verifier</a>
2285
2286 </li><li> <a href="#gnutls_005fsrp_005fbase64_005fencode">gnutls_srp_base64_encode</a>
2287
2288 </li><li> <a href="#gnutls_005fsrp_005fbase64_005fdecode">gnutls_srp_base64_decode</a>
2289
2290 </li></ul>
2291
2292 <p>are included in <acronym>GnuTLS</acronym>, and can be used to generate and
2293 maintain <acronym>SRP</acronym> verifiers and password files.  A program to
2294 manipulate the required parameters for <acronym>SRP</acronym> authentication is
2295 also included.  See <a href="#srptool">srptool</a>, for more information.
2296 </p>
2297
2298 <hr>
2299 <a name="Authentication-using-PSK"></a>
2300 <div class="header">
2301 <p>
2302 Next: <a href="#Authentication-and-credentials" accesskey="n" rel="next">Authentication and credentials</a>, Previous: <a href="#Authentication-using-SRP" accesskey="p" rel="previous">Authentication using SRP</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>
2303 </div>
2304 <a name="Authentication-using-PSK-1"></a>
2305 <h3 class="section">4.4 Authentication using <acronym>PSK</acronym></h3>
2306 <a name="index-PSK-authentication"></a>
2307
2308 <p>Authentication using Pre-shared keys is a method to authenticate using
2309 usernames and binary keys. This protocol avoids making use of public
2310 key infrastructure and expensive calculations, thus it is suitable for
2311 constraint clients.
2312 </p>
2313 <p>The implementation in <acronym>GnuTLS</acronym> is based on paper
2314 [TLSPSK] (see <a href="#Bibliography">Bibliography</a>).  The supported <acronym>PSK</acronym> key exchange methods are:
2315 </p>
2316 <dl compact="compact">
2317 <dt><code>PSK:</code></dt>
2318 <dd><p>Authentication using the <acronym>PSK</acronym> protocol.
2319 </p>
2320 </dd>
2321 <dt><code>DHE-PSK:</code></dt>
2322 <dd><p>Authentication using the <acronym>PSK</acronym> protocol and Diffie-Hellman key
2323 exchange.  This method offers perfect forward secrecy.
2324 </p>
2325 </dd>
2326 </dl>
2327
2328 <p>Clients supporting <acronym>PSK</acronym> should supply the username and key
2329 before the connection to the client credentials by calling the
2330 function <a href="#gnutls_005fpsk_005fset_005fclient_005fcredentials">gnutls_psk_set_client_credentials</a>.  Alternatively they
2331 could specify a callback function by using the function
2332 <a href="#gnutls_005fpsk_005fset_005fclient_005fcredentials_005ffunction">gnutls_psk_set_client_credentials_function</a>.  This has the
2333 advantage that the callback will be called only if <acronym>PSK</acronym> has
2334 been negotiated.
2335 </p>
2336 <p>In server side the default behaviour of <acronym>GnuTLS</acronym> is to read
2337 the usernames and <acronym>PSK</acronym> keys from a password file. The
2338 password file should contain usernames and keys in hexadecimal
2339 format. The name of the password file can be stored to the credentials
2340 structure by calling <a href="#gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffile">gnutls_psk_set_server_credentials_file</a>.  If
2341 a different password file format is to be used, then the function
2342 <a href="#gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffunction">gnutls_psk_set_server_credentials_function</a>, should be used
2343 instead.
2344 </p>
2345 <p>The server can help the client chose a suitable username and password,
2346 by sending a hint.  In the server, specify the hint by calling
2347 <a href="#gnutls_005fpsk_005fset_005fserver_005fcredentials_005fhint">gnutls_psk_set_server_credentials_hint</a>.  The client can retrieve
2348 the hint, for example in the callback function, using
2349 <a href="#gnutls_005fpsk_005fclient_005fget_005fhint">gnutls_psk_client_get_hint</a>.
2350 </p>
2351 <p>There is no mechanism to derive a PSK key from a password
2352 specified by the TLS PSK document<a name="DOCF15" href="#FOOT15">(15)</a>.
2353 For password-based authentication check <a href="#Authentication-using-SRP">Authentication using SRP</a>.
2354 </p>
2355 <p>Some helper functions such as:
2356 </p>
2357 <ul>
2358 <li> <a href="#gnutls_005fhex_005fencode">gnutls_hex_encode</a>
2359
2360 </li><li> <a href="#gnutls_005fhex_005fdecode">gnutls_hex_decode</a>
2361
2362 </li></ul>
2363
2364 <p>are included in <acronym>GnuTLS</acronym>, and may be used to generate and
2365 maintain <acronym>PSK</acronym> keys.
2366 </p>
2367
2368 <hr>
2369 <a name="Authentication-and-credentials"></a>
2370 <div class="header">
2371 <p>
2372 Next: <a href="#Parameters-stored-in-credentials" accesskey="n" rel="next">Parameters stored in credentials</a>, Previous: <a href="#Authentication-using-PSK" accesskey="p" rel="previous">Authentication using PSK</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>
2373 </div>
2374 <a name="Authentication-and-Credentials"></a>
2375 <h3 class="section">4.5 Authentication and Credentials</h3>
2376
2377 <p>In <acronym>GnuTLS</acronym> every key exchange method is associated with a
2378 credentials type. So in order to enable to enable a specific method,
2379 the corresponding credentials type should be initialized and set using
2380 <a href="#gnutls_005fcredentials_005fset">gnutls_credentials_set</a>.  A mapping is shown below.
2381 </p>
2382 <p>Key exchange algorithms and the corresponding credential types:
2383 </p>
2384 <table>
2385 <thead><tr><th width="30%">Key exchange</th><th width="30%">Client credentials</th><th width="30%">Server credentials</th></tr></thead>
2386 <tr><td width="30%"><code>KX_RSA</code></td></tr>
2387 <tr><td width="30%"><code>KX_DHE_RSA</code></td></tr>
2388 <tr><td width="30%"><code>KX_DHE_DSS</code></td></tr>
2389 <tr><td width="30%"><code>KX_RSA_EXPORT</code></td><td width="30%"><code>CRD_CERTIFICATE</code></td><td width="30%"><code>CRD_CERTIFICATE</code></td></tr>
2390 <tr><td width="30%"><code>KX_SRP_RSA</code></td><td width="30%"><code>CRD_SRP</code></td><td width="30%"><code>CRD_SRP</code></td></tr>
2391 <tr><td width="30%"><code>KX_SRP_DSS</code></td><td width="30%"></td><td width="30%"><code>CRD_CERTIFICATE</code></td></tr>
2392 <tr><td width="30%"><code>KX_SRP</code></td><td width="30%"><code>CRD_SRP</code></td><td width="30%"><code>CRD_SRP</code></td></tr>
2393 <tr><td width="30%"><code>KX_ANON_DH</code></td><td width="30%"><code>CRD_ANON</code></td><td width="30%"><code>CRD_ANON</code></td></tr>
2394 <tr><td width="30%"><code>KX_PSK</code></td><td width="30%"><code>CRD_PSK</code></td><td width="30%"><code>CRD_PSK</code></td></tr>
2395 </table>
2396
2397 <hr>
2398 <a name="Parameters-stored-in-credentials"></a>
2399 <div class="header">
2400 <p>
2401 Previous: <a href="#Authentication-and-credentials" accesskey="p" rel="previous">Authentication and credentials</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>
2402 </div>
2403 <a name="Parameters-Stored-in-Credentials"></a>
2404 <h3 class="section">4.6 Parameters Stored in Credentials</h3>
2405
2406 <p>Several parameters such as the ones used for Diffie-Hellman
2407 authentication are stored within the credentials structures, so all
2408 sessions can access them. Those parameters are stored in structures
2409 such as <code>gnutls_dh_params_t</code> and <code>gnutls_rsa_params_t</code>, and
2410 functions like <a href="#gnutls_005fcertificate_005fset_005fdh_005fparams">gnutls_certificate_set_dh_params</a> and
2411 <a href="#gnutls_005fcertificate_005fset_005frsa_005fexport_005fparams">gnutls_certificate_set_rsa_export_params</a> can be used to
2412 associate those parameters with the given credentials structure.
2413 </p>
2414 <p>Since those parameters need to be renewed from time to time and a
2415 global structure such as the credentials, may not be easy to modify
2416 since it is accessible by all sessions, an alternative interface is
2417 available using a callback function.  This can be set using the
2418 <a href="#gnutls_005fcertificate_005fset_005fparams_005ffunction">gnutls_certificate_set_params_function</a>.  An example is shown
2419 below.
2420 </p>
2421 <div class="example">
2422 <pre class="example">#include &lt;gnutls.h&gt;
2423
2424 gnutls_rsa_params_t rsa_params;
2425 gnutls_dh_params_t dh_params;
2426
2427 /* This function will be called once a session requests DH
2428  * or RSA parameters. The parameters returned (if any) will
2429  * be used for the first handshake only.
2430  */
2431 static int get_params( gnutls_session_t session,
2432         gnutls_params_type_t type,
2433         gnutls_params_st *st)
2434 {
2435    if (type == GNUTLS_PARAMS_RSA_EXPORT)
2436       st-&gt;params.rsa_export = rsa_params;
2437    else if (type == GNUTLS_PARAMS_DH)
2438       st-&gt;params.dh = dh_params;
2439    else return -1;
2440
2441    st-&gt;type = type;
2442    /* do not deinitialize those parameters.
2443     */
2444    st-&gt;deinit = 0;
2445
2446    return 0;
2447 }
2448
2449 int main()
2450 {
2451    gnutls_certificate_credentials_t cert_cred;
2452
2453    initialize_params();
2454
2455    /* ...
2456     */
2457
2458    gnutls_certificate_set_params_function( cert_cred, get_params);
2459 }
2460 </pre></div>
2461
2462 <hr>
2463 <a name="More-on-certificate-authentication"></a>
2464 <div class="header">
2465 <p>
2466 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="#Authentication-methods" accesskey="p" rel="previous">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>
2467 </div>
2468 <a name="More-on-Certificate-Authentication"></a>
2469 <h2 class="chapter">5 More on Certificate Authentication</h2>
2470 <a name="Certificate-Authentication"></a><a name="index-Certificate-authentication"></a>
2471
2472 <table class="menu" border="0" cellspacing="0">
2473 <tr><td align="left" valign="top">&bull; <a href="#The-X_002e509-trust-model" accesskey="1">The X.509 trust model</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2474 </td></tr>
2475 <tr><td align="left" valign="top">&bull; <a href="#The-OpenPGP-trust-model" accesskey="2">The OpenPGP trust model</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2476 </td></tr>
2477 <tr><td align="left" valign="top">&bull; <a href="#PKCS-_002311-tokens" accesskey="3">PKCS #11 tokens</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2478 </td></tr>
2479 <tr><td align="left" valign="top">&bull; <a href="#Abstract-data-types" accesskey="4">Abstract data types</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2480 </td></tr>
2481 <tr><td align="left" valign="top">&bull; <a href="#Digital-signatures" accesskey="5">Digital signatures</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2482 </td></tr>
2483 </table>
2484
2485 <hr>
2486 <a name="The-X_002e509-trust-model"></a>
2487 <div class="header">
2488 <p>
2489 Next: <a href="#The-OpenPGP-trust-model" accesskey="n" rel="next">The OpenPGP trust model</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>
2490 </div>
2491 <a name="The-X_002e509-Trust-Model"></a>
2492 <h3 class="section">5.1 The <acronym>X.509</acronym> Trust Model</h3>
2493 <a name="index-X_002e509-certificates-1"></a>
2494
2495 <p>The <acronym>X.509</acronym> protocols rely on a hierarchical trust model. In
2496 this trust model Certification Authorities (CAs) are used to certify
2497 entities.  Usually more than one certification authorities exist, and
2498 certification authorities may certify other authorities to issue
2499 certificates as well, following a hierarchical model.
2500 </p>
2501 <img src="gnutls-x509.png" alt="gnutls-x509">
2502
2503 <p>One needs to trust one or more CAs for his secure communications. In
2504 that case only the certificates issued by the trusted authorities are
2505 acceptable.  See the figure above for a typical example.  The API for
2506 handling <acronym>X.509</acronym> certificates is described at section
2507 <a href="#sec_003ax509api">sec:x509api</a>.  Some examples are listed below.
2508 </p>
2509 <table class="menu" border="0" cellspacing="0">
2510 <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">
2511 </td></tr>
2512 <tr><td align="left" valign="top">&bull; <a href="#Verifying-X_002e509-certificate-paths" accesskey="2">Verifying X.509 certificate paths</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2513 </td></tr>
2514 <tr><td align="left" valign="top">&bull; <a href="#PKCS-_002310-certificate-requests" accesskey="3">PKCS #10 certificate requests</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2515 </td></tr>
2516 <tr><td align="left" valign="top">&bull; <a href="#PKCS-_002312-structures" accesskey="4">PKCS #12 structures</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2517 </td></tr>
2518 </table>
2519
2520 <hr>
2521 <a name="X_002e509-certificates"></a>
2522 <div class="header">
2523 <p>
2524 Next: <a href="#Verifying-X_002e509-certificate-paths" accesskey="n" rel="next">Verifying X.509 certificate paths</a>, Up: <a href="#The-X_002e509-trust-model" accesskey="u" rel="up">The X.509 trust model</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>
2525 </div>
2526 <a name="X_002e509-Certificates"></a>
2527 <h4 class="subsection">5.1.1 <acronym>X.509</acronym> Certificates</h4>
2528
2529 <p>An <acronym>X.509</acronym> certificate usually contains information about the
2530 certificate holder, the signer, a unique serial number, expiration
2531 dates and some other fields [PKIX] (see <a href="#Bibliography">Bibliography</a>) as shown in the table below.
2532 </p>
2533 <dl compact="compact">
2534 <dt><code>version:</code></dt>
2535 <dd><p>The field that indicates the version of the certificate.
2536 </p>
2537 </dd>
2538 <dt><code>serialNumber:</code></dt>
2539 <dd><p>This field holds a unique serial number per certificate.
2540 </p>
2541 </dd>
2542 <dt><code>issuer:</code></dt>
2543 <dd><p>Holds the issuer&rsquo;s distinguished name.
2544 </p>
2545 </dd>
2546 <dt><code>validity:</code></dt>
2547 <dd><p>The activation and expiration dates.
2548 </p>
2549 </dd>
2550 <dt><code>subject:</code></dt>
2551 <dd><p>The subject&rsquo;s distinguished name of the certificate.
2552 </p>
2553 </dd>
2554 <dt><code>extensions:</code></dt>
2555 <dd><p>The extensions are fields only present in version 3 certificates.
2556 </p>
2557 </dd>
2558 </dl>
2559
2560 <p>The certificate&rsquo;s <em>subject or issuer name</em> is not just a single
2561 string.  It is a Distinguished name and in the <acronym>ASN.1</acronym>
2562 notation is a sequence of several object IDs with their corresponding
2563 values. Some of available OIDs to be used in an <acronym>X.509</acronym>
2564 distinguished name are defined in &lsquo;<tt>gnutls/x509.h</tt>&rsquo;.
2565 </p>
2566 <p>The <em>Version</em> field in a certificate has values either 1 or 3 for
2567 version 3 certificates.  Version 1 certificates do not support the
2568 extensions field so it is not possible to distinguish a CA from a
2569 person, thus their usage should be avoided.
2570 </p>
2571 <p>The <em>validity</em> dates are there to indicate the date that the
2572 specific certificate was activated and the date the certificate&rsquo;s key
2573 would be considered invalid.
2574 </p>
2575 <p>Certificate <em>extensions</em> are there to include information about
2576 the certificate&rsquo;s subject that did not fit in the typical certificate
2577 fields. Those may be e-mail addresses, flags that indicate whether the
2578 belongs to a CA etc.  All the supported <acronym>X.509</acronym> version 3
2579 extensions are shown in the table below.
2580 </p>
2581 <dl compact="compact">
2582 <dt><code>subject key id (2.5.29.14):</code></dt>
2583 <dd><p>An identifier of the key of the subject.
2584 </p>
2585 </dd>
2586 <dt><code>authority key id (2.5.29.35):</code></dt>
2587 <dd><p>An identifier of the authority&rsquo;s key used to sign the certificate.
2588 </p>
2589 </dd>
2590 <dt><code>subject alternative name (2.5.29.17):</code></dt>
2591 <dd><p>Alternative names to subject&rsquo;s distinguished name.
2592 </p>
2593 </dd>
2594 <dt><code>key usage (2.5.29.15):</code></dt>
2595 <dd><p>Constraints the key&rsquo;s usage of the certificate.
2596 </p>
2597 </dd>
2598 <dt><code>extended key usage (2.5.29.37):</code></dt>
2599 <dd><p>Constraints the purpose of the certificate.
2600 </p>
2601 </dd>
2602 <dt><code>basic constraints (2.5.29.19):</code></dt>
2603 <dd><p>Indicates whether this is a CA certificate or not, and specify the
2604 maximum path lengths of certificate chains.
2605 </p>
2606 </dd>
2607 <dt><code>CRL distribution points (2.5.29.31):</code></dt>
2608 <dd><p>This extension is set by the CA, in order to inform about the issued
2609 CRLs.
2610 </p>
2611 </dd>
2612 <dt><code>Proxy Certification Information (1.3.6.1.5.5.7.1.14):</code></dt>
2613 <dd><p>Proxy Certificates includes this extension that contains the OID of
2614 the proxy policy language used, and can specify limits on the maximum
2615 lengths of proxy chains.  Proxy Certificates are specified in
2616 [RFC3820] (see <a href="#Bibliography">Bibliography</a>).
2617 </p>
2618 </dd>
2619 </dl>
2620
2621 <p>In <acronym>GnuTLS</acronym> the <acronym>X.509</acronym> certificate structures are
2622 handled using the <code>gnutls_x509_crt_t</code> type and the corresponding
2623 private keys with the <code>gnutls_x509_privkey_t</code> type.  All the
2624 available functions for <acronym>X.509</acronym> certificate handling have
2625 their prototypes in &lsquo;<tt>gnutls/x509.h</tt>&rsquo;. An example program to
2626 demonstrate the <acronym>X.509</acronym> parsing capabilities can be found at
2627 section <a href="#ex_003ax509_002dinfo">ex:x509-info</a>.
2628 </p>
2629 <hr>
2630 <a name="Verifying-X_002e509-certificate-paths"></a>
2631 <div class="header">
2632 <p>
2633 Next: <a href="#PKCS-_002310-certificate-requests" accesskey="n" rel="next">PKCS #10 certificate requests</a>, Previous: <a href="#X_002e509-certificates" accesskey="p" rel="previous">X.509 certificates</a>, Up: <a href="#The-X_002e509-trust-model" accesskey="u" rel="up">The X.509 trust model</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>
2634 </div>
2635 <a name="Verifying-X_002e509-Certificate-Paths"></a>
2636 <h4 class="subsection">5.1.2 Verifying <acronym>X.509</acronym> Certificate Paths</h4>
2637 <a name="index-Verifying-certificate-paths"></a>
2638
2639 <p>Verifying certificate paths is important in <acronym>X.509</acronym>
2640 authentication. For this purpose the function
2641 <a href="#gnutls_005fx509_005fcrt_005fverify">gnutls_x509_crt_verify</a> is provided. The output of this function
2642 is the bitwise OR of the elements of the
2643 <code>gnutls_certificate_status_t</code> enumeration.  A detailed
2644 description of these elements can be found in figure below.  The
2645 function <a href="#gnutls_005fcertificate_005fverify_005fpeers2">gnutls_certificate_verify_peers2</a> is equivalent to the
2646 previous one, and will verify the peer&rsquo;s certificate in a TLS session.
2647 </p>
2648 <dl compact="compact">
2649 <dt><code>GNUTLS_CERT_INVALID:</code></dt>
2650 <dd><p>The certificate is not signed by one of the known authorities, or
2651 the signature is invalid.
2652 </p>
2653 </dd>
2654 <dt><code>GNUTLS_CERT_REVOKED:</code></dt>
2655 <dd><p>The certificate has been revoked by its CA.
2656 </p>
2657 </dd>
2658 <dt><code>GNUTLS_CERT_SIGNER_NOT_FOUND:</code></dt>
2659 <dd><p>The certificate&rsquo;s issuer is not known. This is the case when the
2660 issuer is not in the trusted certificates list.
2661 </p>
2662 </dd>
2663 <dt><code>GNUTLS_CERT_SIGNER_NOT_CA:</code></dt>
2664 <dd><p>The certificate&rsquo;s signer was not a CA. This may happen if
2665 this was a version 1 certificate, which is common with some CAs, or
2666 a version 3 certificate without the basic constrains extension.
2667 </p>
2668 <a name="GNUTLS_005fCERT_005fINSECURE_005fALGORITHM"></a></dd>
2669 <dt><code>GNUTLS_CERT_INSECURE_ALGORITHM:</code></dt>
2670 <dd><p>The certificate was signed using an insecure algorithm such as MD2 or
2671 MD5.  These algorithms have been broken and should not be trusted.
2672 </p>
2673 </dd>
2674 </dl>
2675
2676 <p>There is also to possibility to pass some input to the verification
2677 functions in the form of flags. For <a href="#gnutls_005fx509_005fcrt_005fverify">gnutls_x509_crt_verify</a> the
2678 flags are passed straightforward, but
2679 <a href="#gnutls_005fcertificate_005fverify_005fpeers2">gnutls_certificate_verify_peers2</a> depends on the flags set by
2680 calling <a href="#gnutls_005fcertificate_005fset_005fverify_005fflags">gnutls_certificate_set_verify_flags</a>.  All the available
2681 flags are part of the enumeration
2682 <a href="#gnutls_005fcertificate_005fverify_005fflags">gnutls_certificate_verify_flags</a> and are explained in the table
2683 below.
2684 </p>
2685 <a name="gnutls_005fcertificate_005fverify_005fflags"></a><a name="index-gnutls_005fcertificate_005fverify_005fflags"></a>
2686 <dl compact="compact">
2687 <dt><code>GNUTLS_VERIFY_DISABLE_CA_SIGN:</code></dt>
2688 <dd><p>If set a signer does not have to be a certificate authority. This
2689 flag should normaly be disabled, unless you know what this means.
2690 </p>
2691 </dd>
2692 <dt><code>GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT:</code></dt>
2693 <dd><p>Allow only trusted CA certificates that have version 1.  This is
2694 safer than GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT, and should be
2695 used instead. That way only signers in your trusted list will be
2696 allowed to have certificates of version 1.
2697 </p>
2698 </dd>
2699 <dt><code>GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT:</code></dt>
2700 <dd><p>Allow CA certificates that have version 1 (both root and
2701 intermediate). This is dangerous since those haven&rsquo;t the
2702 basicConstraints extension. Must be used in combination with
2703 GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT.
2704 </p>
2705 </dd>
2706 <dt><code>GNUTLS_VERIFY_DO_NOT_ALLOW_SAME:</code></dt>
2707 <dd><p>If a certificate is not signed by anyone trusted but exists in
2708 the trusted CA list do not treat it as trusted.
2709 </p>
2710 </dd>
2711 <dt><code>GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2:</code></dt>
2712 <dd><p>Allow certificates to be signed using the old MD2 algorithm.
2713 </p>
2714 </dd>
2715 <dt><code>GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5:</code></dt>
2716 <dd><p>Allow certificates to be signed using the broken MD5 algorithm.
2717 </p></dd>
2718 </dl>
2719
2720 <p>Although the verification of a certificate path indicates that the
2721 certificate is signed by trusted authority, does not reveal anything
2722 about the peer&rsquo;s identity. It is required to verify if the
2723 certificate&rsquo;s owner is the one you expect. For more information
2724 consult [RFC2818] (see <a href="#Bibliography">Bibliography</a>) and section <a href="#ex_003averify">ex:verify</a> for an example.
2725 </p>
2726 <hr>
2727 <a name="PKCS-_002310-certificate-requests"></a>
2728 <div class="header">
2729 <p>
2730 Next: <a href="#PKCS-_002312-structures" accesskey="n" rel="next">PKCS #12 structures</a>, Previous: <a href="#Verifying-X_002e509-certificate-paths" accesskey="p" rel="previous">Verifying X.509 certificate paths</a>, Up: <a href="#The-X_002e509-trust-model" accesskey="u" rel="up">The X.509 trust model</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>
2731 </div>
2732 <a name="PKCS-_002310-Certificate-Requests"></a>
2733 <h4 class="subsection">5.1.3 <acronym>PKCS</acronym> #10 Certificate Requests</h4>
2734 <a name="index-Certificate-requests"></a>
2735 <a name="index-PKCS-_002310"></a>
2736
2737 <p>A certificate request is a structure, which contain information about
2738 an applicant of a certificate service.  It usually contains a private
2739 key, a distinguished name and secondary data such as a challenge
2740 password. <acronym>GnuTLS</acronym> supports the requests defined in
2741 <acronym>PKCS</acronym> #10 [RFC2986] (see <a href="#Bibliography">Bibliography</a>). Other certificate request&rsquo;s format
2742 such as PKIX&rsquo;s [RFC4211] (see <a href="#Bibliography">Bibliography</a>) are not currently supported.
2743 </p>
2744 <p>In <acronym>GnuTLS</acronym> the <acronym>PKCS</acronym> #10 structures are handled
2745 using the <code>gnutls_x509_crq_t</code> type.  An example of a certificate
2746 request generation can be found at section <a href="#ex_003acrq">ex:crq</a>.
2747 </p>
2748 <hr>
2749 <a name="PKCS-_002312-structures"></a>
2750 <div class="header">
2751 <p>
2752 Previous: <a href="#PKCS-_002310-certificate-requests" accesskey="p" rel="previous">PKCS #10 certificate requests</a>, Up: <a href="#The-X_002e509-trust-model" accesskey="u" rel="up">The X.509 trust model</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>
2753 </div>
2754 <a name="PKCS-_002312-Structures"></a>
2755 <h4 class="subsection">5.1.4 <acronym>PKCS</acronym> #12 Structures</h4>
2756 <a name="index-PKCS-_002312"></a>
2757
2758 <p>A <acronym>PKCS</acronym> #12 structure [PKCS12] (see <a href="#Bibliography">Bibliography</a>) usually contains a user&rsquo;s
2759 private keys and certificates. It is commonly used in browsers to
2760 export and import the user&rsquo;s identities.
2761 </p>
2762 <p>In <acronym>GnuTLS</acronym> the <acronym>PKCS</acronym> #12 structures are handled
2763 using the <code>gnutls_pkcs12_t</code> type. This is an abstract type that
2764 may hold several <code>gnutls_pkcs12_bag_t</code> types.  The Bag types are
2765 the holders of the actual data, which may be certificates, private
2766 keys or encrypted data.  An Bag of type encrypted should be decrypted
2767 in order for its data to be accessed.
2768 </p>
2769 <p>An example of a <acronym>PKCS</acronym> #12 structure generation can be found
2770 at section <a href="#ex_003apkcs12">ex:pkcs12</a>.
2771 </p>
2772 <hr>
2773 <a name="The-OpenPGP-trust-model"></a>
2774 <div class="header">
2775 <p>
2776 Next: <a href="#PKCS-_002311-tokens" accesskey="n" rel="next">PKCS #11 tokens</a>, Previous: <a href="#The-X_002e509-trust-model" accesskey="p" rel="previous">The X.509 trust model</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>
2777 </div>
2778 <a name="The-OpenPGP-Trust-Model"></a>
2779 <h3 class="section">5.2 The <acronym>OpenPGP</acronym> Trust Model</h3>
2780 <a name="index-OpenPGP-Keys-1"></a>
2781
2782 <p>The <acronym>OpenPGP</acronym> key authentication relies on a distributed trust
2783 model, called the &ldquo;web of trust&rdquo;. The &ldquo;web of trust&rdquo; uses a
2784 decentralized system of trusted introducers, which are the same as a
2785 CA. <acronym>OpenPGP</acronym> allows anyone to sign anyone&rsquo;s else public
2786 key. When Alice signs Bob&rsquo;s key, she is introducing Bob&rsquo;s key to
2787 anyone who trusts Alice. If someone trusts Alice to introduce keys,
2788 then Alice is a trusted introducer in the mind of that observer.
2789 </p>
2790 <img src="gnutls-pgp.png" alt="gnutls-pgp">
2791
2792 <p>For example: If David trusts Alice to be an introducer, and Alice
2793 signed Bob&rsquo;s key, Dave also trusts Bob&rsquo;s key to be the real one.
2794 </p>
2795 <p>There are some key points that are important in that model. In the
2796 example Alice has to sign Bob&rsquo;s key, only if she is sure that the key
2797 belongs to Bob. Otherwise she may also make Dave falsely believe that
2798 this is Bob&rsquo;s key. Dave has also the responsibility to know who to
2799 trust.  This model is similar to real life relations.
2800 </p>
2801 <p>Just see how Charlie behaves in the previous example. Although he has
2802 signed Bob&rsquo;s key - because he knows, somehow, that it belongs to Bob -
2803 he does not trust Bob to be an introducer. Charlie decided to trust
2804 only Kevin, for some reason. A reason could be that Bob is lazy
2805 enough, and signs other people&rsquo;s keys without being sure that they
2806 belong to the actual owner.
2807 </p>
2808 <a name="OpenPGP-Keys"></a>
2809 <h4 class="subsection">5.2.1 <acronym>OpenPGP</acronym> Keys</h4>
2810
2811 <p>In <acronym>GnuTLS</acronym> the <acronym>OpenPGP</acronym> key structures
2812 [RFC2440] (see <a href="#Bibliography">Bibliography</a>) are handled using the <code>gnutls_openpgp_crt_t</code> type
2813 and the corresponding private keys with the
2814 <code>gnutls_openpgp_privkey_t</code> type. All the prototypes for the key
2815 handling functions can be found at &lsquo;<tt>gnutls/openpgp.h</tt>&rsquo;.
2816 </p>
2817 <a name="Verifying-an-OpenPGP-Key"></a>
2818 <h4 class="subsection">5.2.2 Verifying an <acronym>OpenPGP</acronym> Key</h4>
2819
2820 <p>The verification functions of <acronym>OpenPGP</acronym> keys, included in
2821 <acronym>GnuTLS</acronym>, are simple ones, and do not use the features of the
2822 &ldquo;web of trust&rdquo;.  For that reason, if the verification needs are
2823 complex, the assistance of external tools like <acronym>GnuPG</acronym> and
2824 GPGME (<a href="http://www.gnupg.org/related_software/gpgme/">http://www.gnupg.org/related_software/gpgme/</a>) is
2825 recommended.
2826 </p>
2827 <p>There is one verification function in <acronym>GnuTLS</acronym>, the
2828 <a href="#gnutls_005fopenpgp_005fcrt_005fverify_005fring">gnutls_openpgp_crt_verify_ring</a>.  This checks an
2829 <acronym>OpenPGP</acronym> key against a given set of public keys (keyring) and
2830 returns the key status. The key verification status is the same as in
2831 <acronym>X.509</acronym> certificates, although the meaning and interpretation
2832 are different. For example an <acronym>OpenPGP</acronym> key may be valid, if
2833 the self signature is ok, even if no signers were found.  The meaning
2834 of verification status is shown in the figure below.
2835 </p>
2836 <dl compact="compact">
2837 <dt><code>CERT_INVALID:</code></dt>
2838 <dd><p>A signature on the key is invalid. That means that the key was
2839 modified by somebody, or corrupted during transport.
2840 </p>
2841 </dd>
2842 <dt><code>CERT_REVOKED:</code></dt>
2843 <dd><p>The key has been revoked by its owner.
2844 </p>
2845 </dd>
2846 <dt><code>CERT_SIGNER_NOT_FOUND:</code></dt>
2847 <dd><p>The key was not signed by a known signer.
2848 </p>
2849 </dd>
2850 <dt><code>GNUTLS_CERT_INSECURE_ALGORITHM:</code></dt>
2851 <dd><p>The certificate was signed using an insecure algorithm such as MD2 or
2852 MD5.  These algorithms have been broken and should not be trusted.
2853 </p>
2854 </dd>
2855 </dl>
2856
2857
2858 <hr>
2859 <a name="PKCS-_002311-tokens"></a>
2860 <div class="header">
2861 <p>
2862 Next: <a href="#Abstract-data-types" accesskey="n" rel="next">Abstract data types</a>, Previous: <a href="#The-OpenPGP-trust-model" accesskey="p" rel="previous">The OpenPGP trust model</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>
2863 </div>
2864 <a name="PKCS-_002311-tokens-1"></a>
2865 <h3 class="section">5.3 <acronym>PKCS #11</acronym> tokens</h3>
2866 <a name="sec_003apkcs11"></a><a name="index-PKCS-_002311-tokens"></a>
2867
2868 <a name="Introduction"></a>
2869 <h4 class="subsection">5.3.1 Introduction</h4>
2870 <p>This section copes with the <acronym>PKCS #11</acronym> [PKCS11] (see <a href="#Bibliography">Bibliography</a>) support in <acronym>GnuTLS</acronym>.
2871 <acronym>PKCS #11</acronym> is plugin API allowing applications to access cryptographic
2872 operations on a token, as well as to objects residing on the token. A token can
2873 be a real hardware token such as a smart card, or it can be a software component
2874 such as <acronym>Gnome Keyring</acronym>. The objects residing on such token can be
2875 certificates, public keys, private keys or even plain data or  secret keys. Of those
2876 certificates and public/private key pairs can be used with <acronym>GnuTLS</acronym>. Its
2877 main advantage is that it allows operations on private key objects such as decryption
2878 and signing without accessing the key itself.
2879 </p>
2880 <p>Moreover it can be used to allow all applications in the same operating system to access
2881 shared cryptographic keys and certificates in a uniform way, as in the following picture.
2882 </p>
2883 <img src="pkcs11-vision.png" alt="pkcs11-vision">
2884
2885 <a name="Initialization-1"></a>
2886 <h4 class="subsection">5.3.2 Initialization</h4>
2887 <p>To allow all the  <acronym>GnuTLS</acronym> applications to access <acronym>PKCS</acronym> #11 tokens
2888 you can use a configuration per module, such as <code>/etc/pkcs11/modules/mymodule.conf</code>.
2889 This file has the following format:
2890 </p>
2891 <div class="smallexample">
2892 <pre class="smallexample">module: /usr/lib/opensc-pkcs11.so
2893 </pre></div>
2894
2895 <p>If you use this file, then there is no need for other initialization in
2896 <acronym>GnuTLS</acronym>, except for the PIN and token functions. Those allow retrieving a PIN
2897 when accessing a protected object, such as a private key, as well as probe
2898 the user to insert the token. All the initialization functions are below.
2899 </p>
2900 <ul>
2901 <li> <a href="#gnutls_005fpkcs11_005finit">gnutls_pkcs11_init</a>: Global initialization
2902
2903 </li><li> <a href="#gnutls_005fpkcs11_005fdeinit">gnutls_pkcs11_deinit</a>: Global deinitialization
2904
2905 </li><li> <a href="#gnutls_005fpkcs11_005fset_005ftoken_005ffunction">gnutls_pkcs11_set_token_function</a>: Sets the token insertion function
2906
2907 </li><li> <a href="#gnutls_005fpkcs11_005fset_005fpin_005ffunction">gnutls_pkcs11_set_pin_function</a>: Sets the PIN request function
2908
2909 </li><li> <a href="#gnutls_005fpkcs11_005fadd_005fprovider">gnutls_pkcs11_add_provider</a>: Adds an additional <acronym>PKCS #11</acronym> provider
2910
2911 </li></ul>
2912
2913 <p>Note that due to limitations of <acronym>PKCS #11</acronym> there might be issues when multiple libraries
2914 are sharing a module. If this is the case we suggest to use p11-kit<a name="DOCF16" href="#FOOT16">(16)</a>
2915 that provides an intermediate module to control access to resources over the
2916 multiple users.
2917 </p>
2918 <a name="Reading-Objects"></a>
2919 <h4 class="subsection">5.3.3 Reading Objects</h4>
2920
2921 <p>All <acronym>PKCS #11</acronym> objects are referenced by <acronym>GnuTLS</acronym> functions by
2922 URLs as described in <code>draft-pechanec-pkcs11uri-03</code>. For example a public
2923 key on a smart card may be referenced as:
2924 </p>
2925 <div class="example">
2926 <pre class="example">pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
2927 manufacturer=EnterSafe;object=test1;objecttype=public;\
2928 id=32:f1:53:f3:e3:79:90:b0:86:24:14:10:77:ca:5d:ec:2d:15:fa:ed
2929 </pre></div>
2930
2931 <p>while the smart card itself can be referenced as:
2932 </p><div class="example">
2933 <pre class="example">pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
2934 </pre></div>
2935
2936
2937 <p>Objects can be accessed with the following functions
2938 </p><ul>
2939 <li> <a href="#gnutls_005fpkcs11_005fobj_005finit">gnutls_pkcs11_obj_init</a>: Initializes an object
2940
2941 </li><li> <a href="#gnutls_005fpkcs11_005fobj_005fimport_005furl">gnutls_pkcs11_obj_import_url</a>: To import an object from a url
2942
2943 </li><li> <a href="#gnutls_005fpkcs11_005fobj_005fexport_005furl">gnutls_pkcs11_obj_export_url</a>: To export the URL of the object
2944
2945 </li><li> <a href="#gnutls_005fpkcs11_005fobj_005fdeinit">gnutls_pkcs11_obj_deinit</a>: To deinitialize an object
2946
2947 </li><li> <a href="#gnutls_005fpkcs11_005fobj_005fexport">gnutls_pkcs11_obj_export</a>: To export data associated with object
2948
2949 </li><li> <a href="#gnutls_005fpkcs11_005fobj_005fget_005finfo">gnutls_pkcs11_obj_get_info</a>: To obtain information about an object
2950
2951 </li><li> <a href="#gnutls_005fpkcs11_005fobj_005flist_005fimport_005furl">gnutls_pkcs11_obj_list_import_url</a>: To mass load of objects
2952
2953 </li><li> <a href="#gnutls_005fx509_005fcrt_005fimport_005fpkcs11">gnutls_x509_crt_import_pkcs11</a>: Import a certificate object
2954
2955 </li><li> <a href="#gnutls_005fx509_005fcrt_005fimport_005fpkcs11_005furl">gnutls_x509_crt_import_pkcs11_url</a>: Helper function to directly import a URL into a certificate
2956
2957 </li><li> <a href="#gnutls_005fx509_005fcrt_005flist_005fimport_005fpkcs11">gnutls_x509_crt_list_import_pkcs11</a>: Mass import of certificates
2958
2959 </li></ul>
2960
2961
2962 <p>Functions that relate to token handling are shown below
2963 </p><ul>
2964 <li> <a href="#gnutls_005fpkcs11_005ftoken_005finit">gnutls_pkcs11_token_init</a>: Initializes a token
2965
2966 </li><li> <a href="#gnutls_005fpkcs11_005ftoken_005fset_005fpin">gnutls_pkcs11_token_set_pin</a>: Sets the token user&rsquo;s PIN
2967
2968 </li><li> <a href="#gnutls_005fpkcs11_005ftoken_005fget_005furl">gnutls_pkcs11_token_get_url</a>: Returns the URL of a token
2969
2970 </li><li> <a href="#gnutls_005fpkcs11_005ftoken_005fget_005finfo">gnutls_pkcs11_token_get_info</a>: Obtain information about a token
2971
2972 </li><li> <a href="#gnutls_005fpkcs11_005ftoken_005fget_005fflags">gnutls_pkcs11_token_get_flags</a>: Returns flags about a token (i.e. hardware or software)
2973
2974 </li></ul>
2975
2976 <p>The following example will list all tokens.
2977 </p><pre class="verbatim">int i;
2978 char* url;
2979
2980 gnutls_global_init();
2981
2982 for (i=0;;i++) {
2983         ret = gnutls_pkcs11_token_get_url(i, &amp;url);
2984         if (ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
2985                 break;
2986
2987         if (ret &lt; 0)
2988                 exit(1);
2989
2990         fprintf(stdout, &quot;Token[%d]: URL: %s\n&quot;, i, url);
2991         gnutls_free(url);
2992 }
2993 gnutls_global_deinit();
2994 </pre>
2995
2996 <p>The next one will list all certificates in a token, that have a corresponding
2997 private key:
2998 </p><pre class="verbatim">gnutls_pkcs11_obj_t *obj_list;
2999 unsigned int obj_list_size = 0;
3000 gnutls_datum_t cinfo;
3001 int i;
3002
3003 obj_list_size = 0;
3004 ret = gnutls_pkcs11_obj_list_import_url( obj_list, NULL, url, \
3005                         GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY);
3006 if (ret &lt; 0 &amp;&amp; ret != GNUTLS_E_SHORT_MEMORY_BUFFER)
3007         exit(1);
3008
3009 /* no error checking from now on */
3010 obj_list = malloc(sizeof(*obj_list)*obj_list_size);
3011
3012 gnutls_pkcs11_obj_list_import_url( obj_list, &amp;obj_list_size, url, flags);
3013
3014 /* now all certificates are in obj_list */
3015 for (i=0;i&lt;obj_list_size;i++) {
3016
3017         gnutls_x509_crt_init(&amp;xcrt);
3018
3019         gnutls_x509_crt_import_pkcs11(xcrt, obj_list[i]);
3020
3021         gnutls_x509_crt_print (xcrt, GNUTLS_CRT_PRINT_FULL, &amp;cinfo);
3022
3023         fprintf(stdout, &quot;cert[%d]:\n %s\n\n&quot;, cinfo.data);
3024
3025         gnutls_free(cinfo.data);
3026         gnutls_x509_crt_deinit(&amp;xcrt);
3027 }
3028 </pre>
3029
3030 <a name="Writing-Objects"></a>
3031 <h4 class="subsection">5.3.4 Writing Objects</h4>
3032
3033 <p>With <acronym>GnuTLS</acronym> you can copy existing private keys and certificates
3034 to a token. This can be achieved with the following functions
3035 </p>
3036 <ul>
3037 <li> <a href="#gnutls_005fpkcs11_005fdelete_005furl">gnutls_pkcs11_delete_url</a>: To delete an object
3038
3039 </li><li> <a href="#gnutls_005fpkcs11_005fcopy_005fx509_005fprivkey">gnutls_pkcs11_copy_x509_privkey</a>: To copy a private key to a token
3040
3041 </li><li> <a href="#gnutls_005fpkcs11_005fcopy_005fx509_005fcrt">gnutls_pkcs11_copy_x509_crt</a>: To copy a certificate to a token
3042
3043 </li></ul>
3044
3045
3046 <a name="Using-a-PKCS-_002311-token-with-TLS"></a>
3047 <h4 class="subsection">5.3.5 Using a <acronym>PKCS #11</acronym> token with TLS</h4>
3048
3049 <p>It is possible to use a <acronym>PKCS #11</acronym> token to a TLS
3050 session, as shown in <a href="#ex_003apkcs11_002dclient">ex:pkcs11-client</a>. In addition
3051 the following functions can be used to load PKCS #11 key and
3052 certificates.
3053 </p>
3054 <ul>
3055 <li> <a href="#gnutls_005fcertificate_005fset_005fx509_005ftrust_005ffile">gnutls_certificate_set_x509_trust_file</a>: If given a PKCS #11 URL will load the trusted certificates from it.
3056
3057 </li><li> <a href="#gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile">gnutls_certificate_set_x509_key_file</a>: Will also load PKCS #11 URLs for keys and certificates.
3058
3059 </li></ul>
3060
3061
3062 <hr>
3063 <a name="Abstract-data-types"></a>
3064 <div class="header">
3065 <p>
3066 Next: <a href="#Digital-signatures" accesskey="n" rel="next">Digital signatures</a>, Previous: <a href="#PKCS-_002311-tokens" accesskey="p" rel="previous">PKCS #11 tokens</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>
3067 </div>
3068 <a name="Abstract-data-types-1"></a>
3069 <h3 class="section">5.4 Abstract data types</h3>
3070 <a name="sec_003aabstract"></a><a name="index-Abstract-types"></a>
3071
3072 <p>Since there are many forms of a public or private keys supported by <acronym>GnuTLS</acronym> such as
3073 <acronym>X.509</acronym>, <acronym>OpenPGP</acronym>, or <acronym>PKCS #11</acronym> it is desirable to allow common operations
3074 on them. For these reasons the abstract <code>gnutls_privkey_t</code> and <code>gnutls_pubkey_t</code> were
3075 introduced in <code>gnutls/abstract.h</code> header. Those types are initialized using a specific type of key and then can be used to
3076 perform operations in an abstract way. For example in order for someone to sign an X.509 certificate
3077 with a key that resides in a smart he has to follow the steps below:
3078 </p>
3079 <pre class="verbatim">#inlude &lt;gnutls/abstract.h&gt;
3080 #inlude &lt;gnutls/pkcs11.h&gt;
3081
3082 void sign_cert( gnutls_x509_crt_t to_be_signed)
3083 {
3084 gnutls_pkcs11_privkey_t ca_key;
3085 gnutls_x509_crt_t ca_cert;
3086 gnutls_privkey_t abs_key;
3087
3088         /* load the PKCS #11 key and certificates */
3089         gnutls_pkcs11_privkey_init(&amp;ca_key);
3090         gnutls_pkcs11_privkey_import_url(ca_key, key_url);
3091
3092         gnutls_x509_crt_init(&amp;ca_cert);
3093         gnutls_x509_crt_import_pkcs11_url(&amp;ca_cert, cert_url);
3094
3095         /* initialize the abstract key */
3096         gnutls_privkey_init(&amp;abs_key);
3097         gnutls_privkey_import_pkcs11(abs_key, ca_key);
3098
3099         /* sign the certificate to be signed */
3100         gnutls_x509_crt_privkey_sign(to_be_signed, ca_cert, ca_key, GNUTLS_DIG_SHA1, 0);
3101 }
3102 </pre>
3103
3104 <hr>
3105 <a name="Digital-signatures"></a>
3106 <div class="header">
3107 <p>
3108 Previous: <a href="#Abstract-data-types" accesskey="p" rel="previous">Abstract data types</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>
3109 </div>
3110 <a name="Digital-Signatures"></a>
3111 <h3 class="section">5.5 Digital Signatures</h3>
3112 <a name="index-Digital-signatures"></a>
3113
3114 <p>In this section we will provide some information about digital
3115 signatures, how they work, and give the rationale for disabling some
3116 of the algorithms used.
3117 </p>
3118 <p>Digital signatures work by using somebody&rsquo;s secret key to sign some
3119 arbitrary data.  Then anybody else could use the public key of that
3120 person to verify the signature.  Since the data may be arbitrary it is
3121 not suitable input to a cryptographic digital signature algorithm. For
3122 this reason and also for performance cryptographic hash algorithms are
3123 used to preprocess the input to the signature algorithm. This works as
3124 long as it is difficult enough to generate two different messages with
3125 the same hash algorithm output. In that case the same signature could
3126 be used as a proof for both messages. Nobody wants to sign an innocent
3127 message of donating 1 euro to Greenpeace and find out that he
3128 donated 1.000.000 euros to Bad Inc.
3129 </p>
3130 <p>For a hash algorithm to be called cryptographic the following three
3131 requirements must hold:
3132 </p>
3133 <ol>
3134 <li> Preimage resistance.
3135 That means the algorithm must be one way and given the output of the
3136 hash function <em>H(x)</em>, it is impossible to calculate <em>x</em>.
3137
3138 </li><li> 2nd preimage resistance.
3139 That means that given a pair <em>x,y</em> with <em>y=H(x)</em> it is
3140 impossible to calculate an <em>x'</em> such that <em>y=H(x')</em>.
3141
3142 </li><li> Collision resistance.
3143 That means that it is impossible to calculate random <em>x</em> and
3144 <em>x'</em> such <em>H(x')=H(x)</em>.
3145 </li></ol>
3146
3147 <p>The last two requirements in the list are the most important in
3148 digital signatures. These protect against somebody who would like to
3149 generate two messages with the same hash output. When an algorithm is
3150 considered broken usually it means that the Collision resistance of
3151 the algorithm is less than brute force. Using the birthday paradox the
3152 brute force attack takes
3153 <em>2^{((hash size) / 2)}</em>
3154 operations. Today colliding certificates using the MD5 hash algorithm
3155 have been generated as shown in [WEGER] (see <a href="#Bibliography">Bibliography</a>).
3156 </p>
3157 <p>There has been cryptographic results for the SHA-1 hash algorithms as
3158 well, although they are not yet critical.  Before 2004, MD5 had a
3159 presumed collision strength of <em>2^{64}</em>, but it has been showed
3160 to have a collision strength well under <em>2^{50}</em>.  As of November
3161 2005, it is believed that SHA-1&rsquo;s collision strength is around
3162 <em>2^{63}</em>.  We consider this sufficiently hard so that we still
3163 support SHA-1.  We anticipate that SHA-256/386/512 will be used in
3164 publicly-distributed certificates in the future.  When <em>2^{63}</em>
3165 can be considered too weak compared to the computer power available
3166 sometime in the future, SHA-1 will be disabled as well.  The collision
3167 attacks on SHA-1 may also get better, given the new interest in tools
3168 for creating them.
3169 </p>
3170 <a name="Trading-Security-for-Interoperability"></a>
3171 <h4 class="subsection">5.5.1 Trading Security for Interoperability</h4>
3172
3173 <p>If you connect to a server and use GnuTLS&rsquo; functions to verify the
3174 certificate chain, and get a <a href="#GNUTLS_005fCERT_005fINSECURE_005fALGORITHM">GNUTLS_CERT_INSECURE_ALGORITHM</a>
3175 validation error (see <a href="#Verifying-X_002e509-certificate-paths">Verifying X.509 certificate paths</a>), it means
3176 that somewhere in the certificate chain there is a certificate signed
3177 using <code>RSA-MD2</code> or <code>RSA-MD5</code>.  These two digital signature
3178 algorithms are considered broken, so GnuTLS fail when attempting to
3179 verify the certificate.  In some situations, it may be useful to be
3180 able to verify the certificate chain anyway, assuming an attacker did
3181 not utilize the fact that these signatures algorithms are broken.
3182 This section will give help on how to achieve that.
3183 </p>
3184 <p>First, it is important to know that you do not have to enable any of
3185 the flags discussed here to be able to use trusted root CA
3186 certificates signed using <code>RSA-MD2</code> or <code>RSA-MD5</code>.  The only
3187 attack today is that it is possible to generate certificates with
3188 colliding signatures (collision resistance); you cannot generate a
3189 certificate that has the same signature as an already existing
3190 signature (2nd preimage resistance).
3191 </p>
3192 <p>If you are using <a href="#gnutls_005fcertificate_005fverify_005fpeers2">gnutls_certificate_verify_peers2</a> to verify the
3193 certificate chain, you can call
3194 <a href="#gnutls_005fcertificate_005fset_005fverify_005fflags">gnutls_certificate_set_verify_flags</a> with the
3195 <code>GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2</code> or
3196 <code>GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5</code> flag, as in:
3197 </p>
3198 <div class="example">
3199 <pre class="example">  gnutls_certificate_set_verify_flags (x509cred,
3200                                        GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5);
3201 </pre></div>
3202
3203 <p>This will tell the verifier algorithm to enable <code>RSA-MD5</code> when
3204 verifying the certificates.
3205 </p>
3206 <p>If you are using <a href="#gnutls_005fx509_005fcrt_005fverify">gnutls_x509_crt_verify</a> or
3207 <a href="#gnutls_005fx509_005fcrt_005flist_005fverify">gnutls_x509_crt_list_verify</a>, you can pass the
3208 <code>GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5</code> parameter directly in the
3209 <code>flags</code> parameter.
3210 </p>
3211 <p>If you are using these flags, it may also be a good idea to warn the
3212 user when verification failure occur for this reason.  The simplest is
3213 to not use the flags by default, and only fall back to using them
3214 after warning the user.  If you wish to inspect the certificate chain
3215 yourself, you can use <a href="#gnutls_005fcertificate_005fget_005fpeers">gnutls_certificate_get_peers</a> to extract
3216 the raw server&rsquo;s certificate chain, then use
3217 <a href="#gnutls_005fx509_005fcrt_005fimport">gnutls_x509_crt_import</a> to parse each of the certificates, and
3218 then use <a href="#gnutls_005fx509_005fcrt_005fget_005fsignature_005falgorithm">gnutls_x509_crt_get_signature_algorithm</a> to find out the
3219 signing algorithm used for each certificate.  If any of the
3220 intermediary certificates are using <code>GNUTLS_SIGN_RSA_MD2</code> or
3221 <code>GNUTLS_SIGN_RSA_MD5</code>, you could present a warning.
3222 </p>
3223 <hr>
3224 <a name="How-to-use-TLS-in-application-protocols"></a>
3225 <div class="header">
3226 <p>
3227 Next: <a href="#How-to-use-GnuTLS-in-applications" accesskey="n" rel="next">How to use GnuTLS in applications</a>, Previous: <a href="#More-on-certificate-authentication" accesskey="p" rel="previous">More on certificate authentication</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>
3228 </div>
3229 <a name="How-To-Use-TLS-in-Application-Protocols"></a>
3230 <h2 class="chapter">6 How To Use <acronym>TLS</acronym> in Application Protocols</h2>
3231
3232 <p>This chapter is intended to provide some hints on how to use the
3233 <acronym>TLS</acronym> over simple custom made application protocols.  The
3234 discussion below mainly refers to the <em>TCP/IP</em> transport layer
3235 but may be extended to other ones too.
3236 </p>
3237 <table class="menu" border="0" cellspacing="0">
3238 <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">
3239 </td></tr>
3240 <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">
3241 </td></tr>
3242 </table>
3243
3244 <hr>
3245 <a name="Separate-ports"></a>
3246 <div class="header">
3247 <p>
3248 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>
3249 </div>
3250 <a name="Separate-Ports"></a>
3251 <h3 class="section">6.1 Separate Ports</h3>
3252
3253 <p>Traditionally <acronym>SSL</acronym> was used in application protocols by
3254 assigning a new port number for the secure services. That way two
3255 separate ports were assigned, one for the non secure sessions, and one
3256 for the secured ones. This has the benefit that if a user requests a
3257 secure session then the client will try to connect to the secure port
3258 and fail otherwise. The only possible attack with this method is a
3259 denial of service one. The most famous example of this method is the
3260 famous &ldquo;HTTP over TLS&rdquo; or <acronym>HTTPS</acronym> protocol [RFC2818] (see <a href="#Bibliography">Bibliography</a>).
3261 </p>
3262 <p>Despite its wide use, this method is not as good as it seems.  This
3263 approach starts the <acronym>TLS</acronym> Handshake procedure just after the
3264 client connects on the &mdash;so called&mdash; secure port.  That way the
3265 <acronym>TLS</acronym> protocol does not know anything about the client, and
3266 popular methods like the host advertising in HTTP do not
3267 work<a name="DOCF17" href="#FOOT17">(17)</a>.  There is no way for the client to say &ldquo;I
3268 connected to YYY server&rdquo; before the Handshake starts, so the server
3269 cannot possibly know which certificate to use.
3270 </p>
3271 <p>Other than that it requires two separate ports to run a single
3272 service, which is unnecessary complication. Due to the fact that there
3273 is a limitation on the available privileged ports, this approach was
3274 soon obsoleted.
3275 </p>
3276 <hr>
3277 <a name="Upward-negotiation"></a>
3278 <div class="header">
3279 <p>
3280 Previous: <a href="#Separate-ports" accesskey="p" rel="previous">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>
3281 </div>
3282 <a name="Upward-Negotiation"></a>
3283 <h3 class="section">6.2 Upward Negotiation</h3>
3284
3285 <p>Other application protocols<a name="DOCF18" href="#FOOT18">(18)</a>  use a
3286 different approach to enable the secure layer.  They use something
3287 called the &ldquo;TLS upgrade&rdquo; method. This method is quite tricky but it
3288 is more flexible. The idea is to extend the application protocol to
3289 have a &ldquo;STARTTLS&rdquo; request, whose purpose it to start the TLS
3290 protocols just after the client requests it.  This is a really neat
3291 idea and does not require an extra port.
3292 </p>
3293 <p>This method is used by almost all modern protocols and there is even
3294 the [RFC2817] (see <a href="#Bibliography">Bibliography</a>) paper which proposes extensions to HTTP to support
3295 it.
3296 </p>
3297 <p>The tricky part, in this method, is that the &ldquo;STARTTLS&rdquo; request is
3298 sent in the clear, thus is vulnerable to modifications.  A typical
3299 attack is to modify the messages in a way that the client is fooled
3300 and thinks that the server does not have the &ldquo;STARTTLS&rdquo; capability.
3301 See a typical conversation of a hypothetical protocol:
3302 </p>
3303 <blockquote>
3304 <p>(client connects to the server)
3305 </p>
3306 <p>CLIENT: HELLO I&rsquo;M MR. XXX
3307 </p>
3308 <p>SERVER: NICE TO MEET YOU XXX
3309 </p>
3310 <p>CLIENT: PLEASE START TLS
3311 </p>
3312 <p>SERVER: OK
3313 </p>
3314 <p>*** TLS STARTS
3315 </p>
3316 <p>CLIENT: HERE ARE SOME CONFIDENTIAL DATA
3317 </p></blockquote>
3318
3319 <p>And see an example of a conversation where someone is acting
3320 in between:
3321 </p>
3322 <blockquote>
3323 <p>(client connects to the server)
3324 </p>
3325 <p>CLIENT: HELLO I&rsquo;M MR. XXX
3326 </p>
3327 <p>SERVER: NICE TO MEET YOU XXX
3328 </p>
3329 <p>CLIENT: PLEASE START TLS
3330 </p>
3331 <p>(here someone inserts this message)
3332 </p>
3333 <p>SERVER: SORRY I DON&rsquo;T HAVE THIS CAPABILITY
3334 </p>
3335 <p>CLIENT: HERE ARE SOME CONFIDENTIAL DATA
3336 </p></blockquote>
3337
3338 <p>As you can see above the client was fooled, and was dummy enough to
3339 send the confidential data in the clear.
3340 </p>
3341 <p>How to avoid the above attack? As you may have already thought this
3342 one is easy to avoid. The client has to ask the user before it
3343 connects whether the user requests <acronym>TLS</acronym> or not. If the user
3344 answered that he certainly wants the secure layer the last
3345 conversation should be:
3346 </p>
3347 <blockquote>
3348 <p>(client connects to the server)
3349 </p>
3350 <p>CLIENT: HELLO I&rsquo;M MR. XXX
3351 </p>
3352 <p>SERVER: NICE TO MEET YOU XXX
3353 </p>
3354 <p>CLIENT: PLEASE START TLS
3355 </p>
3356 <p>(here someone inserts this message)
3357 </p>
3358 <p>SERVER: SORRY I DON&rsquo;T HAVE THIS CAPABILITY
3359 </p>
3360 <p>CLIENT: BYE
3361 </p>
3362 <p>(the client notifies the user that the secure connection was not possible)
3363 </p></blockquote>
3364
3365 <p>This method, if implemented properly, is far better than the
3366 traditional method, and the security properties remain the same, since
3367 only denial of service is possible. The benefit is that the server may
3368 request additional data before the <acronym>TLS</acronym> Handshake protocol
3369 starts, in order to send the correct certificate, use the correct
3370 password file<a name="DOCF19" href="#FOOT19">(19)</a>, or anything
3371 else!
3372 </p>
3373 <hr>
3374 <a name="How-to-use-GnuTLS-in-applications"></a>
3375 <div class="header">
3376 <p>
3377 Next: <a href="#Included-programs" accesskey="n" rel="next">Included programs</a>, Previous: <a href="#How-to-use-TLS-in-application-protocols" accesskey="p" rel="previous">How to use TLS in application protocols</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>
3378 </div>
3379 <a name="How-To-Use-GnuTLS-in-Applications"></a>
3380 <h2 class="chapter">7 How To Use <acronym>GnuTLS</acronym> in Applications</h2>
3381 <a name="examples"></a><a name="index-Example-programs"></a>
3382
3383 <table class="menu" border="0" cellspacing="0">
3384 <tr><td align="left" valign="top">&bull; <a href="#Preparation" accesskey="1">Preparation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3385 </td></tr>
3386 <tr><td align="left" valign="top">&bull; <a href="#Multi_002dthreaded-applications" accesskey="2">Multi-threaded applications</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3387 </td></tr>
3388 <tr><td align="left" valign="top">&bull; <a href="#Client-examples" accesskey="3">Client examples</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3389 </td></tr>
3390 <tr><td align="left" valign="top">&bull; <a href="#Server-examples" accesskey="4">Server examples</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3391 </td></tr>
3392 <tr><td align="left" valign="top">&bull; <a href="#Miscellaneous-examples" accesskey="5">Miscellaneous examples</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3393 </td></tr>
3394 <tr><td align="left" valign="top">&bull; <a href="#Parameter-generation" accesskey="6">Parameter generation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3395 </td></tr>
3396 <tr><td align="left" valign="top">&bull; <a href="#Keying-Material-Exporters" accesskey="7">Keying Material Exporters</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3397 </td></tr>
3398 <tr><td align="left" valign="top">&bull; <a href="#Channel-Bindings" accesskey="8">Channel Bindings</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3399 </td></tr>
3400 <tr><td align="left" valign="top">&bull; <a href="#Compatibility-with-the-OpenSSL-library" accesskey="9">Compatibility with the OpenSSL library</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3401 </td></tr>
3402 </table>
3403
3404 <hr>
3405 <a name="Preparation"></a>
3406 <div class="header">
3407 <p>
3408 Next: <a href="#Multi_002dthreaded-applications" accesskey="n" rel="next">Multi-threaded applications</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>
3409 </div>
3410 <a name="Preparation-1"></a>
3411 <h3 class="section">7.1 Preparation</h3>
3412
3413 <p>To use <acronym>GnuTLS</acronym>, you have to perform some changes to your
3414 sources and your build system. The necessary changes are explained in
3415 the following subsections.
3416 </p>
3417 <table class="menu" border="0" cellspacing="0">
3418 <tr><td align="left" valign="top">&bull; <a href="#Headers" accesskey="1">Headers</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3419 </td></tr>
3420 <tr><td align="left" valign="top">&bull; <a href="#Initialization" accesskey="2">Initialization</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3421 </td></tr>
3422 <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">
3423 </td></tr>
3424 <tr><td align="left" valign="top">&bull; <a href="#Debugging" accesskey="4">Debugging</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3425 </td></tr>
3426 <tr><td align="left" valign="top">&bull; <a href="#Building-the-source" accesskey="5">Building the source</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3427 </td></tr>
3428 </table>
3429
3430 <hr>
3431 <a name="Headers"></a>
3432 <div class="header">
3433 <p>
3434 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>
3435 </div>
3436 <a name="Headers-1"></a>
3437 <h4 class="subsection">7.1.1 Headers</h4>
3438
3439 <p>All the data types and functions of the <acronym>GnuTLS</acronym> library are
3440 defined in the header file &lsquo;<tt>gnutls/gnutls.h</tt>&rsquo;.  This must be
3441 included in all programs that make use of the <acronym>GnuTLS</acronym>
3442 library.
3443 </p>
3444 <p>The extra functionality of the <acronym>GnuTLS-extra</acronym> library is
3445 available by including the header file &lsquo;<tt>gnutls/extra.h</tt>&rsquo; in your
3446 programs.
3447 </p>
3448 <hr>
3449 <a name="Initialization"></a>
3450 <div class="header">
3451 <p>
3452 Next: <a href="#Version-check" accesskey="n" rel="next">Version check</a>, Previous: <a href="#Headers" accesskey="p" rel="previous">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>
3453 </div>
3454 <a name="Initialization-2"></a>
3455 <h4 class="subsection">7.1.2 Initialization</h4>
3456
3457 <p>GnuTLS must be initialized before it can be used.  The library is
3458 initialized by calling <a href="#gnutls_005fglobal_005finit">gnutls_global_init</a>.  The resources
3459 allocated by the initialization process can be released if the
3460 application no longer has a need to call GnuTLS functions, this is
3461 done by calling <a href="#gnutls_005fglobal_005fdeinit">gnutls_global_deinit</a>.
3462 </p>
3463 <p>The extra functionality of the <acronym>GnuTLS-extra</acronym> library is
3464 available after calling <a href="#gnutls_005fglobal_005finit_005fextra">gnutls_global_init_extra</a>.
3465 </p>
3466 <p>In order to take advantage of the internationalisation features in
3467 GnuTLS, such as translated error messages, the application must set
3468 the current locale using <code>setlocale</code> before initializing GnuTLS.
3469 </p>
3470 <hr>
3471 <a name="Version-check"></a>
3472 <div class="header">
3473 <p>
3474 Next: <a href="#Debugging" accesskey="n" rel="next">Debugging</a>, Previous: <a href="#Initialization" accesskey="p" rel="previous">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>
3475 </div>
3476 <a name="Version-Check"></a>
3477 <h4 class="subsection">7.1.3 Version Check</h4>
3478
3479 <p>It is often desirable to check that the version of &lsquo;gnutls&rsquo; used is
3480 indeed one which fits all requirements.  Even with binary
3481 compatibility new features may have been introduced but due to problem
3482 with the dynamic linker an old version is actually used.  So you may
3483 want to check that the version is okay right after program startup.
3484 See the function <a href="#gnutls_005fcheck_005fversion">gnutls_check_version</a>.
3485 </p>
3486 <hr>
3487 <a name="Debugging"></a>
3488 <div class="header">
3489 <p>
3490 Next: <a href="#Building-the-source" accesskey="n" rel="next">Building the source</a>, Previous: <a href="#Version-check" accesskey="p" rel="previous">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>
3491 </div>
3492 <a name="Debugging-1"></a>
3493 <h4 class="subsection">7.1.4 Debugging</h4>
3494
3495 <p>In many cases things may not go as expected and further information,
3496 to assist debugging, from <acronym>GnuTLS</acronym> is desired. Those are the
3497 case where the <a href="#gnutls_005fglobal_005fset_005flog_005flevel">gnutls_global_set_log_level</a> and
3498 <a href="#gnutls_005fglobal_005fset_005flog_005ffunction">gnutls_global_set_log_function</a> are to be used. Those will print
3499 verbose information on the <acronym>GnuTLS</acronym> functions internal flow.
3500 </p>
3501 <hr>
3502 <a name="Building-the-source"></a>
3503 <div class="header">
3504 <p>
3505 Previous: <a href="#Debugging" accesskey="p" rel="previous">Debugging</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>
3506 </div>
3507 <a name="Building-the-Source"></a>
3508 <h4 class="subsection">7.1.5 Building the Source</h4>
3509
3510 <p>If you want to compile a source file including the
3511 &lsquo;<tt>gnutls/gnutls.h</tt>&rsquo; header file, you must make sure that the
3512 compiler can find it in the directory hierarchy.  This is accomplished
3513 by adding the path to the directory in which the header file is
3514 located to the compilers include file search path (via the &lsquo;<samp>-I</samp>&rsquo;
3515 option).
3516 </p>
3517 <p>However, the path to the include file is determined at the time the
3518 source is configured.  To solve this problem, the library uses the
3519 external package <code>pkg-config</code> that knows the path to the
3520 include file and other configuration options.  The options that need
3521 to be added to the compiler invocation at compile time are output by
3522 the &lsquo;<samp>--cflags</samp>&rsquo; option to <code>pkg-config gnutls</code>.  The
3523 following example shows how it can be used at the command line:
3524 </p>
3525 <div class="example">
3526 <pre class="example">gcc -c foo.c `pkg-config gnutls --cflags`
3527 </pre></div>
3528
3529 <p>Adding the output of &lsquo;<samp>pkg-config gnutls --cflags</samp>&rsquo; to the
3530 compilers command line will ensure that the compiler can find the
3531 &lsquo;<tt>gnutls/gnutls.h</tt>&rsquo; header file.
3532 </p>
3533 <p>A similar problem occurs when linking the program with the library.
3534 Again, the compiler has to find the library files.  For this to work,
3535 the path to the library files has to be added to the library search
3536 path (via the &lsquo;<samp>-L</samp>&rsquo; option).  For this, the option
3537 &lsquo;<samp>--libs</samp>&rsquo; to <code>pkg-config gnutls</code> can be used.  For
3538 convenience, this option also outputs all other options that are
3539 required to link the program with the libarary (for instance, the
3540 &lsquo;<samp>-ltasn1</samp>&rsquo; option).  The example shows how to link &lsquo;<tt>foo.o</tt>&rsquo;
3541 with the library to a program <code>foo</code>.
3542 </p>
3543 <div class="example">
3544 <pre class="example">gcc -o foo foo.o `pkg-config gnutls --libs`
3545 </pre></div>
3546
3547 <p>Of course you can also combine both examples to a single command by
3548 specifying both options to <code>pkg-config</code>:
3549 </p>
3550 <div class="example">
3551 <pre class="example">gcc -o foo foo.c `pkg-config gnutls --cflags --libs`
3552 </pre></div>
3553
3554 <hr>
3555 <a name="Multi_002dthreaded-applications"></a>
3556 <div class="header">
3557 <p>
3558 Next: <a href="#Client-examples" accesskey="n" rel="next">Client examples</a>, Previous: <a href="#Preparation" accesskey="p" rel="previous">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>
3559 </div>
3560 <a name="Multi_002dThreaded-Applications"></a>
3561 <h3 class="section">7.2 Multi-Threaded Applications</h3>
3562
3563 <p>Although the <acronym>GnuTLS</acronym> library is thread safe by design, some
3564 parts of the cryptographic backend, such as the random generator, are not.
3565 Applications can either call <a href="#gnutls_005fglobal_005finit">gnutls_global_init</a> and use the default
3566 operating system provided locks (i.e. <code>pthreads</code> on GNU/Linux), or
3567 specify manualy the locking system using the function <a href="#gnutls_005fglobal_005fset_005fmutex">gnutls_global_set_mutex</a>
3568 before calling <a href="#gnutls_005fglobal_005finit">gnutls_global_init</a>. Setting manually mutexes is recommended
3569 only to applications that have full control of the underlying libraries. If this
3570 is not the case, the use of the operating system defaults is recommended.
3571 </p>
3572
3573 <p>There are helper macros to help you properly initialize the libraries.
3574 Examples are shown below.
3575 </p>
3576 <ul>
3577 <li> POSIX threads in GNU/Linux
3578 <div class="example">
3579 <pre class="example">#include &lt;gnutls.h&gt;
3580 #include &lt;errno.h&gt;
3581 #include &lt;pthread.h&gt;
3582
3583 int main()
3584 {
3585    gnutls_global_init();
3586 }
3587 </pre></div>
3588
3589 </li><li> Other thread packages
3590 <div class="example">
3591 <pre class="example">
3592 int main()
3593 {
3594    gnutls_global_mutex_set (mutex_init, mutex_deinit, mutex_lock, mutex_unlock);
3595    gnutls_global_init();
3596 }
3597 </pre></div>
3598 </li></ul>
3599
3600 <hr>
3601 <a name="Client-examples"></a>
3602 <div class="header">
3603 <p>
3604 Next: <a href="#Server-examples" accesskey="n" rel="next">Server examples</a>, Previous: <a href="#Multi_002dthreaded-applications" accesskey="p" rel="previous">Multi-threaded applications</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>
3605 </div>
3606 <a name="Client-Examples"></a>
3607 <h3 class="section">7.3 Client Examples</h3>
3608
3609 <p>This section contains examples of <acronym>TLS</acronym> and <acronym>SSL</acronym>
3610 clients, using <acronym>GnuTLS</acronym>.  Note that these examples contain
3611 little or no error checking.  Some of the examples require functions
3612 implemented by another example.
3613 </p>
3614 <table class="menu" border="0" cellspacing="0">
3615 <tr><td align="left" valign="top">&bull; <a href="#Simple-client-example-with-anonymous-authentication" accesskey="1">Simple client example with anonymous authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3616 </td></tr>
3617 <tr><td align="left" valign="top">&bull; <a href="#Simple-client-example-with-X_002e509-certificate-support" accesskey="2">Simple client example with X.509 certificate support</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3618 </td></tr>
3619 <tr><td align="left" valign="top">&bull; <a href="#Obtaining-session-information" accesskey="3">Obtaining session information</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3620 </td></tr>
3621 <tr><td align="left" valign="top">&bull; <a href="#Verifying-peer_0027s-certificate" accesskey="4">Verifying peer's certificate</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3622 </td></tr>
3623 <tr><td align="left" valign="top">&bull; <a href="#Using-a-callback-to-select-the-certificate-to-use" accesskey="5">Using a callback to select the certificate to use</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3624 </td></tr>
3625 <tr><td align="left" valign="top">&bull; <a href="#Client-using-a-PKCS-_002311-token-with-TLS" accesskey="6">Client using a PKCS #11 token with TLS</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3626 </td></tr>
3627 <tr><td align="left" valign="top">&bull; <a href="#Client-with-Resume-capability-example" accesskey="7">Client with Resume capability example</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3628 </td></tr>
3629 <tr><td align="left" valign="top">&bull; <a href="#Simple-client-example-with-SRP-authentication" accesskey="8">Simple client example with SRP authentication</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3630 </td></tr>
3631 <tr><td align="left" valign="top">&bull; <a href="#Simple-client-example-in-C_002b_002b" accesskey="9">Simple client example in C++</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3632 </td></tr>
3633 <tr><td align="left" valign="top">&bull; <a href="#Helper-function-for-TCP-connections">Helper function for TCP connections</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3634 </td></tr>
3635 </table>
3636
3637 <hr>
3638 <a name="Simple-client-example-with-anonymous-authentication"></a>
3639 <div class="header">
3640 <p>
3641 Next: <a href="#Simple-client-example-with-X_002e509-certificate-support" accesskey="n" rel="next">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>
3642 </div>
3643 <a name="Simple-Client-Example-with-Anonymous-Authentication"></a>
3644 <h4 class="subsection">7.3.1 Simple Client Example with Anonymous Authentication</h4>
3645
3646 <p>The simplest client using TLS is the one that doesn&rsquo;t do any
3647 authentication.  This means no external certificates or passwords are
3648 needed to set up the connection.  As could be expected, the connection
3649 is vulnerable to man-in-the-middle (active or redirection) attacks.
3650 However, the data is integrity and privacy protected.
3651 </p>
3652 <pre class="verbatim">/* This example code is placed in the public domain. */
3653
3654 #ifdef HAVE_CONFIG_H
3655 #include &lt;config.h&gt;
3656 #endif
3657
3658 #include &lt;stdio.h&gt;
3659 #include &lt;stdlib.h&gt;
3660 #include &lt;string.h&gt;
3661 #include &lt;sys/types.h&gt;
3662 #include &lt;sys/socket.h&gt;
3663 #include &lt;arpa/inet.h&gt;
3664 #include &lt;unistd.h&gt;
3665 #include &lt;gnutls/gnutls.h&gt;
3666
3667 /* A very basic TLS client, with anonymous authentication.
3668  */
3669
3670 #define MAX_BUF 1024
3671 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
3672
3673 extern int tcp_connect (void);
3674 extern void tcp_close (int sd);
3675
3676 int
3677 main (void)
3678 {
3679   int ret, sd, ii;
3680   gnutls_session_t session;
3681   char buffer[MAX_BUF + 1];
3682   gnutls_anon_client_credentials_t anoncred;
3683   /* Need to enable anonymous KX specifically. */
3684
3685   gnutls_global_init ();
3686
3687   gnutls_anon_allocate_client_credentials (&amp;anoncred);
3688
3689   /* Initialize TLS session
3690    */
3691   gnutls_init (&amp;session, GNUTLS_CLIENT);
3692
3693   /* Use default priorities */
3694   gnutls_priority_set_direct (session, &quot;PERFORMANCE:+ANON-DH:!ARCFOUR-128&quot;,
3695                               NULL);
3696
3697   /* put the anonymous credentials to the current session
3698    */
3699   gnutls_credentials_set (session, GNUTLS_CRD_ANON, anoncred);
3700
3701   /* connect to the peer
3702    */
3703   sd = tcp_connect ();
3704
3705   gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd);
3706
3707   /* Perform the TLS handshake
3708    */
3709   ret = gnutls_handshake (session);
3710
3711   if (ret &lt; 0)
3712     {
3713       fprintf (stderr, &quot;*** Handshake failed\n&quot;);
3714       gnutls_perror (ret);
3715       goto end;
3716     }
3717   else
3718     {
3719       printf (&quot;- Handshake was completed\n&quot;);
3720     }
3721
3722   gnutls_record_send (session, MSG, strlen (MSG));
3723
3724   ret = gnutls_record_recv (session, buffer, MAX_BUF);
3725   if (ret == 0)
3726     {
3727       printf (&quot;- Peer has closed the TLS connection\n&quot;);
3728       goto end;
3729     }
3730   else if (ret &lt; 0)
3731     {
3732       fprintf (stderr, &quot;*** Error: %s\n&quot;, gnutls_strerror (ret));
3733       goto end;
3734     }
3735
3736   printf (&quot;- Received %d bytes: &quot;, ret);
3737   for (ii = 0; ii &lt; ret; ii++)
3738     {
3739       fputc (buffer[ii], stdout);
3740     }
3741   fputs (&quot;\n&quot;, stdout);
3742
3743   gnutls_bye (session, GNUTLS_SHUT_RDWR);
3744
3745 end:
3746
3747   tcp_close (sd);
3748
3749   gnutls_deinit (session);
3750
3751   gnutls_anon_free_client_credentials (anoncred);
3752
3753   gnutls_global_deinit ();
3754
3755   return 0;
3756 }
3757 </pre>
3758 <hr>
3759 <a name="Simple-client-example-with-X_002e509-certificate-support"></a>
3760 <div class="header">
3761 <p>
3762 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="previous">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>
3763 </div>
3764 <a name="Simple-Client-Example-with-X_002e509-Certificate-Support"></a>
3765 <h4 class="subsection">7.3.2 Simple Client Example with <acronym>X.509</acronym> Certificate Support</h4>
3766
3767 <p>Let&rsquo;s assume now that we want to create a TCP client which
3768 communicates with servers that use <acronym>X.509</acronym> or
3769 <acronym>OpenPGP</acronym> certificate authentication. The following client is
3770 a very simple <acronym>TLS</acronym> client, it does not support session
3771 resuming, not even certificate verification. The TCP functions defined
3772 in this example are used in most of the other examples below, without
3773 redefining them.
3774 </p>
3775 <pre class="verbatim">/* This example code is placed in the public domain. */
3776
3777 #ifdef HAVE_CONFIG_H
3778 #include &lt;config.h&gt;
3779 #endif
3780
3781 #include &lt;stdio.h&gt;
3782 #include &lt;stdlib.h&gt;
3783 #include &lt;string.h&gt;
3784 #include &lt;sys/types.h&gt;
3785 #include &lt;sys/socket.h&gt;
3786 #include &lt;arpa/inet.h&gt;
3787 #include &lt;unistd.h&gt;
3788 #include &lt;gnutls/gnutls.h&gt;
3789
3790 /* A very basic TLS client, with X.509 authentication.
3791  */
3792
3793 #define MAX_BUF 1024
3794 #define CAFILE &quot;ca.pem&quot;
3795 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
3796
3797 extern int tcp_connect (void);
3798 extern void tcp_close (int sd);
3799
3800 int
3801 main (void)
3802 {
3803   int ret, sd, ii;
3804   gnutls_session_t session;
3805   char buffer[MAX_BUF + 1];
3806   const char *err;
3807   gnutls_certificate_credentials_t xcred;
3808
3809   gnutls_global_init ();
3810
3811   /* X509 stuff */
3812   gnutls_certificate_allocate_credentials (&amp;xcred);
3813
3814   /* sets the trusted cas file
3815    */
3816   gnutls_certificate_set_x509_trust_file (xcred, CAFILE, GNUTLS_X509_FMT_PEM);
3817
3818   /* Initialize TLS session
3819    */
3820   gnutls_init (&amp;session, GNUTLS_CLIENT);
3821
3822   /* Use default priorities */
3823   ret = gnutls_priority_set_direct (session, &quot;PERFORMANCE&quot;, &amp;err);
3824   if (ret &lt; 0)
3825     {
3826       if (ret == GNUTLS_E_INVALID_REQUEST)
3827         {
3828           fprintf (stderr, &quot;Syntax error at: %s\n&quot;, err);
3829         }
3830       exit (1);
3831     }
3832
3833   /* put the x509 credentials to the current session
3834    */
3835   gnutls_credentials_set (session, GNUTLS_CRD_CERTIFICATE, xcred);
3836
3837   /* connect to the peer
3838    */
3839   sd = tcp_connect ();
3840
3841   gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd);
3842
3843   /* Perform the TLS handshake
3844    */
3845   ret = gnutls_handshake (session);
3846
3847   if (ret &lt; 0)
3848     {
3849       fprintf (stderr, &quot;*** Handshake failed\n&quot;);
3850       gnutls_perror (ret);
3851       goto end;
3852     }
3853   else
3854     {
3855       printf (&quot;- Handshake was completed\n&quot;);
3856     }
3857
3858   gnutls_record_send (session, MSG, strlen (MSG));
3859
3860   ret = gnutls_record_recv (session, buffer, MAX_BUF);
3861   if (ret == 0)
3862     {
3863       printf (&quot;- Peer has closed the TLS connection\n&quot;);
3864       goto end;
3865     }
3866   else if (ret &lt; 0)
3867     {
3868       fprintf (stderr, &quot;*** Error: %s\n&quot;, gnutls_strerror (ret));
3869       goto end;
3870     }
3871
3872   printf (&quot;- Received %d bytes: &quot;, ret);
3873   for (ii = 0; ii &lt; ret; ii++)
3874     {
3875       fputc (buffer[ii], stdout);
3876     }
3877   fputs (&quot;\n&quot;, stdout);
3878
3879   gnutls_bye (session, GNUTLS_SHUT_RDWR);
3880
3881 end:
3882
3883   tcp_close (sd);
3884
3885   gnutls_deinit (session);
3886
3887   gnutls_certificate_free_credentials (xcred);
3888
3889   gnutls_global_deinit ();
3890
3891   return 0;
3892 }
3893 </pre>
3894 <hr>
3895 <a name="Obtaining-session-information"></a>
3896 <div class="header">
3897 <p>
3898 Next: <a href="#Verifying-peer_0027s-certificate" accesskey="n" rel="next">Verifying peer's certificate</a>, Previous: <a href="#Simple-client-example-with-X_002e509-certificate-support" accesskey="p" rel="previous">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>
3899 </div>
3900 <a name="Obtaining-Session-Information"></a>
3901 <h4 class="subsection">7.3.3 Obtaining Session Information</h4>
3902
3903 <p>Most of the times it is desirable to know the security properties of
3904 the current established session.  This includes the underlying ciphers
3905 and the protocols involved.  That is the purpose of the following
3906 function.  Note that this function will print meaningful values only
3907 if called after a successful <a href="#gnutls_005fhandshake">gnutls_handshake</a>.
3908 </p>
3909 <pre class="verbatim">/* This example code is placed in the public domain. */
3910
3911 #ifdef HAVE_CONFIG_H
3912 #include &lt;config.h&gt;
3913 #endif
3914
3915 #include &lt;stdio.h&gt;
3916 #include &lt;stdlib.h&gt;
3917 #include &lt;gnutls/gnutls.h&gt;
3918 #include &lt;gnutls/x509.h&gt;
3919
3920 #include &quot;examples.h&quot;
3921
3922 /* This function will print some details of the
3923  * given session.
3924  */
3925 int
3926 print_info (gnutls_session_t session)
3927 {
3928   const char *tmp;
3929   gnutls_credentials_type_t cred;
3930   gnutls_kx_algorithm_t kx;
3931
3932   /* print the key exchange's algorithm name
3933    */
3934   kx = gnutls_kx_get (session);
3935   tmp = gnutls_kx_get_name (kx);
3936   printf (&quot;- Key Exchange: %s\n&quot;, tmp);
3937
3938   /* Check the authentication type used and switch
3939    * to the appropriate.
3940    */
3941   cred = gnutls_auth_get_type (session);
3942   switch (cred)
3943     {
3944     case GNUTLS_CRD_IA:
3945       printf (&quot;- TLS/IA session\n&quot;);
3946       break;
3947
3948
3949 #ifdef ENABLE_SRP
3950     case GNUTLS_CRD_SRP:
3951       printf (&quot;- SRP session with username %s\n&quot;,
3952               gnutls_srp_server_get_username (session));
3953       break;
3954 #endif
3955
3956     case GNUTLS_CRD_PSK:
3957       /* This returns NULL in server side.
3958        */
3959       if (gnutls_psk_client_get_hint (session) != NULL)
3960         printf (&quot;- PSK authentication. PSK hint '%s'\n&quot;,
3961                 gnutls_psk_client_get_hint (session));
3962       /* This returns NULL in client side.
3963        */
3964       if (gnutls_psk_server_get_username (session) != NULL)
3965         printf (&quot;- PSK authentication. Connected as '%s'\n&quot;,
3966                 gnutls_psk_server_get_username (session));
3967       break;
3968
3969     case GNUTLS_CRD_ANON:      /* anonymous authentication */
3970
3971       printf (&quot;- Anonymous DH using prime of %d bits\n&quot;,
3972               gnutls_dh_get_prime_bits (session));
3973       break;
3974
3975     case GNUTLS_CRD_CERTIFICATE:       /* certificate authentication */
3976
3977       /* Check if we have been using ephemeral Diffie-Hellman.
3978        */
3979       if (kx == GNUTLS_KX_DHE_RSA || kx == GNUTLS_KX_DHE_DSS)
3980         {
3981           printf (&quot;\n- Ephemeral DH using prime of %d bits\n&quot;,
3982                   gnutls_dh_get_prime_bits (session));
3983         }
3984
3985       /* if the certificate list is available, then
3986        * print some information about it.
3987        */
3988       print_x509_certificate_info (session);
3989
3990     }                           /* switch */
3991
3992   /* print the protocol's name (ie TLS 1.0)
3993    */
3994   tmp = gnutls_protocol_get_name (gnutls_protocol_get_version (session));
3995   printf (&quot;- Protocol: %s\n&quot;, tmp);
3996
3997   /* print the certificate type of the peer.
3998    * ie X.509
3999    */
4000   tmp =
4001     gnutls_certificate_type_get_name (gnutls_certificate_type_get (session));
4002
4003   printf (&quot;- Certificate Type: %s\n&quot;, tmp);
4004
4005   /* print the compression algorithm (if any)
4006    */
4007   tmp = gnutls_compression_get_name (gnutls_compression_get (session));
4008   printf (&quot;- Compression: %s\n&quot;, tmp);
4009
4010   /* print the name of the cipher used.
4011    * ie 3DES.
4012    */
4013   tmp = gnutls_cipher_get_name (gnutls_cipher_get (session));
4014   printf (&quot;- Cipher: %s\n&quot;, tmp);
4015
4016   /* Print the MAC algorithms name.
4017    * ie SHA1
4018    */
4019   tmp = gnutls_mac_get_name (gnutls_mac_get (session));
4020   printf (&quot;- MAC: %s\n&quot;, tmp);
4021
4022   return 0;
4023 }
4024 </pre>
4025 <hr>
4026 <a name="Verifying-peer_0027s-certificate"></a>
4027 <div class="header">
4028 <p>
4029 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="#Obtaining-session-information" accesskey="p" rel="previous">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>
4030 </div>
4031 <a name="Verifying-Peer_0027s-Certificate"></a>
4032 <h4 class="subsection">7.3.4 Verifying Peer&rsquo;s Certificate</h4>
4033 <a name="ex_003averify"></a>
4034 <p>A <acronym>TLS</acronym> session is not secure just after the handshake
4035 procedure has finished.  It must be considered secure, only after the
4036 peer&rsquo;s certificate and identity have been verified. That is, you have
4037 to verify the signature in peer&rsquo;s certificate, the hostname in the
4038 certificate, and expiration dates.  Just after this step you should
4039 treat the connection as being a secure one.
4040 </p>
4041 <pre class="verbatim">/* This example code is placed in the public domain. */
4042
4043 #ifdef HAVE_CONFIG_H
4044 #include &lt;config.h&gt;
4045 #endif
4046
4047 #include &lt;stdio.h&gt;
4048 #include &lt;stdlib.h&gt;
4049 #include &lt;string.h&gt;
4050 #include &lt;gnutls/gnutls.h&gt;
4051 #include &lt;gnutls/x509.h&gt;
4052 #include &quot;examples.h&quot;
4053
4054 /* A very basic TLS client, with X.509 authentication and server certificate
4055  * verification.
4056  */
4057
4058 #define MAX_BUF 1024
4059 #define CAFILE &quot;ca.pem&quot;
4060 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
4061
4062 extern int tcp_connect (void);
4063 extern void tcp_close (int sd);
4064
4065 /* This function will try to verify the peer's certificate, and
4066  * also check if the hostname matches, and the activation, expiration dates.
4067  */
4068 static int
4069 verify_certificate_callback (gnutls_session_t session)
4070 {
4071   unsigned int status;
4072   const gnutls_datum_t *cert_list;
4073   unsigned int cert_list_size;
4074   int ret;
4075   gnutls_x509_crt_t cert;
4076   const char *hostname;
4077
4078   /* read hostname */
4079   hostname = gnutls_session_get_ptr (session);
4080
4081   /* This verification function uses the trusted CAs in the credentials
4082    * structure. So you must have installed one or more CA certificates.
4083    */
4084   ret = gnutls_certificate_verify_peers2 (session, &amp;status);
4085   if (ret &lt; 0)
4086     {
4087       printf (&quot;Error\n&quot;);
4088       return GNUTLS_E_CERTIFICATE_ERROR;
4089     }
4090
4091   if (status &amp; GNUTLS_CERT_INVALID)
4092     printf (&quot;The certificate is not trusted.\n&quot;);
4093
4094   if (status &amp; GNUTLS_CERT_SIGNER_NOT_FOUND)
4095     printf (&quot;The certificate hasn't got a known issuer.\n&quot;);
4096
4097   if (status &amp; GNUTLS_CERT_REVOKED)
4098     printf (&quot;The certificate has been revoked.\n&quot;);
4099
4100   if (status &amp; GNUTLS_CERT_EXPIRED)
4101     printf (&quot;The certificate has expired\n&quot;);
4102
4103   if (status &amp; GNUTLS_CERT_NOT_ACTIVATED)
4104     printf (&quot;The certificate is not yet activated\n&quot;);
4105
4106   /* Up to here the process is the same for X.509 certificates and
4107    * OpenPGP keys. From now on X.509 certificates are assumed. This can
4108    * be easily extended to work with openpgp keys as well.
4109    */
4110   if (gnutls_certificate_type_get (session) != GNUTLS_CRT_X509)
4111     return GNUTLS_E_CERTIFICATE_ERROR;
4112
4113   if (gnutls_x509_crt_init (&amp;cert) &lt; 0)
4114     {
4115       printf (&quot;error in initialization\n&quot;);
4116       return GNUTLS_E_CERTIFICATE_ERROR;
4117     }
4118
4119   cert_list = gnutls_certificate_get_peers (session, &amp;cert_list_size);
4120   if (cert_list == NULL)
4121     {
4122       printf (&quot;No certificate was found!\n&quot;);
4123       return GNUTLS_E_CERTIFICATE_ERROR;
4124     }
4125
4126   /* This is not a real world example, since we only check the first
4127    * certificate in the given chain.
4128    */
4129   if (gnutls_x509_crt_import (cert, &amp;cert_list[0], GNUTLS_X509_FMT_DER) &lt; 0)
4130     {
4131       printf (&quot;error parsing certificate\n&quot;);
4132       return GNUTLS_E_CERTIFICATE_ERROR;
4133     }
4134
4135
4136   if (!gnutls_x509_crt_check_hostname (cert, hostname))
4137     {
4138       printf (&quot;The certificate's owner does not match hostname '%s'\n&quot;,
4139               hostname);
4140       return GNUTLS_E_CERTIFICATE_ERROR;
4141     }
4142
4143   gnutls_x509_crt_deinit (cert);
4144
4145   /* notify gnutls to continue handshake normally */
4146   return 0;
4147 }
4148
4149
4150 int
4151 main (void)
4152 {
4153   int ret, sd, ii;
4154   gnutls_session_t session;
4155   char buffer[MAX_BUF + 1];
4156   const char *err;
4157   gnutls_certificate_credentials_t xcred;
4158
4159   gnutls_global_init ();
4160
4161   /* X509 stuff */
4162   gnutls_certificate_allocate_credentials (&amp;xcred);
4163
4164   /* sets the trusted cas file
4165    */
4166   gnutls_certificate_set_x509_trust_file (xcred, CAFILE, GNUTLS_X509_FMT_PEM);
4167   gnutls_certificate_set_verify_function (xcred, verify_certificate_callback);
4168   gnutls_certificate_set_verify_flags (xcred,
4169                                        GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT);
4170
4171   /* Initialize TLS session
4172    */
4173   gnutls_init (&amp;session, GNUTLS_CLIENT);
4174
4175   gnutls_session_set_ptr (session, (void *) &quot;my_host_name&quot;);
4176
4177   /* Use default priorities */
4178   ret = gnutls_priority_set_direct (session, &quot;PERFORMANCE&quot;, &amp;err);
4179   if (ret &lt; 0)
4180     {
4181       if (ret == GNUTLS_E_INVALID_REQUEST)
4182         {
4183           fprintf (stderr, &quot;Syntax error at: %s\n&quot;, err);
4184         }
4185       exit (1);
4186     }
4187
4188   /* put the x509 credentials to the current session
4189    */
4190   gnutls_credentials_set (session, GNUTLS_CRD_CERTIFICATE, xcred);
4191
4192   /* connect to the peer
4193    */
4194   sd = tcp_connect ();
4195
4196   gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd);
4197
4198   /* Perform the TLS handshake
4199    */
4200   ret = gnutls_handshake (session);
4201
4202   if (ret &lt; 0)
4203     {
4204       fprintf (stderr, &quot;*** Handshake failed\n&quot;);
4205       gnutls_perror (ret);
4206       goto end;
4207     }
4208   else
4209     {
4210       printf (&quot;- Handshake was completed\n&quot;);
4211     }
4212
4213   gnutls_record_send (session, MSG, strlen (MSG));
4214
4215   ret = gnutls_record_recv (session, buffer, MAX_BUF);
4216   if (ret == 0)
4217     {
4218       printf (&quot;- Peer has closed the TLS connection\n&quot;);
4219       goto end;
4220     }
4221   else if (ret &lt; 0)
4222     {
4223       fprintf (stderr, &quot;*** Error: %s\n&quot;, gnutls_strerror (ret));
4224       goto end;
4225     }
4226
4227   printf (&quot;- Received %d bytes: &quot;, ret);
4228   for (ii = 0; ii &lt; ret; ii++)
4229     {
4230       fputc (buffer[ii], stdout);
4231     }
4232   fputs (&quot;\n&quot;, stdout);
4233
4234   gnutls_bye (session, GNUTLS_SHUT_RDWR);
4235
4236 end:
4237
4238   tcp_close (sd);
4239
4240   gnutls_deinit (session);
4241
4242   gnutls_certificate_free_credentials (xcred);
4243
4244   gnutls_global_deinit ();
4245
4246   return 0;
4247 }
4248 </pre>
4249 <p>Another example is listed below which provides more detailed
4250 verification output, for applications that need it.
4251 </p>
4252 <pre class="verbatim">/* This example code is placed in the public domain. */
4253
4254 #ifdef HAVE_CONFIG_H
4255 #include &lt;config.h&gt;
4256 #endif
4257
4258 #include &lt;stdio.h&gt;
4259 #include &lt;stdlib.h&gt;
4260 #include &lt;gnutls/gnutls.h&gt;
4261 #include &lt;gnutls/x509.h&gt;
4262
4263 #include &quot;examples.h&quot;
4264
4265 /* All the available CRLs
4266  */
4267 gnutls_x509_crl_t *crl_list;
4268 int crl_list_size;
4269
4270 /* All the available trusted CAs
4271  */
4272 gnutls_x509_crt_t *ca_list;
4273 int ca_list_size;
4274
4275 static void verify_cert2 (gnutls_x509_crt_t crt,
4276                           gnutls_x509_crt_t issuer,
4277                           gnutls_x509_crl_t * crl_list, int crl_list_size);
4278 static void verify_last_cert (gnutls_x509_crt_t crt,
4279                               gnutls_x509_crt_t * ca_list, int ca_list_size,
4280                               gnutls_x509_crl_t * crl_list,
4281                               int crl_list_size);
4282
4283
4284 /* This function will try to verify the peer's certificate chain, and
4285  * also check if the hostname matches, and the activation, expiration dates.
4286  */
4287 void
4288 verify_certificate_chain (gnutls_session_t session,
4289                           const char *hostname,
4290                           const gnutls_datum_t * cert_chain,
4291                           int cert_chain_length)
4292 {
4293   int i;
4294   gnutls_x509_crt_t *cert;
4295
4296   cert = malloc (sizeof (*cert) * cert_chain_length);
4297
4298   /* Import all the certificates in the chain to
4299    * native certificate format.
4300    */
4301   for (i = 0; i &lt; cert_chain_length; i++)
4302     {
4303       gnutls_x509_crt_init (&amp;cert[i]);
4304       gnutls_x509_crt_import (cert[i], &amp;cert_chain[i], GNUTLS_X509_FMT_DER);
4305     }
4306
4307   /* If the last certificate in the chain is self signed ignore it.
4308    * That is because we want to check against our trusted certificate
4309    * list.
4310    */
4311   if (gnutls_x509_crt_check_issuer (cert[cert_chain_length - 1],
4312                                     cert[cert_chain_length - 1]) &gt; 0
4313       &amp;&amp; cert_chain_length &gt; 0)
4314     {
4315       cert_chain_length--;
4316     }
4317
4318   /* Now verify the certificates against their issuers
4319    * in the chain.
4320    */
4321   for (i = 1; i &lt; cert_chain_length; i++)
4322     {
4323       verify_cert2 (cert[i - 1], cert[i], crl_list, crl_list_size);
4324     }
4325
4326   /* Here we must verify the last certificate in the chain against
4327    * our trusted CA list.
4328    */
4329   verify_last_cert (cert[cert_chain_length - 1],
4330                     ca_list, ca_list_size, crl_list, crl_list_size);
4331
4332   /* Check if the name in the first certificate matches our destination!
4333    */
4334   if (!gnutls_x509_crt_check_hostname (cert[0], hostname))
4335     {
4336       printf (&quot;The certificate's owner does not match hostname '%s'\n&quot;,
4337               hostname);
4338     }
4339
4340   for (i = 0; i &lt; cert_chain_length; i++)
4341     gnutls_x509_crt_deinit (cert[i]);
4342
4343   return;
4344 }
4345
4346
4347 /* Verifies a certificate against an other certificate
4348  * which is supposed to be it's issuer. Also checks the
4349  * crl_list if the certificate is revoked.
4350  */
4351 static void
4352 verify_cert2 (gnutls_x509_crt_t crt, gnutls_x509_crt_t issuer,
4353               gnutls_x509_crl_t * crl_list, int crl_list_size)
4354 {
4355   unsigned int output;
4356   int ret;
4357   size_t name_size;
4358   char name[64];
4359
4360   /* Print information about the certificates to
4361    * be checked.
4362    */
4363   name_size = sizeof (name);
4364   gnutls_x509_crt_get_dn (crt, name, &amp;name_size);
4365
4366   fprintf (stderr, &quot;\nCertificate: %s\n&quot;, name);
4367
4368   name_size = sizeof (name);
4369   gnutls_x509_crt_get_issuer_dn (crt, name, &amp;name_size);
4370
4371   fprintf (stderr, &quot;Issued by: %s\n&quot;, name);
4372
4373   /* Get the DN of the issuer cert.
4374    */
4375   name_size = sizeof (name);
4376   gnutls_x509_crt_get_dn (issuer, name, &amp;name_size);
4377
4378   fprintf (stderr, &quot;Checking against: %s\n&quot;, name);
4379
4380   /* Do the actual verification.
4381    */
4382   gnutls_x509_crt_verify (crt, &amp;issuer, 1, 0, &amp;output);
4383
4384   if (output &amp; GNUTLS_CERT_INVALID)
4385     {
4386       fprintf (stderr, &quot;Not trusted&quot;);
4387
4388       if (output &amp; GNUTLS_CERT_SIGNER_NOT_FOUND)
4389         fprintf (stderr, &quot;: no issuer was found&quot;);
4390       if (output &amp; GNUTLS_CERT_SIGNER_NOT_CA)
4391         fprintf (stderr, &quot;: issuer is not a CA&quot;);
4392       if (output &amp; GNUTLS_CERT_NOT_ACTIVATED)
4393         fprintf (stderr, &quot;: not yet activated\n&quot;);
4394       if (output &amp; GNUTLS_CERT_EXPIRED)
4395         fprintf (stderr, &quot;: expired\n&quot;);
4396
4397       fprintf (stderr, &quot;\n&quot;);
4398     }
4399   else
4400     fprintf (stderr, &quot;Trusted\n&quot;);
4401
4402   /* Check if the certificate is revoked.
4403    */
4404   ret = gnutls_x509_crt_check_revocation (crt, crl_list, crl_list_size);
4405   if (ret == 1)
4406     {                           /* revoked */
4407       fprintf (stderr, &quot;Revoked\n&quot;);
4408     }
4409 }
4410
4411
4412 /* Verifies a certificate against our trusted CA list.
4413  * Also checks the crl_list if the certificate is revoked.
4414  */
4415 static void
4416 verify_last_cert (gnutls_x509_crt_t crt,
4417                   gnutls_x509_crt_t * ca_list, int ca_list_size,
4418                   gnutls_x509_crl_t * crl_list, int crl_list_size)
4419 {
4420   unsigned int output;
4421   int ret;
4422   size_t name_size;
4423   char name[64];
4424
4425   /* Print information about the certificates to
4426    * be checked.
4427    */
4428   name_size = sizeof (name);
4429   gnutls_x509_crt_get_dn (crt, name, &amp;name_size);
4430
4431   fprintf (stderr, &quot;\nCertificate: %s\n&quot;, name);
4432
4433   name_size = sizeof (name);
4434   gnutls_x509_crt_get_issuer_dn (crt, name, &amp;name_size);
4435
4436   fprintf (stderr, &quot;Issued by: %s\n&quot;, name);
4437
4438   /* Do the actual verification.
4439    */
4440   gnutls_x509_crt_verify (crt, ca_list, ca_list_size,
4441                           GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT, &amp;output);
4442
4443   if (output &amp; GNUTLS_CERT_INVALID)
4444     {
4445       fprintf (stderr, &quot;Not trusted&quot;);
4446
4447       if (output &amp; GNUTLS_CERT_SIGNER_NOT_CA)
4448         fprintf (stderr, &quot;: Issuer is not a CA\n&quot;);
4449       if (output &amp; GNUTLS_CERT_NOT_ACTIVATED)
4450         fprintf (stderr, &quot;: Not yet activated\n&quot;);
4451       if (output &amp; GNUTLS_CERT_EXPIRED)
4452         fprintf (stderr, &quot;: Expired\n&quot;);
4453       fprintf (stderr, &quot;\n&quot;);
4454     }
4455   else
4456     fprintf (stderr, &quot;Trusted\n&quot;);
4457
4458
4459   /* Check if the certificate is revoked.
4460    */
4461   ret = gnutls_x509_crt_check_revocation (crt, crl_list, crl_list_size);
4462   if (ret == 1)
4463     {                           /* revoked */
4464       fprintf (stderr, &quot;Revoked\n&quot;);
4465     }
4466 }
4467 </pre>
4468 <hr>
4469 <a name="Using-a-callback-to-select-the-certificate-to-use"></a>
4470 <div class="header">
4471 <p>
4472 Next: <a href="#Client-using-a-PKCS-_002311-token-with-TLS" accesskey="n" rel="next">Client using a PKCS #11 token with TLS</a>, Previous: <a href="#Verifying-peer_0027s-certificate" accesskey="p" rel="previous">Verifying peer's 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>
4473 </div>
4474 <a name="Using-a-Callback-to-Select-the-Certificate-to-Use"></a>
4475 <h4 class="subsection">7.3.5 Using a Callback to Select the Certificate to Use</h4>
4476
4477 <p>There are cases where a client holds several certificate and key
4478 pairs, and may not want to load all of them in the credentials
4479 structure.  The following example demonstrates the use of the
4480 certificate selection callback.
4481 </p>
4482 <pre class="verbatim">/* This example code is placed in the public domain. */
4483
4484 #ifdef HAVE_CONFIG_H
4485 #include &lt;config.h&gt;
4486 #endif
4487
4488 #include &lt;stdio.h&gt;
4489 #include &lt;stdlib.h&gt;
4490 #include &lt;string.h&gt;
4491 #include &lt;sys/types.h&gt;
4492 #include &lt;sys/socket.h&gt;
4493 #include &lt;arpa/inet.h&gt;
4494 #include &lt;unistd.h&gt;
4495 #include &lt;gnutls/gnutls.h&gt;
4496 #include &lt;gnutls/x509.h&gt;
4497 #include &lt;sys/types.h&gt;
4498 #include &lt;sys/stat.h&gt;
4499 #include &lt;fcntl.h&gt;
4500
4501 /* A TLS client that loads the certificate and key.
4502  */
4503
4504 #define MAX_BUF 1024
4505 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
4506
4507 #define CERT_FILE &quot;cert.pem&quot;
4508 #define KEY_FILE &quot;key.pem&quot;
4509 #define CAFILE &quot;ca.pem&quot;
4510
4511 extern int tcp_connect (void);
4512 extern void tcp_close (int sd);
4513
4514 static int cert_callback (gnutls_session_t session,
4515                           const gnutls_datum_t * req_ca_rdn, int nreqs,
4516                           const gnutls_pk_algorithm_t * sign_algos,
4517                           int sign_algos_length, gnutls_retr2_st * st);
4518
4519 gnutls_x509_crt_t crt;
4520 gnutls_x509_privkey_t key;
4521
4522 /* Helper functions to load a certificate and key
4523  * files into memory.
4524  */
4525 static gnutls_datum_t
4526 load_file (const char *file)
4527 {
4528   FILE *f;
4529   gnutls_datum_t loaded_file = { NULL, 0 };
4530   long filelen;
4531   void *ptr;
4532
4533   if (!(f = fopen (file, &quot;r&quot;))
4534       || fseek (f, 0, SEEK_END) != 0
4535       || (filelen = ftell (f)) &lt; 0
4536       || fseek (f, 0, SEEK_SET) != 0
4537       || !(ptr = malloc ((size_t) filelen))
4538       || fread (ptr, 1, (size_t) filelen, f) &lt; (size_t) filelen)
4539     {
4540       return loaded_file;
4541     }
4542
4543   loaded_file.data = ptr;
4544   loaded_file.size = (unsigned int) filelen;
4545   return loaded_file;
4546 }
4547
4548 static void
4549 unload_file (gnutls_datum_t data)
4550 {
4551   free (data.data);
4552 }
4553
4554 /* Load the certificate and the private key.
4555  */
4556 static void
4557 load_keys (void)
4558 {
4559   int ret;
4560   gnutls_datum_t data;
4561
4562   data = load_file (CERT_FILE);
4563   if (data.data == NULL)
4564     {
4565       fprintf (stderr, &quot;*** Error loading cert file.\n&quot;);
4566       exit (1);
4567     }
4568   gnutls_x509_crt_init (&amp;crt);
4569
4570   ret = gnutls_x509_crt_import (crt, &amp;data, GNUTLS_X509_FMT_PEM);
4571   if (ret &lt; 0)
4572     {
4573       fprintf (stderr, &quot;*** Error loading key file: %s\n&quot;,
4574                gnutls_strerror (ret));
4575       exit (1);
4576     }
4577
4578   unload_file (data);
4579
4580   data = load_file (KEY_FILE);
4581   if (data.data == NULL)
4582     {
4583       fprintf (stderr, &quot;*** Error loading key file.\n&quot;);
4584       exit (1);
4585     }
4586
4587   gnutls_x509_privkey_init (&amp;key);
4588
4589   ret = gnutls_x509_privkey_import (key, &amp;data, GNUTLS_X509_FMT_PEM);
4590   if (ret &lt; 0)
4591     {
4592       fprintf (stderr, &quot;*** Error loading key file: %s\n&quot;,
4593                gnutls_strerror (ret));
4594       exit (1);
4595     }
4596
4597   unload_file (data);
4598
4599 }
4600
4601 int
4602 main (void)
4603 {
4604   int ret, sd, ii;
4605   gnutls_session_t session;
4606   gnutls_priority_t priorities_cache;
4607   char buffer[MAX_BUF + 1];
4608   gnutls_certificate_credentials_t xcred;
4609   /* Allow connections to servers that have OpenPGP keys as well.
4610    */
4611
4612   gnutls_global_init ();
4613
4614   load_keys ();
4615
4616   /* X509 stuff */
4617   gnutls_certificate_allocate_credentials (&amp;xcred);
4618
4619   /* priorities */
4620   gnutls_priority_init (&amp;priorities_cache, &quot;NORMAL&quot;, NULL);
4621
4622
4623   /* sets the trusted cas file
4624    */
4625   gnutls_certificate_set_x509_trust_file (xcred, CAFILE, GNUTLS_X509_FMT_PEM);
4626
4627   gnutls_certificate_set_retrieve_function (xcred, cert_callback);
4628
4629   /* Initialize TLS session
4630    */
4631   gnutls_init (&amp;session, GNUTLS_CLIENT);
4632
4633   /* Use default priorities */
4634   gnutls_priority_set (session, priorities_cache);
4635
4636   /* put the x509 credentials to the current session
4637    */
4638   gnutls_credentials_set (session, GNUTLS_CRD_CERTIFICATE, xcred);
4639
4640   /* connect to the peer
4641    */
4642   sd = tcp_connect ();
4643
4644   gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd);
4645
4646   /* Perform the TLS handshake
4647    */
4648   ret = gnutls_handshake (session);
4649
4650   if (ret &lt; 0)
4651     {
4652       fprintf (stderr, &quot;*** Handshake failed\n&quot;);
4653       gnutls_perror (ret);
4654       goto end;
4655     }
4656   else
4657     {
4658       printf (&quot;- Handshake was completed\n&quot;);
4659     }
4660
4661   gnutls_record_send (session, MSG, strlen (MSG));
4662
4663   ret = gnutls_record_recv (session, buffer, MAX_BUF);
4664   if (ret == 0)
4665     {
4666       printf (&quot;- Peer has closed the TLS connection\n&quot;);
4667       goto end;
4668     }
4669   else if (ret &lt; 0)
4670     {
4671       fprintf (stderr, &quot;*** Error: %s\n&quot;, gnutls_strerror (ret));
4672       goto end;
4673     }
4674
4675   printf (&quot;- Received %d bytes: &quot;, ret);
4676   for (ii = 0; ii &lt; ret; ii++)
4677     {
4678       fputc (buffer[ii], stdout);
4679     }
4680   fputs (&quot;\n&quot;, stdout);
4681
4682   gnutls_bye (session, GNUTLS_SHUT_RDWR);
4683
4684 end:
4685
4686   tcp_close (sd);
4687
4688   gnutls_deinit (session);
4689
4690   gnutls_certificate_free_credentials (xcred);
4691   gnutls_priority_deinit (priorities_cache);
4692
4693   gnutls_global_deinit ();
4694
4695   return 0;
4696 }
4697
4698
4699
4700 /* This callback should be associated with a session by calling
4701  * gnutls_certificate_client_set_retrieve_function( session, cert_callback),
4702  * before a handshake.
4703  */
4704
4705 static int
4706 cert_callback (gnutls_session_t session,
4707                const gnutls_datum_t * req_ca_rdn, int nreqs,
4708                const gnutls_pk_algorithm_t * sign_algos,
4709                int sign_algos_length, gnutls_retr2_st * st)
4710 {
4711   char issuer_dn[256];
4712   int i, ret;
4713   size_t len;
4714   gnutls_certificate_type_t type;
4715
4716   /* Print the server's trusted CAs
4717    */
4718   if (nreqs &gt; 0)
4719     printf (&quot;- Server's trusted authorities:\n&quot;);
4720   else
4721     printf (&quot;- Server did not send us any trusted authorities names.\n&quot;);
4722
4723   /* print the names (if any) */
4724   for (i = 0; i &lt; nreqs; i++)
4725     {
4726       len = sizeof (issuer_dn);
4727       ret = gnutls_x509_rdn_get (&amp;req_ca_rdn[i], issuer_dn, &amp;len);
4728       if (ret &gt;= 0)
4729         {
4730           printf (&quot;   [%d]: &quot;, i);
4731           printf (&quot;%s\n&quot;, issuer_dn);
4732         }
4733     }
4734
4735   /* Select a certificate and return it.
4736    * The certificate must be of any of the &quot;sign algorithms&quot;
4737    * supported by the server.
4738    */
4739
4740   type = gnutls_certificate_type_get (session);
4741   if (type == GNUTLS_CRT_X509)
4742     {
4743       /* check if the certificate we are sending is signed
4744        * with an algorithm that the server accepts */
4745       gnutls_sign_algorithm_t cert_algo, req_algo;
4746       int i, match = 0;
4747
4748       ret = gnutls_x509_crt_get_signature_algorithm (crt);
4749       if (ret &lt; 0)
4750         {
4751           /* error reading signature algorithm
4752            */
4753           return -1;
4754         }
4755       cert_algo = ret;
4756
4757       i = 0;
4758       do
4759         {
4760           ret = gnutls_sign_algorithm_get_requested (session, i, &amp;req_algo);
4761           if (ret &gt;= 0 &amp;&amp; cert_algo == req_algo)
4762             {
4763               match = 1;
4764               break;
4765             }
4766
4767           /* server has not requested anything specific */
4768           if (i == 0 &amp;&amp; ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
4769             {
4770               match = 1;
4771               break;
4772             }
4773           i++;
4774         }
4775       while (ret &gt;= 0);
4776
4777       if (match == 0)
4778         {
4779           printf
4780             (&quot;- Could not find a suitable certificate to send to server\n&quot;);
4781           return -1;
4782         }
4783
4784       st-&gt;cert_type = type;
4785       st-&gt;ncerts = 1;
4786
4787       st-&gt;cert.x509 = &amp;crt;
4788       st-&gt;key.x509 = key;
4789       st-&gt;key_type = GNUTLS_PRIVKEY_X509;
4790
4791       st-&gt;deinit_all = 0;
4792     }
4793   else
4794     {
4795       return -1;
4796     }
4797
4798   return 0;
4799
4800 }
4801 </pre>
4802
4803 <hr>
4804 <a name="Client-using-a-PKCS-_002311-token-with-TLS"></a>
4805 <div class="header">
4806 <p>
4807 Next: <a href="#Client-with-Resume-capability-example" accesskey="n" rel="next">Client with Resume capability example</a>, Previous: <a href="#Using-a-callback-to-select-the-certificate-to-use" accesskey="p" rel="previous">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>
4808 </div>
4809 <a name="Using-a-PKCS-_002311-token-with-TLS-1"></a>
4810 <h4 class="subsection">7.3.6 Using a <acronym>PKCS #11</acronym> token with TLS</h4>
4811 <a name="ex_003apkcs11_002dclient"></a>
4812 <p>This example will demonstrate how to load keys and certificates
4813 from a <acronym>PKCS</acronym> #11 token, and use it with a TLS connection.
4814 </p>
4815 <pre class="verbatim">/* This example code is placed in the public domain. */
4816
4817 #ifdef HAVE_CONFIG_H
4818 #include &lt;config.h&gt;
4819 #endif
4820
4821 #include &lt;getpass.h&gt;
4822
4823 #include &lt;stdio.h&gt;
4824 #include &lt;stdlib.h&gt;
4825 #include &lt;string.h&gt;
4826 #include &lt;sys/types.h&gt;
4827 #include &lt;sys/socket.h&gt;
4828 #include &lt;arpa/inet.h&gt;
4829 #include &lt;unistd.h&gt;
4830 #include &lt;gnutls/gnutls.h&gt;
4831 #include &lt;gnutls/x509.h&gt;
4832 #include &lt;gnutls/pkcs11.h&gt;
4833 #include &lt;sys/types.h&gt;
4834 #include &lt;sys/stat.h&gt;
4835 #include &lt;fcntl.h&gt;
4836
4837 /* A TLS client that loads the certificate and key.
4838  */
4839
4840 #define MAX_BUF 1024
4841 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
4842 #define MIN(x,y) (((x)&lt;(y))?(x):(y))
4843
4844 #define CAFILE &quot;ca.pem&quot;
4845 #define KEY_URL &quot;pkcs11:manufacturer=SomeManufacturer;object=Private%20Key&quot; \
4846   &quot;;objecttype=private;id=db:5b:3e:b5:72:33&quot;
4847 #define CERT_URL &quot;pkcs11:manufacturer=SomeManufacturer;object=Certificate;&quot; \
4848   &quot;objecttype=cert;id=db:5b:3e:b5:72:33&quot;
4849
4850 extern int tcp_connect (void);
4851 extern void tcp_close (int sd);
4852
4853 static int cert_callback (gnutls_session_t session,
4854                           const gnutls_datum_t * req_ca_rdn, int nreqs,
4855                           const gnutls_pk_algorithm_t * sign_algos,
4856                           int sign_algos_length, gnutls_retr2_st * st);
4857
4858 gnutls_x509_crt_t crt;
4859 gnutls_pkcs11_privkey_t key;
4860
4861 /* Load the certificate and the private key.
4862  */
4863 static void
4864 load_keys (void)
4865 {
4866   int ret;
4867
4868   gnutls_x509_crt_init (&amp;crt);
4869
4870   ret = gnutls_x509_crt_import_pkcs11_url (crt, CERT_URL, 0);
4871
4872   /* some tokens require login to read data */
4873   if (ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
4874     ret = gnutls_x509_crt_import_pkcs11_url (crt, CERT_URL,
4875                                              GNUTLS_PKCS11_OBJ_FLAG_LOGIN);
4876
4877   if (ret &lt; 0)
4878     {
4879       fprintf (stderr, &quot;*** Error loading key file: %s\n&quot;,
4880                gnutls_strerror (ret));
4881       exit (1);
4882     }
4883
4884   gnutls_pkcs11_privkey_init (&amp;key);
4885
4886   ret = gnutls_pkcs11_privkey_import_url (key, KEY_URL, 0);
4887   if (ret &lt; 0)
4888     {
4889       fprintf (stderr, &quot;*** Error loading key file: %s\n&quot;,
4890                gnutls_strerror (ret));
4891       exit (1);
4892     }
4893
4894 }
4895
4896 static int
4897 pin_callback (void *user, int attempt, const char *token_url,
4898               const char *token_label, unsigned int flags, char *pin,
4899               size_t pin_max)
4900 {
4901   const char *password;
4902   int len;
4903
4904   printf (&quot;PIN required for token '%s' with URL '%s'\n&quot;, token_label,
4905           token_url);
4906   if (flags &amp; GNUTLS_PKCS11_PIN_FINAL_TRY)
4907     printf (&quot;*** This is the final try before locking!\n&quot;);
4908   if (flags &amp; GNUTLS_PKCS11_PIN_COUNT_LOW)
4909     printf (&quot;*** Only few tries left before locking!\n&quot;);
4910
4911   password = getpass (&quot;Enter pin: &quot;);
4912   if (password == NULL || password[0] == 0)
4913     {
4914       fprintf (stderr, &quot;No password given\n&quot;);
4915       exit (1);
4916     }
4917
4918   len = MIN (pin_max, strlen (password));
4919   memcpy (pin, password, len);
4920   pin[len] = 0;
4921
4922   return 0;
4923 }
4924
4925 int
4926 main (void)
4927 {
4928   int ret, sd, ii;
4929   gnutls_session_t session;
4930   gnutls_priority_t priorities_cache;
4931   char buffer[MAX_BUF + 1];
4932   gnutls_certificate_credentials_t xcred;
4933   /* Allow connections to servers that have OpenPGP keys as well.
4934    */
4935
4936   gnutls_global_init ();
4937   /* PKCS11 private key operations might require PIN.
4938    * Register a callback.
4939    */
4940   gnutls_pkcs11_set_pin_function (pin_callback, NULL);
4941
4942   load_keys ();
4943
4944   /* X509 stuff */
4945   gnutls_certificate_allocate_credentials (&amp;xcred);
4946
4947   /* priorities */
4948   gnutls_priority_init (&amp;priorities_cache, &quot;NORMAL&quot;, NULL);
4949
4950
4951   /* sets the trusted cas file
4952    */
4953   gnutls_certificate_set_x509_trust_file (xcred, CAFILE, GNUTLS_X509_FMT_PEM);
4954
4955   gnutls_certificate_set_retrieve_function (xcred, cert_callback);
4956
4957   /* Initialize TLS session
4958    */
4959   gnutls_init (&amp;session, GNUTLS_CLIENT);
4960
4961   /* Use default priorities */
4962   gnutls_priority_set (session, priorities_cache);
4963
4964   /* put the x509 credentials to the current session
4965    */
4966   gnutls_credentials_set (session, GNUTLS_CRD_CERTIFICATE, xcred);
4967
4968   /* connect to the peer
4969    */
4970   sd = tcp_connect ();
4971
4972   gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd);
4973
4974   /* Perform the TLS handshake
4975    */
4976   ret = gnutls_handshake (session);
4977
4978   if (ret &lt; 0)
4979     {
4980       fprintf (stderr, &quot;*** Handshake failed\n&quot;);
4981       gnutls_perror (ret);
4982       goto end;
4983     }
4984   else
4985     {
4986       printf (&quot;- Handshake was completed\n&quot;);
4987     }
4988
4989   gnutls_record_send (session, MSG, strlen (MSG));
4990
4991   ret = gnutls_record_recv (session, buffer, MAX_BUF);
4992   if (ret == 0)
4993     {
4994       printf (&quot;- Peer has closed the TLS connection\n&quot;);
4995       goto end;
4996     }
4997   else if (ret &lt; 0)
4998     {
4999       fprintf (stderr, &quot;*** Error: %s\n&quot;, gnutls_strerror (ret));
5000       goto end;
5001     }
5002
5003   printf (&quot;- Received %d bytes: &quot;, ret);
5004   for (ii = 0; ii &lt; ret; ii++)
5005     {
5006       fputc (buffer[ii], stdout);
5007     }
5008   fputs (&quot;\n&quot;, stdout);
5009
5010   gnutls_bye (session, GNUTLS_SHUT_RDWR);
5011
5012 end:
5013
5014   tcp_close (sd);
5015
5016   gnutls_deinit (session);
5017
5018   gnutls_certificate_free_credentials (xcred);
5019   gnutls_priority_deinit (priorities_cache);
5020
5021   gnutls_global_deinit ();
5022
5023   return 0;
5024 }
5025
5026
5027
5028 /* This callback should be associated with a session by calling
5029  * gnutls_certificate_client_set_retrieve_function( session, cert_callback),
5030  * before a handshake.
5031  */
5032
5033 static int
5034 cert_callback (gnutls_session_t session,
5035                const gnutls_datum_t * req_ca_rdn, int nreqs,
5036                const gnutls_pk_algorithm_t * sign_algos,
5037                int sign_algos_length, gnutls_retr2_st * st)
5038 {
5039   char issuer_dn[256];
5040   int i, ret;
5041   size_t len;
5042   gnutls_certificate_type_t type;
5043
5044   /* Print the server's trusted CAs
5045    */
5046   if (nreqs &gt; 0)
5047     printf (&quot;- Server's trusted authorities:\n&quot;);
5048   else
5049     printf (&quot;- Server did not send us any trusted authorities names.\n&quot;);
5050
5051   /* print the names (if any) */
5052   for (i = 0; i &lt; nreqs; i++)
5053     {
5054       len = sizeof (issuer_dn);
5055       ret = gnutls_x509_rdn_get (&amp;req_ca_rdn[i], issuer_dn, &amp;len);
5056       if (ret &gt;= 0)
5057         {
5058           printf (&quot;   [%d]: &quot;, i);
5059           printf (&quot;%s\n&quot;, issuer_dn);
5060         }
5061     }
5062
5063   /* Select a certificate and return it.
5064    * The certificate must be of any of the &quot;sign algorithms&quot;
5065    * supported by the server.
5066    */
5067
5068   type = gnutls_certificate_type_get (session);
5069   if (type == GNUTLS_CRT_X509)
5070     {
5071       /* check if the certificate we are sending is signed
5072        * with an algorithm that the server accepts */
5073       gnutls_sign_algorithm_t cert_algo, req_algo;
5074       int i, match = 0;
5075
5076       ret = gnutls_x509_crt_get_signature_algorithm (crt);
5077       if (ret &lt; 0)
5078         {
5079           /* error reading signature algorithm
5080            */
5081           return -1;
5082         }
5083       cert_algo = ret;
5084
5085       i = 0;
5086       do
5087         {
5088           ret = gnutls_sign_algorithm_get_requested (session, i, &amp;req_algo);
5089           if (ret &gt;= 0 &amp;&amp; cert_algo == req_algo)
5090             {
5091               match = 1;
5092               break;
5093             }
5094
5095           /* server has not requested anything specific */
5096           if (i == 0 &amp;&amp; ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
5097             {
5098               match = 1;
5099               break;
5100             }
5101           i++;
5102         }
5103       while (ret &gt;= 0);
5104
5105       if (match == 0)
5106         {
5107           printf
5108             (&quot;- Could not find a suitable certificate to send to server\n&quot;);
5109           return -1;
5110         }
5111
5112       st-&gt;cert_type = type;
5113       st-&gt;ncerts = 1;
5114
5115       st-&gt;cert.x509 = &amp;crt;
5116       st-&gt;key.pkcs11 = key;
5117       st-&gt;key_type = GNUTLS_PRIVKEY_PKCS11;
5118
5119       st-&gt;deinit_all = 0;
5120     }
5121   else
5122     {
5123       return -1;
5124     }
5125
5126   return 0;
5127
5128 }
5129 </pre>
5130
5131 <hr>
5132 <a name="Client-with-Resume-capability-example"></a>
5133 <div class="header">
5134 <p>
5135 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-PKCS-_002311-token-with-TLS" accesskey="p" rel="previous">Client using a PKCS #11 token 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>
5136 </div>
5137 <a name="Client-with-Resume-Capability-Example"></a>
5138 <h4 class="subsection">7.3.7 Client with Resume Capability Example</h4>
5139 <a name="ex_003aresume_002dclient"></a>
5140 <p>This is a modification of the simple client example. Here we
5141 demonstrate the use of session resumption. The client tries to connect
5142 once using <acronym>TLS</acronym>, close the connection and then try to
5143 establish a new connection using the previously negotiated data.
5144 </p>
5145 <pre class="verbatim">/* This example code is placed in the public domain. */
5146
5147 #ifdef HAVE_CONFIG_H
5148 #include &lt;config.h&gt;
5149 #endif
5150
5151 #include &lt;string.h&gt;
5152 #include &lt;stdio.h&gt;
5153 #include &lt;stdlib.h&gt;
5154 #include &lt;gnutls/gnutls.h&gt;
5155
5156 /* Those functions are defined in other examples.
5157  */
5158 extern void check_alert (gnutls_session_t session, int ret);
5159 extern int tcp_connect (void);
5160 extern void tcp_close (int sd);
5161
5162 #define MAX_BUF 1024
5163 #define CAFILE &quot;ca.pem&quot;
5164 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
5165
5166 int
5167 main (void)
5168 {
5169   int ret;
5170   int sd, ii;
5171   gnutls_session_t session;
5172   char buffer[MAX_BUF + 1];
5173   gnutls_certificate_credentials_t xcred;
5174
5175   /* variables used in session resuming
5176    */
5177   int t;
5178   char *session_data = NULL;
5179   size_t session_data_size = 0;
5180
5181   gnutls_global_init ();
5182
5183   /* X509 stuff */
5184   gnutls_certificate_allocate_credentials (&amp;xcred);
5185
5186   gnutls_certificate_set_x509_trust_file (xcred, CAFILE, GNUTLS_X509_FMT_PEM);
5187
5188   for (t = 0; t &lt; 2; t++)
5189     {                           /* connect 2 times to the server */
5190
5191       sd = tcp_connect ();
5192
5193       gnutls_init (&amp;session, GNUTLS_CLIENT);
5194
5195       gnutls_priority_set_direct (session, &quot;PERFORMANCE:!ARCFOUR-128&quot;, NULL);
5196
5197       gnutls_credentials_set (session, GNUTLS_CRD_CERTIFICATE, xcred);
5198
5199       if (t &gt; 0)
5200         {
5201           /* if this is not the first time we connect */
5202           gnutls_session_set_data (session, session_data, session_data_size);
5203           free (session_data);
5204         }
5205
5206       gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd);
5207
5208       /* Perform the TLS handshake
5209        */
5210       ret = gnutls_handshake (session);
5211
5212       if (ret &lt; 0)
5213         {
5214           fprintf (stderr, &quot;*** Handshake failed\n&quot;);
5215           gnutls_perror (ret);
5216           goto end;
5217         }
5218       else
5219         {
5220           printf (&quot;- Handshake was completed\n&quot;);
5221         }
5222
5223       if (t == 0)
5224         {                       /* the first time we connect */
5225           /* get the session data size */
5226           gnutls_session_get_data (session, NULL, &amp;session_data_size);
5227           session_data = malloc (session_data_size);
5228
5229           /* put session data to the session variable */
5230           gnutls_session_get_data (session, session_data, &amp;session_data_size);
5231
5232         }
5233       else
5234         {                       /* the second time we connect */
5235
5236           /* check if we actually resumed the previous session */
5237           if (gnutls_session_is_resumed (session) != 0)
5238             {
5239               printf (&quot;- Previous session was resumed\n&quot;);
5240             }
5241           else
5242             {
5243               fprintf (stderr, &quot;*** Previous session was NOT resumed\n&quot;);
5244             }
5245         }
5246
5247       /* This function was defined in a previous example
5248        */
5249       /* print_info(session); */
5250
5251       gnutls_record_send (session, MSG, strlen (MSG));
5252
5253       ret = gnutls_record_recv (session, buffer, MAX_BUF);
5254       if (ret == 0)
5255         {
5256           printf (&quot;- Peer has closed the TLS connection\n&quot;);
5257           goto end;
5258         }
5259       else if (ret &lt; 0)
5260         {
5261           fprintf (stderr, &quot;*** Error: %s\n&quot;, gnutls_strerror (ret));
5262           goto end;
5263         }
5264
5265       printf (&quot;- Received %d bytes: &quot;, ret);
5266       for (ii = 0; ii &lt; ret; ii++)
5267         {
5268           fputc (buffer[ii], stdout);
5269         }
5270       fputs (&quot;\n&quot;, stdout);
5271
5272       gnutls_bye (session, GNUTLS_SHUT_RDWR);
5273
5274     end:
5275
5276       tcp_close (sd);
5277
5278       gnutls_deinit (session);
5279
5280     }                           /* for() */
5281
5282   gnutls_certificate_free_credentials (xcred);
5283
5284   gnutls_global_deinit ();
5285
5286   return 0;
5287 }
5288 </pre>
5289
5290 <hr>
5291 <a name="Simple-client-example-with-SRP-authentication"></a>
5292 <div class="header">
5293 <p>
5294 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="previous">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>
5295 </div>
5296 <a name="Simple-Client-Example-with-SRP-Authentication"></a>
5297 <h4 class="subsection">7.3.8 Simple Client Example with <acronym>SRP</acronym> Authentication</h4>
5298
5299 <p>The following client is a very simple <acronym>SRP</acronym> <acronym>TLS</acronym>
5300 client which connects to a server and authenticates using a
5301 <em>username</em> and a <em>password</em>. The server may authenticate
5302 itself using a certificate, and in that case it has to be verified.
5303 </p>
5304 <pre class="verbatim">/* This example code is placed in the public domain. */
5305
5306 #ifdef HAVE_CONFIG_H
5307 #include &lt;config.h&gt;
5308 #endif
5309
5310 #include &lt;stdio.h&gt;
5311 #include &lt;stdlib.h&gt;
5312 #include &lt;string.h&gt;
5313 #include &lt;gnutls/gnutls.h&gt;
5314 #include &lt;gnutls/extra.h&gt;
5315
5316 /* Those functions are defined in other examples.
5317  */
5318 extern void check_alert (gnutls_session_t session, int ret);
5319 extern int tcp_connect (void);
5320 extern void tcp_close (int sd);
5321
5322 #define MAX_BUF 1024
5323 #define USERNAME &quot;user&quot;
5324 #define PASSWORD &quot;pass&quot;
5325 #define CAFILE &quot;ca.pem&quot;
5326 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
5327
5328 int
5329 main (void)
5330 {
5331   int ret;
5332   int sd, ii;
5333   gnutls_session_t session;
5334   char buffer[MAX_BUF + 1];
5335   gnutls_srp_client_credentials_t srp_cred;
5336   gnutls_certificate_credentials_t cert_cred;
5337
5338   gnutls_global_init ();
5339
5340   /* now enable the gnutls-extra library which contains the
5341    * SRP stuff.
5342    */
5343   gnutls_global_init_extra ();
5344
5345   gnutls_srp_allocate_client_credentials (&amp;srp_cred);
5346   gnutls_certificate_allocate_credentials (&amp;cert_cred);
5347
5348   gnutls_certificate_set_x509_trust_file (cert_cred, CAFILE,
5349                                           GNUTLS_X509_FMT_PEM);
5350   gnutls_srp_set_client_credentials (srp_cred, USERNAME, PASSWORD);
5351
5352   /* connects to server
5353    */
5354   sd = tcp_connect ();
5355
5356   /* Initialize TLS session
5357    */
5358   gnutls_init (&amp;session, GNUTLS_CLIENT);
5359
5360
5361   /* Set the priorities.
5362    */
5363   gnutls_priority_set_direct (session, &quot;NORMAL:+SRP:+SRP-RSA:+SRP-DSS&quot;, NULL);
5364
5365   /* put the SRP credentials to the current session
5366    */
5367   gnutls_credentials_set (session, GNUTLS_CRD_SRP, srp_cred);
5368   gnutls_credentials_set (session, GNUTLS_CRD_CERTIFICATE, cert_cred);
5369
5370   gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd);
5371
5372   /* Perform the TLS handshake
5373    */
5374   ret = gnutls_handshake (session);
5375
5376   if (ret &lt; 0)
5377     {
5378       fprintf (stderr, &quot;*** Handshake failed\n&quot;);
5379       gnutls_perror (ret);
5380       goto end;
5381     }
5382   else
5383     {
5384       printf (&quot;- Handshake was completed\n&quot;);
5385     }
5386
5387   gnutls_record_send (session, MSG, strlen (MSG));
5388
5389   ret = gnutls_record_recv (session, buffer, MAX_BUF);
5390   if (gnutls_error_is_fatal (ret) == 1 || ret == 0)
5391     {
5392       if (ret == 0)
5393         {
5394           printf (&quot;- Peer has closed the GnuTLS connection\n&quot;);
5395           goto end;
5396         }
5397       else
5398         {
5399           fprintf (stderr, &quot;*** Error: %s\n&quot;, gnutls_strerror (ret));
5400           goto end;
5401         }
5402     }
5403   else
5404     check_alert (session, ret);
5405
5406   if (ret &gt; 0)
5407     {
5408       printf (&quot;- Received %d bytes: &quot;, ret);
5409       for (ii = 0; ii &lt; ret; ii++)
5410         {
5411           fputc (buffer[ii], stdout);
5412         }
5413       fputs (&quot;\n&quot;, stdout);
5414     }
5415   gnutls_bye (session, GNUTLS_SHUT_RDWR);
5416
5417 end:
5418
5419   tcp_close (sd);
5420
5421   gnutls_deinit (session);
5422
5423   gnutls_srp_free_client_credentials (srp_cred);
5424   gnutls_certificate_free_credentials (cert_cred);
5425
5426   gnutls_global_deinit ();
5427
5428   return 0;
5429 }
5430 </pre>
5431 <hr>
5432 <a name="Simple-client-example-in-C_002b_002b"></a>
5433 <div class="header">
5434 <p>
5435 Next: <a href="#Helper-function-for-TCP-connections" accesskey="n" rel="next">Helper function for TCP connections</a>, Previous: <a href="#Simple-client-example-with-SRP-authentication" accesskey="p" rel="previous">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>
5436 </div>
5437 <a name="Simple-Client-Example-using-the-C_002b_002b-API"></a>
5438 <h4 class="subsection">7.3.9 Simple Client Example using the C++ API</h4>
5439
5440 <p>The following client is a simple example of a client client utilizing
5441 the GnuTLS C++ API.
5442 </p>
5443 <pre class="verbatim">#include &lt;iostream&gt;
5444 #include &lt;stdexcept&gt;
5445 #include &lt;gnutls/gnutls.h&gt;
5446 #include &lt;gnutls/gnutlsxx.h&gt;
5447 #include &lt;cstring&gt; /* for strlen */
5448
5449 /* A very basic TLS client, with anonymous authentication.
5450  * written by Eduardo Villanueva Che.
5451  */
5452
5453 #define MAX_BUF 1024
5454 #define SA struct sockaddr
5455
5456 #define CAFILE &quot;ca.pem&quot;
5457 #define MSG &quot;GET / HTTP/1.0\r\n\r\n&quot;
5458
5459 extern &quot;C&quot;
5460 {
5461     int tcp_connect(void);
5462     void tcp_close(int sd);
5463 }
5464
5465
5466 int main(void)
5467 {
5468     int sd = -1;
5469     gnutls_global_init();
5470
5471     try
5472     {
5473
5474         /* Allow connections to servers that have OpenPGP keys as well.
5475          */
5476         gnutls::client_session session;
5477
5478         /* X509 stuff */
5479         gnutls::certificate_credentials credentials;
5480
5481
5482         /* sets the trusted cas file
5483          */
5484         credentials.set_x509_trust_file(CAFILE, GNUTLS_X509_FMT_PEM);
5485         /* put the x509 credentials to the current session
5486          */
5487         session.set_credentials(credentials);
5488
5489         /* Use default priorities */
5490         session.set_priority (&quot;NORMAL&quot;, NULL);
5491
5492         /* connect to the peer
5493          */
5494         sd = tcp_connect();
5495         session.set_transport_ptr((gnutls_transport_ptr_t) sd);
5496
5497         /* Perform the TLS handshake
5498          */
5499         int ret = session.handshake();
5500         if (ret &lt; 0)
5501         {
5502             throw std::runtime_error(&quot;Handshake failed&quot;);
5503         }
5504         else
5505         {
5506             std::cout &lt;&lt; &quot;- Handshake was completed&quot; &lt;&lt; std::endl;
5507         }
5508
5509         session.send(MSG, strlen(MSG));
5510         char buffer[MAX_BUF + 1];
5511         ret = session.recv(buffer, MAX_BUF);
5512         if (ret == 0)
5513         {
5514             throw std::runtime_error(&quot;Peer has closed the TLS connection&quot;);
5515         }
5516         else if (ret &lt; 0)
5517         {
5518             throw std::runtime_error(gnutls_strerror(ret));
5519         }
5520
5521         std::cout &lt;&lt; &quot;- Received &quot; &lt;&lt; ret &lt;&lt; &quot; bytes:&quot; &lt;&lt; std::endl;
5522         std::cout.write(buffer, ret);
5523         std::cout &lt;&lt; std::endl;
5524
5525         session.bye(GNUTLS_SHUT_RDWR);
5526     }
5527     catch (std::exception &amp;ex)
5528     {
5529         std::cerr &lt;&lt; &quot;Exception caught: &quot; &lt;&lt; ex.what() &lt;&lt; std::endl;
5530     }
5531
5532     if (sd != -1)
5533         tcp_close(sd);
5534
5535     gnutls_global_deinit();
5536
5537     return 0;
5538 }
5539 </pre>
5540 <hr>
5541 <a name="Helper-function-for-TCP-connections"></a>
5542 <div class="header">
5543 <p>
5544 Previous: <a href="#Simple-client-example-in-C_002b_002b" accesskey="p" rel="previous">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>
5545 </div>
5546 <a name="Helper-Function-for-TCP-Connections"></a>
5547 <h4 class="subsection">7.3.10 Helper Function for TCP Connections</h4>
5548
5549 <p>This helper function abstracts away TCP connection handling from the
5550 other examples.  It is required to build some examples.
5551 </p>
5552 <pre class="verbatim">/* This example code is placed in the public domain. */
5553
5554 #ifdef HAVE_CONFIG_H
5555 #include &lt;config.h&gt;
5556 #endif
5557
5558 #include &lt;stdio.h&gt;
5559 #include &lt;stdlib.h&gt;
5560 #include &lt;string.h&gt;
5561 #include &lt;sys/types.h&gt;
5562 #include &lt;sys/socket.h&gt;
5563 #include &lt;arpa/inet.h&gt;
5564 #include &lt;netinet/in.h&gt;
5565 #include &lt;unistd.h&gt;
5566
5567 #define SA struct sockaddr
5568
5569 /* tcp.c */
5570 int tcp_connect (void);
5571 void tcp_close (int sd);
5572
5573 /* Connects to the peer and returns a socket
5574  * descriptor.
5575  */
5576 extern int
5577 tcp_connect (void)
5578 {
5579   const char *PORT = &quot;5556&quot;;
5580   const char *SERVER = &quot;127.0.0.1&quot;;
5581   int err, sd;
5582   struct sockaddr_in sa;
5583
5584   /* connects to server
5585    */
5586   sd = socket (AF_INET, SOCK_STREAM, 0);
5587
5588   memset (&amp;sa, '\0', sizeof (sa));
5589   sa.sin_family = AF_INET;
5590   sa.sin_port = htons (atoi (PORT));
5591   inet_pton (AF_INET, SERVER, &amp;sa.sin_addr);
5592
5593   err = connect (sd, (SA *) &amp; sa, sizeof (sa));
5594   if (err &lt; 0)
5595     {
5596       fprintf (stderr, &quot;Connect error\n&quot;);
5597       exit (1);
5598     }
5599
5600   return sd;
5601 }
5602
5603 /* closes the given socket descriptor.
5604  */
5605 extern void
5606 tcp_close (int sd)
5607 {
5608   shutdown (sd, SHUT_RDWR);     /* no more receptions */
5609   close (sd);
5610 }
5611 </pre>
5612 <hr>
5613 <a name="Server-examples"></a>
5614 <div class="header">
5615 <p>
5616 Next: <a href="#Miscellaneous-examples" accesskey="n" rel="next">Miscellaneous examples</a>, Previous: <a href="#Client-examples" accesskey="p" rel="previous">Client examples</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>
5617 </div>
5618 <a name="Server-Examples"></a>
5619 <h3 class="section">7.4 Server Examples</h3>
5620
5621 <p>This section contains examples of <acronym>TLS</acronym> and <acronym>SSL</acronym>
5622 servers, using <acronym>GnuTLS</acronym>.
5623 </p>
5624 <table class="menu" border="0" cellspacing="0">
5625 <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">
5626 </td></tr>
5627 <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">
5628 </td></tr>
5629 <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">
5630 </td></tr>
5631 <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">
5632 </td></tr>
5633 </table>
5634
5635 <hr>
5636 <a name="Echo-Server-with-X_002e509-authentication"></a>
5637 <div class="header">
5638 <p>
5639 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>
5640 </div>
5641 <a name="Echo-Server-with-X_002e509-Authentication"></a>
5642 <h4 class="subsection">7.4.1 Echo Server with <acronym>X.509</acronym> Authentication</h4>
5643
5644 <p>This example is a very simple echo server which supports
5645 <acronym>X.509</acronym> authentication, using the RSA ciphersuites.
5646 </p>
5647 <pre class="verbatim">/* This example code is placed in the public domain. */
5648
5649 #ifdef HAVE_CONFIG_H
5650 #include &lt;config.h&gt;
5651 #endif
5652
5653 #include &lt;stdio.h&gt;
5654 #include &lt;stdlib.h&gt;
5655 #include &lt;errno.h&gt;
5656 #include &lt;sys/types.h&gt;
5657 #include &lt;sys/socket.h&gt;
5658 #include &lt;arpa/inet.h&gt;
5659 #include &lt;netinet/in.h&gt;
5660 #include &lt;string.h&gt;
5661 #include &lt;unistd.h&gt;
5662 #include &lt;gnutls/gnutls.h&gt;
5663
5664 #define KEYFILE &quot;key.pem&quot;
5665 #define CERTFILE &quot;cert.pem&quot;
5666 #define CAFILE &quot;ca.pem&quot;
5667 #define CRLFILE &quot;crl.pem&quot;
5668
5669 /* This is a sample TLS 1.0 echo server, using X.509 authentication.
5670  */
5671
5672
5673 #define SA struct sockaddr
5674 #define SOCKET_ERR(err,s) if(err==-1) {perror(s);return(1);}
5675 #define MAX_BUF 1024
5676 #define PORT 5556               /* listen to 5556 port */
5677 #define DH_BITS 1024
5678
5679 /* These are global */
5680 gnutls_certificate_credentials_t x509_cred;
5681 gnutls_priority_t priority_cache;
5682
5683 static gnutls_session_t
5684 initialize_tls_session (void)
5685 {
5686   gnutls_session_t session;
5687
5688   gnutls_init (&amp;session, GNUTLS_SERVER);
5689
5690   gnutls_priority_set (session, priority_cache);
5691
5692   gnutls_credentials_set (session, GNUTLS_CRD_CERTIFICATE, x509_cred);
5693
5694   /* request client certificate if any.
5695    */
5696   gnutls_certificate_server_set_request (session, GNUTLS_CERT_REQUEST);
5697
5698   /* Set maximum compatibility mode. This is only suggested on public webservers
5699    * that need to trade security for compatibility
5700    */
5701   gnutls_session_enable_compatibility_mode (session);
5702
5703   return session;
5704 }
5705
5706 static gnutls_dh_params_t dh_params;
5707
5708 static int
5709 generate_dh_params (void)
5710 {
5711
5712   /* Generate Diffie-Hellman parameters - for use with DHE
5713    * kx algorithms. When short bit length is used, it might
5714    * be wise to regenerate parameters.
5715    *
5716    * Check the ex-serv-export.c example for using static
5717    * parameters.
5718    */
5719   gnutls_dh_params_init (&amp;dh_params);
5720   gnutls_dh_params_generate2 (dh_params, DH_BITS);
5721
5722   return 0;
5723 }
5724
5725 int
5726 main (void)
5727 {
5728   int err, listen_sd;
5729   int sd, ret;
5730   struct sockaddr_in sa_serv;
5731   struct sockaddr_in sa_cli;
5732   int client_len;
5733   char topbuf[512];
5734   gnutls_session_t session;
5735   char buffer[MAX_BUF + 1];
5736   int optval = 1;
5737
5738   /* this must be called once in the program
5739    */
5740   gnutls_global_init ();
5741
5742   gnutls_certificate_allocate_credentials (&amp;x509_cred);
5743   gnutls_certificate_set_x509_trust_file (x509_cred, CAFILE,
5744                                           GNUTLS_X509_FMT_PEM);
5745
5746   gnutls_certificate_set_x509_crl_file (x509_cred, CRLFILE,
5747                                         GNUTLS_X509_FMT_PEM);
5748
5749   gnutls_certificate_set_x509_key_file (x509_cred, CERTFILE, KEYFILE,
5750                                         GNUTLS_X509_FMT_PEM);
5751
5752   generate_dh_params ();
5753
5754   gnutls_priority_init (&amp;priority_cache, &quot;NORMAL&quot;, NULL);
5755
5756
5757   gnutls_certificate_set_dh_params (x509_cred, dh_params);
5758
5759   /* Socket operations
5760    */
5761   listen_sd = socket (AF_INET, SOCK_STREAM, 0);
5762   SOCKET_ERR (listen_sd, &quot;socket&quot;);
5763
5764   memset (&amp;sa_serv, '\0', sizeof (sa_serv));
5765   sa_serv.sin_family = AF_INET;
5766   sa_serv.sin_addr.s_addr = INADDR_ANY;
5767   sa_serv.sin_port = htons (PORT);      /* Server Port number */
5768
5769   setsockopt (listen_sd, SOL_SOCKET, SO_REUSEADDR, (void *) &amp;optval,
5770               sizeof (int));
5771
5772   err = bind (listen_sd, (SA *) &amp; sa_serv, sizeof (sa_serv));
5773   SOCKET_ERR (err, &quot;bind&quot;);
5774   err = listen (listen_sd, 1024);
5775   SOCKET_ERR (err, &quot;listen&quot;);
5776
5777   printf (&quot;Server ready. Listening to port '%d'.\n\n&quot;, PORT);
5778
5779   client_len = sizeof (sa_cli);
5780   for (;;)
5781     {
5782       session = initialize_tls_session ();
5783
5784       sd = accept (listen_sd, (SA *) &amp; sa_cli, &amp;client_len);
5785
5786       printf (&quot;- connection from %s, port %d\n&quot;,
5787               inet_ntop (AF_INET, &amp;sa_cli.sin_addr, topbuf,
5788                          sizeof (topbuf)), ntohs (sa_cli.sin_port));
5789
5790       gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd);
5791       ret = gnutls_handshake (session);
5792       if (ret &lt; 0)
5793         {
5794           close (sd);
5795           gnutls_deinit (session);
5796           fprintf (stderr, &quot;*** Handshake has failed (%s)\n\n&quot;,
5797                    gnutls_strerror (ret));
5798           continue;
5799         }
5800       printf (&quot;- Handshake was completed\n&quot;);
5801
5802       /* see the Getting peer's information example */
5803       /* print_info(session); */
5804
5805       for (;;)
5806         {
5807           memset (buffer, 0, MAX_BUF + 1);
5808           ret = gnutls_record_recv (session, buffer, MAX_BUF);
5809
5810           if (ret == 0)
5811             {
5812               printf (&quot;\n- Peer has closed the GnuTLS connection\n&quot;);
5813               break;
5814             }
5815           else if (ret &lt; 0)
5816             {
5817               fprintf (stderr, &quot;\n*** Received corrupted &quot;
5818                        &quot;data(%d). Closing the connection.\n\n&quot;, ret);
5819               break;
5820             }
5821           else if (ret &gt; 0)
5822             {
5823               /* echo data back to the client
5824                */
5825               gnutls_record_send (session, buffer, strlen (buffer));
5826             }
5827         }
5828       printf (&quot;\n&quot;);
5829       /* do not wait for the peer to close the connection.
5830        */
5831       gnutls_bye (session, GNUTLS_SHUT_WR);
5832
5833       close (sd);
5834       gnutls_deinit (session);
5835
5836     }
5837   close (listen_sd);
5838
5839   gnutls_certificate_free_credentials (x509_cred);
5840   gnutls_priority_deinit (priority_cache);
5841
5842   gnutls_global_deinit ();
5843
5844   return 0;
5845
5846 }
5847 </pre>
5848 <hr>
5849 <a name="Echo-Server-with-OpenPGP-authentication"></a>
5850 <div class="header">
5851 <p>
5852 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="previous">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>
5853 </div>
5854 <a name="Echo-Server-with-OpenPGP-Authentication"></a>
5855 <h4 class="subsection">7.4.2 Echo Server with <acronym>OpenPGP</acronym> Authentication</h4>
5856 <a name="index-OpenPGP-Server"></a>
5857
5858 <p>The following example is an echo server which supports
5859 <acronym><acronym>OpenPGP</acronym></acronym> key authentication. You can easily combine
5860 this functionality &mdash;that is have a server that supports both
5861 <acronym>X.509</acronym> and <acronym>OpenPGP</acronym> certificates&mdash; but we separated
5862 them to keep these examples as simple as possible.
5863 </p>
5864 <pre class="verbatim">/* This example code is placed in the public domain. */
5865
5866 #ifdef HAVE_CONFIG_H
5867 #include &lt;config.h&gt;
5868 #endif
5869
5870 #include &lt;stdio.h&gt;
5871 #include &lt;stdlib.h&gt;
5872 #include &lt;errno.h&gt;
5873 #include &lt;sys/types.h&gt;
5874 #include &lt;sys/socket.h&gt;
5875 #include &lt;arpa/inet.h&gt;
5876 #include &lt;netinet/in.h&gt;
5877 #include &lt;string.h&gt;
5878 #include &lt;unistd.h&gt;
5879 #include &lt;gnutls/gnutls.h&gt;
5880 #include &lt;gnutls/openpgp.h&gt;
5881
5882 #define KEYFILE &quot;secret.asc&quot;
5883 #define CERTFILE &quot;public.asc&quot;
5884 #define RINGFILE &quot;ring.gpg&quot;
5885
5886 /* This is a sample TLS 1.0-OpenPGP echo server.
5887  */
5888
5889
5890 #define SA struct sockaddr
5891 #define SOCKET_ERR(err,s) if(err==-1) {perror(s);return(1);}
5892 #define MAX_BUF 1024
5893 #define PORT 5556               /* listen to 5556 port */
5894 #define DH_BITS 1024
5895
5896 /* These are global */
5897 gnutls_certificate_credentials_t cred;
5898 gnutls_dh_params_t dh_params;
5899
5900 static int
5901 generate_dh_params (void)
5902 {
5903
5904   /* Generate Diffie-Hellman parameters - for use with DHE
5905    * kx algorithms. These should be discarded and regenerated
5906    * once a day, once a week or once a month. Depending on the
5907    * security requirements.
5908    */
5909   gnutls_dh_params_init (&amp;dh_params);
5910   gnutls_dh_params_generate2 (dh_params, DH_BITS);
5911
5912   return 0;
5913 }
5914
5915 static gnutls_session_t
5916 initialize_tls_session (void)
5917 {
5918   gnutls_session_t session;
5919
5920   gnutls_init (&amp;session, GNUTLS_SERVER);
5921
5922   gnutls_priority_set_direct (session, &quot;NORMAL&quot;, NULL);
5923
5924   /* request client certificate if any.
5925    */
5926   gnutls_certificate_server_set_request (session, GNUTLS_CERT_REQUEST);
5927
5928   gnutls_dh_set_prime_bits (session, DH_BITS);
5929
5930   return session;
5931 }
5932
5933 int
5934 main (void)
5935 {
5936   int err, listen_sd;
5937   int sd, ret;
5938   struct sockaddr_in sa_serv;
5939   struct sockaddr_in sa_cli;
5940   int client_len;
5941   char topbuf[512];
5942   gnutls_session_t session;
5943   char buffer[MAX_BUF + 1];
5944   int optval = 1;
5945   char name[256];
5946
5947   strcpy (name, &quot;Echo Server&quot;);
5948
5949   /* this must be called once in the program
5950    */
5951   gnutls_global_init ();
5952
5953   gnutls_certificate_allocate_credentials (&amp;cred);
5954   gnutls_certificate_set_openpgp_keyring_file (cred, RINGFILE,
5955                                                GNUTLS_OPENPGP_FMT_BASE64);
5956
5957   gnutls_certificate_set_openpgp_key_file (cred, CERTFILE, KEYFILE,
5958                                            GNUTLS_OPENPGP_FMT_BASE64);
5959
5960   generate_dh_params ();
5961
5962   gnutls_certificate_set_dh_params (cred, dh_params);
5963
5964   /* Socket operations
5965    */
5966   listen_sd = socket (AF_INET, SOCK_STREAM, 0);
5967   SOCKET_ERR (listen_sd, &quot;socket&quot;);
5968
5969   memset (&amp;sa_serv, '\0', sizeof (sa_serv));
5970   sa_serv.sin_family = AF_INET;
5971   sa_serv.sin_addr.s_addr = INADDR_ANY;
5972   sa_serv.sin_port = htons (PORT);      /* Server Port number */
5973
5974   setsockopt (listen_sd, SOL_SOCKET, SO_REUSEADDR, (void *) &amp;optval,
5975               sizeof (int));
5976
5977   err = bind (listen_sd, (SA *) &amp; sa_serv, sizeof (sa_serv));
5978   SOCKET_ERR (err, &quot;bind&quot;);
5979   err = listen (listen_sd, 1024);
5980   SOCKET_ERR (err, &quot;listen&quot;);
5981
5982   printf (&quot;%s ready. Listening to port '%d'.\n\n&quot;, name, PORT);
5983
5984   client_len = sizeof (sa_cli);
5985   for (;;)
5986     {
5987       session = initialize_tls_session ();
5988
5989       sd = accept (listen_sd, (SA *) &amp; sa_cli, &amp;client_len);
5990
5991       printf (&quot;- connection from %s, port %d\n&quot;,
5992               inet_ntop (AF_INET, &amp;sa_cli.sin_addr, topbuf,
5993                          sizeof (topbuf)), ntohs (sa_cli.sin_port));
5994
5995       gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd);
5996       ret = gnutls_handshake (session);
5997       if (ret &lt; 0)
5998         {
5999           close (sd);
6000           gnutls_deinit (session);
6001           fprintf (stderr, &quot;*** Handshake has failed (%s)\n\n&quot;,
6002                    gnutls_strerror (ret));
6003           continue;
6004         }
6005       printf (&quot;- Handshake was completed\n&quot;);
6006
6007       /* see the Getting peer's information example */
6008       /* print_info(session); */
6009
6010       for (;;)
6011         {
6012           memset (buffer, 0, MAX_BUF + 1);
6013           ret = gnutls_record_recv (session, buffer, MAX_BUF);
6014
6015           if (ret == 0)
6016             {
6017               printf (&quot;\n- Peer has closed the GnuTLS connection\n&quot;);
6018               break;
6019             }
6020           else if (ret &lt; 0)
6021             {
6022               fprintf (stderr, &quot;\n*** Received corrupted &quot;
6023                        &quot;data(%d). Closing the connection.\n\n&quot;, ret);
6024               break;
6025             }
6026           else if (ret &gt; 0)
6027             {
6028               /* echo data back to the client
6029                */
6030               gnutls_record_send (session, buffer, strlen (buffer));
6031             }
6032         }
6033       printf (&quot;\n&quot;);
6034       /* do not wait for the peer to close the connection.
6035        */
6036       gnutls_bye (session, GNUTLS_SHUT_WR);
6037
6038       close (sd);
6039       gnutls_deinit (session);
6040
6041     }
6042   close (listen_sd);
6043
6044   gnutls_certificate_free_credentials (cred);
6045
6046   gnutls_global_deinit ();
6047
6048   return 0;
6049
6050 }
6051 </pre>
6052 <hr>
6053 <a name="Echo-Server-with-SRP-authentication"></a>
6054 <div class="header">
6055 <p>
6056 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="previous">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>
6057 </div>
6058 <a name="Echo-Server-with-SRP-Authentication"></a>
6059 <h4 class="subsection">7.4.3 Echo Server with <acronym>SRP</acronym> Authentication</h4>
6060
6061 <p>This is a server which supports <acronym>SRP</acronym> authentication. It is
6062 also possible to combine this functionality with a certificate
6063 server. Here it is separate for simplicity.
6064 </p>
6065 <pre class="verbatim">/* This example code is placed in the public domain. */
6066
6067 #ifdef HAVE_CONFIG_H
6068 #include &lt;config.h&gt;
6069 #endif
6070
6071 #include &lt;stdio.h&gt;
6072 #include &lt;stdlib.h&gt;
6073 #include &lt;errno.h&gt;
6074 #include &lt;sys/types.h&gt;
6075 #include &lt;sys/socket.h&gt;
6076 #include &lt;arpa/inet.h&gt;
6077 #include &lt;netinet/in.h&gt;
6078 #include &lt;string.h&gt;
6079 #include &lt;unistd.h&gt;
6080 #include &lt;gnutls/gnutls.h&gt;
6081 #include &lt;gnutls/extra.h&gt;
6082
6083 #define SRP_PASSWD &quot;tpasswd&quot;
6084 #define SRP_PASSWD_CONF &quot;tpasswd.conf&quot;
6085
6086 #define KEYFILE &quot;key.pem&quot;
6087 #define CERTFILE &quot;cert.pem&quot;
6088 #define CAFILE &quot;ca.pem&quot;
6089
6090 /* This is a sample TLS-SRP echo server.
6091  */
6092
6093 #define SA struct sockaddr
6094 #define SOCKET_ERR(err,s) if(err==-1) {perror(s);return(1);}
6095 #define MAX_BUF 1024
6096 #define PORT 5556               /* listen to 5556 port */
6097
6098 /* These are global */
6099 gnutls_srp_server_credentials_t srp_cred;
6100 gnutls_certificate_credentials_t cert_cred;
6101
6102 static gnutls_session_t
6103 initialize_tls_session (void)
6104 {
6105   gnutls_session_t session;
6106
6107   gnutls_init (&amp;session, GNUTLS_SERVER);
6108
6109   gnutls_priority_set_direct (session, &quot;NORMAL:+SRP:+SRP-DSS:+SRP-RSA&quot;, NULL);
6110
6111   gnutls_credentials_set (session, GNUTLS_CRD_SRP, srp_cred);
6112   /* for the certificate authenticated ciphersuites.
6113    */
6114   gnutls_credentials_set (session, GNUTLS_CRD_CERTIFICATE, cert_cred);
6115
6116   /* request client certificate if any.
6117    */
6118   gnutls_certificate_server_set_request (session, GNUTLS_CERT_IGNORE);
6119
6120   return session;
6121 }
6122
6123 int
6124 main (void)
6125 {
6126   int err, listen_sd;
6127   int sd, ret;
6128   struct sockaddr_in sa_serv;
6129   struct sockaddr_in sa_cli;
6130   int client_len;
6131   char topbuf[512];
6132   gnutls_session_t session;
6133   char buffer[MAX_BUF + 1];
6134   int optval = 1;
6135   char name[256];
6136
6137   strcpy (name, &quot;Echo Server&quot;);
6138
6139   /* these must be called once in the program
6140    */
6141   gnutls_global_init ();
6142   gnutls_global_init_extra ();  /* for SRP */
6143
6144   /* SRP_PASSWD a password file (created with the included srptool utility)
6145    */
6146   gnutls_srp_allocate_server_credentials (&amp;srp_cred);
6147   gnutls_srp_set_server_credentials_file (srp_cred, SRP_PASSWD,
6148                                           SRP_PASSWD_CONF);
6149
6150   gnutls_certificate_allocate_credentials (&amp;cert_cred);
6151   gnutls_certificate_set_x509_trust_file (cert_cred, CAFILE,
6152                                           GNUTLS_X509_FMT_PEM);
6153   gnutls_certificate_set_x509_key_file (cert_cred, CERTFILE, KEYFILE,
6154                                         GNUTLS_X509_FMT_PEM);
6155
6156   /* TCP socket operations
6157    */
6158   listen_sd = socket (AF_INET, SOCK_STREAM, 0);
6159   SOCKET_ERR (listen_sd, &quot;socket&quot;);
6160
6161   memset (&amp;sa_serv, '\0', sizeof (sa_serv));
6162   sa_serv.sin_family = AF_INET;
6163   sa_serv.sin_addr.s_addr = INADDR_ANY;
6164   sa_serv.sin_port = htons (PORT);      /* Server Port number */
6165
6166   setsockopt (listen_sd, SOL_SOCKET, SO_REUSEADDR, (void *) &amp;optval,
6167               sizeof (int));
6168
6169   err = bind (listen_sd, (SA *) &amp; sa_serv, sizeof (sa_serv));
6170   SOCKET_ERR (err, &quot;bind&quot;);
6171   err = listen (listen_sd, 1024);
6172   SOCKET_ERR (err, &quot;listen&quot;);
6173
6174   printf (&quot;%s ready. Listening to port '%d'.\n\n&quot;, name, PORT);
6175
6176   client_len = sizeof (sa_cli);
6177   for (;;)
6178     {
6179       session = initialize_tls_session ();
6180
6181       sd = accept (listen_sd, (SA *) &amp; sa_cli, &amp;client_len);
6182
6183       printf (&quot;- connection from %s, port %d\n&quot;,
6184               inet_ntop (AF_INET, &amp;sa_cli.sin_addr, topbuf,
6185                          sizeof (topbuf)), ntohs (sa_cli.sin_port));
6186
6187       gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd);
6188       ret = gnutls_handshake (session);
6189       if (ret &lt; 0)
6190         {
6191           close (sd);
6192           gnutls_deinit (session);
6193           fprintf (stderr, &quot;*** Handshake has failed (%s)\n\n&quot;,
6194                    gnutls_strerror (ret));
6195           continue;
6196         }
6197       printf (&quot;- Handshake was completed\n&quot;);
6198
6199       /* print_info(session); */
6200
6201       for (;;)
6202         {
6203           memset (buffer, 0, MAX_BUF + 1);
6204           ret = gnutls_record_recv (session, buffer, MAX_BUF);
6205
6206           if (ret == 0)
6207             {
6208               printf (&quot;\n- Peer has closed the GnuTLS connection\n&quot;);
6209               break;
6210             }
6211           else if (ret &lt; 0)
6212             {
6213               fprintf (stderr, &quot;\n*** Received corrupted &quot;
6214                        &quot;data(%d). Closing the connection.\n\n&quot;, ret);
6215               break;
6216             }
6217           else if (ret &gt; 0)
6218             {
6219               /* echo data back to the client
6220                */
6221               gnutls_record_send (session, buffer, strlen (buffer));
6222             }
6223         }
6224       printf (&quot;\n&quot;);
6225       /* do not wait for the peer to close the connection. */
6226       gnutls_bye (session, GNUTLS_SHUT_WR);
6227
6228       close (sd);
6229       gnutls_deinit (session);
6230
6231     }
6232   close (listen_sd);
6233
6234   gnutls_srp_free_server_credentials (srp_cred);
6235   gnutls_certificate_free_credentials (cert_cred);
6236
6237   gnutls_global_deinit ();
6238
6239   return 0;
6240
6241 }
6242 </pre>
6243 <hr>
6244 <a name="Echo-Server-with-anonymous-authentication"></a>
6245 <div class="header">
6246 <p>
6247 Previous: <a href="#Echo-Server-with-SRP-authentication" accesskey="p" rel="previous">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>
6248 </div>
6249 <a name="Echo-Server-with-Anonymous-Authentication"></a>
6250 <h4 class="subsection">7.4.4 Echo Server with Anonymous Authentication</h4>
6251
6252 <p>This example server support anonymous authentication, and could be
6253 used to serve the example client for anonymous authentication.
6254 </p>
6255 <pre class="verbatim">/* This example code is placed in the public domain. */
6256
6257 #ifdef HAVE_CONFIG_H
6258 #include &lt;config.h&gt;
6259 #endif
6260
6261 #include &lt;stdio.h&gt;
6262 #include &lt;stdlib.h&gt;
6263 #include &lt;errno.h&gt;
6264 #include &lt;sys/types.h&gt;
6265 #include &lt;sys/socket.h&gt;
6266 #include &lt;arpa/inet.h&gt;
6267 #include &lt;netinet/in.h&gt;
6268 #include &lt;string.h&gt;
6269 #include &lt;unistd.h&gt;
6270 #include &lt;gnutls/gnutls.h&gt;
6271
6272 /* This is a sample TLS 1.0 echo server, for anonymous authentication only.
6273  */
6274
6275
6276 #define SA struct sockaddr
6277 #define SOCKET_ERR(err,s) if(err==-1) {perror(s);return(1);}
6278 #define MAX_BUF 1024
6279 #define PORT 5556               /* listen to 5556 port */
6280 #define DH_BITS 1024
6281
6282 /* These are global */
6283 gnutls_anon_server_credentials_t anoncred;
6284
6285 static gnutls_session_t
6286 initialize_tls_session (void)
6287 {
6288   gnutls_session_t session;
6289
6290   gnutls_init (&amp;session, GNUTLS_SERVER);
6291
6292   gnutls_priority_set_direct (session, &quot;NORMAL:+ANON-DH&quot;, NULL);
6293
6294   gnutls_credentials_set (session, GNUTLS_CRD_ANON, anoncred);
6295
6296   gnutls_dh_set_prime_bits (session, DH_BITS);
6297
6298   return session;
6299 }
6300
6301 static gnutls_dh_params_t dh_params;
6302
6303 static int
6304 generate_dh_params (void)
6305 {
6306
6307   /* Generate Diffie-Hellman parameters - for use with DHE
6308    * kx algorithms. These should be discarded and regenerated
6309    * once a day, once a week or once a month. Depending on the
6310    * security requirements.
6311    */
6312   gnutls_dh_params_init (&amp;dh_params);
6313   gnutls_dh_params_generate2 (dh_params, DH_BITS);
6314
6315   return 0;
6316 }
6317
6318 int
6319 main (void)
6320 {
6321   int err, listen_sd;
6322   int sd, ret;
6323   struct sockaddr_in sa_serv;
6324   struct sockaddr_in sa_cli;
6325   int client_len;
6326   char topbuf[512];
6327   gnutls_session_t session;
6328   char buffer[MAX_BUF + 1];
6329   int optval = 1;
6330
6331   /* this must be called once in the program
6332    */
6333   gnutls_global_init ();
6334
6335   gnutls_anon_allocate_server_credentials (&amp;anoncred);
6336
6337   generate_dh_params ();
6338
6339   gnutls_anon_set_server_dh_params (anoncred, dh_params);
6340
6341   /* Socket operations
6342    */
6343   listen_sd = socket (AF_INET, SOCK_STREAM, 0);
6344   SOCKET_ERR (listen_sd, &quot;socket&quot;);
6345
6346   memset (&amp;sa_serv, '\0', sizeof (sa_serv));
6347   sa_serv.sin_family = AF_INET;
6348   sa_serv.sin_addr.s_addr = INADDR_ANY;
6349   sa_serv.sin_port = htons (PORT);      /* Server Port number */
6350
6351   setsockopt (listen_sd, SOL_SOCKET, SO_REUSEADDR, (void *) &amp;optval,
6352               sizeof (int));
6353
6354   err = bind (listen_sd, (SA *) &amp; sa_serv, sizeof (sa_serv));
6355   SOCKET_ERR (err, &quot;bind&quot;);
6356   err = listen (listen_sd, 1024);
6357   SOCKET_ERR (err, &quot;listen&quot;);
6358
6359   printf (&quot;Server ready. Listening to port '%d'.\n\n&quot;, PORT);
6360
6361   client_len = sizeof (sa_cli);
6362   for (;;)
6363     {
6364       session = initialize_tls_session ();
6365
6366       sd = accept (listen_sd, (SA *) &amp; sa_cli, &amp;client_len);
6367
6368       printf (&quot;- connection from %s, port %d\n&quot;,
6369               inet_ntop (AF_INET, &amp;sa_cli.sin_addr, topbuf,
6370                          sizeof (topbuf)), ntohs (sa_cli.sin_port));
6371
6372       gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd);
6373       ret = gnutls_handshake (session);
6374       if (ret &lt; 0)
6375         {
6376           close (sd);
6377           gnutls_deinit (session);
6378           fprintf (stderr, &quot;*** Handshake has failed (%s)\n\n&quot;,
6379                    gnutls_strerror (ret));
6380           continue;
6381         }
6382       printf (&quot;- Handshake was completed\n&quot;);
6383
6384       /* see the Getting peer's information example */
6385       /* print_info(session); */
6386
6387       for (;;)
6388         {
6389           memset (buffer, 0, MAX_BUF + 1);
6390           ret = gnutls_record_recv (session, buffer, MAX_BUF);
6391
6392           if (ret == 0)
6393             {
6394               printf (&quot;\n- Peer has closed the GnuTLS connection\n&quot;);
6395               break;
6396             }
6397           else if (ret &lt; 0)
6398             {
6399               fprintf (stderr, &quot;\n*** Received corrupted &quot;
6400                        &quot;data(%d). Closing the connection.\n\n&quot;, ret);
6401               break;
6402             }
6403           else if (ret &gt; 0)
6404             {
6405               /* echo data back to the client
6406                */
6407               gnutls_record_send (session, buffer, strlen (buffer));
6408             }
6409         }
6410       printf (&quot;\n&quot;);
6411       /* do not wait for the peer to close the connection.
6412        */
6413       gnutls_bye (session, GNUTLS_SHUT_WR);
6414
6415       close (sd);
6416       gnutls_deinit (session);
6417
6418     }
6419   close (listen_sd);
6420
6421   gnutls_anon_free_server_credentials (anoncred);
6422
6423   gnutls_global_deinit ();
6424
6425   return 0;
6426
6427 }
6428 </pre>
6429 <hr>
6430 <a name="Miscellaneous-examples"></a>
6431 <div class="header">
6432 <p>
6433 Next: <a href="#Parameter-generation" accesskey="n" rel="next">Parameter generation</a>, Previous: <a href="#Server-examples" accesskey="p" rel="previous">Server examples</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>
6434 </div>
6435 <a name="Miscellaneous-Examples"></a>
6436 <h3 class="section">7.5 Miscellaneous Examples</h3>
6437
6438 <table class="menu" border="0" cellspacing="0">
6439 <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">
6440 </td></tr>
6441 <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">
6442 </td></tr>
6443 <tr><td align="left" valign="top">&bull; <a href="#Certificate-request-generation" accesskey="3">Certificate request generation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
6444 </td></tr>
6445 <tr><td align="left" valign="top">&bull; <a href="#PKCS-_002312-structure-generation" accesskey="4">PKCS #12 structure generation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
6446 </td></tr>
6447 </table>
6448
6449 <hr>
6450 <a name="Checking-for-an-alert"></a>
6451 <div class="header">
6452 <p>
6453 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>
6454 </div>
6455 <a name="Checking-for-an-Alert"></a>
6456 <h4 class="subsection">7.5.1 Checking for an Alert</h4>
6457
6458 <p>This is a function that checks if an alert has been received in the
6459 current session.
6460 </p>
6461 <pre class="verbatim">/* This example code is placed in the public domain. */
6462
6463 #ifdef HAVE_CONFIG_H
6464 #include &lt;config.h&gt;
6465 #endif
6466
6467 #include &lt;stdio.h&gt;
6468 #include &lt;stdlib.h&gt;
6469 #include &lt;gnutls/gnutls.h&gt;
6470
6471 #include &quot;examples.h&quot;
6472
6473 /* This function will check whether the given return code from
6474  * a gnutls function (recv/send), is an alert, and will print
6475  * that alert.
6476  */
6477 void
6478 check_alert (gnutls_session_t session, int ret)
6479 {
6480   int last_alert;
6481
6482   if (ret == GNUTLS_E_WARNING_ALERT_RECEIVED
6483       || ret == GNUTLS_E_FATAL_ALERT_RECEIVED)
6484     {
6485       last_alert = gnutls_alert_get (session);
6486
6487       /* The check for renegotiation is only useful if we are
6488        * a server, and we had requested a rehandshake.
6489        */
6490       if (last_alert == GNUTLS_A_NO_RENEGOTIATION &amp;&amp;
6491           ret == GNUTLS_E_WARNING_ALERT_RECEIVED)
6492         printf (&quot;* Received NO_RENEGOTIATION alert. &quot;
6493                 &quot;Client Does not support renegotiation.\n&quot;);
6494       else
6495         printf (&quot;* Received alert '%d': %s.\n&quot;, last_alert,
6496                 gnutls_alert_get_name (last_alert));
6497     }
6498 }
6499 </pre>
6500 <hr>
6501 <a name="X_002e509-certificate-parsing-example"></a>
6502 <div class="header">
6503 <p>
6504 Next: <a href="#Certificate-request-generation" accesskey="n" rel="next">Certificate request generation</a>, Previous: <a href="#Checking-for-an-alert" accesskey="p" rel="previous">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>
6505 </div>
6506 <a name="X_002e509-Certificate-Parsing-Example"></a>
6507 <h4 class="subsection">7.5.2 <acronym>X.509</acronym> Certificate Parsing Example</h4>
6508 <a name="ex_003ax509_002dinfo"></a>
6509 <p>To demonstrate the <acronym>X.509</acronym> parsing capabilities an example program is
6510 listed below.  That program reads the peer&rsquo;s certificate, and prints
6511 information about it.
6512 </p>
6513 <pre class="verbatim">/* This example code is placed in the public domain. */
6514
6515 #ifdef HAVE_CONFIG_H
6516 #include &lt;config.h&gt;
6517 #endif
6518
6519 #include &lt;stdio.h&gt;
6520 #include &lt;stdlib.h&gt;
6521 #include &lt;gnutls/gnutls.h&gt;
6522 #include &lt;gnutls/x509.h&gt;
6523
6524 #include &quot;examples.h&quot;
6525
6526 static const char *
6527 bin2hex (const void *bin, size_t bin_size)
6528 {
6529   static char printable[110];
6530   const unsigned char *_bin = bin;
6531   char *print;
6532   size_t i;
6533
6534   if (bin_size &gt; 50)
6535     bin_size = 50;
6536
6537   print = printable;
6538   for (i = 0; i &lt; bin_size; i++)
6539     {
6540       sprintf (print, &quot;%.2x &quot;, _bin[i]);
6541       print += 2;
6542     }
6543
6544   return printable;
6545 }
6546
6547 /* This function will print information about this session's peer
6548  * certificate.
6549  */
6550 void
6551 print_x509_certificate_info (gnutls_session_t session)
6552 {
6553   char serial[40];
6554   char dn[256];
6555   size_t size;
6556   unsigned int algo, bits;
6557   time_t expiration_time, activation_time;
6558   const gnutls_datum_t *cert_list;
6559   unsigned int cert_list_size = 0;
6560   gnutls_x509_crt_t cert;
6561   gnutls_datum_t cinfo;
6562
6563   /* This function only works for X.509 certificates.
6564    */
6565   if (gnutls_certificate_type_get (session) != GNUTLS_CRT_X509)
6566     return;
6567
6568   cert_list = gnutls_certificate_get_peers (session, &amp;cert_list_size);
6569
6570   printf (&quot;Peer provided %d certificates.\n&quot;, cert_list_size);
6571
6572   if (cert_list_size &gt; 0)
6573     {
6574       int ret;
6575
6576       /* we only print information about the first certificate.
6577        */
6578       gnutls_x509_crt_init (&amp;cert);
6579
6580       gnutls_x509_crt_import (cert, &amp;cert_list[0], GNUTLS_X509_FMT_DER);
6581
6582       printf (&quot;Certificate info:\n&quot;);
6583
6584       /* This is the preferred way of printing short information about
6585          a certificate. */
6586
6587       ret = gnutls_x509_crt_print (cert, GNUTLS_CRT_PRINT_ONELINE, &amp;cinfo);
6588       if (ret == 0)
6589         {
6590           printf (&quot;\t%s\n&quot;, cinfo.data);
6591           gnutls_free (cinfo.data);
6592         }
6593
6594       /* If you want to extract fields manually for some other reason,
6595          below are popular example calls. */
6596
6597       expiration_time = gnutls_x509_crt_get_expiration_time (cert);
6598       activation_time = gnutls_x509_crt_get_activation_time (cert);
6599
6600       printf (&quot;\tCertificate is valid since: %s&quot;, ctime (&amp;activation_time));
6601       printf (&quot;\tCertificate expires: %s&quot;, ctime (&amp;expiration_time));
6602
6603       /* Print the serial number of the certificate.
6604        */
6605       size = sizeof (serial);
6606       gnutls_x509_crt_get_serial (cert, serial, &amp;size);
6607
6608       printf (&quot;\tCertificate serial number: %s\n&quot;, bin2hex (serial, size));
6609
6610       /* Extract some of the public key algorithm's parameters
6611        */
6612       algo = gnutls_x509_crt_get_pk_algorithm (cert, &amp;bits);
6613
6614       printf (&quot;Certificate public key: %s&quot;,
6615               gnutls_pk_algorithm_get_name (algo));
6616
6617       /* Print the version of the X.509
6618        * certificate.
6619        */
6620       printf (&quot;\tCertificate version: #%d\n&quot;,
6621               gnutls_x509_crt_get_version (cert));
6622
6623       size = sizeof (dn);
6624       gnutls_x509_crt_get_dn (cert, dn, &amp;size);
6625       printf (&quot;\tDN: %s\n&quot;, dn);
6626
6627       size = sizeof (dn);
6628       gnutls_x509_crt_get_issuer_dn (cert, dn, &amp;size);
6629       printf (&quot;\tIssuer's DN: %s\n&quot;, dn);
6630
6631       gnutls_x509_crt_deinit (cert);
6632
6633     }
6634 }
6635 </pre>
6636 <hr>
6637 <a name="Certificate-request-generation"></a>
6638 <div class="header">
6639 <p>
6640 Next: <a href="#PKCS-_002312-structure-generation" accesskey="n" rel="next">PKCS #12 structure generation</a>, Previous: <a href="#X_002e509-certificate-parsing-example" accesskey="p" rel="previous">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>
6641 </div>
6642 <a name="Certificate-Request-Generation"></a>
6643 <h4 class="subsection">7.5.3 Certificate Request Generation</h4>
6644 <a name="ex_003acrq"></a>
6645 <p>The following example is about generating a certificate request, and a
6646 private key. A certificate request can be later be processed by a CA,
6647 which should return a signed certificate.
6648 </p>
6649 <pre class="verbatim">/* This example code is placed in the public domain. */
6650
6651 #ifdef HAVE_CONFIG_H
6652 #include &lt;config.h&gt;
6653 #endif
6654
6655 #include &lt;stdio.h&gt;
6656 #include &lt;stdlib.h&gt;
6657 #include &lt;string.h&gt;
6658 #include &lt;gnutls/gnutls.h&gt;
6659 #include &lt;gnutls/x509.h&gt;
6660 #include &lt;gnutls/abstract.h&gt;
6661 #include &lt;time.h&gt;
6662
6663 /* This example will generate a private key and a certificate
6664  * request.
6665  */
6666
6667 int
6668 main (void)
6669 {
6670   gnutls_x509_crq_t crq;
6671   gnutls_x509_privkey_t key;
6672   gnutls_privkey_t pkey; /* object used for signing */
6673   unsigned char buffer[10 * 1024];
6674   size_t buffer_size = sizeof (buffer);
6675   unsigned int bits;
6676
6677   gnutls_global_init ();
6678
6679   /* Initialize an empty certificate request, and
6680    * an empty private key.
6681    */
6682   gnutls_x509_crq_init (&amp;crq);
6683
6684   gnutls_x509_privkey_init (&amp;key);
6685   gnutls_privkey_init (&amp;pkey);
6686
6687   /* Generate an RSA key of moderate security.
6688    */
6689   bits = gnutls_sec_param_to_pk_bits (GNUTLS_PK_RSA, GNUTLS_SEC_PARAM_NORMAL);
6690   gnutls_x509_privkey_generate (key, GNUTLS_PK_RSA, bits, 0);
6691
6692   /* Add stuff to the distinguished name
6693    */
6694   gnutls_x509_crq_set_dn_by_oid (crq, GNUTLS_OID_X520_COUNTRY_NAME,
6695                                  0, &quot;GR&quot;, 2);
6696
6697   gnutls_x509_crq_set_dn_by_oid (crq, GNUTLS_OID_X520_COMMON_NAME,
6698                                  0, &quot;Nikos&quot;, strlen (&quot;Nikos&quot;));
6699
6700   /* Set the request version.
6701    */
6702   gnutls_x509_crq_set_version (crq, 1);
6703
6704   /* Set a challenge password.
6705    */
6706   gnutls_x509_crq_set_challenge_password (crq, &quot;something to remember here&quot;);
6707
6708   /* Associate the request with the private key
6709    */
6710   gnutls_x509_crq_set_key (crq, key);
6711
6712   /* Self sign the certificate request.
6713    */
6714   gnutls_privkey_import_x509( pkey, key, 0);
6715   gnutls_x509_crq_privkey_sign (crq, pkey, GNUTLS_DIG_SHA1, 0);
6716
6717   /* Export the PEM encoded certificate request, and
6718    * display it.
6719    */
6720   gnutls_x509_crq_export (crq, GNUTLS_X509_FMT_PEM, buffer, &amp;buffer_size);
6721
6722   printf (&quot;Certificate Request: \n%s&quot;, buffer);
6723
6724
6725   /* Export the PEM encoded private key, and
6726    * display it.
6727    */
6728   buffer_size = sizeof (buffer);
6729   gnutls_x509_privkey_export (key, GNUTLS_X509_FMT_PEM, buffer, &amp;buffer_size);
6730
6731   printf (&quot;\n\nPrivate key: \n%s&quot;, buffer);
6732
6733   gnutls_x509_crq_deinit (crq);
6734   gnutls_x509_privkey_deinit (key);
6735
6736   return 0;
6737
6738 }
6739 </pre>
6740 <hr>
6741 <a name="PKCS-_002312-structure-generation"></a>
6742 <div class="header">
6743 <p>
6744 Previous: <a href="#Certificate-request-generation" accesskey="p" rel="previous">Certificate request generation</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>
6745 </div>
6746 <a name="PKCS-_002312-Structure-Generation"></a>
6747 <h4 class="subsection">7.5.4 <acronym>PKCS</acronym> #12 Structure Generation</h4>
6748 <a name="ex_003apkcs12"></a>
6749 <p>The following example is about generating a <acronym>PKCS</acronym> #12
6750 structure.
6751 </p>
6752 <pre class="verbatim">/* This example code is placed in the public domain. */
6753
6754 #ifdef HAVE_CONFIG_H
6755 #include &lt;config.h&gt;
6756 #endif
6757
6758 #include &lt;stdio.h&gt;
6759 #include &lt;stdlib.h&gt;
6760 #include &lt;gnutls/gnutls.h&gt;
6761 #include &lt;gnutls/pkcs12.h&gt;
6762
6763 #include &quot;examples.h&quot;
6764
6765 #define OUTFILE &quot;out.p12&quot;
6766
6767 /* This function will write a pkcs12 structure into a file.
6768  * cert: is a DER encoded certificate
6769  * pkcs8_key: is a PKCS #8 encrypted key (note that this must be
6770  *  encrypted using a PKCS #12 cipher, or some browsers will crash)
6771  * password: is the password used to encrypt the PKCS #12 packet.
6772  */
6773 int
6774 write_pkcs12 (const gnutls_datum_t * cert,
6775               const gnutls_datum_t * pkcs8_key, const char *password)
6776 {
6777   gnutls_pkcs12_t pkcs12;
6778   int ret, bag_index;
6779   gnutls_pkcs12_bag_t bag, key_bag;
6780   char pkcs12_struct[10 * 1024];
6781   size_t pkcs12_struct_size;
6782   FILE *fd;
6783
6784   /* A good idea might be to use gnutls_x509_privkey_get_key_id()
6785    * to obtain a unique ID.
6786    */
6787   gnutls_datum_t key_id = { (char *) &quot;\x00\x00\x07&quot;, 3 };
6788
6789   gnutls_global_init ();
6790
6791   /* Firstly we create two helper bags, which hold the certificate,
6792    * and the (encrypted) key.
6793    */
6794
6795   gnutls_pkcs12_bag_init (&amp;bag);
6796   gnutls_pkcs12_bag_init (&amp;key_bag);
6797
6798   ret = gnutls_pkcs12_bag_set_data (bag, GNUTLS_BAG_CERTIFICATE, cert);
6799   if (ret &lt; 0)
6800     {
6801       fprintf (stderr, &quot;ret: %s\n&quot;, gnutls_strerror (ret));
6802       return 1;
6803     }
6804
6805   /* ret now holds the bag's index.
6806    */
6807   bag_index = ret;
6808
6809   /* Associate a friendly name with the given certificate. Used
6810    * by browsers.
6811    */
6812   gnutls_pkcs12_bag_set_friendly_name (bag, bag_index, &quot;My name&quot;);
6813
6814   /* Associate the certificate with the key using a unique key
6815    * ID.
6816    */
6817   gnutls_pkcs12_bag_set_key_id (bag, bag_index, &amp;key_id);
6818
6819   /* use weak encryption for the certificate.
6820    */
6821   gnutls_pkcs12_bag_encrypt (bag, password, GNUTLS_PKCS_USE_PKCS12_RC2_40);
6822
6823   /* Now the key.
6824    */
6825
6826   ret = gnutls_pkcs12_bag_set_data (key_bag,
6827                                     GNUTLS_BAG_PKCS8_ENCRYPTED_KEY,
6828                                     pkcs8_key);
6829   if (ret &lt; 0)
6830     {
6831       fprintf (stderr, &quot;ret: %s\n&quot;, gnutls_strerror (ret));
6832       return 1;
6833     }
6834
6835   /* Note that since the PKCS #8 key is already encrypted we don't
6836    * bother encrypting that bag.
6837    */
6838   bag_index = ret;
6839
6840   gnutls_pkcs12_bag_set_friendly_name (key_bag, bag_index, &quot;My name&quot;);
6841
6842   gnutls_pkcs12_bag_set_key_id (key_bag, bag_index, &amp;key_id);
6843
6844
6845   /* The bags were filled. Now create the PKCS #12 structure.
6846    */
6847   gnutls_pkcs12_init (&amp;pkcs12);
6848
6849   /* Insert the two bags in the PKCS #12 structure.
6850    */
6851
6852   gnutls_pkcs12_set_bag (pkcs12, bag);
6853   gnutls_pkcs12_set_bag (pkcs12, key_bag);
6854
6855
6856   /* Generate a message authentication code for the PKCS #12
6857    * structure.
6858    */
6859   gnutls_pkcs12_generate_mac (pkcs12, password);
6860
6861   pkcs12_struct_size = sizeof (pkcs12_struct);
6862   ret =
6863     gnutls_pkcs12_export (pkcs12, GNUTLS_X509_FMT_DER, pkcs12_struct,
6864                           &amp;pkcs12_struct_size);
6865   if (ret &lt; 0)
6866     {
6867       fprintf (stderr, &quot;ret: %s\n&quot;, gnutls_strerror (ret));
6868       return 1;
6869     }
6870
6871   fd = fopen (OUTFILE, &quot;w&quot;);
6872   if (fd == NULL)
6873     {
6874       fprintf (stderr, &quot;cannot open file\n&quot;);
6875       return 1;
6876     }
6877   fwrite (pkcs12_struct, 1, pkcs12_struct_size, fd);
6878   fclose (fd);
6879
6880   gnutls_pkcs12_bag_deinit (bag);
6881   gnutls_pkcs12_bag_deinit (key_bag);
6882   gnutls_pkcs12_deinit (pkcs12);
6883
6884   return 0;
6885 }
6886 </pre>
6887 <hr>
6888 <a name="Parameter-generation"></a>
6889 <div class="header">
6890 <p>
6891 Next: <a href="#Keying-Material-Exporters" accesskey="n" rel="next">Keying Material Exporters</a>, Previous: <a href="#Miscellaneous-examples" accesskey="p" rel="previous">Miscellaneous examples</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>
6892 </div>
6893 <a name="Parameter-generation-1"></a>
6894 <h3 class="section">7.6 Parameter generation</h3>
6895 <a name="index-parameter-generation"></a>
6896 <a name="index-generating-parameters"></a>
6897
6898 <p>Several TLS ciphersuites require additional parameters that
6899 need to be generated or provided by the application. The
6900 Diffie-Hellman based ciphersuites (ANON-DH or DHE), require
6901 the group information to be provided. This information can be either
6902 be generated on the fly using <a href="#gnutls_005fdh_005fparams_005fgenerate2">gnutls_dh_params_generate2</a>
6903 or imported from some pregenerated value using <a href="#gnutls_005fdh_005fparams_005fimport_005fpkcs3">gnutls_dh_params_import_pkcs3</a>.
6904 The parameters can be used in a session by calling
6905 <a href="#gnutls_005fcertificate_005fset_005fdh_005fparams">gnutls_certificate_set_dh_params</a> or
6906 <a href="#gnutls_005fanon_005fset_005fserver_005fdh_005fparams">gnutls_anon_set_server_dh_params</a> for anonymous sessions.
6907 </p>
6908 <p>Due to the time-consuming calculations required for the generation
6909 of Diffie-Hellman parameters we suggest against performing generation
6910 of them within an application. The <code>certtool</code> tool can be used to
6911 generate or export known safe values that can be stored in code
6912 or in a configuration file to provide the ability to replace. We also
6913 recommend the usage of <a href="#gnutls_005fsec_005fparam_005fto_005fpk_005fbits">gnutls_sec_param_to_pk_bits</a> to determine
6914 the bit size of the parameters to be generated.
6915 </p>
6916 <p>The ciphersuites that involve the RSA-EXPORT key exchange require
6917 additional parameters. Those ciphersuites are rarely used today
6918 because they are by design insecure, thus if you have no requirement
6919 for them, this section should be skipped. The RSA-EXPORT key exchange
6920 requires 512-bit RSA keys to be generated. It is recommended those
6921 parameters to be refreshed (regenerated) in short intervals. The
6922 following functions can be used for these parameters.
6923 </p>
6924 <ul>
6925 <li> <a href="#gnutls_005frsa_005fparams_005fgenerate2">gnutls_rsa_params_generate2</a>
6926
6927 </li><li> <a href="#gnutls_005fcertificate_005fset_005frsa_005fexport_005fparams">gnutls_certificate_set_rsa_export_params</a>
6928
6929 </li><li> <a href="#gnutls_005frsa_005fparams_005fimport_005fpkcs1">gnutls_rsa_params_import_pkcs1</a>
6930
6931 </li><li> <a href="#gnutls_005frsa_005fparams_005fexport_005fpkcs1">gnutls_rsa_params_export_pkcs1</a>
6932
6933 </li></ul>
6934
6935
6936 <hr>
6937 <a name="Keying-Material-Exporters"></a>
6938 <div class="header">
6939 <p>
6940 Next: <a href="#Channel-Bindings" accesskey="n" rel="next">Channel Bindings</a>, Previous: <a href="#Parameter-generation" accesskey="p" rel="previous">Parameter generation</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>
6941 </div>
6942 <a name="Keying-Material-Exporters-1"></a>
6943 <h3 class="section">7.7 Keying Material Exporters</h3>
6944 <a name="index-Keying-Material-Exporters"></a>
6945 <a name="index-Exporting-Keying-Material"></a>
6946
6947 <p>The TLS PRF can be used by other protocols to derive data.  The API to
6948 use is <a href="#gnutls_005fprf">gnutls_prf</a>.  The function needs to be provided with the
6949 label in the parameter <code>label</code>, and the extra data to mix in the
6950 <code>extra</code> parameter.  Depending on whether you want to mix in the
6951 client or server random data first, you can set the
6952 <code>server_random_first</code> parameter.
6953 </p>
6954 <p>For example, after establishing a TLS session using
6955 <a href="#gnutls_005fhandshake">gnutls_handshake</a>, you can invoke the TLS PRF with this call:
6956 </p>
6957 <div class="smallexample">
6958 <pre class="smallexample">#define MYLABEL &quot;EXPORTER-FOO&quot;
6959 #define MYCONTEXT &quot;some context data&quot;
6960 char out[32];
6961 rc = gnutls_prf (session, strlen (MYLABEL), MYLABEL, 0,
6962                  strlen (MYCONTEXT), MYCONTEXT, 32, out);
6963 </pre></div>
6964
6965 <p>If you don&rsquo;t want to mix in the client/server random, there is a more
6966 low-level TLS PRF interface called <a href="#gnutls_005fprf_005fraw">gnutls_prf_raw</a>.
6967 </p>
6968 <hr>
6969 <a name="Channel-Bindings"></a>
6970 <div class="header">
6971 <p>
6972 Next: <a href="#Compatibility-with-the-OpenSSL-library" accesskey="n" rel="next">Compatibility with the OpenSSL library</a>, Previous: <a href="#Keying-Material-Exporters" accesskey="p" rel="previous">Keying Material Exporters</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>
6973 </div>
6974 <a name="Channel-Bindings-1"></a>
6975 <h3 class="section">7.8 Channel Bindings</h3>
6976 <a name="index-Channel-Bindings"></a>
6977
6978 <p>In user authentication protocols (e.g., EAP or SASL mechanisms) it is
6979 useful to have a unique string that identifies the secure channel that
6980 is used, to bind together the user authentication with the secure
6981 channel.  This can protect against man-in-the-middle attacks in some
6982 situations.  The unique strings is a &ldquo;channel bindings&rdquo;.  For
6983 background and more discussion see [RFC5056] (see <a href="#Bibliography">Bibliography</a>).
6984 </p>
6985 <p>You can extract a channel bindings using the
6986 <a href="#gnutls_005fsession_005fchannel_005fbinding">gnutls_session_channel_binding</a> function.  Currently only the
6987 <code>GNUTLS_CB_TLS_UNIQUE</code> type is supported, which corresponds to
6988 the <code>tls-unique</code> channel bindings for TLS defined in
6989 [RFC5929] (see <a href="#Bibliography">Bibliography</a>).
6990 </p>
6991 <p>The following example describes how to print the channel binding data.
6992 Note that it must be run after a successful TLS handshake.
6993 </p>
6994 <div class="smallexample">
6995 <pre class="smallexample">{
6996   gnutls_datum cb;
6997   int rc;
6998
6999   rc = gnutls_session_channel_binding (session,
7000                                        GNUTLS_CB_TLS_UNIQUE,
7001                                        &amp;cb);
7002   if (rc)
7003     fprintf (stderr, &quot;Channel binding error: %s\n&quot;,
7004              gnutls_strerror (rc));
7005   else
7006     {
7007       size_t i;
7008       printf (&quot;- Channel binding 'tls-unique': &quot;);
7009       for (i = 0; i &lt; cb.size; i++)
7010         printf (&quot;%02x&quot;, cb.data[i]);
7011       printf (&quot;\n&quot;);
7012     }
7013 }
7014 </pre></div>
7015
7016 <hr>
7017 <a name="Compatibility-with-the-OpenSSL-library"></a>
7018 <div class="header">
7019 <p>
7020 Previous: <a href="#Channel-Bindings" accesskey="p" rel="previous">Channel Bindings</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>
7021 </div>
7022 <a name="Compatibility-with-the-OpenSSL-Library"></a>
7023 <h3 class="section">7.9 Compatibility with the OpenSSL Library</h3>
7024 <a name="index-OpenSSL"></a>
7025
7026 <p>To ease <acronym>GnuTLS</acronym>&rsquo; integration with existing applications, a
7027 compatibility layer with the widely used OpenSSL library is included
7028 in the <code>gnutls-openssl</code> library. This compatibility layer is not
7029 complete and it is not intended to completely reimplement the OpenSSL
7030 API with <acronym>GnuTLS</acronym>.  It only provides source-level
7031 compatibility. There is currently no attempt to make it
7032 binary-compatible with OpenSSL.
7033 </p>
7034 <p>The prototypes for the compatibility functions are in the
7035 &lsquo;<tt>gnutls/openssl.h</tt>&rsquo; header file.
7036 </p>
7037 <p>Current limitations imposed by the compatibility layer include:
7038 </p>
7039 <ul>
7040 <li> Error handling is not thread safe.
7041
7042 </li></ul>
7043
7044
7045 <hr>
7046 <a name="Included-programs"></a>
7047 <div class="header">
7048 <p>
7049 Next: <a href="#Function-reference" accesskey="n" rel="next">Function reference</a>, Previous: <a href="#How-to-use-GnuTLS-in-applications" accesskey="p" rel="previous">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>
7050 </div>
7051 <a name="Included-Programs"></a>
7052 <h2 class="chapter">8 Included Programs</h2>
7053
7054 <p>Included with <acronym>GnuTLS</acronym> are also a few command line tools that
7055 let you use the library for common tasks without writing an
7056 application.  The applications are discussed in this chapter.
7057 </p>
7058 <table class="menu" border="0" cellspacing="0">
7059 <tr><td align="left" valign="top">&bull; <a href="#Invoking-certtool" accesskey="1">Invoking certtool</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7060 </td></tr>
7061 <tr><td align="left" valign="top">&bull; <a href="#Invoking-gnutls_002dcli" accesskey="2">Invoking gnutls-cli</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7062 </td></tr>
7063 <tr><td align="left" valign="top">&bull; <a href="#Invoking-gnutls_002dcli_002ddebug" accesskey="3">Invoking gnutls-cli-debug</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7064 </td></tr>
7065 <tr><td align="left" valign="top">&bull; <a href="#Invoking-gnutls_002dserv" accesskey="4">Invoking gnutls-serv</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7066 </td></tr>
7067 <tr><td align="left" valign="top">&bull; <a href="#Invoking-psktool" accesskey="5">Invoking psktool</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7068 </td></tr>
7069 <tr><td align="left" valign="top">&bull; <a href="#Invoking-srptool" accesskey="6">Invoking srptool</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7070 </td></tr>
7071 <tr><td align="left" valign="top">&bull; <a href="#Invoking-p11tool" accesskey="7">Invoking p11tool</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7072 </td></tr>
7073 </table>
7074
7075 <hr>
7076 <a name="Invoking-certtool"></a>
7077 <div class="header">
7078 <p>
7079 Next: <a href="#Invoking-gnutls_002dcli" accesskey="n" rel="next">Invoking gnutls-cli</a>, Up: <a href="#Included-programs" accesskey="u" rel="up">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>
7080 </div>
7081 <a name="Invoking-certtool-1"></a>
7082 <h3 class="section">8.1 Invoking certtool</h3>
7083 <a name="index-certtool"></a>
7084
7085 <p>This is a program to generate <acronym>X.509</acronym> certificates, certificate
7086 requests, CRLs and private keys.
7087 </p>
7088 <pre class="verbatim">Certtool help
7089 Usage: certtool [options]
7090      -s, --generate-self-signed
7091                               Generate a self-signed certificate.
7092      -c, --generate-certificate
7093                               Generate a signed certificate.
7094      --generate-proxy         Generate a proxy certificate.
7095      --generate-crl           Generate a CRL.
7096      -u, --update-certificate
7097                               Update a signed certificate.
7098      -p, --generate-privkey   Generate a private key.
7099      -q, --generate-request   Generate a PKCS #10 certificate
7100                               request.
7101      -e, --verify-chain       Verify a PEM encoded certificate chain.
7102                               The last certificate in the chain must
7103                               be a self signed one.
7104      --verify-crl             Verify a CRL.
7105      --generate-dh-params     Generate PKCS #3 encoded Diffie-Hellman
7106                               parameters.
7107      --get-dh-params          Get the included PKCS #3 encoded Diffie
7108                               Hellman parameters.
7109      --load-privkey FILE      Private key file to use.
7110      --load-request FILE      Certificate request file to use.
7111      --load-certificate FILE
7112                               Certificate file to use.
7113      --load-ca-privkey FILE   Certificate authority's private key
7114                               file to use.
7115      --load-ca-certificate FILE
7116                               Certificate authority's certificate
7117                               file to use.
7118      --password PASSWORD      Password to use.
7119      -i, --certificate-info   Print information on a certificate.
7120      -l, --crl-info           Print information on a CRL.
7121      --p12-info               Print information on a PKCS #12
7122                               structure.
7123      --p7-info                Print information on a PKCS #7
7124                               structure.
7125      --smime-to-p7            Convert S/MIME to PKCS #7 structure.
7126      -k, --key-info           Print information on a private key.
7127      --fix-key                Regenerate the parameters in a private
7128                               key.
7129      --to-p12                 Generate a PKCS #12 structure.
7130      -8, --pkcs8              Use PKCS #8 format for private keys.
7131      --dsa                    Use DSA keys.
7132      --hash STR               Hash algorithm to use for signing
7133                               (MD5,SHA1,RMD160).
7134      --export-ciphers         Use weak encryption algorithms.
7135      --inder                  Use DER format for input certificates
7136                               and private keys.
7137      --outder                 Use DER format for output certificates
7138                               and private keys.
7139      --bits BITS              specify the number of bits for key
7140                               generation.
7141      --outfile FILE           Output file.
7142      --infile FILE            Input file.
7143      --template FILE          Template file to use for non
7144                               interactive operation.
7145      -d, --debug LEVEL        specify the debug level. Default is 1.
7146      -h, --help               shows this help text
7147      -v, --version            shows the program's version
7148 </pre>
7149 <p>The program can be used interactively or non interactively by
7150 specifying the <code>--template</code> command line option. See below for an
7151 example of a template file.
7152 </p>
7153 <p>How to use certtool interactively:
7154 </p>
7155 <ul>
7156 <li> To generate parameters for Diffie-Hellman key exchange, use the command:
7157 <div class="example">
7158 <pre class="example">$ certtool --generate-dh-params --outfile dh.pem
7159 </pre></div>
7160
7161 </li><li> To generate parameters for the RSA-EXPORT key exchange, use the command:
7162 <div class="example">
7163 <pre class="example">$ certtool --generate-privkey --bits 512 --outfile rsa.pem
7164 </pre></div>
7165
7166 </li></ul>
7167
7168 <ul>
7169 <li> To create a self signed certificate, use the command:
7170 <div class="example">
7171 <pre class="example">$ certtool --generate-privkey --outfile ca-key.pem
7172 $ certtool --generate-self-signed --load-privkey ca-key.pem \
7173    --outfile ca-cert.pem
7174 </pre></div>
7175
7176 <p>Note that a self-signed certificate usually belongs to a certificate
7177 authority, that signs other certificates.
7178 </p>
7179 </li><li> To create a private key (RSA by default), run:
7180
7181 <div class="example">
7182 <pre class="example">$ certtool --generate-privkey --outfile key.pem
7183 </pre></div>
7184
7185 <p>To create a DSA private key, run:
7186 </p>
7187 <div class="example">
7188 <pre class="example">$ certtool --dsa --generate-privkey --outfile key-dsa.pem
7189 </pre></div>
7190
7191 </li><li> To generate a certificate using the private key, use the command:
7192
7193 <div class="example">
7194 <pre class="example">$ certtool --generate-certificate --load-privkey key.pem \
7195    --outfile cert.pem --load-ca-certificate ca-cert.pem \
7196    --load-ca-privkey ca-key.pem
7197 </pre></div>
7198
7199 </li><li> To create a certificate request (needed when the certificate is issued by
7200 another party), run:
7201
7202 <div class="example">
7203 <pre class="example">$ certtool --generate-request --load-privkey key.pem \
7204   --outfile request.pem
7205 </pre></div>
7206
7207 </li><li> To generate a certificate using the previous request, use the command:
7208
7209 <div class="example">
7210 <pre class="example">$ certtool --generate-certificate --load-request request.pem \
7211    --outfile cert.pem \
7212    --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
7213 </pre></div>
7214
7215 </li><li> To view the certificate information, use:
7216
7217 <div class="example">
7218 <pre class="example">$ certtool --certificate-info --infile cert.pem
7219 </pre></div>
7220
7221 </li><li> To generate a <acronym>PKCS</acronym> #12 structure using the previous key and
7222 certificate, use the command:
7223
7224 <div class="example">
7225 <pre class="example">$ certtool --load-certificate cert.pem --load-privkey key.pem \
7226   --to-p12 --outder --outfile key.p12
7227 </pre></div>
7228
7229 <p>Some tools (reportedly web browsers) have problems with that file
7230 because it does not contain the CA certificate for the certificate.
7231 To work around that problem in the tool, you can use the
7232 &lsquo;<samp>--load-ca-certificate</samp>&rsquo; parameter as follows:
7233 </p>
7234 <div class="example">
7235 <pre class="example">$ certtool --load-ca-certificate ca.pem \
7236   --load-certificate cert.pem --load-privkey key.pem \
7237   --to-p12 --outder --outfile key.p12
7238 </pre></div>
7239
7240 </li><li> Proxy certificate can be used to delegate your credential to a
7241 temporary, typically short-lived, certificate.  To create one from the
7242 previously created certificate, first create a temporary key and then
7243 generate a proxy certificate for it, using the commands:
7244
7245 <div class="example">
7246 <pre class="example">$ certtool --generate-privkey &gt; proxy-key.pem
7247 $ certtool --generate-proxy --load-ca-privkey key.pem \
7248   --load-privkey proxy-key.pem --load-certificate cert.pem \
7249   --outfile proxy-cert.pem
7250 </pre></div>
7251
7252 </li><li> To create an empty Certificate Revocation List (CRL) do:
7253
7254 <div class="example">
7255 <pre class="example">$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem
7256 </pre></div>
7257
7258 <p>To create a CRL that contains some revoked certificates, place the
7259 certificates in a file and use <code>--load-certificate</code> as follows:
7260 </p>
7261 <div class="example">
7262 <pre class="example">$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
7263 </pre></div>
7264
7265 </li><li> To verify a Certificate Revocation List (CRL) do:
7266
7267 <div class="example">
7268 <pre class="example">$ certtool --verify-crl --load-ca-certificate x509-ca.pem &lt; crl.pem
7269 </pre></div>
7270
7271 </li></ul>
7272
7273 <p>Certtool&rsquo;s template file format:
7274 </p>
7275 <ul>
7276 <li> Firstly create a file named &rsquo;cert.cfg&rsquo; that contains the information
7277 about the certificate. An example file is listed below.
7278
7279 </li><li> Then execute:
7280
7281 <div class="example">
7282 <pre class="example">$ certtool --generate-certificate cert.pem --load-privkey key.pem  \
7283    --template cert.cfg \
7284    --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
7285 </pre></div>
7286
7287 </li></ul>
7288
7289 <p>An example certtool template file:
7290 </p>
7291 <div class="example">
7292 <pre class="example"># X.509 Certificate options
7293 #
7294 # DN options
7295
7296 # The organization of the subject.
7297 organization = &quot;Koko inc.&quot;
7298
7299 # The organizational unit of the subject.
7300 unit = &quot;sleeping dept.&quot;
7301
7302 # The locality of the subject.
7303 # locality =
7304
7305 # The state of the certificate owner.
7306 state = &quot;Attiki&quot;
7307
7308 # The country of the subject. Two letter code.
7309 country = GR
7310
7311 # The common name of the certificate owner.
7312 cn = &quot;Cindy Lauper&quot;
7313
7314 # A user id of the certificate owner.
7315 #uid = &quot;clauper&quot;
7316
7317 # If the supported DN OIDs are not adequate you can set
7318 # any OID here.
7319 # For example set the X.520 Title and the X.520 Pseudonym
7320 # by using OID and string pairs.
7321 #dn_oid = &quot;2.5.4.12&quot; &quot;Dr.&quot; &quot;2.5.4.65&quot; &quot;jackal&quot;
7322
7323 # This is deprecated and should not be used in new
7324 # certificates.
7325 # pkcs9_email = &quot;none@none.org&quot;
7326
7327 # The serial number of the certificate
7328 serial = 007
7329
7330 # In how many days, counting from today, this certificate will expire.
7331 expiration_days = 700
7332
7333 # X.509 v3 extensions
7334
7335 # A dnsname in case of a WWW server.
7336 #dns_name = &quot;www.none.org&quot;
7337 #dns_name = &quot;www.morethanone.org&quot;
7338
7339 # An IP address in case of a server.
7340 #ip_address = &quot;192.168.1.1&quot;
7341
7342 # An email in case of a person
7343 email = &quot;none@none.org&quot;
7344
7345 # An URL that has CRLs (certificate revocation lists)
7346 # available. Needed in CA certificates.
7347 #crl_dist_points = &quot;http://www.getcrl.crl/getcrl/&quot;
7348
7349 # Whether this is a CA certificate or not
7350 #ca
7351
7352 # Whether this certificate will be used for a TLS client
7353 #tls_www_client
7354
7355 # Whether this certificate will be used for a TLS server
7356 #tls_www_server
7357
7358 # Whether this certificate will be used to sign data (needed
7359 # in TLS DHE ciphersuites).
7360 signing_key
7361
7362 # Whether this certificate will be used to encrypt data (needed
7363 # in TLS RSA ciphersuites). Note that it is preferred to use different
7364 # keys for encryption and signing.
7365 #encryption_key
7366
7367 # Whether this key will be used to sign other certificates.
7368 #cert_signing_key
7369
7370 # Whether this key will be used to sign CRLs.
7371 #crl_signing_key
7372
7373 # Whether this key will be used to sign code.
7374 #code_signing_key
7375
7376 # Whether this key will be used to sign OCSP data.
7377 #ocsp_signing_key
7378
7379 # Whether this key will be used for time stamping.
7380 #time_stamping_key
7381
7382 # Whether this key will be used for IPsec IKE operations.
7383 #ipsec_ike_key
7384 </pre></div>
7385
7386 <hr>
7387 <a name="Invoking-gnutls_002dcli"></a>
7388 <div class="header">
7389 <p>
7390 Next: <a href="#Invoking-gnutls_002dcli_002ddebug" accesskey="n" rel="next">Invoking gnutls-cli-debug</a>, Previous: <a href="#Invoking-certtool" accesskey="p" rel="previous">Invoking certtool</a>, Up: <a href="#Included-programs" accesskey="u" rel="up">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>
7391 </div>
7392 <a name="Invoking-gnutls_002dcli-1"></a>
7393 <h3 class="section">8.2 Invoking gnutls-cli</h3>
7394 <a name="index-gnutls_002dcli"></a>
7395
7396 <p>Simple client program to set up a TLS connection to some other
7397 computer.  It sets up a TLS connection and forwards data from the
7398 standard input to the secured socket and vice versa.
7399 </p>
7400 <pre class="verbatim">GnuTLS test client
7401 Usage:  gnutls-cli [options] hostname
7402
7403      -d, --debug integer      Enable debugging
7404      -r, --resume             Connect, establish a session. Connect
7405                               again and resume this session.
7406      -s, --starttls           Connect, establish a plain session and
7407                               start TLS when EOF or a SIGALRM is
7408                               received.
7409      --crlf                   Send CR LF instead of LF.
7410      --x509fmtder             Use DER format for certificates to read
7411                               from.
7412      -f, --fingerprint        Send the openpgp fingerprint, instead
7413                               of the key.
7414      --disable-extensions     Disable all the TLS extensions.
7415      --print-cert             Print the certificate in PEM format.
7416      --recordsize integer     The maximum record size to advertize.
7417      -V, --verbose            More verbose output.
7418      --ciphers cipher1 cipher2...
7419                               Ciphers to enable.
7420      --protocols protocol1 protocol2...
7421                               Protocols to enable.
7422      --comp comp1 comp2...    Compression methods to enable.
7423      --macs mac1 mac2...      MACs to enable.
7424      --kx kx1 kx2...          Key exchange methods to enable.
7425      --ctypes certType1 certType2...
7426                               Certificate types to enable.
7427      --priority PRIORITY STRING
7428                               Priorities string.
7429      --x509cafile FILE        Certificate file to use.
7430      --x509crlfile FILE       CRL file to use.
7431      --pgpkeyfile FILE        PGP Key file to use.
7432      --pgpkeyring FILE        PGP Key ring file to use.
7433      --pgpcertfile FILE       PGP Public Key (certificate) file to
7434                               use.
7435      --pgpsubkey HEX|auto     PGP subkey to use.
7436      --x509keyfile FILE       X.509 key file to use.
7437      --x509certfile FILE      X.509 Certificate file to use.
7438      --srpusername NAME       SRP username to use.
7439      --srppasswd PASSWD       SRP password to use.
7440      --pskusername NAME       PSK username to use.
7441      --pskkey KEY             PSK key (in hex) to use.
7442      --opaque-prf-input DATA
7443                               Use Opaque PRF Input DATA.
7444      -p, --port PORT          The port to connect to.
7445      --insecure               Don't abort program if server
7446                               certificate can't be validated.
7447      -l, --list               Print a list of the supported
7448                               algorithms and modes.
7449      -h, --help               prints this help
7450      -v, --version            prints the program's version number
7451 </pre>
7452 <p>To connect to a server using PSK authentication, you may use something
7453 like:
7454 </p>
7455 <div class="smallexample">
7456 <pre class="smallexample">$ gnutls-cli -p 5556 test.gnutls.org --pskusername jas --pskkey 9e32cf7786321a828ef7668f09fb35db --priority NORMAL:+DHE-PSK:+PSK:-RSA:-DHE-RSA -d 4711
7457 </pre></div>
7458
7459 <table class="menu" border="0" cellspacing="0">
7460 <tr><td align="left" valign="top">&bull; <a href="#Example-client-PSK-connection" accesskey="1">Example client PSK connection</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7461 </td></tr>
7462 </table>
7463
7464 <hr>
7465 <a name="Example-client-PSK-connection"></a>
7466 <div class="header">
7467 <p>
7468 Up: <a href="#Invoking-gnutls_002dcli" accesskey="u" rel="up">Invoking gnutls-cli</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>
7469 </div>
7470 <a name="Example-client-PSK-connection-1"></a>
7471 <h4 class="subsection">8.2.1 Example client PSK connection</h4>
7472 <a name="index-PSK-client"></a>
7473
7474 <p>If your server only supports the PSK ciphersuite, connecting to it
7475 should be as simple as connecting to the server:
7476 </p>
7477 <div class="smallexample">
7478 <pre class="smallexample">$ ./gnutls-cli -p 5556 localhost
7479 Resolving 'localhost'...
7480 Connecting to '127.0.0.1:5556'...
7481 - PSK client callback.
7482 Enter PSK identity: psk_identity
7483 Enter password:
7484 - PSK authentication.
7485 - Version: TLS1.1
7486 - Key Exchange: PSK
7487 - Cipher: AES-128-CBC
7488 - MAC: SHA1
7489 - Compression: NULL
7490 - Handshake was completed
7491
7492 - Simple Client Mode:
7493 </pre></div>
7494
7495 <p>If the server supports several cipher suites, you may need to force it
7496 to chose PSK by using a cipher priority parameter such as
7497 <code>--priority NORMAL:+PSK:-RSA:-DHE-RSA:-DHE-PSK</code>.
7498 </p>
7499 <a name="index-Netconf"></a>
7500 <p>Instead of using the Netconf-way to derive the PSK key from a
7501 password, you can also give the PSK username and key directly on the
7502 command line:
7503 </p>
7504 <div class="smallexample">
7505 <pre class="smallexample">$ ./gnutls-cli -p 5556 localhost --pskusername psk_identity --pskkey 88f3824b3e5659f52d00e959bacab954b6540344  --priority NORMAL:+DHE-PSK:+PSK
7506 Resolving 'localhost'...
7507 Connecting to '127.0.0.1:5556'...
7508 - PSK authentication.
7509 - Version: TLS1.1
7510 - Key Exchange: PSK
7511 - Cipher: AES-128-CBC
7512 - MAC: SHA1
7513 - Compression: NULL
7514 - Handshake was completed
7515
7516 - Simple Client Mode:
7517 </pre></div>
7518
7519 <p>By keeping the <code>--pskusername</code> parameter and removing the
7520 <code>--pskkey</code> parameter, it will query only for the password during
7521 the handshake.
7522 </p>
7523 <hr>
7524 <a name="Invoking-gnutls_002dcli_002ddebug"></a>
7525 <div class="header">
7526 <p>
7527 Next: <a href="#Invoking-gnutls_002dserv" accesskey="n" rel="next">Invoking gnutls-serv</a>, Previous: <a href="#Invoking-gnutls_002dcli" accesskey="p" rel="previous">Invoking gnutls-cli</a>, Up: <a href="#Included-programs" accesskey="u" rel="up">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>
7528 </div>
7529 <a name="Invoking-gnutls_002dcli_002ddebug-1"></a>
7530 <h3 class="section">8.3 Invoking gnutls-cli-debug</h3>
7531 <a name="index-gnutls_002dcli_002ddebug"></a>
7532
7533 <p>This program was created to assist in debugging <acronym>GnuTLS</acronym>, but
7534 it might be useful to extract a <acronym>TLS</acronym> server&rsquo;s capabilities.
7535 It&rsquo;s purpose is to connect onto a <acronym>TLS</acronym> server, perform some
7536 tests and print the server&rsquo;s capabilities. If called with the &lsquo;-v&rsquo;
7537 parameter a more checks will be performed. An example output is:
7538 </p>
7539 <div class="smallexample">
7540 <pre class="smallexample">crystal:/cvs/gnutls/src$ ./gnutls-cli-debug localhost -p 5556
7541 Resolving 'localhost'...
7542 Connecting to '127.0.0.1:5556'...
7543 Checking for TLS 1.1 support... yes
7544 Checking fallback from TLS 1.1 to... N/A
7545 Checking for TLS 1.0 support... yes
7546 Checking for SSL 3.0 support... yes
7547 Checking for version rollback bug in RSA PMS... no
7548 Checking for version rollback bug in Client Hello... no
7549 Checking whether we need to disable TLS 1.0... N/A
7550 Checking whether the server ignores the RSA PMS version... no
7551 Checking whether the server can accept Hello Extensions... yes
7552 Checking whether the server can accept cipher suites not in SSL 3.0 spec... yes
7553 Checking whether the server can accept a bogus TLS record version in the client hello... yes
7554 Checking for certificate information... N/A
7555 Checking for trusted CAs... N/A
7556 Checking whether the server understands TLS closure alerts... yes
7557 Checking whether the server supports session resumption... yes
7558 Checking for export-grade ciphersuite support... no
7559 Checking RSA-export ciphersuite info... N/A
7560 Checking for anonymous authentication support... no
7561 Checking anonymous Diffie-Hellman group info... N/A
7562 Checking for ephemeral Diffie-Hellman support... no
7563 Checking ephemeral Diffie-Hellman group info... N/A
7564 Checking for AES cipher support (TLS extension)... yes
7565 Checking for 3DES cipher support... yes
7566 Checking for ARCFOUR 128 cipher support... yes
7567 Checking for ARCFOUR 40 cipher support... no
7568 Checking for MD5 MAC support... yes
7569 Checking for SHA1 MAC support... yes
7570 Checking for ZLIB compression support (TLS extension)... yes
7571 Checking for LZO compression support (GnuTLS extension)... yes
7572 Checking for max record size (TLS extension)... yes
7573 Checking for SRP authentication support (TLS extension)... yes
7574 Checking for OpenPGP authentication support (TLS extension)... no
7575 </pre></div>
7576
7577 <hr>
7578 <a name="Invoking-gnutls_002dserv"></a>
7579 <div class="header">
7580 <p>
7581 Next: <a href="#Invoking-psktool" accesskey="n" rel="next">Invoking psktool</a>, Previous: <a href="#Invoking-gnutls_002dcli_002ddebug" accesskey="p" rel="previous">Invoking gnutls-cli-debug</a>, Up: <a href="#Included-programs" accesskey="u" rel="up">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>
7582 </div>
7583 <a name="Invoking-gnutls_002dserv-1"></a>
7584 <h3 class="section">8.4 Invoking gnutls-serv</h3>
7585 <a name="index-gnutls_002dserv"></a>
7586
7587 <p>Simple server program that listens to incoming TLS connections.
7588 </p>
7589 <pre class="verbatim">GnuTLS test server
7590 Usage: gnutls-serv [options]
7591
7592      -d, --debug integer      Enable debugging
7593      -g, --generate           Generate Diffie-Hellman Parameters.
7594      -p, --port integer       The port to connect to.
7595      -q, --quiet              Suppress some messages.
7596      --nodb                   Does not use the resume database.
7597      --http                   Act as an HTTP Server.
7598      --echo                   Act as an Echo Server.
7599      --dhparams FILE          DH params file to use.
7600      --x509fmtder             Use DER format for certificates
7601      --x509cafile FILE        Certificate file to use.
7602      --x509crlfile FILE       CRL file to use.
7603      --pgpkeyring FILE        PGP Key ring file to use.
7604      --pgpkeyfile FILE        PGP Key file to use.
7605      --pgpcertfile FILE       PGP Public Key (certificate) file to
7606                               use.
7607      --pgpsubkey HEX|auto     PGP subkey to use.
7608      --x509keyfile FILE       X.509 key file to use.
7609      --x509certfile FILE      X.509 Certificate file to use.
7610      --x509dsakeyfile FILE    Alternative X.509 key file to use.
7611      --x509dsacertfile FILE   Alternative X.509 certificate file to
7612                               use.
7613      -r, --require-cert       Require a valid certificate.
7614      -a, --disable-client-cert
7615                               Disable request for a client
7616                               certificate.
7617      --pskpasswd FILE         PSK password file to use.
7618      --pskhint HINT           PSK identity hint to use.
7619      --srppasswd FILE         SRP password file to use.
7620      --srppasswdconf FILE     SRP password conf file to use.
7621      --opaque-prf-input DATA
7622                               Use Opaque PRF Input DATA.
7623      --ciphers cipher1 cipher2...
7624                               Ciphers to enable.
7625      --protocols protocol1 protocol2...
7626                               Protocols to enable.
7627      --comp comp1 comp2...    Compression methods to enable.
7628      --macs mac1 mac2...      MACs to enable.
7629      --kx kx1 kx2...          Key exchange methods to enable.
7630      --ctypes certType1 certType2...
7631                               Certificate types to enable.
7632      --priority PRIORITY STRING
7633                               Priorities string.
7634      -l, --list               Print a list of the supported
7635                               algorithms  and modes.
7636      -h, --help               prints this help
7637      -v, --version            prints the program's version number
7638 </pre>
7639 <a name="Setting-Up-a-Test-HTTPS-Server"></a>
7640 <h4 class="subsection">8.4.1 Setting Up a Test HTTPS Server</h4>
7641 <a name="index-HTTPS-server"></a>
7642 <a name="index-debug-server"></a>
7643
7644 <p>Running your own TLS server based on GnuTLS can be useful when
7645 debugging clients and/or GnuTLS itself.  This section describes how to
7646 use <code>gnutls-serv</code> as a simple HTTPS server.
7647 </p>
7648 <p>The most basic server can be started as:
7649 </p>
7650 <div class="example">
7651 <pre class="example">gnutls-serv --http
7652 </pre></div>
7653
7654 <p>It will only support anonymous ciphersuites, which many TLS clients
7655 refuse to use.
7656 </p>
7657 <p>The next step is to add support for X.509.  First we generate a CA:
7658 </p>
7659 <div class="example">
7660 <pre class="example">certtool --generate-privkey &gt; x509-ca-key.pem
7661 echo 'cn = GnuTLS test CA' &gt; ca.tmpl
7662 echo 'ca' &gt;&gt; ca.tmpl
7663 echo 'cert_signing_key' &gt;&gt; ca.tmpl
7664 certtool --generate-self-signed --load-privkey x509-ca-key.pem \
7665   --template ca.tmpl --outfile x509-ca.pem
7666 ...
7667 </pre></div>
7668
7669 <p>Then generate a server certificate.  Remember to change the dns_name
7670 value to the name of your server host, or skip that command to avoid
7671 the field.
7672 </p>
7673 <div class="example">
7674 <pre class="example">certtool --generate-privkey &gt; x509-server-key.pem
7675 echo 'organization = GnuTLS test server' &gt; server.tmpl
7676 echo 'cn = test.gnutls.org' &gt;&gt; server.tmpl
7677 echo 'tls_www_server' &gt;&gt; server.tmpl
7678 echo 'encryption_key' &gt;&gt; server.tmpl
7679 echo 'signing_key' &gt;&gt; server.tmpl
7680 echo 'dns_name = test.gnutls.org' &gt;&gt; server.tmpl
7681 certtool --generate-certificate --load-privkey x509-server-key.pem \
7682   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
7683   --template server.tmpl --outfile x509-server.pem
7684 ...
7685 </pre></div>
7686
7687 <p>For use in the client, you may want to generate a client certificate
7688 as well.
7689 </p>
7690 <div class="example">
7691 <pre class="example">certtool --generate-privkey &gt; x509-client-key.pem
7692 echo 'cn = GnuTLS test client' &gt; client.tmpl
7693 echo 'tls_www_client' &gt;&gt; client.tmpl
7694 echo 'encryption_key' &gt;&gt; client.tmpl
7695 echo 'signing_key' &gt;&gt; client.tmpl
7696 certtool --generate-certificate --load-privkey x509-client-key.pem \
7697   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
7698   --template client.tmpl --outfile x509-client.pem
7699 ...
7700 </pre></div>
7701
7702 <p>To be able to import the client key/certificate into some
7703 applications, you will need to convert them into a PKCS#12 structure.
7704 This also encrypts the security sensitive key with a password.
7705 </p>
7706 <div class="example">
7707 <pre class="example">certtool --to-p12 --load-ca-certificate x509-ca.pem --load-privkey x509-client-key.pem --load-certificate x509-client.pem --outder --outfile x509-client.p12
7708 </pre></div>
7709
7710 <p>For icing, we&rsquo;ll create a proxy certificate for the client too.
7711 </p>
7712 <div class="example">
7713 <pre class="example">certtool --generate-privkey &gt; x509-proxy-key.pem
7714 echo 'cn = GnuTLS test client proxy' &gt; proxy.tmpl
7715 certtool --generate-proxy --load-privkey x509-proxy-key.pem \
7716   --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \
7717   --load-certificate x509-client.pem --template proxy.tmpl \
7718   --outfile x509-proxy.pem
7719 ...
7720 </pre></div>
7721
7722 <p>Then start the server again:
7723 </p>
7724 <div class="example">
7725 <pre class="example">gnutls-serv --http \
7726             --x509cafile x509-ca.pem \
7727             --x509keyfile x509-server-key.pem \
7728             --x509certfile x509-server.pem
7729 </pre></div>
7730
7731 <p>Try connecting to the server using your web browser.  Note that the
7732 server listens to port 5556 by default.
7733 </p>
7734 <p>While you are at it, to allow connections using DSA, you can also
7735 create a DSA key and certificate for the server.  These credentials
7736 will be used in the final example below.
7737 </p>
7738 <div class="example">
7739 <pre class="example">certtool --generate-privkey --dsa &gt; x509-server-key-dsa.pem
7740 certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \
7741   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
7742   --template server.tmpl --outfile x509-server-dsa.pem
7743 ...
7744 </pre></div>
7745
7746 <p>The next step is to create OpenPGP credentials for the server.
7747 </p>
7748 <div class="example">
7749 <pre class="example">gpg --gen-key
7750 ...enter whatever details you want, use 'test.gnutls.org' as name...
7751 </pre></div>
7752
7753 <p>Make a note of the OpenPGP key identifier of the newly generated key,
7754 here it was <code>5D1D14D8</code>.  You will need to export the key for
7755 GnuTLS to be able to use it.
7756 </p>
7757 <div class="example">
7758 <pre class="example">gpg -a --export 5D1D14D8 &gt; openpgp-server.txt
7759 gpg --export 5D1D14D8 &gt; openpgp-server.bin
7760 gpg --export-secret-keys 5D1D14D8 &gt; openpgp-server-key.bin
7761 gpg -a --export-secret-keys 5D1D14D8 &gt; openpgp-server-key.txt
7762 </pre></div>
7763
7764 <p>Let&rsquo;s start the server with support for OpenPGP credentials:
7765 </p>
7766 <div class="example">
7767 <pre class="example">gnutls-serv --http \
7768             --pgpkeyfile openpgp-server-key.txt \
7769             --pgpcertfile openpgp-server.txt
7770 </pre></div>
7771
7772 <p>The next step is to add support for SRP authentication.
7773 </p>
7774 <div class="example">
7775 <pre class="example">srptool --create-conf srp-tpasswd.conf
7776 srptool --passwd-conf srp-tpasswd.conf --username jas --passwd srp-passwd.txt
7777 Enter password: [TYPE &quot;foo&quot;]
7778 </pre></div>
7779
7780 <p>Start the server with SRP support:
7781 </p>
7782 <div class="example">
7783 <pre class="example">gnutls-serv --http \
7784             --srppasswdconf srp-tpasswd.conf \
7785             --srppasswd srp-passwd.txt
7786 </pre></div>
7787
7788 <p>Let&rsquo;s also add support for PSK.
7789 </p>
7790 <div class="example">
7791 <pre class="example">$ psktool --passwd psk-passwd.txt
7792 </pre></div>
7793
7794 <p>Start the server with PSK support:
7795 </p>
7796 <div class="example">
7797 <pre class="example">gnutls-serv --http \
7798             --pskpasswd psk-passwd.txt
7799 </pre></div>
7800
7801 <p>Finally, we start the server with all the earlier parameters and you
7802 get this command:
7803 </p>
7804 <div class="example">
7805 <pre class="example">gnutls-serv --http \
7806             --x509cafile x509-ca.pem \
7807             --x509keyfile x509-server-key.pem \
7808             --x509certfile x509-server.pem \
7809             --x509dsakeyfile x509-server-key-dsa.pem \
7810             --x509dsacertfile x509-server-dsa.pem \
7811             --pgpkeyfile openpgp-server-key.txt \
7812             --pgpcertfile openpgp-server.txt \
7813             --srppasswdconf srp-tpasswd.conf \
7814             --srppasswd srp-passwd.txt \
7815             --pskpasswd psk-passwd.txt
7816 </pre></div>
7817
7818 <table class="menu" border="0" cellspacing="0">
7819 <tr><td align="left" valign="top">&bull; <a href="#Example-server-PSK-connection" accesskey="1">Example server PSK connection</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
7820 </td></tr>
7821 </table>
7822
7823 <hr>
7824 <a name="Example-server-PSK-connection"></a>
7825 <div class="header">
7826 <p>
7827 Up: <a href="#Invoking-gnutls_002dserv" accesskey="u" rel="up">Invoking gnutls-serv</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>
7828 </div>
7829 <a name="Example-server-PSK-connection-1"></a>
7830 <h4 class="subsection">8.4.2 Example server PSK connection</h4>
7831 <a name="index-PSK-server"></a>
7832
7833 <p>To set up a PSK server with <code>gnutls-serv</code> you need to create PSK
7834 password file (see <a href="#Invoking-psktool">Invoking psktool</a>).  In the example below, I
7835 type <code>password</code> at the prompt.
7836 </p>
7837 <div class="smallexample">
7838 <pre class="smallexample">$ ./psktool -u psk_identity -p psks.txt
7839 Enter password:
7840 Key stored to psks.txt
7841 $ cat psks.txt
7842 psk_identity:88f3824b3e5659f52d00e959bacab954b6540344
7843 $
7844 </pre></div>
7845
7846 <p>After this, start the server pointing to the password file.  We
7847 disable DHE-PSK.
7848 </p>
7849 <div class="smallexample">
7850 <pre class="smallexample">$ ./gnutls-serv --pskpasswd psks.txt  --pskhint psk_identity_hint --priority NORMAL:-DHE-PSK
7851 Set static Diffie-Hellman parameters, consider --dhparams.
7852 Echo Server ready. Listening to port '5556'.
7853 </pre></div>
7854
7855 <p>You can now connect to the server using a PSK client (see <a href="#Example-client-PSK-connection">Example
7856 client PSK connection</a>).
7857 </p>
7858 <hr>
7859 <a name="Invoking-psktool"></a>
7860 <div class="header">
7861 <p>
7862 Next: <a href="#Invoking-srptool" accesskey="n" rel="next">Invoking srptool</a>, Previous: <a href="#Invoking-gnutls_002dserv" accesskey="p" rel="previous">Invoking gnutls-serv</a>, Up: <a href="#Included-programs" accesskey="u" rel="up">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>
7863 </div>
7864 <a name="Invoking-psktool-1"></a>
7865 <h3 class="section">8.5 Invoking psktool</h3>
7866 <a name="index-psktool"></a>
7867
7868 <p>This is a program to manage <acronym>PSK</acronym> username and keys.
7869 </p>
7870 <pre class="verbatim">PSKtool help
7871 Usage : psktool [options]
7872      -u, --username username
7873                               specify username.
7874      -p, --passwd FILE        specify a password file.
7875      -n, --netconf-hint HINT
7876                               derive key from Netconf password, using
7877                               HINT as the psk_identity_hint.
7878      -s, --keysize SIZE       specify the key size in bytes.
7879      -v, --version            prints the program's version number
7880      -h, --help               shows this help text
7881 </pre>
7882 <p>Normally the file will generate random keys for the indicate username.
7883 You may also derive PSK keys from passwords, using the algorithm
7884 specified in &lsquo;<tt>draft-ietf-netconf-tls-02.txt</tt>&rsquo;.  The algorithm
7885 needs a PSK identity hint, which you specify using
7886 <code>--netconf-hint</code>.  To derive a PSK key from a password with an
7887 empty PSK identity hint, using <code>--netconf-hint &quot;&quot;</code>.
7888 </p>
7889 <hr>
7890 <a name="Invoking-srptool"></a>
7891 <div class="header">
7892 <p>
7893 Next: <a href="#Invoking-p11tool" accesskey="n" rel="next">Invoking p11tool</a>, Previous: <a href="#Invoking-psktool" accesskey="p" rel="previous">Invoking psktool</a>, Up: <a href="#Included-programs" accesskey="u" rel="up">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>
7894 </div>
7895 <a name="Invoking-srptool-1"></a>
7896 <h3 class="section">8.6 Invoking srptool</h3>
7897 <a name="srptool"></a><a name="index-srptool"></a>
7898
7899 <p>The &lsquo;<tt>srptool</tt>&rsquo; is a very simple program that emulates the programs
7900 in the <em>Stanford SRP libraries</em>, see
7901 <a href="http://srp.stanford.edu/">http://srp.stanford.edu/</a>.  It is intended for use in places
7902 where you don&rsquo;t expect <acronym>SRP</acronym> authentication to be the used for
7903 system users.
7904 </p>
7905 <p>Traditionally <em>libsrp</em> used two files. One called <code>tpasswd</code>
7906 which holds usernames and verifiers, and <code>tpasswd.conf</code> which
7907 holds generators and primes.
7908 </p>
7909 <p>How to use srptool:
7910 </p>
7911 <ul>
7912 <li> To create tpasswd.conf which holds the g and n values for
7913 <acronym>SRP</acronym> protocol (generator and a large prime), run:
7914
7915 <div class="example">
7916 <pre class="example">$ srptool --create-conf /etc/tpasswd.conf
7917 </pre></div>
7918
7919 </li><li> This command will create /etc/tpasswd and will add user &rsquo;test&rsquo; (you
7920 will also be prompted for a password).  Verifiers are stored by
7921 default in the way libsrp expects.
7922
7923 <div class="example">
7924 <pre class="example">$ srptool --passwd /etc/tpasswd \
7925     --passwd-conf /etc/tpasswd.conf -u test
7926 </pre></div>
7927
7928 </li><li> This command will check against a password.  If the password matches
7929 the one in /etc/tpasswd you will get an ok.
7930
7931 <div class="example">
7932 <pre class="example">$ srptool --passwd /etc/tpasswd \
7933     --passwd-conf /etc/tpasswd.conf --verify -u test
7934 </pre></div>
7935
7936 </li></ul>
7937
7938 <hr>
7939 <a name="Invoking-p11tool"></a>
7940 <div class="header">
7941 <p>
7942 Previous: <a href="#Invoking-srptool" accesskey="p" rel="previous">Invoking srptool</a>, Up: <a href="#Included-programs" accesskey="u" rel="up">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>
7943 </div>
7944 <a name="Invoking-p11tool-1"></a>
7945 <h3 class="section">8.7 Invoking p11tool</h3>
7946 <a name="p11tool"></a><a name="index-p11tool"></a>
7947
7948 <p>The &lsquo;<tt>p11tool</tt>&rsquo; is a program that helps with accessing tokens
7949 and security modules that support the PKCS #11 API. It requires
7950 the individual PKCS #11 modules to be loaded either with the
7951 <code>--provider</code> option, or by setting up the GnuTLS configuration
7952 file for PKCS #11 as in <a href="#sec_003apkcs11">sec:pkcs11</a>.
7953 </p>
7954 <pre class="verbatim">p11tool help
7955 Usage: p11tool [options]
7956
7957      --export URL             Export an object specified by a pkcs11
7958                               URL
7959      --list-tokens            List all available tokens
7960      --list-mechanisms URL    List all available mechanisms in token.
7961      --list-all               List all objects specified by a PKCS#11
7962                               URL
7963      --list-all-certs         List all certificates specified by a
7964                               PKCS#11 URL
7965      --list-certs             List certificates that have a private
7966                               key specified by a PKCS#11 URL
7967      --list-privkeys          List private keys specified by a
7968                               PKCS#11 URL
7969      --list-trusted           List certificates marked as trusted,
7970                               specified by a PKCS#11 URL
7971      --initialize URL         Initializes a PKCS11 token.
7972      --write URL              Writes loaded certificates, private or
7973                               secret keys to a PKCS11 token.
7974      --delete URL             Deletes objects matching the URL.
7975      --label label            Sets a label for the write operation.
7976      --trusted                Marks the certificate to be imported as
7977                               trusted.
7978      --login                  Force login to token
7979      --detailed-url           Export detailed URLs.
7980      --no-detailed-url        Export less detailed URLs.
7981      --secret-key HEX_KEY     Provide a hex encoded secret key.
7982      --load-privkey FILE      Private key file to use.
7983      --load-pubkey FILE       Private key file to use.
7984      --load-certificate FILE
7985                               Certificate file to use.
7986      -8, --pkcs8              Use PKCS #8 format for private keys.
7987      --inder                  Use DER format for input certificates
7988                               and private keys.
7989      --inraw                  Use RAW/DER format for input
7990                               certificates and private keys.
7991      --provider Library       Specify the pkcs11 provider library
7992      --outfile FILE           Output file.
7993      -d, --debug LEVEL        specify the debug level. Default is 1.
7994      -h, --help               shows this help text
7995 </pre>
7996 <p>After being provided the available PKCS #11 modules, it can list all tokens
7997 available in your system, the objects on the tokens, and perform operations
7998 on them.
7999 </p>
8000 <p>Some examples on how to use p11tool:
8001 </p>
8002 <ul>
8003 <li> List all tokens
8004 <div class="example">
8005 <pre class="example">$ p11tool --list-tokens
8006 </pre></div>
8007
8008 </li><li> List all objects
8009 <div class="example">
8010 <pre class="example">$ p11tool --login --list-all
8011 </pre></div>
8012
8013 </li><li> To export an object
8014 <div class="example">
8015 <pre class="example">$ p11tool --login --export pkcs11:(OBJECT URL)
8016 </pre></div>
8017
8018 </li><li> To copy an object to a token
8019 <div class="example">
8020 <pre class="example">$ p11tool --login --write pkcs11:(TOKEN URL) --load-certificate (certificate file) --label &quot;my_cert&quot;
8021 </pre></div>
8022
8023 </li></ul>
8024
8025 <p>Note that typically PKCS #11 private key objects are not allowed
8026 to be extracted from the token.
8027 </p>
8028 <hr>
8029 <a name="Function-reference"></a>
8030 <div class="header">
8031 <p>
8032 Next: <a href="#All-the-supported-ciphersuites-in-GnuTLS" accesskey="n" rel="next">All the supported ciphersuites in GnuTLS</a>, Previous: <a href="#Included-programs" accesskey="p" rel="previous">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>
8033 </div>
8034 <a name="Function-Reference"></a>
8035 <h2 class="chapter">9 Function Reference</h2>
8036 <a name="index-Function-reference"></a>
8037
8038 <table class="menu" border="0" cellspacing="0">
8039 <tr><td align="left" valign="top">&bull; <a href="#Core-functions" accesskey="1">Core functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8040 </td></tr>
8041 <tr><td align="left" valign="top">&bull; <a href="#X_002e509-certificate-functions" accesskey="2">X.509 certificate functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8042 </td></tr>
8043 <tr><td align="left" valign="top">&bull; <a href="#GnuTLS_002dextra-functions" accesskey="3">GnuTLS-extra functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8044 </td></tr>
8045 <tr><td align="left" valign="top">&bull; <a href="#OpenPGP-functions" accesskey="4">OpenPGP functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8046 </td></tr>
8047 <tr><td align="left" valign="top">&bull; <a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions" accesskey="5">TLS Inner Application (TLS/IA) functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8048 </td></tr>
8049 <tr><td align="left" valign="top">&bull; <a href="#Error-codes-and-descriptions" accesskey="6">Error codes and descriptions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
8050 </td></tr>
8051 </table>
8052
8053 <hr>
8054 <a name="Core-functions"></a>
8055 <div class="header">
8056 <p>
8057 Next: <a href="#X_002e509-certificate-functions" accesskey="n" rel="next">X.509 certificate functions</a>, Up: <a href="#Function-reference" accesskey="u" rel="up">Function 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>
8058 </div>
8059 <a name="Core-Functions"></a>
8060 <h3 class="section">9.1 Core Functions</h3>
8061
8062 <p>The prototypes for the following functions lie in
8063 &lsquo;<tt>gnutls/gnutls.h</tt>&rsquo;.
8064 </p>
8065
8066
8067
8068
8069 <a name="gnutls_005falert_005fget_005fname-1"></a>
8070 <h4 class="subheading">gnutls_alert_get_name</h4>
8071 <a name="gnutls_005falert_005fget_005fname"></a><dl>
8072 <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>
8073 <dd><p><var>alert</var>: is an alert number <code>gnutls_session_t</code> structure.
8074 </p>
8075 <p>This function will return a string that describes the given alert
8076 number, or <code>NULL</code>.  See <code>gnutls_alert_get()</code>.
8077 </p>
8078 <p><strong>Returns:</strong> string corresponding to <code>gnutls_alert_description_t</code> value.
8079 </p></dd></dl>
8080
8081 <a name="gnutls_005falert_005fget-1"></a>
8082 <h4 class="subheading">gnutls_alert_get</h4>
8083 <a name="gnutls_005falert_005fget"></a><dl>
8084 <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>
8085 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
8086 </p>
8087 <p>This function will return the last alert number received.  This
8088 function should be called if <code>GNUTLS_E_WARNING_ALERT_RECEIVED</code> or
8089 <code>GNUTLS_E_FATAL_ALERT_RECEIVED</code> has been returned by a gnutls
8090 function.  The peer may send alerts if he thinks some things were
8091 not right. Check gnutls.h for the available alert descriptions.
8092 </p>
8093 <p>If no alert has been received the returned value is undefined.
8094 </p>
8095 <p><strong>Returns:</strong> returns the last alert received, a
8096 <code>gnutls_alert_description_t</code> value.
8097 </p></dd></dl>
8098
8099 <a name="gnutls_005falert_005fsend_005fappropriate-1"></a>
8100 <h4 class="subheading">gnutls_alert_send_appropriate</h4>
8101 <a name="gnutls_005falert_005fsend_005fappropriate"></a><dl>
8102 <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>
8103 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
8104 </p>
8105 <p><var>err</var>: is an integer
8106 </p>
8107 <p>Sends an alert to the peer depending on the error code returned by
8108 a gnutls function. This function will call <code>gnutls_error_to_alert()</code>
8109 to determine the appropriate alert to send.
8110 </p>
8111 <p>This function may also return <code>GNUTLS_E_AGAIN</code>, or
8112 <code>GNUTLS_E_INTERRUPTED</code>.
8113 </p>
8114 <p>If the return value is <code>GNUTLS_E_INVALID_REQUEST</code>, then no alert has
8115 been sent to the peer.
8116 </p>
8117 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
8118 an error code is returned.
8119 </p></dd></dl>
8120
8121 <a name="gnutls_005falert_005fsend-1"></a>
8122 <h4 class="subheading">gnutls_alert_send</h4>
8123 <a name="gnutls_005falert_005fsend"></a><dl>
8124 <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>
8125 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
8126 </p>
8127 <p><var>level</var>: is the level of the alert
8128 </p>
8129 <p><var>desc</var>: is the alert description
8130 </p>
8131 <p>This function will send an alert to the peer in order to inform
8132 him of something important (eg. his Certificate could not be verified).
8133 If the alert level is Fatal then the peer is expected to close the
8134 connection, otherwise he may ignore the alert and continue.
8135 </p>
8136 <p>The error code of the underlying record send function will be
8137 returned, so you may also receive <code>GNUTLS_E_INTERRUPTED</code> or
8138 <code>GNUTLS_E_AGAIN</code> as well.
8139 </p>
8140 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
8141 an error code is returned.
8142 </p></dd></dl>
8143
8144 <a name="gnutls_005fanon_005fallocate_005fclient_005fcredentials-1"></a>
8145 <h4 class="subheading">gnutls_anon_allocate_client_credentials</h4>
8146 <a name="gnutls_005fanon_005fallocate_005fclient_005fcredentials"></a><dl>
8147 <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>
8148 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_anon_client_credentials_t</code> structure.
8149 </p>
8150 <p>This structure is complex enough to manipulate directly thus
8151 this helper function is provided in order to allocate it.
8152 </p>
8153 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
8154 </p></dd></dl>
8155
8156 <a name="gnutls_005fanon_005fallocate_005fserver_005fcredentials-1"></a>
8157 <h4 class="subheading">gnutls_anon_allocate_server_credentials</h4>
8158 <a name="gnutls_005fanon_005fallocate_005fserver_005fcredentials"></a><dl>
8159 <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>
8160 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_anon_server_credentials_t</code> structure.
8161 </p>
8162 <p>This structure is complex enough to manipulate directly thus this
8163 helper function is provided in order to allocate it.
8164 </p>
8165 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
8166 </p></dd></dl>
8167
8168 <a name="gnutls_005fanon_005ffree_005fclient_005fcredentials-1"></a>
8169 <h4 class="subheading">gnutls_anon_free_client_credentials</h4>
8170 <a name="gnutls_005fanon_005ffree_005fclient_005fcredentials"></a><dl>
8171 <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>
8172 <dd><p><var>sc</var>: is a <code>gnutls_anon_client_credentials_t</code> structure.
8173 </p>
8174 <p>This structure is complex enough to manipulate directly thus this
8175 helper function is provided in order to free (deallocate) it.
8176 </p></dd></dl>
8177
8178 <a name="gnutls_005fanon_005ffree_005fserver_005fcredentials-1"></a>
8179 <h4 class="subheading">gnutls_anon_free_server_credentials</h4>
8180 <a name="gnutls_005fanon_005ffree_005fserver_005fcredentials"></a><dl>
8181 <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>
8182 <dd><p><var>sc</var>: is a <code>gnutls_anon_server_credentials_t</code> structure.
8183 </p>
8184 <p>This structure is complex enough to manipulate directly thus this
8185 helper function is provided in order to free (deallocate) it.
8186 </p></dd></dl>
8187
8188 <a name="gnutls_005fanon_005fset_005fparams_005ffunction-1"></a>
8189 <h4 class="subheading">gnutls_anon_set_params_function</h4>
8190 <a name="gnutls_005fanon_005fset_005fparams_005ffunction"></a><dl>
8191 <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>
8192 <dd><p><var>res</var>: is a gnutls_anon_server_credentials_t structure
8193 </p>
8194 <p><var>func</var>: is the function to be called
8195 </p>
8196 <p>This function will set a callback in order for the server to get
8197 the Diffie-Hellman or RSA parameters for anonymous authentication.
8198 The callback should return zero on success.
8199 </p></dd></dl>
8200
8201 <a name="gnutls_005fanon_005fset_005fserver_005fdh_005fparams-1"></a>
8202 <h4 class="subheading">gnutls_anon_set_server_dh_params</h4>
8203 <a name="gnutls_005fanon_005fset_005fserver_005fdh_005fparams"></a><dl>
8204 <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>
8205 <dd><p><var>res</var>: is a gnutls_anon_server_credentials_t structure
8206 </p>
8207 <p><var>dh_params</var>: is a structure that holds Diffie-Hellman parameters.
8208 </p>
8209 <p>This function will set the Diffie-Hellman parameters for an
8210 anonymous server to use.  These parameters will be used in
8211 Anonymous Diffie-Hellman cipher suites.
8212 </p></dd></dl>
8213
8214 <a name="gnutls_005fanon_005fset_005fserver_005fparams_005ffunction-1"></a>
8215 <h4 class="subheading">gnutls_anon_set_server_params_function</h4>
8216 <a name="gnutls_005fanon_005fset_005fserver_005fparams_005ffunction"></a><dl>
8217 <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>
8218 <dd><p><var>res</var>: is a gnutls_certificate_credentials_t structure
8219 </p>
8220 <p><var>func</var>: is the function to be called
8221 </p>
8222 <p>This function will set a callback in order for the server to get
8223 the Diffie-Hellman parameters for anonymous authentication.  The
8224 callback should return zero on success.
8225 </p></dd></dl>
8226
8227 <a name="gnutls_005fauth_005fclient_005fget_005ftype-1"></a>
8228 <h4 class="subheading">gnutls_auth_client_get_type</h4>
8229 <a name="gnutls_005fauth_005fclient_005fget_005ftype"></a><dl>
8230 <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>
8231 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
8232 </p>
8233 <p>Returns the type of credentials that were used for client authentication.
8234 The returned information is to be used to distinguish the function used
8235 to access authentication data.
8236 </p>
8237 <p><strong>Returns:</strong> The type of credentials for the client authentication
8238 schema, a <code>gnutls_credentials_type_t</code> type.
8239 </p></dd></dl>
8240
8241 <a name="gnutls_005fauth_005fget_005ftype-1"></a>
8242 <h4 class="subheading">gnutls_auth_get_type</h4>
8243 <a name="gnutls_005fauth_005fget_005ftype"></a><dl>
8244 <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>
8245 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
8246 </p>
8247 <p>Returns type of credentials for the current authentication schema.
8248 The returned information is to be used to distinguish the function used
8249 to access authentication data.
8250 </p>
8251 <p>Eg. for CERTIFICATE ciphersuites (key exchange algorithms:
8252 <code>GNUTLS_KX_RSA</code>, <code>GNUTLS_KX_DHE_RSA</code>), the same function are to be
8253 used to access the authentication data.
8254 </p>
8255 <p><strong>Returns:</strong> The type of credentials for the current authentication
8256 schema, a <code>gnutls_credentials_type_t</code> type.
8257 </p></dd></dl>
8258
8259 <a name="gnutls_005fauth_005fserver_005fget_005ftype-1"></a>
8260 <h4 class="subheading">gnutls_auth_server_get_type</h4>
8261 <a name="gnutls_005fauth_005fserver_005fget_005ftype"></a><dl>
8262 <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>
8263 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
8264 </p>
8265 <p>Returns the type of credentials that were used for server authentication.
8266 The returned information is to be used to distinguish the function used
8267 to access authentication data.
8268 </p>
8269 <p><strong>Returns:</strong> The type of credentials for the server authentication
8270 schema, a <code>gnutls_credentials_type_t</code> type.
8271 </p></dd></dl>
8272
8273 <a name="gnutls_005fbye-1"></a>
8274 <h4 class="subheading">gnutls_bye</h4>
8275 <a name="gnutls_005fbye"></a><dl>
8276 <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>
8277 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
8278 </p>
8279 <p><var>how</var>: is an integer
8280 </p>
8281 <p>Terminates the current TLS/SSL connection. The connection should
8282 have been initiated using <code>gnutls_handshake()</code>.  <code>how</code> should be one
8283 of <code>GNUTLS_SHUT_RDWR</code>, <code>GNUTLS_SHUT_WR</code>.
8284 </p>
8285 <p>In case of <code>GNUTLS_SHUT_RDWR</code> then the TLS connection gets
8286 terminated and further receives and sends will be disallowed.  If
8287 the return value is zero you may continue using the connection.
8288 <code>GNUTLS_SHUT_RDWR</code> actually sends an alert containing a close
8289 request and waits for the peer to reply with the same message.
8290 </p>
8291 <p>In case of <code>GNUTLS_SHUT_WR</code> then the TLS connection gets terminated
8292 and further sends will be disallowed. In order to reuse the
8293 connection you should wait for an EOF from the peer.
8294 <code>GNUTLS_SHUT_WR</code> sends an alert containing a close request.
8295 </p>
8296 <p>Note that not all implementations will properly terminate a TLS
8297 connection.  Some of them, usually for performance reasons, will
8298 terminate only the underlying transport layer, thus causing a
8299 transmission error to the peer.  This error cannot be
8300 distinguished from a malicious party prematurely terminating the
8301 session, thus this behavior is not recommended.
8302 </p>
8303 <p>This function may also return <code>GNUTLS_E_AGAIN</code> or
8304 <code>GNUTLS_E_INTERRUPTED</code>; cf.  <code>gnutls_record_get_direction()</code>.
8305 </p>
8306 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code, see
8307 function documentation for entire semantics.
8308 </p></dd></dl>
8309
8310 <a name="gnutls_005fcertificate_005factivation_005ftime_005fpeers-1"></a>
8311 <h4 class="subheading">gnutls_certificate_activation_time_peers</h4>
8312 <a name="gnutls_005fcertificate_005factivation_005ftime_005fpeers"></a><dl>
8313 <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>
8314 <dd><p><var>session</var>: is a gnutls session
8315 </p>
8316 <p>This function will return the peer&rsquo;s certificate activation time.
8317 This is the creation time for openpgp keys.
8318 </p>
8319 <p><strong>Returns:</strong> (time_t)-1 on error.
8320 </p>
8321 <p><strong>Deprecated:</strong> <code>gnutls_certificate_verify_peers2()</code> now verifies activation times.
8322 </p></dd></dl>
8323
8324 <a name="gnutls_005fcertificate_005fallocate_005fcredentials-1"></a>
8325 <h4 class="subheading">gnutls_certificate_allocate_credentials</h4>
8326 <a name="gnutls_005fcertificate_005fallocate_005fcredentials"></a><dl>
8327 <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>
8328 <dd><p><var>res</var>: is a pointer to a <code>gnutls_certificate_credentials_t</code> structure.
8329 </p>
8330 <p>This structure is complex enough to manipulate directly thus this
8331 helper function is provided in order to allocate it.
8332 </p>
8333 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
8334 </p></dd></dl>
8335
8336 <a name="gnutls_005fcertificate_005fclient_005fget_005frequest_005fstatus-1"></a>
8337 <h4 class="subheading">gnutls_certificate_client_get_request_status</h4>
8338 <a name="gnutls_005fcertificate_005fclient_005fget_005frequest_005fstatus"></a><dl>
8339 <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>
8340 <dd><p><var>session</var>: is a gnutls session
8341 </p>
8342 <p>Get whether client certificate is requested or not.
8343 </p>
8344 <p><strong>Returns:</strong> 0 if the peer (server) did not request client
8345 authentication or 1 otherwise, or a negative value in case of
8346 error.
8347 </p></dd></dl>
8348
8349 <a name="gnutls_005fcertificate_005fclient_005fset_005fretrieve_005ffunction-1"></a>
8350 <h4 class="subheading">gnutls_certificate_client_set_retrieve_function</h4>
8351 <a name="gnutls_005fcertificate_005fclient_005fset_005fretrieve_005ffunction"></a><dl>
8352 <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>
8353 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8354 </p>
8355 <p><var>func</var>: is the callback function
8356 </p>
8357 <p>This function sets a callback to be called in order to retrieve the
8358 certificate to be used in the handshake.
8359 </p>
8360 <p>The callback&rsquo;s function prototype is:
8361 int (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int nreqs,
8362 const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length, gnutls_retr_st* st);
8363 </p>
8364 <p><code>req_ca_cert</code> is only used in X.509 certificates.
8365 Contains a list with the CA names that the server considers trusted.
8366 Normally we should send a certificate that is signed
8367 by one of these CAs. These names are DER encoded. To get a more
8368 meaningful value use the function <code>gnutls_x509_rdn_get()</code>.
8369 </p>
8370 <p><code>pk_algos</code> contains a list with server&rsquo;s acceptable signature algorithms.
8371 The certificate returned should support the server&rsquo;s given algorithms.
8372 </p>
8373 <p><code>st</code> should contain the certificates and private keys.
8374 </p>
8375 <p>If the callback function is provided then gnutls will call it, in the
8376 handshake, after the certificate request message has been received.
8377 </p>
8378 <p>The callback function should set the certificate list to be sent,
8379 and return 0 on success. If no certificate was selected then the
8380 number of certificates should be set to zero. The value (-1)
8381 indicates error and the handshake will be terminated.
8382 </p></dd></dl>
8383
8384 <a name="gnutls_005fcertificate_005fexpiration_005ftime_005fpeers-1"></a>
8385 <h4 class="subheading">gnutls_certificate_expiration_time_peers</h4>
8386 <a name="gnutls_005fcertificate_005fexpiration_005ftime_005fpeers"></a><dl>
8387 <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>
8388 <dd><p><var>session</var>: is a gnutls session
8389 </p>
8390 <p>This function will return the peer&rsquo;s certificate expiration time.
8391 </p>
8392 <p><strong>Returns:</strong> (time_t)-1 on error.
8393 </p>
8394 <p><strong>Deprecated:</strong> <code>gnutls_certificate_verify_peers2()</code> now verifies expiration times.
8395 </p></dd></dl>
8396
8397 <a name="gnutls_005fcertificate_005ffree_005fca_005fnames-1"></a>
8398 <h4 class="subheading">gnutls_certificate_free_ca_names</h4>
8399 <a name="gnutls_005fcertificate_005ffree_005fca_005fnames"></a><dl>
8400 <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>
8401 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8402 </p>
8403 <p>This function will delete all the CA name in the given
8404 credentials. Clients may call this to save some memory since in
8405 client side the CA names are not used. Servers might want to use
8406 this function if a large list of trusted CAs is present and
8407 sending the names of it would just consume bandwidth without providing
8408 information to client.
8409 </p>
8410 <p>CA names are used by servers to advertize the CAs they support to
8411 clients.
8412 </p></dd></dl>
8413
8414 <a name="gnutls_005fcertificate_005ffree_005fcas-1"></a>
8415 <h4 class="subheading">gnutls_certificate_free_cas</h4>
8416 <a name="gnutls_005fcertificate_005ffree_005fcas"></a><dl>
8417 <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>
8418 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8419 </p>
8420 <p>This function will delete all the CAs associated with the given
8421 credentials. Servers that do not use
8422 <code>gnutls_certificate_verify_peers2()</code> may call this to save some
8423 memory.
8424 </p></dd></dl>
8425
8426 <a name="gnutls_005fcertificate_005ffree_005fcredentials-1"></a>
8427 <h4 class="subheading">gnutls_certificate_free_credentials</h4>
8428 <a name="gnutls_005fcertificate_005ffree_005fcredentials"></a><dl>
8429 <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>
8430 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8431 </p>
8432 <p>This structure is complex enough to manipulate directly thus this
8433 helper function is provided in order to free (deallocate) it.
8434 </p>
8435 <p>This function does not free any temporary parameters associated
8436 with this structure (ie RSA and DH parameters are not freed by this
8437 function).
8438 </p></dd></dl>
8439
8440 <a name="gnutls_005fcertificate_005ffree_005fcrls-1"></a>
8441 <h4 class="subheading">gnutls_certificate_free_crls</h4>
8442 <a name="gnutls_005fcertificate_005ffree_005fcrls"></a><dl>
8443 <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>
8444 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8445 </p>
8446 <p>This function will delete all the CRLs associated
8447 with the given credentials.
8448 </p></dd></dl>
8449
8450 <a name="gnutls_005fcertificate_005ffree_005fkeys-1"></a>
8451 <h4 class="subheading">gnutls_certificate_free_keys</h4>
8452 <a name="gnutls_005fcertificate_005ffree_005fkeys"></a><dl>
8453 <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>
8454 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8455 </p>
8456 <p>This function will delete all the keys and the certificates associated
8457 with the given credentials. This function must not be called when a
8458 TLS negotiation that uses the credentials is in progress.
8459 </p></dd></dl>
8460
8461 <a name="gnutls_005fcertificate_005fget_005fissuer-1"></a>
8462 <h4 class="subheading">gnutls_certificate_get_issuer</h4>
8463 <a name="gnutls_005fcertificate_005fget_005fissuer"></a><dl>
8464 <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>
8465 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8466 </p>
8467 <p><var>cert</var>: is the certificate to find issuer for
8468 </p>
8469 <p><var>issuer</var>: Will hold the issuer if any. Should be treated as constant.
8470 </p>
8471 <p><var>flags</var>: Use zero.
8472 </p>
8473 <p>This function will return the issuer of a given certificate.
8474 </p>
8475 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
8476 negative error value.
8477 </p></dd></dl>
8478
8479 <a name="gnutls_005fcertificate_005fget_005fopenpgp_005fkeyring-1"></a>
8480 <h4 class="subheading">gnutls_certificate_get_openpgp_keyring</h4>
8481 <a name="gnutls_005fcertificate_005fget_005fopenpgp_005fkeyring"></a><dl>
8482 <dt><a name="index-gnutls_005fcertificate_005fget_005fopenpgp_005fkeyring"></a>Function: <em>void</em> <strong>gnutls_certificate_get_openpgp_keyring</strong> <em>(gnutls_certificate_credentials_t <var>sc</var>, gnutls_openpgp_keyring_t * <var>keyring</var>)</em></dt>
8483 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8484 </p>
8485 <p><var>keyring</var>: the exported keyring. Should be treated as constant
8486 </p>
8487 <p>This function will export the OpenPGP keyring associated with the
8488 given credentials.
8489 </p>
8490 <p><strong>Since:</strong> 2.4.0
8491 </p></dd></dl>
8492
8493 <a name="gnutls_005fcertificate_005fget_005fours-1"></a>
8494 <h4 class="subheading">gnutls_certificate_get_ours</h4>
8495 <a name="gnutls_005fcertificate_005fget_005fours"></a><dl>
8496 <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>
8497 <dd><p><var>session</var>: is a gnutls session
8498 </p>
8499 <p>Get the certificate as sent to the peer, in the last handshake.
8500 These certificates are in raw format.  In X.509 this is a
8501 certificate list. In OpenPGP this is a single certificate.
8502 </p>
8503 <p><strong>Returns:</strong> return a pointer to a <code>gnutls_datum_t</code> containing our
8504 certificates, or <code>NULL</code> in case of an error or if no certificate
8505 was used.
8506 </p></dd></dl>
8507
8508 <a name="gnutls_005fcertificate_005fget_005fpeers-1"></a>
8509 <h4 class="subheading">gnutls_certificate_get_peers</h4>
8510 <a name="gnutls_005fcertificate_005fget_005fpeers"></a><dl>
8511 <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>
8512 <dd><p><var>session</var>: is a gnutls session
8513 </p>
8514 <p><var>list_size</var>: is the length of the certificate list
8515 </p>
8516 <p>Get the peer&rsquo;s raw certificate (chain) as sent by the peer.  These
8517 certificates are in raw format (DER encoded for X.509).  In case of
8518 a X.509 then a certificate list may be present.  The first
8519 certificate in the list is the peer&rsquo;s certificate, following the
8520 issuer&rsquo;s certificate, then the issuer&rsquo;s issuer etc.
8521 </p>
8522 <p>In case of OpenPGP keys a single key will be returned in raw
8523 format.
8524 </p>
8525 <p><strong>Returns:</strong> return a pointer to a <code>gnutls_datum_t</code> containing our
8526 certificates, or <code>NULL</code> in case of an error or if no certificate
8527 was used.
8528 </p></dd></dl>
8529
8530 <a name="gnutls_005fcertificate_005fget_005fx509_005fcas-1"></a>
8531 <h4 class="subheading">gnutls_certificate_get_x509_cas</h4>
8532 <a name="gnutls_005fcertificate_005fget_005fx509_005fcas"></a><dl>
8533 <dt><a name="index-gnutls_005fcertificate_005fget_005fx509_005fcas"></a>Function: <em>void</em> <strong>gnutls_certificate_get_x509_cas</strong> <em>(gnutls_certificate_credentials_t <var>sc</var>, gnutls_x509_crt_t ** <var>x509_ca_list</var>, unsigned int * <var>ncas</var>)</em></dt>
8534 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8535 </p>
8536 <p><var>x509_ca_list</var>: will point to the CA list. Should be treated as constant
8537 </p>
8538 <p><var>ncas</var>: the number of CAs
8539 </p>
8540 <p>This function will export all the CAs associated with the given
8541 credentials.
8542 </p>
8543 <p><strong>Since:</strong> 2.4.0
8544 </p></dd></dl>
8545
8546 <a name="gnutls_005fcertificate_005fget_005fx509_005fcrls-1"></a>
8547 <h4 class="subheading">gnutls_certificate_get_x509_crls</h4>
8548 <a name="gnutls_005fcertificate_005fget_005fx509_005fcrls"></a><dl>
8549 <dt><a name="index-gnutls_005fcertificate_005fget_005fx509_005fcrls"></a>Function: <em>void</em> <strong>gnutls_certificate_get_x509_crls</strong> <em>(gnutls_certificate_credentials_t <var>sc</var>, gnutls_x509_crl_t ** <var>x509_crl_list</var>, unsigned int * <var>ncrls</var>)</em></dt>
8550 <dd><p><var>sc</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8551 </p>
8552 <p><var>x509_crl_list</var>: the exported CRL list. Should be treated as constant
8553 </p>
8554 <p><var>ncrls</var>: the number of exported CRLs
8555 </p>
8556 <p>This function will export all the CRLs associated with the given
8557 credentials.
8558 </p>
8559 <p><strong>Since:</strong> 2.4.0
8560 </p></dd></dl>
8561
8562 <a name="gnutls_005fcertificate_005fsend_005fx509_005frdn_005fsequence-1"></a>
8563 <h4 class="subheading">gnutls_certificate_send_x509_rdn_sequence</h4>
8564 <a name="gnutls_005fcertificate_005fsend_005fx509_005frdn_005fsequence"></a><dl>
8565 <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>
8566 <dd><p><var>session</var>: is a pointer to a <code>gnutls_session_t</code> structure.
8567 </p>
8568 <p><var>status</var>: is 0 or 1
8569 </p>
8570 <p>If status is non zero, this function will order gnutls not to send
8571 the rdnSequence in the certificate request message. That is the
8572 server will not advertize it&rsquo;s trusted CAs to the peer. If status
8573 is zero then the default behaviour will take effect, which is to
8574 advertize the server&rsquo;s trusted CAs.
8575 </p>
8576 <p>This function has no effect in clients, and in authentication
8577 methods other than certificate with X.509 certificates.
8578 </p></dd></dl>
8579
8580 <a name="gnutls_005fcertificate_005fserver_005fset_005frequest-1"></a>
8581 <h4 class="subheading">gnutls_certificate_server_set_request</h4>
8582 <a name="gnutls_005fcertificate_005fserver_005fset_005frequest"></a><dl>
8583 <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>
8584 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
8585 </p>
8586 <p><var>req</var>: is one of GNUTLS_CERT_REQUEST, GNUTLS_CERT_REQUIRE
8587 </p>
8588 <p>This function specifies if we (in case of a server) are going to
8589 send a certificate request message to the client. If <code>req</code> is
8590 GNUTLS_CERT_REQUIRE then the server will return an error if the
8591 peer does not provide a certificate. If you do not call this
8592 function then the client will not be asked to send a certificate.
8593 </p></dd></dl>
8594
8595 <a name="gnutls_005fcertificate_005fserver_005fset_005fretrieve_005ffunction-1"></a>
8596 <h4 class="subheading">gnutls_certificate_server_set_retrieve_function</h4>
8597 <a name="gnutls_005fcertificate_005fserver_005fset_005fretrieve_005ffunction"></a><dl>
8598 <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>
8599 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8600 </p>
8601 <p><var>func</var>: is the callback function
8602 </p>
8603 <p>This function sets a callback to be called in order to retrieve the
8604 certificate to be used in the handshake.
8605 </p>
8606 <p>The callback&rsquo;s function prototype is:
8607 int (*callback)(gnutls_session_t, gnutls_retr_st* st);
8608 </p>
8609 <p><code>st</code> should contain the certificates and private keys.
8610 </p>
8611 <p>If the callback function is provided then gnutls will call it, in the
8612 handshake, after the certificate request message has been received.
8613 </p>
8614 <p>The callback function should set the certificate list to be sent, and
8615 return 0 on success.  The value (-1) indicates error and the handshake
8616 will be terminated.
8617 </p></dd></dl>
8618
8619 <a name="gnutls_005fcertificate_005fset_005fdh_005fparams-1"></a>
8620 <h4 class="subheading">gnutls_certificate_set_dh_params</h4>
8621 <a name="gnutls_005fcertificate_005fset_005fdh_005fparams"></a><dl>
8622 <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>
8623 <dd><p><var>res</var>: is a gnutls_certificate_credentials_t structure
8624 </p>
8625 <p><var>dh_params</var>: is a structure that holds Diffie-Hellman parameters.
8626 </p>
8627 <p>This function will set the Diffie-Hellman parameters for a
8628 certificate server to use. These parameters will be used in
8629 Ephemeral Diffie-Hellman cipher suites.  Note that only a pointer
8630 to the parameters are stored in the certificate handle, so if you
8631 deallocate the parameters before the certificate is deallocated,
8632 you must change the parameters stored in the certificate first.
8633 </p></dd></dl>
8634
8635 <a name="gnutls_005fcertificate_005fset_005fparams_005ffunction-1"></a>
8636 <h4 class="subheading">gnutls_certificate_set_params_function</h4>
8637 <a name="gnutls_005fcertificate_005fset_005fparams_005ffunction"></a><dl>
8638 <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>
8639 <dd><p><var>res</var>: is a gnutls_certificate_credentials_t structure
8640 </p>
8641 <p><var>func</var>: is the function to be called
8642 </p>
8643 <p>This function will set a callback in order for the server to get
8644 the Diffie-Hellman or RSA parameters for certificate
8645 authentication.  The callback should return zero on success.
8646 </p></dd></dl>
8647
8648 <a name="gnutls_005fcertificate_005fset_005fretrieve_005ffunction-1"></a>
8649 <h4 class="subheading">gnutls_certificate_set_retrieve_function</h4>
8650 <a name="gnutls_005fcertificate_005fset_005fretrieve_005ffunction"></a><dl>
8651 <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>
8652 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8653 </p>
8654 <p><var>func</var>: is the callback function
8655 </p>
8656 <p>This function sets a callback to be called in order to retrieve the
8657 certificate to be used in the handshake.
8658 </p>
8659 <p>The callback&rsquo;s function prototype is:
8660 int (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int nreqs,
8661 const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length, gnutls_retr2_st* st);
8662 </p>
8663 <p><code>req_ca_cert</code> is only used in X.509 certificates.
8664 Contains a list with the CA names that the server considers trusted.
8665 Normally we should send a certificate that is signed
8666 by one of these CAs. These names are DER encoded. To get a more
8667 meaningful value use the function <code>gnutls_x509_rdn_get()</code>.
8668 </p>
8669 <p><code>pk_algos</code> contains a list with server&rsquo;s acceptable signature algorithms.
8670 The certificate returned should support the server&rsquo;s given algorithms.
8671 </p>
8672 <p><code>st</code> should contain the certificates and private keys.
8673 </p>
8674 <p>If the callback function is provided then gnutls will call it, in the
8675 handshake, after the certificate request message has been received.
8676 </p>
8677 <p>In server side pk_algos and req_ca_dn are NULL.
8678 </p>
8679 <p>The callback function should set the certificate list to be sent,
8680 and return 0 on success. If no certificate was selected then the
8681 number of certificates should be set to zero. The value (-1)
8682 indicates error and the handshake will be terminated.
8683 </p></dd></dl>
8684
8685 <a name="gnutls_005fcertificate_005fset_005frsa_005fexport_005fparams-1"></a>
8686 <h4 class="subheading">gnutls_certificate_set_rsa_export_params</h4>
8687 <a name="gnutls_005fcertificate_005fset_005frsa_005fexport_005fparams"></a><dl>
8688 <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>
8689 <dd><p><var>res</var>: is a gnutls_certificate_credentials_t structure
8690 </p>
8691 <p><var>rsa_params</var>: is a structure that holds temporary RSA parameters.
8692 </p>
8693 <p>This function will set the temporary RSA parameters for a
8694 certificate server to use.  These parameters will be used in
8695 RSA-EXPORT cipher suites.
8696 </p></dd></dl>
8697
8698 <a name="gnutls_005fcertificate_005fset_005fverify_005fflags-1"></a>
8699 <h4 class="subheading">gnutls_certificate_set_verify_flags</h4>
8700 <a name="gnutls_005fcertificate_005fset_005fverify_005fflags"></a><dl>
8701 <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>
8702 <dd><p><var>res</var>: is a gnutls_certificate_credentials_t structure
8703 </p>
8704 <p><var>flags</var>: are the flags
8705 </p>
8706 <p>This function will set the flags to be used at verification of the
8707 certificates.  Flags must be OR of the
8708 <code>gnutls_certificate_verify_flags</code> enumerations.
8709 </p></dd></dl>
8710
8711 <a name="gnutls_005fcertificate_005fset_005fverify_005ffunction-1"></a>
8712 <h4 class="subheading">gnutls_certificate_set_verify_function</h4>
8713 <a name="gnutls_005fcertificate_005fset_005fverify_005ffunction"></a><dl>
8714 <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>
8715 <dd><p><var>cred</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8716 </p>
8717 <p><var>func</var>: is the callback function
8718 </p>
8719 <p>This function sets a callback to be called when peer&rsquo;s certificate
8720 has been received in order to verify it on receipt rather than
8721 doing after the handshake is completed.
8722 </p>
8723 <p>The callback&rsquo;s function prototype is:
8724 int (*callback)(gnutls_session_t);
8725 </p>
8726 <p>If the callback function is provided then gnutls will call it, in the
8727 handshake, just after the certificate message has been received.
8728 To verify or obtain the certificate the <code>gnutls_certificate_verify_peers2()</code>,
8729 <code>gnutls_certificate_type_get()</code>, <code>gnutls_certificate_get_peers()</code> functions
8730 can be used.
8731 </p>
8732 <p>The callback function should return 0 for the handshake to continue
8733 or non-zero to terminate.
8734 </p>
8735 <p><strong>Since:</strong> 2.10.0
8736 </p></dd></dl>
8737
8738 <a name="gnutls_005fcertificate_005fset_005fverify_005flimits-1"></a>
8739 <h4 class="subheading">gnutls_certificate_set_verify_limits</h4>
8740 <a name="gnutls_005fcertificate_005fset_005fverify_005flimits"></a><dl>
8741 <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>
8742 <dd><p><var>res</var>: is a gnutls_certificate_credentials structure
8743 </p>
8744 <p><var>max_bits</var>: is the number of bits of an acceptable certificate (default 8200)
8745 </p>
8746 <p><var>max_depth</var>: is maximum depth of the verification of a certificate chain (default 5)
8747 </p>
8748 <p>This function will set some upper limits for the default
8749 verification function, <code>gnutls_certificate_verify_peers2()</code>, to avoid
8750 denial of service attacks.  You can set them to zero to disable
8751 limits.
8752 </p></dd></dl>
8753
8754 <a name="gnutls_005fcertificate_005fset_005fx509_005fcrl_005ffile-1"></a>
8755 <h4 class="subheading">gnutls_certificate_set_x509_crl_file</h4>
8756 <a name="gnutls_005fcertificate_005fset_005fx509_005fcrl_005ffile"></a><dl>
8757 <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>
8758 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8759 </p>
8760 <p><var>crlfile</var>: is a file containing the list of verified CRLs (DER or PEM list)
8761 </p>
8762 <p><var>type</var>: is PEM or DER
8763 </p>
8764 <p>This function adds the trusted CRLs in order to verify client or server
8765 certificates.  In case of a client this is not required
8766 to be called if the certificates are not verified using
8767 <code>gnutls_certificate_verify_peers2()</code>.
8768 This function may be called multiple times.
8769 </p>
8770 <p><strong>Returns:</strong> number of CRLs processed or a negative value on error.
8771 </p></dd></dl>
8772
8773 <a name="gnutls_005fcertificate_005fset_005fx509_005fcrl_005fmem-1"></a>
8774 <h4 class="subheading">gnutls_certificate_set_x509_crl_mem</h4>
8775 <a name="gnutls_005fcertificate_005fset_005fx509_005fcrl_005fmem"></a><dl>
8776 <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>
8777 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8778 </p>
8779 <p><var>CRL</var>: is a list of trusted CRLs. They should have been verified before.
8780 </p>
8781 <p><var>type</var>: is DER or PEM
8782 </p>
8783 <p>This function adds the trusted CRLs in order to verify client or
8784 server certificates.  In case of a client this is not required to
8785 be called if the certificates are not verified using
8786 <code>gnutls_certificate_verify_peers2()</code>.  This function may be called
8787 multiple times.
8788 </p>
8789 <p><strong>Returns:</strong> number of CRLs processed, or a negative value on error.
8790 </p></dd></dl>
8791
8792 <a name="gnutls_005fcertificate_005fset_005fx509_005fcrl-1"></a>
8793 <h4 class="subheading">gnutls_certificate_set_x509_crl</h4>
8794 <a name="gnutls_005fcertificate_005fset_005fx509_005fcrl"></a><dl>
8795 <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>
8796 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8797 </p>
8798 <p><var>crl_list</var>: is a list of trusted CRLs. They should have been verified before.
8799 </p>
8800 <p><var>crl_list_size</var>: holds the size of the crl_list
8801 </p>
8802 <p>This function adds the trusted CRLs in order to verify client or
8803 server certificates.  In case of a client this is not required to
8804 be called if the certificates are not verified using
8805 <code>gnutls_certificate_verify_peers2()</code>.  This function may be called
8806 multiple times.
8807 </p>
8808 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
8809 </p>
8810 <p><strong>Since:</strong> 2.4.0
8811 </p></dd></dl>
8812
8813 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile-1"></a>
8814 <h4 class="subheading">gnutls_certificate_set_x509_key_file</h4>
8815 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey_005ffile"></a><dl>
8816 <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>
8817 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8818 </p>
8819 <p><var>certfile</var>: is a file that containing the certificate list (path) for
8820 the specified private key, in PKCS7 format, or a list of certificates
8821 </p>
8822 <p><var>keyfile</var>: is a file that contains the private key
8823 </p>
8824 <p><var>type</var>: is PEM or DER
8825 </p>
8826 <p>This function sets a certificate/private key pair in the
8827 gnutls_certificate_credentials_t structure.  This function may be
8828 called more than once (in case multiple keys/certificates exist for
8829 the server).  For clients that wants to send more than its own end
8830 entity certificate (e.g., also an intermediate CA cert) then put
8831 the certificate chain in <code>certfile</code>.
8832 </p>
8833 <p>Currently only PKCS-1 encoded RSA and DSA private keys are accepted by
8834 this function.
8835 </p>
8836 <p>This function can also accept PKCS <code>11</code> URLs. In that case it
8837 will import the private key and certificate indicated by the urls.
8838 </p>
8839 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
8840 </p></dd></dl>
8841
8842 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey_005fmem-1"></a>
8843 <h4 class="subheading">gnutls_certificate_set_x509_key_mem</h4>
8844 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey_005fmem"></a><dl>
8845 <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>
8846 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8847 </p>
8848 <p><var>cert</var>: contains a certificate list (path) for the specified private key
8849 </p>
8850 <p><var>key</var>: is the private key, or <code>NULL</code>
8851 </p>
8852 <p><var>type</var>: is PEM or DER
8853 </p>
8854 <p>This function sets a certificate/private key pair in the
8855 gnutls_certificate_credentials_t structure. This function may be called
8856 more than once (in case multiple keys/certificates exist for the
8857 server).
8858 </p>
8859 <p><strong>Currently are supported:</strong> RSA PKCS-1 encoded private keys,
8860 DSA private keys.
8861 </p>
8862 <p>DSA private keys are encoded the OpenSSL way, which is an ASN.1
8863 DER sequence of 6 INTEGERs - version, p, q, g, pub, priv.
8864 </p>
8865 <p>Note that the keyUsage (2.5.29.15) PKIX extension in X.509 certificates
8866 is supported. This means that certificates intended for signing cannot
8867 be used for ciphersuites that require encryption.
8868 </p>
8869 <p>If the certificate and the private key are given in PEM encoding
8870 then the strings that hold their values must be null terminated.
8871 </p>
8872 <p>The <code>key</code> may be <code>NULL</code> if you are using a sign callback, see
8873 <code>gnutls_sign_callback_set()</code>.
8874 </p>
8875 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
8876 </p></dd></dl>
8877
8878 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey-1"></a>
8879 <h4 class="subheading">gnutls_certificate_set_x509_key</h4>
8880 <a name="gnutls_005fcertificate_005fset_005fx509_005fkey"></a><dl>
8881 <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>
8882 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8883 </p>
8884 <p><var>cert_list</var>: contains a certificate list (path) for the specified private key
8885 </p>
8886 <p><var>cert_list_size</var>: holds the size of the certificate list
8887 </p>
8888 <p><var>key</var>: is a gnutls_x509_privkey_t key
8889 </p>
8890 <p>This function sets a certificate/private key pair in the
8891 gnutls_certificate_credentials_t structure.  This function may be
8892 called more than once (in case multiple keys/certificates exist for
8893 the server).  For clients that wants to send more than its own end
8894 entity certificate (e.g., also an intermediate CA cert) then put
8895 the certificate chain in <code>cert_list</code>.
8896 </p>
8897 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
8898 </p>
8899 <p><strong>Since:</strong> 2.4.0
8900 </p></dd></dl>
8901
8902 <a name="gnutls_005fcertificate_005fset_005fx509_005fsimple_005fpkcs12_005ffile-1"></a>
8903 <h4 class="subheading">gnutls_certificate_set_x509_simple_pkcs12_file</h4>
8904 <a name="gnutls_005fcertificate_005fset_005fx509_005fsimple_005fpkcs12_005ffile"></a><dl>
8905 <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>
8906 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8907 </p>
8908 <p><var>pkcs12file</var>: filename of file containing PKCS<code>12</code> blob.
8909 </p>
8910 <p><var>type</var>: is PEM or DER of the <code>pkcs12file</code>.
8911 </p>
8912 <p><var>password</var>: optional password used to decrypt PKCS<code>12</code> file, bags and keys.
8913 </p>
8914 <p>This function sets a certificate/private key pair and/or a CRL in
8915 the gnutls_certificate_credentials_t structure.  This function may
8916 be called more than once (in case multiple keys/certificates exist
8917 for the server).
8918 </p>
8919 <p><strong>MAC:</strong> ed PKCS<code>12</code> files are supported.  Encrypted PKCS<code>12</code> bags are
8920 supported.  Encrypted PKCS<code>8</code> private keys are supported.  However,
8921 only password based security, and the same password for all
8922 operations, are supported.
8923 </p>
8924 <p>The private keys may be RSA PKCS<code>1</code> or DSA private keys encoded in
8925 the OpenSSL way.
8926 </p>
8927 <p>PKCS<code>12</code> file may contain many keys and/or certificates, and there
8928 is no way to identify which key/certificate pair you want.  You
8929 should make sure the PKCS<code>12</code> file only contain one key/certificate
8930 pair and/or one CRL.
8931 </p>
8932 <p>It is believed that the limitations of this function is acceptable
8933 for most usage, and that any more flexibility would introduce
8934 complexity that would make it harder to use this functionality at
8935 all.
8936 </p>
8937 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
8938 </p></dd></dl>
8939
8940 <a name="gnutls_005fcertificate_005fset_005fx509_005fsimple_005fpkcs12_005fmem-1"></a>
8941 <h4 class="subheading">gnutls_certificate_set_x509_simple_pkcs12_mem</h4>
8942 <a name="gnutls_005fcertificate_005fset_005fx509_005fsimple_005fpkcs12_005fmem"></a><dl>
8943 <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>
8944 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8945 </p>
8946 <p><var>p12blob</var>: the PKCS<code>12</code> blob.
8947 </p>
8948 <p><var>type</var>: is PEM or DER of the <code>pkcs12file</code>.
8949 </p>
8950 <p><var>password</var>: optional password used to decrypt PKCS<code>12</code> file, bags and keys.
8951 </p>
8952 <p>This function sets a certificate/private key pair and/or a CRL in
8953 the gnutls_certificate_credentials_t structure.  This function may
8954 be called more than once (in case multiple keys/certificates exist
8955 for the server).
8956 </p>
8957 <p><strong>MAC:</strong> ed PKCS<code>12</code> files are supported.  Encrypted PKCS<code>12</code> bags are
8958 supported.  Encrypted PKCS<code>8</code> private keys are supported.  However,
8959 only password based security, and the same password for all
8960 operations, are supported.
8961 </p>
8962 <p>The private keys may be RSA PKCS<code>1</code> or DSA private keys encoded in
8963 the OpenSSL way.
8964 </p>
8965 <p>PKCS<code>12</code> file may contain many keys and/or certificates, and there
8966 is no way to identify which key/certificate pair you want.  You
8967 should make sure the PKCS<code>12</code> file only contain one key/certificate
8968 pair and/or one CRL.
8969 </p>
8970 <p>It is believed that the limitations of this function is acceptable
8971 for most usage, and that any more flexibility would introduce
8972 complexity that would make it harder to use this functionality at
8973 all.
8974 </p>
8975 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
8976 </p>
8977 <p><strong>Since:</strong> 2.8.0
8978 </p></dd></dl>
8979
8980 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust_005ffile-1"></a>
8981 <h4 class="subheading">gnutls_certificate_set_x509_trust_file</h4>
8982 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust_005ffile"></a><dl>
8983 <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>res</var>, const char * <var>cafile</var>, gnutls_x509_crt_fmt_t <var>type</var>)</em></dt>
8984 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
8985 </p>
8986 <p><var>cafile</var>: is a file containing the list of trusted CAs (DER or PEM list)
8987 </p>
8988 <p><var>type</var>: is PEM or DER
8989 </p>
8990 <p>This function adds the trusted CAs in order to verify client or
8991 server certificates. In case of a client this is not required to
8992 be called if the certificates are not verified using
8993 <code>gnutls_certificate_verify_peers2()</code>.  This function may be called
8994 multiple times.
8995 </p>
8996 <p>In case of a server the names of the CAs set here will be sent to
8997 the client if a certificate request is sent. This can be disabled
8998 using <code>gnutls_certificate_send_x509_rdn_sequence()</code>.
8999 </p>
9000 <p>This function can also accept PKCS <code>11</code> URLs. In that case it
9001 will import all certificates that are marked as trusted.
9002 </p>
9003 <p><strong>Returns:</strong> number of certificates processed, or a negative value on
9004 error.
9005 </p></dd></dl>
9006
9007 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust_005fmem-1"></a>
9008 <h4 class="subheading">gnutls_certificate_set_x509_trust_mem</h4>
9009 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust_005fmem"></a><dl>
9010 <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>
9011 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
9012 </p>
9013 <p><var>ca</var>: is a list of trusted CAs or a DER certificate
9014 </p>
9015 <p><var>type</var>: is DER or PEM
9016 </p>
9017 <p>This function adds the trusted CAs in order to verify client or
9018 server certificates. In case of a client this is not required to be
9019 called if the certificates are not verified using
9020 <code>gnutls_certificate_verify_peers2()</code>.  This function may be called
9021 multiple times.
9022 </p>
9023 <p>In case of a server the CAs set here will be sent to the client if
9024 a certificate request is sent. This can be disabled using
9025 <code>gnutls_certificate_send_x509_rdn_sequence()</code>.
9026 </p>
9027 <p><strong>Returns:</strong> the number of certificates processed or a negative value
9028 on error.
9029 </p></dd></dl>
9030
9031 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust-1"></a>
9032 <h4 class="subheading">gnutls_certificate_set_x509_trust</h4>
9033 <a name="gnutls_005fcertificate_005fset_005fx509_005ftrust"></a><dl>
9034 <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>
9035 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
9036 </p>
9037 <p><var>ca_list</var>: is a list of trusted CAs
9038 </p>
9039 <p><var>ca_list_size</var>: holds the size of the CA list
9040 </p>
9041 <p>This function adds the trusted CAs in order to verify client
9042 or server certificates. In case of a client this is not required
9043 to be called if the certificates are not verified using
9044 <code>gnutls_certificate_verify_peers2()</code>.
9045 This function may be called multiple times.
9046 </p>
9047 <p>In case of a server the CAs set here will be sent to the client if
9048 a certificate request is sent. This can be disabled using
9049 <code>gnutls_certificate_send_x509_rdn_sequence()</code>.
9050 </p>
9051 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
9052 </p>
9053 <p><strong>Since:</strong> 2.4.0
9054 </p></dd></dl>
9055
9056 <a name="gnutls_005fcertificate_005ftype_005fget_005fid-1"></a>
9057 <h4 class="subheading">gnutls_certificate_type_get_id</h4>
9058 <a name="gnutls_005fcertificate_005ftype_005fget_005fid"></a><dl>
9059 <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>
9060 <dd><p><var>name</var>: is a certificate type name
9061 </p>
9062 <p>The names are compared in a case insensitive way.
9063 </p>
9064 <p><strong>Returns:</strong> a <code>gnutls_certificate_type_t</code> for the specified in a
9065 string certificate type, or <code>GNUTLS_CRT_UNKNOWN</code> on error.
9066 </p></dd></dl>
9067
9068 <a name="gnutls_005fcertificate_005ftype_005fget_005fname-1"></a>
9069 <h4 class="subheading">gnutls_certificate_type_get_name</h4>
9070 <a name="gnutls_005fcertificate_005ftype_005fget_005fname"></a><dl>
9071 <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>
9072 <dd><p><var>type</var>: is a certificate type
9073 </p>
9074 <p>Convert a <code>gnutls_certificate_type_t</code> type to a string.
9075 </p>
9076 <p><strong>Returns:</strong> a string that contains the name of the specified
9077 certificate type, or <code>NULL</code> in case of unknown types.
9078 </p></dd></dl>
9079
9080 <a name="gnutls_005fcertificate_005ftype_005fget-1"></a>
9081 <h4 class="subheading">gnutls_certificate_type_get</h4>
9082 <a name="gnutls_005fcertificate_005ftype_005fget"></a><dl>
9083 <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>
9084 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9085 </p>
9086 <p>The certificate type is by default X.509, unless it is negotiated
9087 as a TLS extension.
9088 </p>
9089 <p><strong>Returns:</strong> the currently used <code>gnutls_certificate_type_t</code> certificate
9090 type.
9091 </p></dd></dl>
9092
9093 <a name="gnutls_005fcertificate_005ftype_005flist-1"></a>
9094 <h4 class="subheading">gnutls_certificate_type_list</h4>
9095 <a name="gnutls_005fcertificate_005ftype_005flist"></a><dl>
9096 <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>
9097 <dd>
9098 <p>Get a list of certificate types.  Note that to be able to use
9099 OpenPGP certificates, you must link to libgnutls-extra and call
9100 <code>gnutls_global_init_extra()</code>.
9101 </p>
9102 <p><strong>Returns:</strong> a zero-terminated list of <code>gnutls_certificate_type_t</code>
9103 integers indicating the available certificate types.
9104 </p></dd></dl>
9105
9106 <a name="gnutls_005fcertificate_005ftype_005fset_005fpriority-1"></a>
9107 <h4 class="subheading">gnutls_certificate_type_set_priority</h4>
9108 <a name="gnutls_005fcertificate_005ftype_005fset_005fpriority"></a><dl>
9109 <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>
9110 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9111 </p>
9112 <p><var>list</var>: is a 0 terminated list of gnutls_certificate_type_t elements.
9113 </p>
9114 <p>Sets the priority on the certificate types supported by gnutls.
9115 Priority is higher for elements specified before others.
9116 After specifying the types you want, you must append a 0.
9117 Note that the certificate type priority is set on the client.
9118 The server does not use the cert type priority except for disabling
9119 types that were not specified.
9120 </p>
9121 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
9122 </p></dd></dl>
9123
9124 <a name="gnutls_005fcertificate_005fverify_005fpeers2-1"></a>
9125 <h4 class="subheading">gnutls_certificate_verify_peers2</h4>
9126 <a name="gnutls_005fcertificate_005fverify_005fpeers2"></a><dl>
9127 <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>
9128 <dd><p><var>session</var>: is a gnutls session
9129 </p>
9130 <p><var>status</var>: is the output of the verification
9131 </p>
9132 <p>This function will try to verify the peer&rsquo;s certificate and return
9133 its status (trusted, invalid etc.).  The value of <code>status</code> should
9134 be one or more of the gnutls_certificate_status_t enumerated
9135 elements bitwise or&rsquo;d. To avoid denial of service attacks some
9136 default upper limits regarding the certificate key size and chain
9137 size are set. To override them use
9138 <code>gnutls_certificate_set_verify_limits()</code>.
9139 </p>
9140 <p>Note that you must also check the peer&rsquo;s name in order to check if
9141 the verified certificate belongs to the actual peer.
9142 </p>
9143 <p>This function uses <code>gnutls_x509_crt_list_verify()</code> with the CAs in
9144 the credentials as trusted CAs.
9145 </p>
9146 <p><strong>Returns:</strong> a negative error code on error and zero on success.
9147 </p></dd></dl>
9148
9149 <a name="gnutls_005fcertificate_005fverify_005fpeers-1"></a>
9150 <h4 class="subheading">gnutls_certificate_verify_peers</h4>
9151 <a name="gnutls_005fcertificate_005fverify_005fpeers"></a><dl>
9152 <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>)</em></dt>
9153 <dd><p><var>session</var>: is a gnutls session
9154 </p>
9155 <p>This function will try to verify the peer&rsquo;s certificate and return
9156 its status (trusted, invalid etc.).  However you must also check
9157 the peer&rsquo;s name in order to check if the verified certificate
9158 belongs to the actual peer.
9159 </p>
9160 <p>This function uses <code>gnutls_x509_crt_list_verify()</code>.
9161 </p>
9162 <p><strong>Returns:</strong> one or more of the <code>gnutls_certificate_status_t</code>
9163 enumerated elements bitwise or&rsquo;d, or a negative value on error.
9164 </p>
9165 <p><strong>Deprecated:</strong> Use <code>gnutls_certificate_verify_peers2()</code> instead.
9166 </p></dd></dl>
9167
9168 <a name="gnutls_005fcheck_005fversion-1"></a>
9169 <h4 class="subheading">gnutls_check_version</h4>
9170 <a name="gnutls_005fcheck_005fversion"></a><dl>
9171 <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>
9172 <dd><p><var>req_version</var>: version string to compare with, or <code>NULL</code>.
9173 </p>
9174 <p>Check GnuTLS Library version.
9175 </p>
9176 <p>See <code>GNUTLS_VERSION</code> for a suitable <code>req_version</code> string.
9177 </p>
9178 <p><strong>Return value:</strong> Check that the version of the library is at
9179 minimum the one given as a string in <code>req_version</code> and return the
9180 actual version string of the library; return <code>NULL</code> if the
9181 condition is not met.  If <code>NULL</code> is passed to this function no
9182 check is done and only the version string is returned.
9183 </p></dd></dl>
9184
9185 <a name="gnutls_005fcipher_005fdecrypt2-1"></a>
9186 <h4 class="subheading">gnutls_cipher_decrypt2</h4>
9187 <a name="gnutls_005fcipher_005fdecrypt2"></a><dl>
9188 <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>
9189 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code> structure.
9190 </p>
9191 <p><var>ciphertext</var>: the data to encrypt
9192 </p>
9193 <p><var>ciphertextlen</var>: The length of data to encrypt
9194 </p>
9195 <p><var>text</var>: the decrypted data
9196 </p>
9197 <p><var>textlen</var>: The available length for decrypted data
9198 </p>
9199 <p>This function will decrypt the given data using the algorithm
9200 specified by the context.
9201 </p>
9202 <p><strong>Returns:</strong> Zero or a negative value on error.
9203 </p>
9204 <p><strong>Since:</strong> 2.10.0
9205 </p></dd></dl>
9206
9207 <a name="gnutls_005fcipher_005fdecrypt-1"></a>
9208 <h4 class="subheading">gnutls_cipher_decrypt</h4>
9209 <a name="gnutls_005fcipher_005fdecrypt"></a><dl>
9210 <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>
9211 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code> structure.
9212 </p>
9213 <p><var>ciphertext</var>: the data to encrypt
9214 </p>
9215 <p><var>ciphertextlen</var>: The length of data to encrypt
9216 </p>
9217 <p>This function will decrypt the given data using the algorithm
9218 specified by the context.
9219 </p>
9220 <p><strong>Returns:</strong> Zero or a negative value on error.
9221 </p>
9222 <p><strong>Since:</strong> 2.10.0
9223 </p></dd></dl>
9224
9225 <a name="gnutls_005fcipher_005fdeinit-1"></a>
9226 <h4 class="subheading">gnutls_cipher_deinit</h4>
9227 <a name="gnutls_005fcipher_005fdeinit"></a><dl>
9228 <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>
9229 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code> structure.
9230 </p>
9231 <p>This function will deinitialize all resources occupied by the given
9232 encryption context.
9233 </p>
9234 <p><strong>Since:</strong> 2.10.0
9235 </p></dd></dl>
9236
9237 <a name="gnutls_005fcipher_005fencrypt2-1"></a>
9238 <h4 class="subheading">gnutls_cipher_encrypt2</h4>
9239 <a name="gnutls_005fcipher_005fencrypt2"></a><dl>
9240 <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>, void * <var>text</var>, size_t <var>textlen</var>, void * <var>ciphertext</var>, size_t <var>ciphertextlen</var>)</em></dt>
9241 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code> structure.
9242 </p>
9243 <p><var>text</var>: the data to encrypt
9244 </p>
9245 <p><var>textlen</var>: The length of data to encrypt
9246 </p>
9247 <p><var>ciphertext</var>: the encrypted data
9248 </p>
9249 <p><var>ciphertextlen</var>: The available length for encrypted data
9250 </p>
9251 <p>This function will encrypt the given data using the algorithm
9252 specified by the context.
9253 </p>
9254 <p><strong>Returns:</strong> Zero or a negative value on error.
9255 </p>
9256 <p><strong>Since:</strong> 2.10.0
9257 </p></dd></dl>
9258
9259 <a name="gnutls_005fcipher_005fencrypt-1"></a>
9260 <h4 class="subheading">gnutls_cipher_encrypt</h4>
9261 <a name="gnutls_005fcipher_005fencrypt"></a><dl>
9262 <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>
9263 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code> structure.
9264 </p>
9265 <p><var>text</var>: the data to encrypt
9266 </p>
9267 <p><var>textlen</var>: The length of data to encrypt
9268 </p>
9269 <p>This function will encrypt the given data using the algorithm
9270 specified by the context.
9271 </p>
9272 <p><strong>Returns:</strong> Zero or a negative value on error.
9273 </p>
9274 <p><strong>Since:</strong> 2.10.0
9275 </p></dd></dl>
9276
9277 <a name="gnutls_005fcipher_005fget_005fblock_005fsize-1"></a>
9278 <h4 class="subheading">gnutls_cipher_get_block_size</h4>
9279 <a name="gnutls_005fcipher_005fget_005fblock_005fsize"></a><dl>
9280 <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>
9281 <dd><p><var>algorithm</var>: is an encryption algorithm
9282 </p>
9283 <p>Get block size for encryption algorithm.
9284 </p>
9285 <p><strong>Returns:</strong> block size for encryption algorithm.
9286 </p>
9287 <p><strong>Since:</strong> 2.10.0
9288 </p></dd></dl>
9289
9290 <a name="gnutls_005fcipher_005fget_005fid-1"></a>
9291 <h4 class="subheading">gnutls_cipher_get_id</h4>
9292 <a name="gnutls_005fcipher_005fget_005fid"></a><dl>
9293 <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>
9294 <dd><p><var>name</var>: is a MAC algorithm name
9295 </p>
9296 <p>The names are compared in a case insensitive way.
9297 </p>
9298 <p><strong>Returns:</strong> return a <code>gnutls_cipher_algorithm_t</code> value corresponding to
9299 the specified cipher, or <code>GNUTLS_CIPHER_UNKNOWN</code> on error.
9300 </p></dd></dl>
9301
9302 <a name="gnutls_005fcipher_005fget_005fkey_005fsize-1"></a>
9303 <h4 class="subheading">gnutls_cipher_get_key_size</h4>
9304 <a name="gnutls_005fcipher_005fget_005fkey_005fsize"></a><dl>
9305 <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>
9306 <dd><p><var>algorithm</var>: is an encryption algorithm
9307 </p>
9308 <p>Get key size for cipher.
9309 </p>
9310 <p><strong>Returns:</strong> length (in bytes) of the given cipher&rsquo;s key size, or 0 if
9311 the given cipher is invalid.
9312 </p></dd></dl>
9313
9314 <a name="gnutls_005fcipher_005fget_005fname-1"></a>
9315 <h4 class="subheading">gnutls_cipher_get_name</h4>
9316 <a name="gnutls_005fcipher_005fget_005fname"></a><dl>
9317 <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>
9318 <dd><p><var>algorithm</var>: is an encryption algorithm
9319 </p>
9320 <p>Convert a <code>gnutls_cipher_algorithm_t</code> type to a string.
9321 </p>
9322 <p><strong>Returns:</strong> a pointer to a string that contains the name of the
9323 specified cipher, or <code>NULL</code>.
9324 </p></dd></dl>
9325
9326 <a name="gnutls_005fcipher_005fget-1"></a>
9327 <h4 class="subheading">gnutls_cipher_get</h4>
9328 <a name="gnutls_005fcipher_005fget"></a><dl>
9329 <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>
9330 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9331 </p>
9332 <p>Get currently used cipher.
9333 </p>
9334 <p><strong>Returns:</strong> the currently used cipher, a <code>gnutls_cipher_algorithm_t</code>
9335 type.
9336 </p></dd></dl>
9337
9338 <a name="gnutls_005fcipher_005finit-1"></a>
9339 <h4 class="subheading">gnutls_cipher_init</h4>
9340 <a name="gnutls_005fcipher_005finit"></a><dl>
9341 <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>
9342 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code> structure.
9343 </p>
9344 <p><var>cipher</var>: the encryption algorithm to use
9345 </p>
9346 <p><var>key</var>: The key to be used for encryption
9347 </p>
9348 <p><var>iv</var>: The IV to use (if not applicable set NULL)
9349 </p>
9350 <p>This function will initialize an context that can be used for
9351 encryption/decryption of data. This will effectively use the
9352 current crypto backend in use by gnutls or the cryptographic
9353 accelerator in use.
9354 </p>
9355 <p><strong>Returns:</strong> Zero or a negative value on error.
9356 </p>
9357 <p><strong>Since:</strong> 2.10.0
9358 </p></dd></dl>
9359
9360 <a name="gnutls_005fcipher_005flist-1"></a>
9361 <h4 class="subheading">gnutls_cipher_list</h4>
9362 <a name="gnutls_005fcipher_005flist"></a><dl>
9363 <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>
9364 <dd>
9365 <p>Get a list of supported cipher algorithms.  Note that not
9366 necessarily all ciphers are supported as TLS cipher suites.  For
9367 example, DES is not supported as a cipher suite, but is supported
9368 for other purposes (e.g., PKCS<code>8</code> or similar).
9369 </p>
9370 <p><strong>Returns:</strong> a zero-terminated list of <code>gnutls_cipher_algorithm_t</code>
9371 integers indicating the available ciphers.
9372 </p></dd></dl>
9373
9374 <a name="gnutls_005fcipher_005fset_005fpriority-1"></a>
9375 <h4 class="subheading">gnutls_cipher_set_priority</h4>
9376 <a name="gnutls_005fcipher_005fset_005fpriority"></a><dl>
9377 <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>
9378 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9379 </p>
9380 <p><var>list</var>: is a 0 terminated list of gnutls_cipher_algorithm_t elements.
9381 </p>
9382 <p>Sets the priority on the ciphers supported by gnutls.  Priority is
9383 higher for elements specified before others.  After specifying the
9384 ciphers you want, you must append a 0.  Note that the priority is
9385 set on the client. The server does not use the algorithm&rsquo;s
9386 priority except for disabling algorithms that were not specified.
9387 </p>
9388 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
9389 </p></dd></dl>
9390
9391 <a name="gnutls_005fcipher_005fsuite_005fget_005fname-1"></a>
9392 <h4 class="subheading">gnutls_cipher_suite_get_name</h4>
9393 <a name="gnutls_005fcipher_005fsuite_005fget_005fname"></a><dl>
9394 <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>
9395 <dd><p><var>kx_algorithm</var>: is a Key exchange algorithm
9396 </p>
9397 <p><var>cipher_algorithm</var>: is a cipher algorithm
9398 </p>
9399 <p><var>mac_algorithm</var>: is a MAC algorithm
9400 </p>
9401 <p>Note that the full cipher suite name must be prepended by TLS or
9402 SSL depending of the protocol in use.
9403 </p>
9404 <p><strong>Returns:</strong> a string that contains the name of a TLS cipher suite,
9405 specified by the given algorithms, or <code>NULL</code>.
9406 </p></dd></dl>
9407
9408 <a name="gnutls_005fcipher_005fsuite_005finfo-1"></a>
9409 <h4 class="subheading">gnutls_cipher_suite_info</h4>
9410 <a name="gnutls_005fcipher_005fsuite_005finfo"></a><dl>
9411 <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>, 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>
9412 <dd><p><var>idx</var>: index of cipher suite to get information about, starts on 0.
9413 </p>
9414 <p><var>cs_id</var>: output buffer with room for 2 bytes, indicating cipher suite value
9415 </p>
9416 <p><var>kx</var>: output variable indicating key exchange algorithm, or <code>NULL</code>.
9417 </p>
9418 <p><var>cipher</var>: output variable indicating cipher, or <code>NULL</code>.
9419 </p>
9420 <p><var>mac</var>: output variable indicating MAC algorithm, or <code>NULL</code>.
9421 </p>
9422 <p>Get information about supported cipher suites.  Use the function
9423 iteratively to get information about all supported cipher suites.
9424 Call with idx=0 to get information about first cipher suite, then
9425 idx=1 and so on until the function returns NULL.
9426 </p>
9427 <p><strong>Returns:</strong> the name of <code>idx</code> cipher suite, and set the information
9428 about the cipher suite in the output variables.  If <code>idx</code> is out of
9429 bounds, <code>NULL</code> is returned.
9430 </p></dd></dl>
9431
9432 <a name="gnutls_005fcompression_005fget_005fid-1"></a>
9433 <h4 class="subheading">gnutls_compression_get_id</h4>
9434 <a name="gnutls_005fcompression_005fget_005fid"></a><dl>
9435 <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>
9436 <dd><p><var>name</var>: is a compression method name
9437 </p>
9438 <p>The names are compared in a case insensitive way.
9439 </p>
9440 <p><strong>Returns:</strong> an id of the specified in a string compression method, or
9441 <code>GNUTLS_COMP_UNKNOWN</code> on error.
9442 </p></dd></dl>
9443
9444 <a name="gnutls_005fcompression_005fget_005fname-1"></a>
9445 <h4 class="subheading">gnutls_compression_get_name</h4>
9446 <a name="gnutls_005fcompression_005fget_005fname"></a><dl>
9447 <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>
9448 <dd><p><var>algorithm</var>: is a Compression algorithm
9449 </p>
9450 <p>Convert a <code>gnutls_compression_method_t</code> value to a string.
9451 </p>
9452 <p><strong>Returns:</strong> a pointer to a string that contains the name of the
9453 specified compression algorithm, or <code>NULL</code>.
9454 </p></dd></dl>
9455
9456 <a name="gnutls_005fcompression_005fget-1"></a>
9457 <h4 class="subheading">gnutls_compression_get</h4>
9458 <a name="gnutls_005fcompression_005fget"></a><dl>
9459 <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>
9460 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9461 </p>
9462 <p>Get currently used compression algorithm.
9463 </p>
9464 <p><strong>Returns:</strong> the currently used compression method, a
9465 <code>gnutls_compression_method_t</code> value.
9466 </p></dd></dl>
9467
9468 <a name="gnutls_005fcompression_005flist-1"></a>
9469 <h4 class="subheading">gnutls_compression_list</h4>
9470 <a name="gnutls_005fcompression_005flist"></a><dl>
9471 <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>
9472 <dd>
9473 <p>Get a list of compression methods.  Note that to be able to use LZO
9474 compression, you must link to libgnutls-extra and call
9475 <code>gnutls_global_init_extra()</code>.
9476 </p>
9477 <p><strong>Returns:</strong> a zero-terminated list of <code>gnutls_compression_method_t</code>
9478 integers indicating the available compression methods.
9479 </p></dd></dl>
9480
9481 <a name="gnutls_005fcompression_005fset_005fpriority-1"></a>
9482 <h4 class="subheading">gnutls_compression_set_priority</h4>
9483 <a name="gnutls_005fcompression_005fset_005fpriority"></a><dl>
9484 <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>
9485 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9486 </p>
9487 <p><var>list</var>: is a 0 terminated list of gnutls_compression_method_t elements.
9488 </p>
9489 <p>Sets the priority on the compression algorithms supported by
9490 gnutls.  Priority is higher for elements specified before others.
9491 After specifying the algorithms you want, you must append a 0.
9492 Note that the priority is set on the client. The server does not
9493 use the algorithm&rsquo;s priority except for disabling algorithms that
9494 were not specified.
9495 </p>
9496 <p>TLS 1.0 does not define any compression algorithms except
9497 NULL. Other compression algorithms are to be considered as gnutls
9498 extensions.
9499 </p>
9500 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
9501 </p></dd></dl>
9502
9503 <a name="gnutls_005fcredentials_005fclear-1"></a>
9504 <h4 class="subheading">gnutls_credentials_clear</h4>
9505 <a name="gnutls_005fcredentials_005fclear"></a><dl>
9506 <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>
9507 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9508 </p>
9509 <p>Clears all the credentials previously set in this session.
9510 </p></dd></dl>
9511
9512 <a name="gnutls_005fcredentials_005fset-1"></a>
9513 <h4 class="subheading">gnutls_credentials_set</h4>
9514 <a name="gnutls_005fcredentials_005fset"></a><dl>
9515 <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>
9516 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9517 </p>
9518 <p><var>type</var>: is the type of the credentials
9519 </p>
9520 <p><var>cred</var>: is a pointer to a structure.
9521 </p>
9522 <p>Sets the needed credentials for the specified type.  Eg username,
9523 password - or public and private keys etc.  The <code>cred</code> parameter is
9524 a structure that depends on the specified type and on the current
9525 session (client or server).
9526 </p>
9527 <p>In order to minimize memory usage, and share credentials between
9528 several threads gnutls keeps a pointer to cred, and not the whole
9529 cred structure.  Thus you will have to keep the structure allocated
9530 until you call <code>gnutls_deinit()</code>.
9531 </p>
9532 <p>For <code>GNUTLS_CRD_ANON</code>, <code>cred</code> should be
9533 <code>gnutls_anon_client_credentials_t</code> in case of a client.  In case of
9534 a server it should be <code>gnutls_anon_server_credentials_t</code>.
9535 </p>
9536 <p>For <code>GNUTLS_CRD_SRP</code>, <code>cred</code> should be <code>gnutls_srp_client_credentials_t</code>
9537 in case of a client, and <code>gnutls_srp_server_credentials_t</code>, in case
9538 of a server.
9539 </p>
9540 <p>For <code>GNUTLS_CRD_CERTIFICATE</code>, <code>cred</code> should be
9541 <code>gnutls_certificate_credentials_t</code>.
9542 </p>
9543 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
9544 otherwise an error code is returned.
9545 </p></dd></dl>
9546
9547 <a name="gnutls_005fcrypto_005fbigint_005fregister2-1"></a>
9548 <h4 class="subheading">gnutls_crypto_bigint_register2</h4>
9549 <a name="gnutls_005fcrypto_005fbigint_005fregister2"></a><dl>
9550 <dt><a name="index-gnutls_005fcrypto_005fbigint_005fregister2"></a>Function: <em>int</em> <strong>gnutls_crypto_bigint_register2</strong> <em>(int <var>priority</var>, int <var>version</var>, const gnutls_crypto_bigint_st * <var>s</var>)</em></dt>
9551 <dd><p><var>priority</var>: is the priority of the interface
9552 </p>
9553 <p><var>version</var>: should be set to <code>GNUTLS_CRYPTO_API_VERSION</code>
9554 </p>
9555 <p><var>s</var>: is a structure holding new interface&rsquo;s data
9556 </p>
9557 <p>This function will register an interface for gnutls to operate
9558 on big integers. Any interface registered will override
9559 the included interface. The interface with the lowest
9560 priority will be used by gnutls.
9561 </p>
9562 <p>Note that the bigint interface must interoperate with the public
9563 key interface. Thus if this interface is updated the
9564 <code>gnutls_crypto_pk_register()</code> should also be used.
9565 </p>
9566 <p>This function should be called before <code>gnutls_global_init()</code>.
9567 </p>
9568 <p>For simplicity you can use the convenience <code>gnutls_crypto_bigint_register()</code>
9569 macro.
9570 </p>
9571 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
9572 </p>
9573 <p><strong>Since:</strong> 2.6.0
9574 </p></dd></dl>
9575
9576 <a name="gnutls_005fcrypto_005fcipher_005fregister2-1"></a>
9577 <h4 class="subheading">gnutls_crypto_cipher_register2</h4>
9578 <a name="gnutls_005fcrypto_005fcipher_005fregister2"></a><dl>
9579 <dt><a name="index-gnutls_005fcrypto_005fcipher_005fregister2"></a>Function: <em>int</em> <strong>gnutls_crypto_cipher_register2</strong> <em>(int <var>priority</var>, int <var>version</var>, const gnutls_crypto_cipher_st * <var>s</var>)</em></dt>
9580 <dd><p><var>priority</var>: is the priority of the cipher interface
9581 </p>
9582 <p><var>version</var>: should be set to <code>GNUTLS_CRYPTO_API_VERSION</code>
9583 </p>
9584 <p><var>s</var>: is a structure holding new interface&rsquo;s data
9585 </p>
9586 <p>This function will register a cipher interface to be used by
9587 gnutls. Any interface registered will override the included engine
9588 and by convention kernel implemented interfaces should have
9589 priority of 90. The interface with the lowest priority will be used
9590 by gnutls.
9591 </p>
9592 <p>This function should be called before <code>gnutls_global_init()</code>.
9593 </p>
9594 <p>For simplicity you can use the convenience
9595 <code>gnutls_crypto_cipher_register()</code> macro.
9596 </p>
9597 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
9598 </p>
9599 <p><strong>Since:</strong> 2.6.0
9600 </p></dd></dl>
9601
9602 <a name="gnutls_005fcrypto_005fdigest_005fregister2-1"></a>
9603 <h4 class="subheading">gnutls_crypto_digest_register2</h4>
9604 <a name="gnutls_005fcrypto_005fdigest_005fregister2"></a><dl>
9605 <dt><a name="index-gnutls_005fcrypto_005fdigest_005fregister2"></a>Function: <em>int</em> <strong>gnutls_crypto_digest_register2</strong> <em>(int <var>priority</var>, int <var>version</var>, const gnutls_crypto_digest_st * <var>s</var>)</em></dt>
9606 <dd><p><var>priority</var>: is the priority of the digest interface
9607 </p>
9608 <p><var>version</var>: should be set to <code>GNUTLS_CRYPTO_API_VERSION</code>
9609 </p>
9610 <p><var>s</var>: is a structure holding new interface&rsquo;s data
9611 </p>
9612 <p>This function will register a digest interface to be used by
9613 gnutls. Any interface registered will override the included engine
9614 and by convention kernel implemented interfaces should have
9615 priority of 90. The interface with the lowest priority will be used
9616 by gnutls.
9617 </p>
9618 <p>This function should be called before <code>gnutls_global_init()</code>.
9619 </p>
9620 <p>For simplicity you can use the convenience
9621 <code>gnutls_crypto_digest_register()</code> macro.
9622 </p>
9623 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
9624 </p>
9625 <p><strong>Since:</strong> 2.6.0
9626 </p></dd></dl>
9627
9628 <a name="gnutls_005fcrypto_005fmac_005fregister2-1"></a>
9629 <h4 class="subheading">gnutls_crypto_mac_register2</h4>
9630 <a name="gnutls_005fcrypto_005fmac_005fregister2"></a><dl>
9631 <dt><a name="index-gnutls_005fcrypto_005fmac_005fregister2"></a>Function: <em>int</em> <strong>gnutls_crypto_mac_register2</strong> <em>(int <var>priority</var>, int <var>version</var>, const gnutls_crypto_mac_st * <var>s</var>)</em></dt>
9632 <dd><p><var>priority</var>: is the priority of the mac interface
9633 </p>
9634 <p><var>version</var>: should be set to <code>GNUTLS_CRYPTO_API_VERSION</code>
9635 </p>
9636 <p><var>s</var>: is a structure holding new interface&rsquo;s data
9637 </p>
9638 <p>This function will register a mac interface to be used by
9639 gnutls. Any interface registered will override the included engine
9640 and by convention kernel implemented interfaces should have
9641 priority of 90. The interface with the lowest priority will be used
9642 by gnutls.
9643 </p>
9644 <p>This function should be called before <code>gnutls_global_init()</code>.
9645 </p>
9646 <p>For simplicity you can use the convenience
9647 <code>gnutls_crypto_digest_register()</code> macro.
9648 </p>
9649 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
9650 </p>
9651 <p><strong>Since:</strong> 2.6.0
9652 </p></dd></dl>
9653
9654 <a name="gnutls_005fcrypto_005fpk_005fregister2-1"></a>
9655 <h4 class="subheading">gnutls_crypto_pk_register2</h4>
9656 <a name="gnutls_005fcrypto_005fpk_005fregister2"></a><dl>
9657 <dt><a name="index-gnutls_005fcrypto_005fpk_005fregister2"></a>Function: <em>int</em> <strong>gnutls_crypto_pk_register2</strong> <em>(int <var>priority</var>, int <var>version</var>, const gnutls_crypto_pk_st * <var>s</var>)</em></dt>
9658 <dd><p><var>priority</var>: is the priority of the interface
9659 </p>
9660 <p><var>version</var>: should be set to <code>GNUTLS_CRYPTO_API_VERSION</code>
9661 </p>
9662 <p><var>s</var>: is a structure holding new interface&rsquo;s data
9663 </p>
9664 <p>This function will register an interface for gnutls to operate
9665 on public key operations. Any interface registered will override
9666 the included interface. The interface with the lowest
9667 priority will be used by gnutls.
9668 </p>
9669 <p>Note that the bigint interface must interoperate with the bigint
9670 interface. Thus if this interface is updated the
9671 <code>gnutls_crypto_bigint_register()</code> should also be used.
9672 </p>
9673 <p>This function should be called before <code>gnutls_global_init()</code>.
9674 </p>
9675 <p>For simplicity you can use the convenience <code>gnutls_crypto_pk_register()</code>
9676 macro.
9677 </p>
9678 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
9679 </p>
9680 <p><strong>Since:</strong> 2.6.0
9681 </p></dd></dl>
9682
9683 <a name="gnutls_005fcrypto_005frnd_005fregister2-1"></a>
9684 <h4 class="subheading">gnutls_crypto_rnd_register2</h4>
9685 <a name="gnutls_005fcrypto_005frnd_005fregister2"></a><dl>
9686 <dt><a name="index-gnutls_005fcrypto_005frnd_005fregister2"></a>Function: <em>int</em> <strong>gnutls_crypto_rnd_register2</strong> <em>(int <var>priority</var>, int <var>version</var>, const gnutls_crypto_rnd_st * <var>s</var>)</em></dt>
9687 <dd><p><var>priority</var>: is the priority of the generator
9688 </p>
9689 <p><var>version</var>: should be set to <code>GNUTLS_CRYPTO_API_VERSION</code>
9690 </p>
9691 <p><var>s</var>: is a structure holding new generator&rsquo;s data
9692 </p>
9693 <p>This function will register a random generator to be used by
9694 gnutls.  Any generator registered will override the included
9695 generator and by convention kernel implemented generators have
9696 priority of 90.  The generator with the lowest priority will be
9697 used by gnutls.
9698 </p>
9699 <p>This function should be called before <code>gnutls_global_init()</code>.
9700 </p>
9701 <p>For simplicity you can use the convenience
9702 <code>gnutls_crypto_rnd_register()</code> macro.
9703 </p>
9704 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
9705 </p>
9706 <p><strong>Since:</strong> 2.6.0
9707 </p></dd></dl>
9708
9709 <a name="gnutls_005fcrypto_005fsingle_005fcipher_005fregister2-1"></a>
9710 <h4 class="subheading">gnutls_crypto_single_cipher_register2</h4>
9711 <a name="gnutls_005fcrypto_005fsingle_005fcipher_005fregister2"></a><dl>
9712 <dt><a name="index-gnutls_005fcrypto_005fsingle_005fcipher_005fregister2"></a>Function: <em>int</em> <strong>gnutls_crypto_single_cipher_register2</strong> <em>(gnutls_cipher_algorithm_t <var>algorithm</var>, int <var>priority</var>, int <var>version</var>, const gnutls_crypto_cipher_st * <var>s</var>)</em></dt>
9713 <dd><p><var>algorithm</var>: is the gnutls algorithm identifier
9714 </p>
9715 <p><var>priority</var>: is the priority of the algorithm
9716 </p>
9717 <p><var>version</var>: should be set to <code>GNUTLS_CRYPTO_API_VERSION</code>
9718 </p>
9719 <p><var>s</var>: is a structure holding new cipher&rsquo;s data
9720 </p>
9721 <p>This function will register a cipher algorithm to be used by
9722 gnutls.  Any algorithm registered will override the included
9723 algorithms and by convention kernel implemented algorithms have
9724 priority of 90.  The algorithm with the lowest priority will be
9725 used by gnutls.
9726 </p>
9727 <p>This function should be called before <code>gnutls_global_init()</code>.
9728 </p>
9729 <p>For simplicity you can use the convenience
9730 <code>gnutls_crypto_single_cipher_register()</code> macro.
9731 </p>
9732 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
9733 </p>
9734 <p><strong>Since:</strong> 2.6.0
9735 </p></dd></dl>
9736
9737 <a name="gnutls_005fcrypto_005fsingle_005fdigest_005fregister2-1"></a>
9738 <h4 class="subheading">gnutls_crypto_single_digest_register2</h4>
9739 <a name="gnutls_005fcrypto_005fsingle_005fdigest_005fregister2"></a><dl>
9740 <dt><a name="index-gnutls_005fcrypto_005fsingle_005fdigest_005fregister2"></a>Function: <em>int</em> <strong>gnutls_crypto_single_digest_register2</strong> <em>(gnutls_digest_algorithm_t <var>algorithm</var>, int <var>priority</var>, int <var>version</var>, const gnutls_crypto_digest_st * <var>s</var>)</em></dt>
9741 <dd><p><var>algorithm</var>: is the gnutls algorithm identifier
9742 </p>
9743 <p><var>priority</var>: is the priority of the algorithm
9744 </p>
9745 <p><var>version</var>: should be set to <code>GNUTLS_CRYPTO_API_VERSION</code>
9746 </p>
9747 <p><var>s</var>: is a structure holding new algorithms&rsquo;s data
9748 </p>
9749 <p>This function will register a digest (hash) algorithm to be used by
9750 gnutls.  Any algorithm registered will override the included
9751 algorithms and by convention kernel implemented algorithms have
9752 priority of 90.  The algorithm with the lowest priority will be
9753 used by gnutls.
9754 </p>
9755 <p>This function should be called before <code>gnutls_global_init()</code>.
9756 </p>
9757 <p>For simplicity you can use the convenience
9758 <code>gnutls_crypto_single_digest_register()</code> macro.
9759 </p>
9760 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
9761 </p>
9762 <p><strong>Since:</strong> 2.6.0
9763 </p></dd></dl>
9764
9765 <a name="gnutls_005fcrypto_005fsingle_005fmac_005fregister2-1"></a>
9766 <h4 class="subheading">gnutls_crypto_single_mac_register2</h4>
9767 <a name="gnutls_005fcrypto_005fsingle_005fmac_005fregister2"></a><dl>
9768 <dt><a name="index-gnutls_005fcrypto_005fsingle_005fmac_005fregister2"></a>Function: <em>int</em> <strong>gnutls_crypto_single_mac_register2</strong> <em>(gnutls_mac_algorithm_t <var>algorithm</var>, int <var>priority</var>, int <var>version</var>, const gnutls_crypto_mac_st * <var>s</var>)</em></dt>
9769 <dd><p><var>algorithm</var>: is the gnutls algorithm identifier
9770 </p>
9771 <p><var>priority</var>: is the priority of the algorithm
9772 </p>
9773 <p><var>version</var>: should be set to <code>GNUTLS_CRYPTO_API_VERSION</code>
9774 </p>
9775 <p><var>s</var>: is a structure holding new algorithms&rsquo;s data
9776 </p>
9777 <p>This function will register a MAC algorithm to be used by gnutls.
9778 Any algorithm registered will override the included algorithms and
9779 by convention kernel implemented algorithms have priority of 90.
9780 The algorithm with the lowest priority will be used by gnutls.
9781 </p>
9782 <p>This function should be called before <code>gnutls_global_init()</code>.
9783 </p>
9784 <p>For simplicity you can use the convenience
9785 <code>gnutls_crypto_single_mac_register()</code> macro.
9786 </p>
9787 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
9788 </p>
9789 <p><strong>Since:</strong> 2.6.0
9790 </p></dd></dl>
9791
9792 <a name="gnutls_005fdb_005fcheck_005fentry-1"></a>
9793 <h4 class="subheading">gnutls_db_check_entry</h4>
9794 <a name="gnutls_005fdb_005fcheck_005fentry"></a><dl>
9795 <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>
9796 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9797 </p>
9798 <p><var>session_entry</var>: is the session data (not key)
9799 </p>
9800 <p>Check if database entry has expired.  This function is to be used
9801 when you want to clear unnesessary session which occupy space in
9802 your backend.
9803 </p>
9804 <p><strong>Returns:</strong> Returns <code>GNUTLS_E_EXPIRED</code>, if the database entry has
9805 expired or 0 otherwise.
9806 </p></dd></dl>
9807
9808 <a name="gnutls_005fdb_005fget_005fptr-1"></a>
9809 <h4 class="subheading">gnutls_db_get_ptr</h4>
9810 <a name="gnutls_005fdb_005fget_005fptr"></a><dl>
9811 <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>
9812 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9813 </p>
9814 <p>Get db function pointer.
9815 </p>
9816 <p><strong>Returns:</strong> the pointer that will be sent to db store, retrieve and
9817 delete functions, as the first argument.
9818 </p></dd></dl>
9819
9820 <a name="gnutls_005fdb_005fremove_005fsession-1"></a>
9821 <h4 class="subheading">gnutls_db_remove_session</h4>
9822 <a name="gnutls_005fdb_005fremove_005fsession"></a><dl>
9823 <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>
9824 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9825 </p>
9826 <p>This function will remove the current session data from the
9827 session database.  This will prevent future handshakes reusing
9828 these session data.  This function should be called if a session
9829 was terminated abnormally, and before <code>gnutls_deinit()</code> is called.
9830 </p>
9831 <p>Normally <code>gnutls_deinit()</code> will remove abnormally terminated
9832 sessions.
9833 </p></dd></dl>
9834
9835 <a name="gnutls_005fdb_005fset_005fcache_005fexpiration-1"></a>
9836 <h4 class="subheading">gnutls_db_set_cache_expiration</h4>
9837 <a name="gnutls_005fdb_005fset_005fcache_005fexpiration"></a><dl>
9838 <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>
9839 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9840 </p>
9841 <p><var>seconds</var>: is the number of seconds.
9842 </p>
9843 <p>Set the expiration time for resumed sessions. The default is 3600
9844 (one hour) at the time writing this.
9845 </p></dd></dl>
9846
9847 <a name="gnutls_005fdb_005fset_005fptr-1"></a>
9848 <h4 class="subheading">gnutls_db_set_ptr</h4>
9849 <a name="gnutls_005fdb_005fset_005fptr"></a><dl>
9850 <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>
9851 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9852 </p>
9853 <p><var>ptr</var>: is the pointer
9854 </p>
9855 <p>Sets the pointer that will be provided to db store, retrieve and
9856 delete functions, as the first argument.
9857 </p></dd></dl>
9858
9859 <a name="gnutls_005fdb_005fset_005fremove_005ffunction-1"></a>
9860 <h4 class="subheading">gnutls_db_set_remove_function</h4>
9861 <a name="gnutls_005fdb_005fset_005fremove_005ffunction"></a><dl>
9862 <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>
9863 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9864 </p>
9865 <p><var>rem_func</var>: is the function.
9866 </p>
9867 <p>Sets the function that will be used to remove data from the
9868 resumed sessions database. This function must return 0 on success.
9869 </p>
9870 <p>The first argument to <code>rem_func</code> will be null unless
9871 <code>gnutls_db_set_ptr()</code> has been called.
9872 </p></dd></dl>
9873
9874 <a name="gnutls_005fdb_005fset_005fretrieve_005ffunction-1"></a>
9875 <h4 class="subheading">gnutls_db_set_retrieve_function</h4>
9876 <a name="gnutls_005fdb_005fset_005fretrieve_005ffunction"></a><dl>
9877 <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>
9878 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9879 </p>
9880 <p><var>retr_func</var>: is the function.
9881 </p>
9882 <p>Sets the function that will be used to retrieve data from the
9883 resumed sessions database.  This function must return a
9884 gnutls_datum_t containing the data on success, or a gnutls_datum_t
9885 containing null and 0 on failure.
9886 </p>
9887 <p>The datum&rsquo;s data must be allocated using the function
9888 <code>gnutls_malloc()</code>.
9889 </p>
9890 <p>The first argument to <code>retr_func</code> will be null unless
9891 <code>gnutls_db_set_ptr()</code> has been called.
9892 </p></dd></dl>
9893
9894 <a name="gnutls_005fdb_005fset_005fstore_005ffunction-1"></a>
9895 <h4 class="subheading">gnutls_db_set_store_function</h4>
9896 <a name="gnutls_005fdb_005fset_005fstore_005ffunction"></a><dl>
9897 <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>
9898 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9899 </p>
9900 <p><var>store_func</var>: is the function
9901 </p>
9902 <p>Sets the function that will be used to store data from the resumed
9903 sessions database. This function must remove 0 on success.
9904 </p>
9905 <p>The first argument to <code>store_func()</code> will be null unless
9906 <code>gnutls_db_set_ptr()</code> has been called.
9907 </p></dd></dl>
9908
9909 <a name="gnutls_005fdeinit-1"></a>
9910 <h4 class="subheading">gnutls_deinit</h4>
9911 <a name="gnutls_005fdeinit"></a><dl>
9912 <dt><a name="index-gnutls_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_deinit</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
9913 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
9914 </p>
9915 <p>This function clears all buffers associated with the <code>session</code>.
9916 This function will also remove session data from the session
9917 database if the session was terminated abnormally.
9918 </p></dd></dl>
9919
9920 <a name="gnutls_005fdh_005fget_005fgroup-1"></a>
9921 <h4 class="subheading">gnutls_dh_get_group</h4>
9922 <a name="gnutls_005fdh_005fget_005fgroup"></a><dl>
9923 <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>
9924 <dd><p><var>session</var>: is a gnutls session
9925 </p>
9926 <p><var>raw_gen</var>: will hold the generator.
9927 </p>
9928 <p><var>raw_prime</var>: will hold the prime.
9929 </p>
9930 <p>This function will return the group parameters used in the last
9931 Diffie-Hellman key exchange with the peer.  These are the prime and
9932 the generator used.  This function should be used for both
9933 anonymous and ephemeral Diffie-Hellman.  The output parameters must
9934 be freed with <code>gnutls_free()</code>.
9935 </p>
9936 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
9937 an error code is returned.
9938 </p></dd></dl>
9939
9940 <a name="gnutls_005fdh_005fget_005fpeers_005fpublic_005fbits-1"></a>
9941 <h4 class="subheading">gnutls_dh_get_peers_public_bits</h4>
9942 <a name="gnutls_005fdh_005fget_005fpeers_005fpublic_005fbits"></a><dl>
9943 <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>
9944 <dd><p><var>session</var>: is a gnutls session
9945 </p>
9946 <p>Get the Diffie-Hellman public key bit size.  Can be used for both
9947 anonymous and ephemeral Diffie-Hellman.
9948 </p>
9949 <p><strong>Returns:</strong> the public key bit size used in the last Diffie-Hellman
9950 key exchange with the peer, or a negative value in case of error.
9951 </p></dd></dl>
9952
9953 <a name="gnutls_005fdh_005fget_005fprime_005fbits-1"></a>
9954 <h4 class="subheading">gnutls_dh_get_prime_bits</h4>
9955 <a name="gnutls_005fdh_005fget_005fprime_005fbits"></a><dl>
9956 <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>
9957 <dd><p><var>session</var>: is a gnutls session
9958 </p>
9959 <p>This function will return the bits of the prime used in the last
9960 Diffie-Hellman key exchange with the peer.  Should be used for both
9961 anonymous and ephemeral Diffie-Hellman.  Note that some ciphers,
9962 like RSA and DSA without DHE, does not use a Diffie-Hellman key
9963 exchange, and then this function will return 0.
9964 </p>
9965 <p><strong>Returns:</strong> The Diffie-Hellman bit strength is returned, or 0 if no
9966 Diffie-Hellman key exchange was done, or a negative error code on
9967 failure.
9968 </p></dd></dl>
9969
9970 <a name="gnutls_005fdh_005fget_005fpubkey-1"></a>
9971 <h4 class="subheading">gnutls_dh_get_pubkey</h4>
9972 <a name="gnutls_005fdh_005fget_005fpubkey"></a><dl>
9973 <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>
9974 <dd><p><var>session</var>: is a gnutls session
9975 </p>
9976 <p><var>raw_key</var>: will hold the public key.
9977 </p>
9978 <p>This function will return the peer&rsquo;s public key used in the last
9979 Diffie-Hellman key exchange.  This function should be used for both
9980 anonymous and ephemeral Diffie-Hellman.  The output parameters must
9981 be freed with <code>gnutls_free()</code>.
9982 </p>
9983 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
9984 an error code is returned.
9985 </p></dd></dl>
9986
9987 <a name="gnutls_005fdh_005fget_005fsecret_005fbits-1"></a>
9988 <h4 class="subheading">gnutls_dh_get_secret_bits</h4>
9989 <a name="gnutls_005fdh_005fget_005fsecret_005fbits"></a><dl>
9990 <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>
9991 <dd><p><var>session</var>: is a gnutls session
9992 </p>
9993 <p>This function will return the bits used in the last Diffie-Hellman
9994 key exchange with the peer.  Should be used for both anonymous and
9995 ephemeral Diffie-Hellman.
9996 </p>
9997 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
9998 an error code is returned.
9999 </p></dd></dl>
10000
10001 <a name="gnutls_005fdh_005fparams_005fcpy-1"></a>
10002 <h4 class="subheading">gnutls_dh_params_cpy</h4>
10003 <a name="gnutls_005fdh_005fparams_005fcpy"></a><dl>
10004 <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>
10005 <dd><p><var>dst</var>: Is the destination structure, which should be initialized.
10006 </p>
10007 <p><var>src</var>: Is the source structure
10008 </p>
10009 <p>This function will copy the DH parameters structure from source
10010 to destination.
10011 </p>
10012 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
10013 otherwise an error code is returned.
10014 </p></dd></dl>
10015
10016 <a name="gnutls_005fdh_005fparams_005fdeinit-1"></a>
10017 <h4 class="subheading">gnutls_dh_params_deinit</h4>
10018 <a name="gnutls_005fdh_005fparams_005fdeinit"></a><dl>
10019 <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>
10020 <dd><p><var>dh_params</var>: Is a structure that holds the prime numbers
10021 </p>
10022 <p>This function will deinitialize the DH parameters structure.
10023 </p></dd></dl>
10024
10025 <a name="gnutls_005fdh_005fparams_005fexport_005fpkcs3-1"></a>
10026 <h4 class="subheading">gnutls_dh_params_export_pkcs3</h4>
10027 <a name="gnutls_005fdh_005fparams_005fexport_005fpkcs3"></a><dl>
10028 <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>
10029 <dd><p><var>params</var>: Holds the DH parameters
10030 </p>
10031 <p><var>format</var>: the format of output params. One of PEM or DER.
10032 </p>
10033 <p><var>params_data</var>: will contain a PKCS3 DHParams structure PEM or DER encoded
10034 </p>
10035 <p><var>params_data_size</var>: holds the size of params_data (and will be replaced by the actual size of parameters)
10036 </p>
10037 <p>This function will export the given dh parameters to a PKCS3
10038 DHParams structure. This is the format generated by &quot;openssl dhparam&quot; tool.
10039 If the buffer provided is not long enough to hold the output, then
10040 GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
10041 </p>
10042 <p>If the structure is PEM encoded, it will have a header
10043 of &quot;BEGIN DH PARAMETERS&quot;.
10044 </p>
10045 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
10046 otherwise an error code is returned.
10047 </p></dd></dl>
10048
10049 <a name="gnutls_005fdh_005fparams_005fexport_005fraw-1"></a>
10050 <h4 class="subheading">gnutls_dh_params_export_raw</h4>
10051 <a name="gnutls_005fdh_005fparams_005fexport_005fraw"></a><dl>
10052 <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>
10053 <dd><p><var>params</var>: Holds the DH parameters
10054 </p>
10055 <p><var>prime</var>: will hold the new prime
10056 </p>
10057 <p><var>generator</var>: will hold the new generator
10058 </p>
10059 <p><var>bits</var>: if non null will hold is the prime&rsquo;s number of bits
10060 </p>
10061 <p>This function will export the pair of prime and generator for use
10062 in the Diffie-Hellman key exchange.  The new parameters will be
10063 allocated using <code>gnutls_malloc()</code> and will be stored in the
10064 appropriate datum.
10065 </p>
10066 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
10067 otherwise an error code is returned.
10068 </p></dd></dl>
10069
10070 <a name="gnutls_005fdh_005fparams_005fgenerate2-1"></a>
10071 <h4 class="subheading">gnutls_dh_params_generate2</h4>
10072 <a name="gnutls_005fdh_005fparams_005fgenerate2"></a><dl>
10073 <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>params</var>, unsigned int <var>bits</var>)</em></dt>
10074 <dd><p><var>params</var>: Is the structure that the DH parameters will be stored
10075 </p>
10076 <p><var>bits</var>: is the prime&rsquo;s number of bits
10077 </p>
10078 <p>This function will generate a new pair of prime and generator for use in
10079 the Diffie-Hellman key exchange. The new parameters will be allocated using
10080 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
10081 This function is normally slow.
10082 </p>
10083 <p>Do not set the number of bits directly, use <code>gnutls_sec_param_to_pk_bits()</code> to
10084 get bits for <code>GNUTLS_PK_DSA</code>.
10085 Also note that the DH parameters are only useful to servers.
10086 Since clients use the parameters sent by the server, it&rsquo;s of
10087 no use to call this in client side.
10088 </p>
10089 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
10090 otherwise an error code is returned.
10091 </p></dd></dl>
10092
10093 <a name="gnutls_005fdh_005fparams_005fimport_005fpkcs3-1"></a>
10094 <h4 class="subheading">gnutls_dh_params_import_pkcs3</h4>
10095 <a name="gnutls_005fdh_005fparams_005fimport_005fpkcs3"></a><dl>
10096 <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>
10097 <dd><p><var>params</var>: A structure where the parameters will be copied to
10098 </p>
10099 <p><var>pkcs3_params</var>: should contain a PKCS3 DHParams structure PEM or DER encoded
10100 </p>
10101 <p><var>format</var>: the format of params. PEM or DER.
10102 </p>
10103 <p>This function will extract the DHParams found in a PKCS3 formatted
10104 structure. This is the format generated by &quot;openssl dhparam&quot; tool.
10105 </p>
10106 <p>If the structure is PEM encoded, it should have a header
10107 of &quot;BEGIN DH PARAMETERS&quot;.
10108 </p>
10109 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
10110 otherwise an error code is returned.
10111 </p></dd></dl>
10112
10113 <a name="gnutls_005fdh_005fparams_005fimport_005fraw-1"></a>
10114 <h4 class="subheading">gnutls_dh_params_import_raw</h4>
10115 <a name="gnutls_005fdh_005fparams_005fimport_005fraw"></a><dl>
10116 <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>
10117 <dd><p><var>dh_params</var>: Is a structure that will hold the prime numbers
10118 </p>
10119 <p><var>prime</var>: holds the new prime
10120 </p>
10121 <p><var>generator</var>: holds the new generator
10122 </p>
10123 <p>This function will replace the pair of prime and generator for use
10124 in the Diffie-Hellman key exchange.  The new parameters should be
10125 stored in the appropriate gnutls_datum.
10126 </p>
10127 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
10128 otherwise an error code is returned.
10129 </p></dd></dl>
10130
10131 <a name="gnutls_005fdh_005fparams_005finit-1"></a>
10132 <h4 class="subheading">gnutls_dh_params_init</h4>
10133 <a name="gnutls_005fdh_005fparams_005finit"></a><dl>
10134 <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>
10135 <dd><p><var>dh_params</var>: Is a structure that will hold the prime numbers
10136 </p>
10137 <p>This function will initialize the DH parameters structure.
10138 </p>
10139 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
10140 otherwise an error code is returned.
10141 </p></dd></dl>
10142
10143 <a name="gnutls_005fdh_005fset_005fprime_005fbits-1"></a>
10144 <h4 class="subheading">gnutls_dh_set_prime_bits</h4>
10145 <a name="gnutls_005fdh_005fset_005fprime_005fbits"></a><dl>
10146 <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>
10147 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
10148 </p>
10149 <p><var>bits</var>: is the number of bits
10150 </p>
10151 <p>This function sets the number of bits, for use in an Diffie-Hellman
10152 key exchange.  This is used both in DH ephemeral and DH anonymous
10153 cipher suites.  This will set the minimum size of the prime that
10154 will be used for the handshake.
10155 </p>
10156 <p>In the client side it sets the minimum accepted number of bits.  If
10157 a server sends a prime with less bits than that
10158 <code>GNUTLS_E_DH_PRIME_UNACCEPTABLE</code> will be returned by the handshake.
10159 </p>
10160 <p>This function has no effect in server side.
10161 </p></dd></dl>
10162
10163 <a name="gnutls_005ferror_005fis_005ffatal-1"></a>
10164 <h4 class="subheading">gnutls_error_is_fatal</h4>
10165 <a name="gnutls_005ferror_005fis_005ffatal"></a><dl>
10166 <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>
10167 <dd><p><var>error</var>: is a GnuTLS error code, a negative value
10168 </p>
10169 <p>If a GnuTLS function returns a negative value you may feed that
10170 value to this function to see if the error condition is fatal.
10171 </p>
10172 <p>Note that you may want to check the error code manually, since some
10173 non-fatal errors to the protocol may be fatal for you program.
10174 </p>
10175 <p>This function is only useful if you are dealing with errors from
10176 the record layer or the handshake layer.
10177 </p>
10178 <p><strong>Returns:</strong> 1 if the error code is fatal, for positive <code>error</code> values,
10179 0 is returned.  For unknown <code>error</code> values, -1 is returned.
10180 </p></dd></dl>
10181
10182 <a name="gnutls_005ferror_005fto_005falert-1"></a>
10183 <h4 class="subheading">gnutls_error_to_alert</h4>
10184 <a name="gnutls_005ferror_005fto_005falert"></a><dl>
10185 <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>
10186 <dd><p><var>err</var>: is a negative integer
10187 </p>
10188 <p><var>level</var>: the alert level will be stored there
10189 </p>
10190 <p>Get an alert depending on the error code returned by a gnutls
10191 function.  All alerts sent by this function should be considered
10192 fatal.  The only exception is when <code>err</code> is <code>GNUTLS_E_REHANDSHAKE</code>,
10193 where a warning alert should be sent to the peer indicating that no
10194 renegotiation will be performed.
10195 </p>
10196 <p>If there is no mapping to a valid alert the alert to indicate
10197 internal error is returned.
10198 </p>
10199 <p><strong>Returns:</strong> the alert code to use for a particular error code.
10200 </p></dd></dl>
10201
10202 <a name="gnutls_005fext_005fregister-1"></a>
10203 <h4 class="subheading">gnutls_ext_register</h4>
10204 <a name="gnutls_005fext_005fregister"></a><dl>
10205 <dt><a name="index-gnutls_005fext_005fregister"></a>Function: <em>int</em> <strong>gnutls_ext_register</strong> <em>(int <var>type</var>, const char * <var>name</var>, gnutls_ext_parse_type_t <var>parse_type</var>, gnutls_ext_recv_func <var>recv_func</var>, gnutls_ext_send_func <var>send_func</var>)</em></dt>
10206 <dd><p><var>type</var>: the 16-bit integer referring to the extension type
10207 </p>
10208 <p><var>name</var>: human printable name of the extension used for debugging
10209 </p>
10210 <p><var>parse_type</var>: either <code>GNUTLS_EXT_TLS</code> or <code>GNUTLS_EXT_APPLICATION</code>.
10211 </p>
10212 <p><var>recv_func</var>: a function to receive extension data
10213 </p>
10214 <p><var>send_func</var>: a function to send extension data
10215 </p>
10216 <p>This function is used to register a new TLS extension handler.
10217 </p>
10218 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
10219 </p>
10220 <p><strong>Deprecated in:</strong> 2.12.0
10221 </p></dd></dl>
10222
10223 <a name="gnutls_005ffingerprint-1"></a>
10224 <h4 class="subheading">gnutls_fingerprint</h4>
10225 <a name="gnutls_005ffingerprint"></a><dl>
10226 <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>
10227 <dd><p><var>algo</var>: is a digest algorithm
10228 </p>
10229 <p><var>data</var>: is the data
10230 </p>
10231 <p><var>result</var>: is the place where the result will be copied (may be null).
10232 </p>
10233 <p><var>result_size</var>: should hold the size of the result. The actual size
10234 of the returned result will also be copied there.
10235 </p>
10236 <p>This function will calculate a fingerprint (actually a hash), of
10237 the given data.  The result is not printable data.  You should
10238 convert it to hex, or to something else printable.
10239 </p>
10240 <p>This is the usual way to calculate a fingerprint of an X.509 DER
10241 encoded certificate.  Note however that the fingerprint of an
10242 OpenPGP is not just a hash and cannot be calculated with this
10243 function.
10244 </p>
10245 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
10246 an error code is returned.
10247 </p></dd></dl>
10248
10249 <a name="gnutls_005ffree-1"></a>
10250 <h4 class="subheading">gnutls_free</h4>
10251 <a name="gnutls_005ffree"></a><dl>
10252 <dt><a name="index-gnutls_005ffree"></a>Function: <em>void</em> <strong>gnutls_free</strong> <em>(void * <var>ptr</var>)</em></dt>
10253 <dd><p>This function will free data pointed by ptr.
10254 </p>
10255 <p>The deallocation function used is the one set by
10256 <code>gnutls_global_set_mem_functions()</code>.
10257 </p></dd></dl>
10258
10259 <a name="gnutls_005fglobal_005fdeinit-1"></a>
10260 <h4 class="subheading">gnutls_global_deinit</h4>
10261 <a name="gnutls_005fglobal_005fdeinit"></a><dl>
10262 <dt><a name="index-gnutls_005fglobal_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_global_deinit</strong> <em>( <var>void</var>)</em></dt>
10263 <dd>
10264 <p>This function deinitializes the global data, that were initialized
10265 using <code>gnutls_global_init()</code>.
10266 </p>
10267 <p>Note!  This function is not thread safe.  See the discussion for
10268 <code>gnutls_global_init()</code> for more information.
10269 </p></dd></dl>
10270
10271 <a name="gnutls_005fglobal_005finit-1"></a>
10272 <h4 class="subheading">gnutls_global_init</h4>
10273 <a name="gnutls_005fglobal_005finit"></a><dl>
10274 <dt><a name="index-gnutls_005fglobal_005finit"></a>Function: <em>int</em> <strong>gnutls_global_init</strong> <em>( <var>void</var>)</em></dt>
10275 <dd>
10276 <p>This function initializes the global data to defaults.  Every
10277 gnutls application has a global data which holds common parameters
10278 shared by gnutls session structures.  You should call
10279 <code>gnutls_global_deinit()</code> when gnutls usage is no longer needed
10280 </p>
10281 <p>Note that this function will also initialize the underlying crypto
10282 backend, if it has not been initialized before.
10283 </p>
10284 <p>This function increment a global counter, so that
10285 <code>gnutls_global_deinit()</code> only releases resources when it has been
10286 called as many times as <code>gnutls_global_init()</code>.  This is useful when
10287 GnuTLS is used by more than one library in an application.  This
10288 function can be called many times, but will only do something the
10289 first time.
10290 </p>
10291 <p>Note!  This function is not thread safe.  If two threads call this
10292 function simultaneously, they can cause a race between checking
10293 the global counter and incrementing it, causing both threads to
10294 execute the library initialization code.  That would lead to a
10295 memory leak.  To handle this, your application could invoke this
10296 function after aquiring a thread mutex.  To ignore the potential
10297 memory leak is also an option.
10298 </p>
10299 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
10300 otherwise an error code is returned.
10301 </p></dd></dl>
10302
10303 <a name="gnutls_005fglobal_005fset_005flog_005ffunction-1"></a>
10304 <h4 class="subheading">gnutls_global_set_log_function</h4>
10305 <a name="gnutls_005fglobal_005fset_005flog_005ffunction"></a><dl>
10306 <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>
10307 <dd><p><var>log_func</var>: it&rsquo;s a log function
10308 </p>
10309 <p>This is the function where you set the logging function gnutls is
10310 going to use.  This function only accepts a character array.
10311 Normally you may not use this function since it is only used for
10312 debugging purposes.
10313 </p>
10314 <p>gnutls_log_func is of the form,
10315 void (*gnutls_log_func)( int level, const char*);
10316 </p></dd></dl>
10317
10318 <a name="gnutls_005fglobal_005fset_005flog_005flevel-1"></a>
10319 <h4 class="subheading">gnutls_global_set_log_level</h4>
10320 <a name="gnutls_005fglobal_005fset_005flog_005flevel"></a><dl>
10321 <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>
10322 <dd><p><var>level</var>: it&rsquo;s an integer from 0 to 9.
10323 </p>
10324 <p>This is the function that allows you to set the log level.  The
10325 level is an integer between 0 and 9.  Higher values mean more
10326 verbosity. The default value is 0.  Larger values should only be
10327 used with care, since they may reveal sensitive information.
10328 </p>
10329 <p>Use a log level over 10 to enable all debugging options.
10330 </p></dd></dl>
10331
10332 <a name="gnutls_005fglobal_005fset_005fmem_005ffunctions-1"></a>
10333 <h4 class="subheading">gnutls_global_set_mem_functions</h4>
10334 <a name="gnutls_005fglobal_005fset_005fmem_005ffunctions"></a><dl>
10335 <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>
10336 <dd><p><var>alloc_func</var>: it&rsquo;s the default memory allocation function. Like <code>malloc()</code>.
10337 </p>
10338 <p><var>secure_alloc_func</var>: This is the memory allocation function that will be used for sensitive data.
10339 </p>
10340 <p><var>is_secure_func</var>: a function that returns 0 if the memory given is not secure. May be NULL.
10341 </p>
10342 <p><var>realloc_func</var>: A realloc function
10343 </p>
10344 <p><var>free_func</var>: The function that frees allocated data. Must accept a NULL pointer.
10345 </p>
10346 <p>This is the function were you set the memory allocation functions
10347 gnutls is going to use. By default the libc&rsquo;s allocation functions
10348 (<code>malloc()</code>, <code>free()</code>), are used by gnutls, to allocate both sensitive
10349 and not sensitive data.  This function is provided to set the
10350 memory allocation functions to something other than the defaults
10351 </p>
10352 <p>This function must be called before <code>gnutls_global_init()</code> is called.
10353 This function is not thread safe.
10354 </p></dd></dl>
10355
10356 <a name="gnutls_005fglobal_005fset_005fmutex-1"></a>
10357 <h4 class="subheading">gnutls_global_set_mutex</h4>
10358 <a name="gnutls_005fglobal_005fset_005fmutex"></a><dl>
10359 <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>
10360 <dd><p><var>init</var>: mutex initialization function
10361 </p>
10362 <p><var>deinit</var>: mutex deinitialization function
10363 </p>
10364 <p><var>lock</var>: mutex locking function
10365 </p>
10366 <p><var>unlock</var>: mutex unlocking function
10367 </p>
10368 <p>With this function you are allowed to override the default mutex
10369 locks used in some parts of gnutls and dependent libraries. This function
10370 should be used if you have complete control of your program and libraries.
10371 Do not call this function from a library. Instead only initialize gnutls and
10372 the default OS mutex locks will be used.
10373 </p>
10374 <p>This function must be called before <code>gnutls_global_init()</code>.
10375 </p></dd></dl>
10376
10377 <a name="gnutls_005fglobal_005fset_005ftime_005ffunction-1"></a>
10378 <h4 class="subheading">gnutls_global_set_time_function</h4>
10379 <a name="gnutls_005fglobal_005fset_005ftime_005ffunction"></a><dl>
10380 <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>
10381 <dd><p><var>time_func</var>: it&rsquo;s the system time function
10382 </p>
10383 <p>This is the function where you can override the default system
10384 time function.
10385 </p>
10386 <p>gnutls_time_func is of the form,
10387 time_t (*gnutls_time_func)( time*);
10388 </p></dd></dl>
10389
10390 <a name="gnutls_005fhandshake_005fget_005flast_005fin-1"></a>
10391 <h4 class="subheading">gnutls_handshake_get_last_in</h4>
10392 <a name="gnutls_005fhandshake_005fget_005flast_005fin"></a><dl>
10393 <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>
10394 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
10395 </p>
10396 <p>This function is only useful to check where the last performed
10397 handshake failed.  If the previous handshake succeed or was not
10398 performed at all then no meaningful value will be returned.
10399 </p>
10400 <p>Check <code>gnutls_handshake_description_t</code> in gnutls.h for the
10401 available handshake descriptions.
10402 </p>
10403 <p><strong>Returns:</strong> the last handshake message type received, a
10404 <code>gnutls_handshake_description_t</code>.
10405 </p></dd></dl>
10406
10407 <a name="gnutls_005fhandshake_005fget_005flast_005fout-1"></a>
10408 <h4 class="subheading">gnutls_handshake_get_last_out</h4>
10409 <a name="gnutls_005fhandshake_005fget_005flast_005fout"></a><dl>
10410 <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>
10411 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
10412 </p>
10413 <p>This function is only useful to check where the last performed
10414 handshake failed.  If the previous handshake succeed or was not
10415 performed at all then no meaningful value will be returned.
10416 </p>
10417 <p>Check <code>gnutls_handshake_description_t</code> in gnutls.h for the
10418 available handshake descriptions.
10419 </p>
10420 <p><strong>Returns:</strong> the last handshake message type sent, a
10421 <code>gnutls_handshake_description_t</code>.
10422 </p></dd></dl>
10423
10424 <a name="gnutls_005fhandshake_005fset_005fmax_005fpacket_005flength-1"></a>
10425 <h4 class="subheading">gnutls_handshake_set_max_packet_length</h4>
10426 <a name="gnutls_005fhandshake_005fset_005fmax_005fpacket_005flength"></a><dl>
10427 <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>
10428 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
10429 </p>
10430 <p><var>max</var>: is the maximum number.
10431 </p>
10432 <p>This function will set the maximum size of all handshake messages.
10433 Handshakes over this size are rejected with
10434 <code>GNUTLS_E_HANDSHAKE_TOO_LARGE</code> error code.  The default value is
10435 48kb which is typically large enough.  Set this to 0 if you do not
10436 want to set an upper limit.
10437 </p>
10438 <p>The reason for restricting the handshake message sizes are to
10439 limit Denial of Service attacks.
10440 </p></dd></dl>
10441
10442 <a name="gnutls_005fhandshake_005fset_005fpost_005fclient_005fhello_005ffunction-1"></a>
10443 <h4 class="subheading">gnutls_handshake_set_post_client_hello_function</h4>
10444 <a name="gnutls_005fhandshake_005fset_005fpost_005fclient_005fhello_005ffunction"></a><dl>
10445 <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>
10446 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
10447 </p>
10448 <p><var>func</var>: is the function to be called
10449 </p>
10450 <p>This function will set a callback to be called after the client
10451 hello has been received (callback valid in server side only). This
10452 allows the server to adjust settings based on received extensions.
10453 </p>
10454 <p>Those settings could be ciphersuites, requesting certificate, or
10455 anything else except for version negotiation (this is done before
10456 the hello message is parsed).
10457 </p>
10458 <p>This callback must return 0 on success or a gnutls error code to
10459 terminate the handshake.
10460 </p>
10461 <p><strong>Warning:</strong> You should not use this function to terminate the
10462 handshake based on client input unless you know what you are
10463 doing. Before the handshake is finished there is no way to know if
10464 there is a man-in-the-middle attack being performed.
10465 </p></dd></dl>
10466
10467 <a name="gnutls_005fhandshake_005fset_005fprivate_005fextensions-1"></a>
10468 <h4 class="subheading">gnutls_handshake_set_private_extensions</h4>
10469 <a name="gnutls_005fhandshake_005fset_005fprivate_005fextensions"></a><dl>
10470 <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>
10471 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
10472 </p>
10473 <p><var>allow</var>: is an integer (0 or 1)
10474 </p>
10475 <p>This function will enable or disable the use of private cipher
10476 suites (the ones that start with 0xFF).  By default or if <code>allow</code>
10477 is 0 then these cipher suites will not be advertized nor used.
10478 </p>
10479 <p>Unless this function is called with the option to allow (1), then
10480 no compression algorithms, like LZO.  That is because these
10481 algorithms are not yet defined in any RFC or even internet draft.
10482 </p>
10483 <p>Enabling the private ciphersuites when talking to other than
10484 gnutls servers and clients may cause interoperability problems.
10485 </p></dd></dl>
10486
10487 <a name="gnutls_005fhandshake-1"></a>
10488 <h4 class="subheading">gnutls_handshake</h4>
10489 <a name="gnutls_005fhandshake"></a><dl>
10490 <dt><a name="index-gnutls_005fhandshake"></a>Function: <em>int</em> <strong>gnutls_handshake</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
10491 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
10492 </p>
10493 <p>This function does the handshake of the TLS/SSL protocol, and
10494 initializes the TLS connection.
10495 </p>
10496 <p>This function will fail if any problem is encountered, and will
10497 return a negative error code. In case of a client, if the client
10498 has asked to resume a session, but the server couldn&rsquo;t, then a
10499 full handshake will be performed.
10500 </p>
10501 <p>The non-fatal errors such as <code>GNUTLS_E_AGAIN</code> and
10502 <code>GNUTLS_E_INTERRUPTED</code> interrupt the handshake procedure, which
10503 should be later be resumed.  Call this function again, until it
10504 returns 0; cf.  <code>gnutls_record_get_direction()</code> and
10505 <code>gnutls_error_is_fatal()</code>.
10506 </p>
10507 <p>If this function is called by a server after a rehandshake request
10508 then <code>GNUTLS_E_GOT_APPLICATION_DATA</code> or
10509 <code>GNUTLS_E_WARNING_ALERT_RECEIVED</code> may be returned.  Note that these
10510 are non fatal errors, only in the specific case of a rehandshake.
10511 Their meaning is that the client rejected the rehandshake request or
10512 in the case of <code>GNUTLS_E_GOT_APPLICATION_DATA</code> it might also mean that
10513 some data were pending.
10514 </p>
10515 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
10516 </p></dd></dl>
10517
10518 <a name="gnutls_005fhash_005fdeinit-1"></a>
10519 <h4 class="subheading">gnutls_hash_deinit</h4>
10520 <a name="gnutls_005fhash_005fdeinit"></a><dl>
10521 <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>
10522 <dd><p><var>handle</var>: is a <code>gnutls_hash_hd_t</code> structure.
10523 </p>
10524 <p><var>digest</var>: is the output value of the hash
10525 </p>
10526 <p>This function will deinitialize all resources occupied by
10527 the given hash context.
10528 </p>
10529 <p><strong>Since:</strong> 2.10.0
10530 </p></dd></dl>
10531
10532 <a name="gnutls_005fhash_005ffast-1"></a>
10533 <h4 class="subheading">gnutls_hash_fast</h4>
10534 <a name="gnutls_005fhash_005ffast"></a><dl>
10535 <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>
10536 <dd><p><var>algorithm</var>: the hash algorithm to use
10537 </p>
10538 <p><var>text</var>: the data to hash
10539 </p>
10540 <p><var>textlen</var>: The length of data to hash
10541 </p>
10542 <p><var>digest</var>: is the output value of the hash
10543 </p>
10544 <p>This convenience function will hash the given data and return output
10545 on a single call.
10546 </p>
10547 <p><strong>Returns:</strong> Zero or a negative value on error.
10548 </p>
10549 <p><strong>Since:</strong> 2.10.0
10550 </p></dd></dl>
10551
10552 <a name="gnutls_005fhash_005fget_005flen-1"></a>
10553 <h4 class="subheading">gnutls_hash_get_len</h4>
10554 <a name="gnutls_005fhash_005fget_005flen"></a><dl>
10555 <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>
10556 <dd><p><var>algorithm</var>: the hash algorithm to use
10557 </p>
10558 <p>This function will return the length of the output data
10559 of the given hash algorithm.
10560 </p>
10561 <p><strong>Returns:</strong> The length or zero on error.
10562 </p>
10563 <p><strong>Since:</strong> 2.10.0
10564 </p></dd></dl>
10565
10566 <a name="gnutls_005fhash_005finit-1"></a>
10567 <h4 class="subheading">gnutls_hash_init</h4>
10568 <a name="gnutls_005fhash_005finit"></a><dl>
10569 <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>
10570 <dd><p><var>dig</var>: is a <code>gnutls_hash_hd_t</code> structure.
10571 </p>
10572 <p><var>algorithm</var>: the hash algorithm to use
10573 </p>
10574 <p>This function will initialize an context that can be used to
10575 produce a Message Digest of data.  This will effectively use the
10576 current crypto backend in use by gnutls or the cryptographic
10577 accelerator in use.
10578 </p>
10579 <p><strong>Returns:</strong> Zero or a negative value on error.
10580 </p>
10581 <p><strong>Since:</strong> 2.10.0
10582 </p></dd></dl>
10583
10584 <a name="gnutls_005fhash_005foutput-1"></a>
10585 <h4 class="subheading">gnutls_hash_output</h4>
10586 <a name="gnutls_005fhash_005foutput"></a><dl>
10587 <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>
10588 <dd><p><var>handle</var>: is a <code>gnutls_hash_hd_t</code> structure.
10589 </p>
10590 <p><var>digest</var>: is the output value of the hash
10591 </p>
10592 <p>This function will output the current hash value.
10593 </p>
10594 <p><strong>Since:</strong> 2.10.0
10595 </p></dd></dl>
10596
10597 <a name="gnutls_005fhash-1"></a>
10598 <h4 class="subheading">gnutls_hash</h4>
10599 <a name="gnutls_005fhash"></a><dl>
10600 <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>
10601 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code> structure.
10602 </p>
10603 <p><var>text</var>: the data to hash
10604 </p>
10605 <p><var>textlen</var>: The length of data to hash
10606 </p>
10607 <p>This function will hash the given data using the algorithm
10608 specified by the context.
10609 </p>
10610 <p><strong>Returns:</strong> Zero or a negative value on error.
10611 </p>
10612 <p><strong>Since:</strong> 2.10.0
10613 </p></dd></dl>
10614
10615 <a name="gnutls_005fhex2bin-1"></a>
10616 <h4 class="subheading">gnutls_hex2bin</h4>
10617 <a name="gnutls_005fhex2bin"></a><dl>
10618 <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>, char * <var>bin_data</var>, size_t * <var>bin_size</var>)</em></dt>
10619 <dd><p><var>hex_data</var>: string with data in hex format
10620 </p>
10621 <p><var>hex_size</var>: size of hex data
10622 </p>
10623 <p><var>bin_data</var>: output array with binary data
10624 </p>
10625 <p><var>bin_size</var>: when calling *<code>bin_size</code> should hold size of <code>bin_data</code>,
10626 on return will hold actual size of <code>bin_data</code>.
10627 </p>
10628 <p>Convert a buffer with hex data to binary data.
10629 </p>
10630 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
10631 </p>
10632 <p><strong>Since:</strong> 2.4.0
10633 </p></dd></dl>
10634
10635 <a name="gnutls_005fhex_005fdecode-1"></a>
10636 <h4 class="subheading">gnutls_hex_decode</h4>
10637 <a name="gnutls_005fhex_005fdecode"></a><dl>
10638 <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>, char * <var>result</var>, size_t * <var>result_size</var>)</em></dt>
10639 <dd><p><var>hex_data</var>: contain the encoded data
10640 </p>
10641 <p><var>result</var>: the place where decoded data will be copied
10642 </p>
10643 <p><var>result_size</var>: holds the size of the result
10644 </p>
10645 <p>This function will decode the given encoded data, using the hex
10646 encoding used by PSK password files.
10647 </p>
10648 <p>Note that hex_data should be null terminated.
10649 </p>
10650 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the buffer given is not
10651 long enough, or 0 on success.
10652 </p></dd></dl>
10653
10654 <a name="gnutls_005fhex_005fencode-1"></a>
10655 <h4 class="subheading">gnutls_hex_encode</h4>
10656 <a name="gnutls_005fhex_005fencode"></a><dl>
10657 <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>
10658 <dd><p><var>data</var>: contain the raw data
10659 </p>
10660 <p><var>result</var>: the place where hex data will be copied
10661 </p>
10662 <p><var>result_size</var>: holds the size of the result
10663 </p>
10664 <p>This function will convert the given data to printable data, using
10665 the hex encoding, as used in the PSK password files.
10666 </p>
10667 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the buffer given is not
10668 long enough, or 0 on success.
10669 </p></dd></dl>
10670
10671 <a name="gnutls_005fhmac_005fdeinit-1"></a>
10672 <h4 class="subheading">gnutls_hmac_deinit</h4>
10673 <a name="gnutls_005fhmac_005fdeinit"></a><dl>
10674 <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>
10675 <dd><p><var>handle</var>: is a <code>gnutls_hmac_hd_t</code> structure.
10676 </p>
10677 <p><var>digest</var>: is the output value of the MAC
10678 </p>
10679 <p>This function will deinitialize all resources occupied by
10680 the given hmac context.
10681 </p>
10682 <p><strong>Since:</strong> 2.10.0
10683 </p></dd></dl>
10684
10685 <a name="gnutls_005fhmac_005ffast-1"></a>
10686 <h4 class="subheading">gnutls_hmac_fast</h4>
10687 <a name="gnutls_005fhmac_005ffast"></a><dl>
10688 <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>
10689 <dd><p><var>algorithm</var>: the hash algorithm to use
10690 </p>
10691 <p><var>key</var>: the key to use
10692 </p>
10693 <p><var>keylen</var>: The length of the key
10694 </p>
10695 <p><var>text</var>: the data to hash
10696 </p>
10697 <p><var>textlen</var>: The length of data to hash
10698 </p>
10699 <p><var>digest</var>: is the output value of the hash
10700 </p>
10701 <p>This convenience function will hash the given data and return output
10702 on a single call.
10703 </p>
10704 <p><strong>Returns:</strong> Zero or a negative value on error.
10705 </p>
10706 <p><strong>Since:</strong> 2.10.0
10707 </p></dd></dl>
10708
10709 <a name="gnutls_005fhmac_005fget_005flen-1"></a>
10710 <h4 class="subheading">gnutls_hmac_get_len</h4>
10711 <a name="gnutls_005fhmac_005fget_005flen"></a><dl>
10712 <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>
10713 <dd><p><var>algorithm</var>: the hmac algorithm to use
10714 </p>
10715 <p>This function will return the length of the output data
10716 of the given hmac algorithm.
10717 </p>
10718 <p><strong>Returns:</strong> The length or zero on error.
10719 </p>
10720 <p><strong>Since:</strong> 2.10.0
10721 </p></dd></dl>
10722
10723 <a name="gnutls_005fhmac_005finit-1"></a>
10724 <h4 class="subheading">gnutls_hmac_init</h4>
10725 <a name="gnutls_005fhmac_005finit"></a><dl>
10726 <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_digest_algorithm_t <var>algorithm</var>, const void * <var>key</var>, size_t <var>keylen</var>)</em></dt>
10727 <dd><p><var>dig</var>: is a <code>gnutls_hmac_hd_t</code> structure.
10728 </p>
10729 <p><var>algorithm</var>: the HMAC algorithm to use
10730 </p>
10731 <p><var>key</var>: The key to be used for encryption
10732 </p>
10733 <p><var>keylen</var>: The length of the key
10734 </p>
10735 <p>This function will initialize an context that can be used to
10736 produce a Message Authentication Code (MAC) of data.  This will
10737 effectively use the current crypto backend in use by gnutls or the
10738 cryptographic accelerator in use.
10739 </p>
10740 <p><strong>Returns:</strong> Zero or a negative value on error.
10741 </p>
10742 <p><strong>Since:</strong> 2.10.0
10743 </p></dd></dl>
10744
10745 <a name="gnutls_005fhmac_005foutput-1"></a>
10746 <h4 class="subheading">gnutls_hmac_output</h4>
10747 <a name="gnutls_005fhmac_005foutput"></a><dl>
10748 <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>
10749 <dd><p><var>handle</var>: is a <code>gnutls_hmac_hd_t</code> structure.
10750 </p>
10751 <p><var>digest</var>: is the output value of the MAC
10752 </p>
10753 <p>This function will output the current MAC value.
10754 </p>
10755 <p><strong>Since:</strong> 2.10.0
10756 </p></dd></dl>
10757
10758 <a name="gnutls_005fhmac-1"></a>
10759 <h4 class="subheading">gnutls_hmac</h4>
10760 <a name="gnutls_005fhmac"></a><dl>
10761 <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>
10762 <dd><p><var>handle</var>: is a <code>gnutls_cipher_hd_t</code> structure.
10763 </p>
10764 <p><var>text</var>: the data to hash
10765 </p>
10766 <p><var>textlen</var>: The length of data to hash
10767 </p>
10768 <p>This function will hash the given data using the algorithm
10769 specified by the context.
10770 </p>
10771 <p><strong>Returns:</strong> Zero or a negative value on error.
10772 </p>
10773 <p><strong>Since:</strong> 2.10.0
10774 </p></dd></dl>
10775
10776 <a name="gnutls_005finit-1"></a>
10777 <h4 class="subheading">gnutls_init</h4>
10778 <a name="gnutls_005finit"></a><dl>
10779 <dt><a name="index-gnutls_005finit"></a>Function: <em>int</em> <strong>gnutls_init</strong> <em>(gnutls_session_t * <var>session</var>, gnutls_connection_end_t <var>con_end</var>)</em></dt>
10780 <dd><p><var>session</var>: is a pointer to a <code>gnutls_session_t</code> structure.
10781 </p>
10782 <p><var>con_end</var>: indicate if this session is to be used for server or client.
10783 </p>
10784 <p>This function initializes the current session to null. Every
10785 session must be initialized before use, so internal structures can
10786 be allocated.  This function allocates structures which can only
10787 be free&rsquo;d by calling <code>gnutls_deinit()</code>.  Returns zero on success.
10788 </p>
10789 <p><code>con_end</code> can be one of <code>GNUTLS_CLIENT</code> and <code>GNUTLS_SERVER</code>.
10790 </p>
10791 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
10792 </p></dd></dl>
10793
10794 <a name="gnutls_005fkx_005fget_005fid-1"></a>
10795 <h4 class="subheading">gnutls_kx_get_id</h4>
10796 <a name="gnutls_005fkx_005fget_005fid"></a><dl>
10797 <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>
10798 <dd><p><var>name</var>: is a KX name
10799 </p>
10800 <p>Convert a string to a <code>gnutls_kx_algorithm_t</code> value.  The names are
10801 compared in a case insensitive way.
10802 </p>
10803 <p><strong>Returns:</strong> an id of the specified KX algorithm, or <code>GNUTLS_KX_UNKNOWN</code>
10804 on error.
10805 </p></dd></dl>
10806
10807 <a name="gnutls_005fkx_005fget_005fname-1"></a>
10808 <h4 class="subheading">gnutls_kx_get_name</h4>
10809 <a name="gnutls_005fkx_005fget_005fname"></a><dl>
10810 <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>
10811 <dd><p><var>algorithm</var>: is a key exchange algorithm
10812 </p>
10813 <p>Convert a <code>gnutls_kx_algorithm_t</code> value to a string.
10814 </p>
10815 <p><strong>Returns:</strong> a pointer to a string that contains the name of the
10816 specified key exchange algorithm, or <code>NULL</code>.
10817 </p></dd></dl>
10818
10819 <a name="gnutls_005fkx_005fget-1"></a>
10820 <h4 class="subheading">gnutls_kx_get</h4>
10821 <a name="gnutls_005fkx_005fget"></a><dl>
10822 <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>
10823 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
10824 </p>
10825 <p>Get currently used key exchange algorithm.
10826 </p>
10827 <p><strong>Returns:</strong> the key exchange algorithm used in the last handshake, a
10828 <code>gnutls_kx_algorithm_t</code> value.
10829 </p></dd></dl>
10830
10831 <a name="gnutls_005fkx_005flist-1"></a>
10832 <h4 class="subheading">gnutls_kx_list</h4>
10833 <a name="gnutls_005fkx_005flist"></a><dl>
10834 <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>
10835 <dd>
10836 <p>Get a list of supported key exchange algorithms.
10837 </p>
10838 <p><strong>Returns:</strong> a zero-terminated list of <code>gnutls_kx_algorithm_t</code> integers
10839 indicating the available key exchange algorithms.
10840 </p></dd></dl>
10841
10842 <a name="gnutls_005fkx_005fset_005fpriority-1"></a>
10843 <h4 class="subheading">gnutls_kx_set_priority</h4>
10844 <a name="gnutls_005fkx_005fset_005fpriority"></a><dl>
10845 <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>
10846 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
10847 </p>
10848 <p><var>list</var>: is a 0 terminated list of gnutls_kx_algorithm_t elements.
10849 </p>
10850 <p>Sets the priority on the key exchange algorithms supported by
10851 gnutls.  Priority is higher for elements specified before others.
10852 After specifying the algorithms you want, you must append a 0.
10853 Note that the priority is set on the client. The server does not
10854 use the algorithm&rsquo;s priority except for disabling algorithms that
10855 were not specified.
10856 </p>
10857 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
10858 </p></dd></dl>
10859
10860 <a name="gnutls_005fmac_005fget_005fid-1"></a>
10861 <h4 class="subheading">gnutls_mac_get_id</h4>
10862 <a name="gnutls_005fmac_005fget_005fid"></a><dl>
10863 <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>
10864 <dd><p><var>name</var>: is a MAC algorithm name
10865 </p>
10866 <p>Convert a string to a <code>gnutls_mac_algorithm_t</code> value.  The names are
10867 compared in a case insensitive way.
10868 </p>
10869 <p><strong>Returns:</strong> a <code>gnutls_mac_algorithm_t</code> id of the specified MAC
10870 algorithm string, or <code>GNUTLS_MAC_UNKNOWN</code> on failures.
10871 </p></dd></dl>
10872
10873 <a name="gnutls_005fmac_005fget_005fkey_005fsize-1"></a>
10874 <h4 class="subheading">gnutls_mac_get_key_size</h4>
10875 <a name="gnutls_005fmac_005fget_005fkey_005fsize"></a><dl>
10876 <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>
10877 <dd><p><var>algorithm</var>: is an encryption algorithm
10878 </p>
10879 <p>Get size of MAC key.
10880 </p>
10881 <p><strong>Returns:</strong> length (in bytes) of the given MAC key size, or 0 if the
10882 given MAC algorithm is invalid.
10883 </p></dd></dl>
10884
10885 <a name="gnutls_005fmac_005fget_005fname-1"></a>
10886 <h4 class="subheading">gnutls_mac_get_name</h4>
10887 <a name="gnutls_005fmac_005fget_005fname"></a><dl>
10888 <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>
10889 <dd><p><var>algorithm</var>: is a MAC algorithm
10890 </p>
10891 <p>Convert a <code>gnutls_mac_algorithm_t</code> value to a string.
10892 </p>
10893 <p><strong>Returns:</strong> a string that contains the name of the specified MAC
10894 algorithm, or <code>NULL</code>.
10895 </p></dd></dl>
10896
10897 <a name="gnutls_005fmac_005fget-1"></a>
10898 <h4 class="subheading">gnutls_mac_get</h4>
10899 <a name="gnutls_005fmac_005fget"></a><dl>
10900 <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>
10901 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
10902 </p>
10903 <p>Get currently used MAC algorithm.
10904 </p>
10905 <p><strong>Returns:</strong> the currently used mac algorithm, a
10906 <code>gnutls_mac_algorithm_t</code> value.
10907 </p></dd></dl>
10908
10909 <a name="gnutls_005fmac_005flist-1"></a>
10910 <h4 class="subheading">gnutls_mac_list</h4>
10911 <a name="gnutls_005fmac_005flist"></a><dl>
10912 <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>
10913 <dd>
10914 <p>Get a list of hash algorithms for use as MACs.  Note that not
10915 necessarily all MACs are supported in TLS cipher suites.  For
10916 example, MD2 is not supported as a cipher suite, but is supported
10917 for other purposes (e.g., X.509 signature verification or similar).
10918 </p>
10919 <p><strong>Returns:</strong> Return a zero-terminated list of <code>gnutls_mac_algorithm_t</code>
10920 integers indicating the available MACs.
10921 </p></dd></dl>
10922
10923 <a name="gnutls_005fmac_005fset_005fpriority-1"></a>
10924 <h4 class="subheading">gnutls_mac_set_priority</h4>
10925 <a name="gnutls_005fmac_005fset_005fpriority"></a><dl>
10926 <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>
10927 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
10928 </p>
10929 <p><var>list</var>: is a 0 terminated list of gnutls_mac_algorithm_t elements.
10930 </p>
10931 <p>Sets the priority on the mac algorithms supported by gnutls.
10932 Priority is higher for elements specified before others.  After
10933 specifying the algorithms you want, you must append a 0.  Note
10934 that the priority is set on the client. The server does not use
10935 the algorithm&rsquo;s priority except for disabling algorithms that were
10936 not specified.
10937 </p>
10938 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
10939 </p></dd></dl>
10940
10941 <a name="gnutls_005fmalloc-1"></a>
10942 <h4 class="subheading">gnutls_malloc</h4>
10943 <a name="gnutls_005fmalloc"></a><dl>
10944 <dt><a name="index-gnutls_005fmalloc"></a>Function: <em>void *</em> <strong>gnutls_malloc</strong> <em>(size_t <var>s</var>)</em></dt>
10945 <dd>
10946 <p>This function will allocate &rsquo;s&rsquo; bytes data, and
10947 return a pointer to memory. This function is supposed
10948 to be used by callbacks.
10949 </p>
10950 <p>The allocation function used is the one set by
10951 <code>gnutls_global_set_mem_functions()</code>.
10952 </p></dd></dl>
10953
10954 <a name="gnutls_005fopenpgp_005fsend_005fcert-1"></a>
10955 <h4 class="subheading">gnutls_openpgp_send_cert</h4>
10956 <a name="gnutls_005fopenpgp_005fsend_005fcert"></a><dl>
10957 <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>
10958 <dd><p><var>session</var>: is a pointer to a <code>gnutls_session_t</code> structure.
10959 </p>
10960 <p><var>status</var>: is one of GNUTLS_OPENPGP_CERT, or GNUTLS_OPENPGP_CERT_FINGERPRINT
10961 </p>
10962 <p>This function will order gnutls to send the key fingerprint
10963 instead of the key in the initial handshake procedure. This should
10964 be used with care and only when there is indication or knowledge
10965 that the server can obtain the client&rsquo;s key.
10966 </p></dd></dl>
10967
10968 <a name="gnutls_005fpem_005fbase64_005fdecode_005falloc-1"></a>
10969 <h4 class="subheading">gnutls_pem_base64_decode_alloc</h4>
10970 <a name="gnutls_005fpem_005fbase64_005fdecode_005falloc"></a><dl>
10971 <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>
10972 <dd><p><var>header</var>: The PEM header (eg. CERTIFICATE)
10973 </p>
10974 <p><var>b64_data</var>: contains the encoded data
10975 </p>
10976 <p><var>result</var>: the place where decoded data lie
10977 </p>
10978 <p>This function will decode the given encoded data. The decoded data
10979 will be allocated, and stored into result.  If the header given is
10980 non null this function will search for &quot;&mdash;&ndash;BEGIN header&quot; and
10981 decode only this part. Otherwise it will decode the first PEM
10982 packet found.
10983 </p>
10984 <p>You should use <code>gnutls_free()</code> to free the returned data.
10985 </p>
10986 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
10987 an error code is returned.
10988 </p></dd></dl>
10989
10990 <a name="gnutls_005fpem_005fbase64_005fdecode-1"></a>
10991 <h4 class="subheading">gnutls_pem_base64_decode</h4>
10992 <a name="gnutls_005fpem_005fbase64_005fdecode"></a><dl>
10993 <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>
10994 <dd><p><var>header</var>: A null terminated string with the PEM header (eg. CERTIFICATE)
10995 </p>
10996 <p><var>b64_data</var>: contain the encoded data
10997 </p>
10998 <p><var>result</var>: the place where decoded data will be copied
10999 </p>
11000 <p><var>result_size</var>: holds the size of the result
11001 </p>
11002 <p>This function will decode the given encoded data.  If the header
11003 given is non null this function will search for &quot;&mdash;&ndash;BEGIN header&quot;
11004 and decode only this part.  Otherwise it will decode the first PEM
11005 packet found.
11006 </p>
11007 <p><strong>Returns:</strong> On success <code>GNUTLS_E_SUCCESS</code> (0) is returned,
11008 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> is returned if the buffer given is
11009 not long enough, or 0 on success.
11010 </p></dd></dl>
11011
11012 <a name="gnutls_005fpem_005fbase64_005fencode_005falloc-1"></a>
11013 <h4 class="subheading">gnutls_pem_base64_encode_alloc</h4>
11014 <a name="gnutls_005fpem_005fbase64_005fencode_005falloc"></a><dl>
11015 <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>
11016 <dd><p><var>msg</var>: is a message to be put in the encoded header
11017 </p>
11018 <p><var>data</var>: contains the raw data
11019 </p>
11020 <p><var>result</var>: will hold the newly allocated encoded data
11021 </p>
11022 <p>This function will convert the given data to printable data, using
11023 the base64 encoding.  This is the encoding used in PEM messages.
11024 This function will allocate the required memory to hold the encoded
11025 data.
11026 </p>
11027 <p>You should use <code>gnutls_free()</code> to free the returned data.
11028 </p>
11029 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
11030 an error code is returned.
11031 </p></dd></dl>
11032
11033 <a name="gnutls_005fpem_005fbase64_005fencode-1"></a>
11034 <h4 class="subheading">gnutls_pem_base64_encode</h4>
11035 <a name="gnutls_005fpem_005fbase64_005fencode"></a><dl>
11036 <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>
11037 <dd><p><var>msg</var>: is a message to be put in the header
11038 </p>
11039 <p><var>data</var>: contain the raw data
11040 </p>
11041 <p><var>result</var>: the place where base64 data will be copied
11042 </p>
11043 <p><var>result_size</var>: holds the size of the result
11044 </p>
11045 <p>This function will convert the given data to printable data, using
11046 the base64 encoding. This is the encoding used in PEM messages.
11047 </p>
11048 <p>The output string will be null terminated, although the size will
11049 not include the terminating null.
11050 </p>
11051 <p><strong>Returns:</strong> On success <code>GNUTLS_E_SUCCESS</code> (0) is returned,
11052 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> is returned if the buffer given is
11053 not long enough, or 0 on success.
11054 </p></dd></dl>
11055
11056 <a name="gnutls_005fperror-1"></a>
11057 <h4 class="subheading">gnutls_perror</h4>
11058 <a name="gnutls_005fperror"></a><dl>
11059 <dt><a name="index-gnutls_005fperror"></a>Function: <em>void</em> <strong>gnutls_perror</strong> <em>(int <var>error</var>)</em></dt>
11060 <dd><p><var>error</var>: is a GnuTLS error code, a negative value
11061 </p>
11062 <p>This function is like <code>perror()</code>. The only difference is that it
11063 accepts an error number returned by a gnutls function.
11064 </p></dd></dl>
11065
11066 <a name="gnutls_005fpk_005falgorithm_005fget_005fname-1"></a>
11067 <h4 class="subheading">gnutls_pk_algorithm_get_name</h4>
11068 <a name="gnutls_005fpk_005falgorithm_005fget_005fname"></a><dl>
11069 <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>
11070 <dd><p><var>algorithm</var>: is a pk algorithm
11071 </p>
11072 <p>Convert a <code>gnutls_pk_algorithm_t</code> value to a string.
11073 </p>
11074 <p><strong>Returns:</strong> a string that contains the name of the specified public
11075 key algorithm, or <code>NULL</code>.
11076 </p></dd></dl>
11077
11078 <a name="gnutls_005fpk_005fbits_005fto_005fsec_005fparam-1"></a>
11079 <h4 class="subheading">gnutls_pk_bits_to_sec_param</h4>
11080 <a name="gnutls_005fpk_005fbits_005fto_005fsec_005fparam"></a><dl>
11081 <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>
11082 <dd><p><var>algo</var>: is a public key algorithm
11083 </p>
11084 <p><var>bits</var>: is the number of bits
11085 </p>
11086 <p>This is the inverse of <code>gnutls_sec_param_to_pk_bits()</code>. Given an algorithm
11087 and the number of bits, it will return the security parameter. This is
11088 a rough indication.
11089 </p>
11090 <p><strong>Returns:</strong> The security parameter.
11091 </p></dd></dl>
11092
11093 <a name="gnutls_005fpk_005fget_005fid-1"></a>
11094 <h4 class="subheading">gnutls_pk_get_id</h4>
11095 <a name="gnutls_005fpk_005fget_005fid"></a><dl>
11096 <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>
11097 <dd><p><var>name</var>: is a string containing a public key algorithm name.
11098 </p>
11099 <p>Convert a string to a <code>gnutls_pk_algorithm_t</code> value.  The names are
11100 compared in a case insensitive way.  For example,
11101 gnutls_pk_get_id(&quot;RSA&quot;) will return <code>GNUTLS_PK_RSA</code>.
11102 </p>
11103 <p><strong>Returns:</strong> a <code>gnutls_pk_algorithm_t</code> id of the specified public key
11104 algorithm string, or <code>GNUTLS_PK_UNKNOWN</code> on failures.
11105 </p>
11106 <p><strong>Since:</strong> 2.6.0
11107 </p></dd></dl>
11108
11109 <a name="gnutls_005fpk_005fget_005fname-1"></a>
11110 <h4 class="subheading">gnutls_pk_get_name</h4>
11111 <a name="gnutls_005fpk_005fget_005fname"></a><dl>
11112 <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>
11113 <dd><p><var>algorithm</var>: is a public key algorithm
11114 </p>
11115 <p>Convert a <code>gnutls_pk_algorithm_t</code> value to a string.
11116 </p>
11117 <p><strong>Returns:</strong> a pointer to a string that contains the name of the
11118 specified public key algorithm, or <code>NULL</code>.
11119 </p>
11120 <p><strong>Since:</strong> 2.6.0
11121 </p></dd></dl>
11122
11123 <a name="gnutls_005fpk_005flist-1"></a>
11124 <h4 class="subheading">gnutls_pk_list</h4>
11125 <a name="gnutls_005fpk_005flist"></a><dl>
11126 <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>
11127 <dd>
11128 <p>Get a list of supported public key algorithms.
11129 </p>
11130 <p><strong>Returns:</strong> a zero-terminated list of <code>gnutls_pk_algorithm_t</code> integers
11131 indicating the available ciphers.
11132 </p>
11133 <p><strong>Since:</strong> 2.6.0
11134 </p></dd></dl>
11135
11136 <a name="gnutls_005fpkcs11_005fadd_005fprovider-1"></a>
11137 <h4 class="subheading">gnutls_pkcs11_add_provider</h4>
11138 <a name="gnutls_005fpkcs11_005fadd_005fprovider"></a><dl>
11139 <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>
11140 <dd><p><var>name</var>: The filename of the module
11141 </p>
11142 <p><var>params</var>: should be NULL
11143 </p>
11144 <p>This function will load and add a PKCS 11 module to the module
11145 list used in gnutls. After this function is called the module will
11146 be used for PKCS 11 operations.
11147 </p>
11148 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11149 negative error value.
11150 </p></dd></dl>
11151
11152 <a name="gnutls_005fpkcs11_005fcopy_005fsecret_005fkey-1"></a>
11153 <h4 class="subheading">gnutls_pkcs11_copy_secret_key</h4>
11154 <a name="gnutls_005fpkcs11_005fcopy_005fsecret_005fkey"></a><dl>
11155 <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>
11156 <dd><p><var>token_url</var>: A PKCS <code>11</code> URL specifying a token
11157 </p>
11158 <p><var>key</var>: The raw key
11159 </p>
11160 <p><var>label</var>: A name to be used for the stored data
11161 </p>
11162 <p><var>key_usage</var>: One of GNUTLS_KEY_*
11163 </p>
11164 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_FLAG_*
11165 </p>
11166 <p>This function will copy a raw secret (symmetric) key into a PKCS <code>11</code>
11167 token specified by a URL. The key can be marked as sensitive or not.
11168 </p>
11169 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11170 negative error value.
11171 </p></dd></dl>
11172
11173 <a name="gnutls_005fpkcs11_005fcopy_005fx509_005fcrt-1"></a>
11174 <h4 class="subheading">gnutls_pkcs11_copy_x509_crt</h4>
11175 <a name="gnutls_005fpkcs11_005fcopy_005fx509_005fcrt"></a><dl>
11176 <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>
11177 <dd><p><var>token_url</var>: A PKCS <code>11</code> URL specifying a token
11178 </p>
11179 <p><var>crt</var>: A certificate
11180 </p>
11181 <p><var>label</var>: A name to be used for the stored data
11182 </p>
11183 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_FLAG_*
11184 </p>
11185 <p>This function will copy a certificate into a PKCS <code>11</code> token specified by
11186 a URL. The certificate can be marked as trusted or not.
11187 </p>
11188 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11189 negative error value.
11190 </p></dd></dl>
11191
11192 <a name="gnutls_005fpkcs11_005fcopy_005fx509_005fprivkey-1"></a>
11193 <h4 class="subheading">gnutls_pkcs11_copy_x509_privkey</h4>
11194 <a name="gnutls_005fpkcs11_005fcopy_005fx509_005fprivkey"></a><dl>
11195 <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>
11196 <dd><p><var>token_url</var>: A PKCS <code>11</code> URL specifying a token
11197 </p>
11198 <p><var>key</var>: A private key
11199 </p>
11200 <p><var>label</var>: A name to be used for the stored data
11201 </p>
11202 <p><var>key_usage</var>: One of GNUTLS_KEY_*
11203 </p>
11204 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
11205 </p>
11206 <p>This function will copy a private key into a PKCS <code>11</code> token specified by
11207 a URL. It is highly recommended flags to contain <code>GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE</code>
11208 unless there is a strong reason not to.
11209 </p>
11210 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11211 negative error value.
11212 </p></dd></dl>
11213
11214 <a name="gnutls_005fpkcs11_005fdeinit-1"></a>
11215 <h4 class="subheading">gnutls_pkcs11_deinit</h4>
11216 <a name="gnutls_005fpkcs11_005fdeinit"></a><dl>
11217 <dt><a name="index-gnutls_005fpkcs11_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_pkcs11_deinit</strong> <em>( <var>void</var>)</em></dt>
11218 <dd>
11219 <p>This function will deinitialize the PKCS 11 subsystem in gnutls.
11220 </p></dd></dl>
11221
11222 <a name="gnutls_005fpkcs11_005fdelete_005furl-1"></a>
11223 <h4 class="subheading">gnutls_pkcs11_delete_url</h4>
11224 <a name="gnutls_005fpkcs11_005fdelete_005furl"></a><dl>
11225 <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>
11226 <dd><p><var>object_url</var>: The URL of the object to delete.
11227 </p>
11228 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
11229 </p>
11230 <p>This function will delete objects matching the given URL.
11231 </p>
11232 <p><strong>Returns:</strong> On success, the number of objects deleted is returned, otherwise a
11233 negative error value.
11234 </p></dd></dl>
11235
11236 <a name="gnutls_005fpkcs11_005finit-1"></a>
11237 <h4 class="subheading">gnutls_pkcs11_init</h4>
11238 <a name="gnutls_005fpkcs11_005finit"></a><dl>
11239 <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>
11240 <dd><p><var>flags</var>: <code>GNUTLS_PKCS11_FLAG_MANUAL</code> or <code>GNUTLS_PKCS11_FLAG_AUTO</code>
11241 </p>
11242 <p><var>deprecated_config_file</var>: either NULL or the location of a deprecated
11243 configuration file
11244 </p>
11245 <p>This function will initialize the PKCS 11 subsystem in gnutls. It will
11246 read configuration files if <code>GNUTLS_PKCS11_FLAG_AUTO</code> is used or allow
11247 you to independently load PKCS 11 modules using <code>gnutls_pkcs11_add_provider()</code>
11248 if <code>GNUTLS_PKCS11_FLAG_MANUAL</code> is specified.
11249 </p>
11250 <p>Using a custom configfile is deprecated and will not be supported in future
11251 versions of gnutls.
11252 </p>
11253 <p>Normally you don&rsquo;t need to call this function since it is being called
11254 by <code>gnutls_global_init()</code> using the <code>GNUTLS_PKCS11_FLAG_AUTO</code>. If you need to
11255 call this function, you must call it before <code>gnutls_global_init()</code>.
11256 </p>
11257 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11258 negative error value.
11259 </p></dd></dl>
11260
11261 <a name="gnutls_005fpkcs11_005fobj_005fdeinit-1"></a>
11262 <h4 class="subheading">gnutls_pkcs11_obj_deinit</h4>
11263 <a name="gnutls_005fpkcs11_005fobj_005fdeinit"></a><dl>
11264 <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>
11265 <dd><p><var>obj</var>: The structure to be initialized
11266 </p>
11267 <p>This function will deinitialize a certificate structure.
11268 </p></dd></dl>
11269
11270 <a name="gnutls_005fpkcs11_005fobj_005fexport_005furl-1"></a>
11271 <h4 class="subheading">gnutls_pkcs11_obj_export_url</h4>
11272 <a name="gnutls_005fpkcs11_005fobj_005fexport_005furl"></a><dl>
11273 <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>
11274 <dd><p><var>obj</var>: Holds the PKCS 11 certificate
11275 </p>
11276 <p><var>detailed</var>: non zero if a detailed URL is required
11277 </p>
11278 <p><var>url</var>: will contain an allocated url
11279 </p>
11280 <p>This function will export a URL identifying the given certificate.
11281 </p>
11282 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11283 negative error value.
11284 </p></dd></dl>
11285
11286 <a name="gnutls_005fpkcs11_005fobj_005fexport-1"></a>
11287 <h4 class="subheading">gnutls_pkcs11_obj_export</h4>
11288 <a name="gnutls_005fpkcs11_005fobj_005fexport"></a><dl>
11289 <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>
11290 <dd><p><var>obj</var>: Holds the object
11291 </p>
11292 <p><var>output_data</var>: will contain a certificate PEM or DER encoded
11293 </p>
11294 <p><var>output_data_size</var>: holds the size of output_data (and will be
11295 replaced by the actual size of parameters)
11296 </p>
11297 <p>This function will export the pkcs11 object data. It is normal
11298 for PKCS <code>11</code> data to be inaccesible and in that case <code>GNUTLS_E_INVALID_REQUEST</code>
11299 will be returned.
11300 </p>
11301 <p>If the buffer provided is not long enough to hold the output, then
11302 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
11303 be returned.
11304 </p>
11305 <p>If the structure is PEM encoded, it will have a header
11306 of &quot;BEGIN CERTIFICATE&quot;.
11307 </p>
11308 <p><strong>Return value:</strong> In case of failure a negative value will be
11309 returned, and 0 on success.
11310 </p></dd></dl>
11311
11312 <a name="gnutls_005fpkcs11_005fobj_005fget_005finfo-1"></a>
11313 <h4 class="subheading">gnutls_pkcs11_obj_get_info</h4>
11314 <a name="gnutls_005fpkcs11_005fobj_005fget_005finfo"></a><dl>
11315 <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>crt</var>, gnutls_pkcs11_obj_info_t <var>itype</var>, void * <var>output</var>, size_t * <var>output_size</var>)</em></dt>
11316 <dd><p><var>crt</var>: should contain a <code>gnutls_pkcs11_obj_t</code> structure
11317 </p>
11318 <p><var>itype</var>: Denotes the type of information requested
11319 </p>
11320 <p><var>output</var>: where output will be stored
11321 </p>
11322 <p><var>output_size</var>: contains the maximum size of the output and will be overwritten with actual
11323 </p>
11324 <p>This function will return information about the PKCS 11 certificatesuch
11325 as the label, id as well as token information where the key is stored. When
11326 output is text it returns null terminated string although <code>output_size</code> contains
11327 the size of the actual data only.
11328 </p>
11329 <p><strong>Returns:</strong> zero on success or a negative value on error.
11330 </p></dd></dl>
11331
11332 <a name="gnutls_005fpkcs11_005fobj_005fget_005ftype-1"></a>
11333 <h4 class="subheading">gnutls_pkcs11_obj_get_type</h4>
11334 <a name="gnutls_005fpkcs11_005fobj_005fget_005ftype"></a><dl>
11335 <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>
11336 <dd><p>This function will return the type of the certificate being
11337 stored in the structure.
11338 </p>
11339 <p><strong>Returns:</strong> The type of the certificate.
11340 </p></dd></dl>
11341
11342 <a name="gnutls_005fpkcs11_005fobj_005fimport_005furl-1"></a>
11343 <h4 class="subheading">gnutls_pkcs11_obj_import_url</h4>
11344 <a name="gnutls_005fpkcs11_005fobj_005fimport_005furl"></a><dl>
11345 <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>cert</var>, const char * <var>url</var>, unsigned int <var>flags</var>)</em></dt>
11346 <dd><p><var>cert</var>: The structure to store the parsed certificate
11347 </p>
11348 <p><var>url</var>: a PKCS 11 url identifying the key
11349 </p>
11350 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
11351 </p>
11352 <p>This function will &quot;import&quot; a PKCS 11 URL identifying a certificate
11353 key to the <code>gnutls_pkcs11_obj_t</code> structure. This does not involve any
11354 parsing (such as X.509 or OpenPGP) since the <code>gnutls_pkcs11_obj_t</code> is
11355 format agnostic. Only data are transferred.
11356 </p>
11357 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11358 negative error value.
11359 </p></dd></dl>
11360
11361 <a name="gnutls_005fpkcs11_005fobj_005finit-1"></a>
11362 <h4 class="subheading">gnutls_pkcs11_obj_init</h4>
11363 <a name="gnutls_005fpkcs11_005fobj_005finit"></a><dl>
11364 <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>
11365 <dd><p><var>obj</var>: The structure to be initialized
11366 </p>
11367 <p>This function will initialize a pkcs11 certificate structure.
11368 </p>
11369 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11370 negative error value.
11371 </p></dd></dl>
11372
11373 <a name="gnutls_005fpkcs11_005fobj_005flist_005fimport_005furl-1"></a>
11374 <h4 class="subheading">gnutls_pkcs11_obj_list_import_url</h4>
11375 <a name="gnutls_005fpkcs11_005fobj_005flist_005fimport_005furl"></a><dl>
11376 <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>
11377 <dd><p><var>p_list</var>: An uninitialized object list (may be NULL)
11378 </p>
11379 <p><var>n_list</var>: initially should hold the maximum size of the list. Will contain the actual size.
11380 </p>
11381 <p><var>url</var>: A PKCS 11 url identifying a set of objects
11382 </p>
11383 <p><var>attrs</var>: Attributes of type <code>gnutls_pkcs11_obj_attr_t</code> that can be used to limit output
11384 </p>
11385 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
11386 </p>
11387 <p>This function will initialize and set values to an object list
11388 by using all objects identified by a PKCS 11 URL.
11389 </p>
11390 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11391 negative error value.
11392 </p></dd></dl>
11393
11394 <a name="gnutls_005fpkcs11_005fprivkey_005fdeinit-1"></a>
11395 <h4 class="subheading">gnutls_pkcs11_privkey_deinit</h4>
11396 <a name="gnutls_005fpkcs11_005fprivkey_005fdeinit"></a><dl>
11397 <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>
11398 <dd><p><var>key</var>: The structure to be initialized
11399 </p>
11400 <p>This function will deinitialize a private key structure.
11401 </p></dd></dl>
11402
11403 <a name="gnutls_005fpkcs11_005fprivkey_005fexport_005furl-1"></a>
11404 <h4 class="subheading">gnutls_pkcs11_privkey_export_url</h4>
11405 <a name="gnutls_005fpkcs11_005fprivkey_005fexport_005furl"></a><dl>
11406 <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>
11407 <dd><p><var>key</var>: Holds the PKCS 11 key
11408 </p>
11409 <p><var>detailed</var>: non zero if a detailed URL is required
11410 </p>
11411 <p><var>url</var>: will contain an allocated url
11412 </p>
11413 <p>This function will export a URL identifying the given key.
11414 </p>
11415 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11416 negative error value.
11417 </p></dd></dl>
11418
11419 <a name="gnutls_005fpkcs11_005fprivkey_005fget_005finfo-1"></a>
11420 <h4 class="subheading">gnutls_pkcs11_privkey_get_info</h4>
11421 <a name="gnutls_005fpkcs11_005fprivkey_005fget_005finfo"></a><dl>
11422 <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>
11423 <dd><p><var>pkey</var>: should contain a <code>gnutls_pkcs11_privkey_t</code> structure
11424 </p>
11425 <p><var>itype</var>: Denotes the type of information requested
11426 </p>
11427 <p><var>output</var>: where output will be stored
11428 </p>
11429 <p><var>output_size</var>: contains the maximum size of the output and will be overwritten with actual
11430 </p>
11431 <p>This function will return information about the PKCS 11 private key such
11432 as the label, id as well as token information where the key is stored. When
11433 output is text it returns null terminated string although <code>output_size</code> contains
11434 the size of the actual data only.
11435 </p>
11436 <p><strong>Returns:</strong> zero on success or a negative value on error.
11437 </p></dd></dl>
11438
11439 <a name="gnutls_005fpkcs11_005fprivkey_005fget_005fpk_005falgorithm-1"></a>
11440 <h4 class="subheading">gnutls_pkcs11_privkey_get_pk_algorithm</h4>
11441 <a name="gnutls_005fpkcs11_005fprivkey_005fget_005fpk_005falgorithm"></a><dl>
11442 <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>
11443 <dd><p><var>key</var>: should contain a <code>gnutls_pkcs11_privkey_t</code> structure
11444 </p>
11445 <p>This function will return the public key algorithm of a private
11446 key.
11447 </p>
11448 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code> enumeration on
11449 success, or a negative value on error.
11450 </p></dd></dl>
11451
11452 <a name="gnutls_005fpkcs11_005fprivkey_005fimport_005furl-1"></a>
11453 <h4 class="subheading">gnutls_pkcs11_privkey_import_url</h4>
11454 <a name="gnutls_005fpkcs11_005fprivkey_005fimport_005furl"></a><dl>
11455 <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>
11456 <dd><p><var>pkey</var>: The structure to store the parsed key
11457 </p>
11458 <p><var>url</var>: a PKCS 11 url identifying the key
11459 </p>
11460 <p><var>flags</var>: sequence of GNUTLS_PKCS_PRIVKEY_*
11461 </p>
11462 <p>This function will &quot;import&quot; a PKCS 11 URL identifying a private
11463 key to the <code>gnutls_pkcs11_privkey_t</code> structure. In reality since
11464 in most cases keys cannot be exported, the private key structure
11465 is being associated with the available operations on the token.
11466 </p>
11467 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11468 negative error value.
11469 </p></dd></dl>
11470
11471 <a name="gnutls_005fpkcs11_005fprivkey_005finit-1"></a>
11472 <h4 class="subheading">gnutls_pkcs11_privkey_init</h4>
11473 <a name="gnutls_005fpkcs11_005fprivkey_005finit"></a><dl>
11474 <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>
11475 <dd><p><var>key</var>: The structure to be initialized
11476 </p>
11477 <p>This function will initialize an private key structure.
11478 </p>
11479 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11480 negative error value.
11481 </p></dd></dl>
11482
11483 <a name="gnutls_005fpkcs11_005freinit-1"></a>
11484 <h4 class="subheading">gnutls_pkcs11_reinit</h4>
11485 <a name="gnutls_005fpkcs11_005freinit"></a><dl>
11486 <dt><a name="index-gnutls_005fpkcs11_005freinit"></a>Function: <em>int</em> <strong>gnutls_pkcs11_reinit</strong> <em>( <var>void</var>)</em></dt>
11487 <dd>
11488 <p>This function will reinitialize the PKCS 11 subsystem in gnutls.
11489 This is required by PKCS 11 when an application uses <code>fork()</code>. The
11490 reinitialization function must be called on the child.
11491 </p>
11492 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise a
11493 negative error value.
11494 </p>
11495 <p><strong>Since:</strong> 3.0.0
11496 </p></dd></dl>
11497
11498 <a name="gnutls_005fpkcs11_005fset_005fpin_005ffunction-1"></a>
11499 <h4 class="subheading">gnutls_pkcs11_set_pin_function</h4>
11500 <a name="gnutls_005fpkcs11_005fset_005fpin_005ffunction"></a><dl>
11501 <dt><a name="index-gnutls_005fpkcs11_005fset_005fpin_005ffunction"></a>Function: <em>void</em> <strong>gnutls_pkcs11_set_pin_function</strong> <em>(gnutls_pkcs11_pin_callback_t <var>fn</var>, void * <var>userdata</var>)</em></dt>
11502 <dd><p><var>fn</var>: The PIN callback
11503 </p>
11504 <p><var>userdata</var>: data to be supplied to callback
11505 </p>
11506 <p>This function will set a callback function to be used when a PIN
11507 is required for PKCS 11 operations.
11508 </p>
11509 <p>Callback for PKCS<code>11</code> PIN entry.  The callback provides the PIN code
11510 to unlock the token with label &rsquo;token_label&rsquo;, specified by the URL
11511 &rsquo;token_url&rsquo;.
11512 </p>
11513 <p>The PIN code, as a NUL-terminated ASCII string, should be copied
11514 into the &rsquo;pin&rsquo; buffer (of maximum size pin_max), and
11515 return 0 to indicate success. Alternatively, the callback may
11516 return a negative gnutls error code to indicate failure and cancel
11517 PIN entry (in which case, the contents of the &rsquo;pin&rsquo; parameter are ignored).
11518 </p>
11519 <p>When a PIN is required, the callback will be invoked repeatedly
11520 (and indefinitely) until either the returned PIN code is correct,
11521 the callback returns failure, or the token refuses login (e.g. when
11522 the token is locked due to too many incorrect PINs!).  For the
11523 first such invocation, the &rsquo;attempt&rsquo; counter will have value zero;
11524 it will increase by one for each subsequent attempt.
11525 </p>
11526 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11527 negative error value.
11528 </p></dd></dl>
11529
11530 <a name="gnutls_005fpkcs11_005fset_005ftoken_005ffunction-1"></a>
11531 <h4 class="subheading">gnutls_pkcs11_set_token_function</h4>
11532 <a name="gnutls_005fpkcs11_005fset_005ftoken_005ffunction"></a><dl>
11533 <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>
11534 <dd><p><var>fn</var>: The token callback
11535 </p>
11536 <p><var>userdata</var>: data to be supplied to callback
11537 </p>
11538 <p>This function will set a callback function to be used when a token
11539 needs to be inserted to continue PKCS 11 operations.
11540 </p>
11541 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11542 negative error value.
11543 </p></dd></dl>
11544
11545 <a name="gnutls_005fpkcs11_005ftoken_005fget_005fflags-1"></a>
11546 <h4 class="subheading">gnutls_pkcs11_token_get_flags</h4>
11547 <a name="gnutls_005fpkcs11_005ftoken_005fget_005fflags"></a><dl>
11548 <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>
11549 <dd><p><var>url</var>: should contain a PKCS 11 URL
11550 </p>
11551 <p><var>flags</var>: The output flags (GNUTLS_PKCS11_TOKEN_*)
11552 </p>
11553 <p>This function will return information about the PKCS 11 token flags.
11554 </p>
11555 <p><strong>Returns:</strong> zero on success or a negative value on error.
11556 </p></dd></dl>
11557
11558 <a name="gnutls_005fpkcs11_005ftoken_005fget_005finfo-1"></a>
11559 <h4 class="subheading">gnutls_pkcs11_token_get_info</h4>
11560 <a name="gnutls_005fpkcs11_005ftoken_005fget_005finfo"></a><dl>
11561 <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>
11562 <dd><p><var>url</var>: should contain a PKCS 11 URL
11563 </p>
11564 <p><var>ttype</var>: Denotes the type of information requested
11565 </p>
11566 <p><var>output</var>: where output will be stored
11567 </p>
11568 <p><var>output_size</var>: contains the maximum size of the output and will be overwritten with actual
11569 </p>
11570 <p>This function will return information about the PKCS 11 token such
11571 as the label, id as well as token information where the key is stored.
11572 </p>
11573 <p><strong>Returns:</strong> zero on success or a negative value on error.
11574 </p></dd></dl>
11575
11576 <a name="gnutls_005fpkcs11_005ftoken_005fget_005fmechanism-1"></a>
11577 <h4 class="subheading">gnutls_pkcs11_token_get_mechanism</h4>
11578 <a name="gnutls_005fpkcs11_005ftoken_005fget_005fmechanism"></a><dl>
11579 <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>, int <var>idx</var>, unsigned long * <var>mechanism</var>)</em></dt>
11580 <dd><p><var>url</var>: should contain a PKCS 11 URL
11581 </p>
11582 <p><var>idx</var>: The index of the mechanism
11583 </p>
11584 <p><var>mechanism</var>: The PKCS <code>11</code> mechanism ID
11585 </p>
11586 <p>This function will return the names of the supported mechanisms
11587 by the token. It should be called with an increasing index until
11588 it return GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE.
11589 </p>
11590 <p><strong>Returns:</strong> zero on success or a negative value on error.
11591 </p></dd></dl>
11592
11593 <a name="gnutls_005fpkcs11_005ftoken_005fget_005furl-1"></a>
11594 <h4 class="subheading">gnutls_pkcs11_token_get_url</h4>
11595 <a name="gnutls_005fpkcs11_005ftoken_005fget_005furl"></a><dl>
11596 <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>
11597 <dd><p><var>seq</var>: sequence number starting from 0
11598 </p>
11599 <p><var>detailed</var>: non zero if a detailed URL is required
11600 </p>
11601 <p><var>url</var>: will contain an allocated url
11602 </p>
11603 <p>This function will return the URL for each token available
11604 in system. The url has to be released using <code>gnutls_free()</code>
11605 </p>
11606 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
11607 if the sequence number exceeds the available tokens, otherwise a negative error value.
11608 </p></dd></dl>
11609
11610 <a name="gnutls_005fpkcs11_005ftoken_005finit-1"></a>
11611 <h4 class="subheading">gnutls_pkcs11_token_init</h4>
11612 <a name="gnutls_005fpkcs11_005ftoken_005finit"></a><dl>
11613 <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>
11614 <dd><p><var>token_url</var>: A PKCS <code>11</code> URL specifying a token
11615 </p>
11616 <p><var>so_pin</var>: Security Officer&rsquo;s PIN
11617 </p>
11618 <p><var>label</var>: A name to be used for the token
11619 </p>
11620 <p>This function will initialize (format) a token. If the token is
11621 at a factory defaults state the security officer&rsquo;s PIN given will be
11622 set to be the default. Otherwise it should match the officer&rsquo;s PIN.
11623 </p>
11624 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11625 negative error value.
11626 </p></dd></dl>
11627
11628 <a name="gnutls_005fpkcs11_005ftoken_005fset_005fpin-1"></a>
11629 <h4 class="subheading">gnutls_pkcs11_token_set_pin</h4>
11630 <a name="gnutls_005fpkcs11_005ftoken_005fset_005fpin"></a><dl>
11631 <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>
11632 <dd><p><var>token_url</var>: A PKCS <code>11</code> URL specifying a token
11633 </p>
11634 <p><var>oldpin</var>: old user&rsquo;s PIN
11635 </p>
11636 <p><var>newpin</var>: new user&rsquo;s PIN
11637 </p>
11638 <p><var>flags</var>: one of gnutls_pkcs11_pin_flag_t
11639 </p>
11640 <p>This function will modify or set a user&rsquo;s PIN for the given token.
11641 If it is called to set a user pin for first time the oldpin must
11642 be NULL.
11643 </p>
11644 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11645 negative error value.
11646 </p></dd></dl>
11647
11648 <a name="gnutls_005fprf_005fraw-1"></a>
11649 <h4 class="subheading">gnutls_prf_raw</h4>
11650 <a name="gnutls_005fprf_005fraw"></a><dl>
11651 <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>
11652 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
11653 </p>
11654 <p><var>label_size</var>: length of the <code>label</code> variable.
11655 </p>
11656 <p><var>label</var>: label used in PRF computation, typically a short string.
11657 </p>
11658 <p><var>seed_size</var>: length of the <code>seed</code> variable.
11659 </p>
11660 <p><var>seed</var>: optional extra data to seed the PRF with.
11661 </p>
11662 <p><var>outsize</var>: size of pre-allocated output buffer to hold the output.
11663 </p>
11664 <p><var>out</var>: pre-allocate buffer to hold the generated data.
11665 </p>
11666 <p>Apply the TLS Pseudo-Random-Function (PRF) using the master secret
11667 on some data.
11668 </p>
11669 <p>The <code>label</code> variable usually contain a string denoting the purpose
11670 for the generated data.  The <code>seed</code> usually contain data such as the
11671 client and server random, perhaps together with some additional
11672 data that is added to guarantee uniqueness of the output for a
11673 particular purpose.
11674 </p>
11675 <p>Because the output is not guaranteed to be unique for a particular
11676 session unless <code>seed</code> include the client random and server random
11677 fields (the PRF would output the same data on another connection
11678 resumed from the first one), it is not recommended to use this
11679 function directly.  The <code>gnutls_prf()</code> function seed the PRF with the
11680 client and server random fields directly, and is recommended if you
11681 want to generate pseudo random data unique for each session.
11682 </p>
11683 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
11684 </p></dd></dl>
11685
11686 <a name="gnutls_005fprf-1"></a>
11687 <h4 class="subheading">gnutls_prf</h4>
11688 <a name="gnutls_005fprf"></a><dl>
11689 <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>
11690 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
11691 </p>
11692 <p><var>label_size</var>: length of the <code>label</code> variable.
11693 </p>
11694 <p><var>label</var>: label used in PRF computation, typically a short string.
11695 </p>
11696 <p><var>server_random_first</var>: non-0 if server random field should be first in seed
11697 </p>
11698 <p><var>extra_size</var>: length of the <code>extra</code> variable.
11699 </p>
11700 <p><var>extra</var>: optional extra data to seed the PRF with.
11701 </p>
11702 <p><var>outsize</var>: size of pre-allocated output buffer to hold the output.
11703 </p>
11704 <p><var>out</var>: pre-allocate buffer to hold the generated data.
11705 </p>
11706 <p>Apply the TLS Pseudo-Random-Function (PRF) using the master secret
11707 on some data, seeded with the client and server random fields.
11708 </p>
11709 <p>The <code>label</code> variable usually contain a string denoting the purpose
11710 for the generated data.  The <code>server_random_first</code> indicate whether
11711 the client random field or the server random field should be first
11712 in the seed.  Non-0 indicate that the server random field is first,
11713 0 that the client random field is first.
11714 </p>
11715 <p>The <code>extra</code> variable can be used to add more data to the seed, after
11716 the random variables.  It can be used to tie make sure the
11717 generated output is strongly connected to some additional data
11718 (e.g., a string used in user authentication).
11719 </p>
11720 <p>The output is placed in *<code>OUT</code>, which must be pre-allocated.
11721 </p>
11722 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
11723 </p></dd></dl>
11724
11725 <a name="gnutls_005fpriority_005fdeinit-1"></a>
11726 <h4 class="subheading">gnutls_priority_deinit</h4>
11727 <a name="gnutls_005fpriority_005fdeinit"></a><dl>
11728 <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>
11729 <dd><p><var>priority_cache</var>: is a <code>gnutls_prioritity_t</code> structure.
11730 </p>
11731 <p>Deinitializes the priority cache.
11732 </p></dd></dl>
11733
11734 <a name="gnutls_005fpriority_005finit-1"></a>
11735 <h4 class="subheading">gnutls_priority_init</h4>
11736 <a name="gnutls_005fpriority_005finit"></a><dl>
11737 <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>
11738 <dd><p><var>priority_cache</var>: is a <code>gnutls_prioritity_t</code> structure.
11739 </p>
11740 <p><var>priorities</var>: is a string describing priorities
11741 </p>
11742 <p><var>err_pos</var>: In case of an error this will have the position in the string the error occured
11743 </p>
11744 <p>Sets priorities for the ciphers, key exchange methods, macs and
11745 compression methods.
11746 </p>
11747 <p>The <code>priorities</code> option allows you to specify a colon
11748 separated list of the cipher priorities to enable.
11749 </p>
11750 <p><strong>Common keywords:</strong> Some keywords are defined to provide quick access
11751 to common preferences.
11752 </p>
11753 <p>&quot;PERFORMANCE&quot; means all the &quot;secure&quot; ciphersuites are enabled,
11754 limited to 128 bit ciphers and sorted by terms of speed
11755 performance.
11756 </p>
11757 <p>&quot;NORMAL&quot; means all &quot;secure&quot; ciphersuites. The 256-bit ciphers are
11758 included as a fallback only.  The ciphers are sorted by security
11759 margin.
11760 </p>
11761 <p>&quot;SECURE128&quot; means all &quot;secure&quot; ciphersuites with ciphers up to 128
11762 bits, sorted by security margin.
11763 </p>
11764 <p>&quot;SECURE256&quot; means all &quot;secure&quot; ciphersuites including the 256 bit
11765 ciphers, sorted by security margin.
11766 </p>
11767 <p>&quot;EXPORT&quot; means all ciphersuites are enabled, including the
11768 low-security 40 bit ciphers.
11769 </p>
11770 <p>&quot;NONE&quot; means nothing is enabled.  This disables even protocols and
11771 compression methods.
11772 </p>
11773 <p><strong>Special keywords:</strong> &quot;!&quot; or &quot;-&quot; appended with an algorithm will remove this algorithm.
11774 </p>
11775 <p>&quot;+&quot; appended with an algorithm will add this algorithm.
11776 </p>
11777 <p>Check the GnuTLS manual section &quot;Priority strings&quot; for detailed
11778 information.
11779 </p>
11780 <p><strong>Examples:</strong>
11781 &quot;NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL&quot;
11782 </p>
11783 <p>&quot;NORMAL:-ARCFOUR-128&quot; means normal ciphers except for ARCFOUR-128.
11784 </p>
11785 <p>&quot;SECURE:-VERS-SSL3.0:+COMP-DEFLATE&quot; means that only secure ciphers are
11786 enabled, SSL3.0 is disabled, and libz compression enabled.
11787 </p>
11788 <p>&quot;NONE:+VERS-TLS-ALL:+AES-128-CBC:+RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1&quot;,
11789 </p>
11790 <p>&quot;NORMAL:<code>COMPAT</code>&quot; is the most compatible mode.
11791 </p>
11792 <p><strong>Returns:</strong> On syntax error <code>GNUTLS_E_INVALID_REQUEST</code> is returned,
11793 <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
11794 </p></dd></dl>
11795
11796 <a name="gnutls_005fpriority_005fset_005fdirect-1"></a>
11797 <h4 class="subheading">gnutls_priority_set_direct</h4>
11798 <a name="gnutls_005fpriority_005fset_005fdirect"></a><dl>
11799 <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>
11800 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
11801 </p>
11802 <p><var>priorities</var>: is a string describing priorities
11803 </p>
11804 <p><var>err_pos</var>: In case of an error this will have the position in the string the error occured
11805 </p>
11806 <p>Sets the priorities to use on the ciphers, key exchange methods,
11807 macs and compression methods.  This function avoids keeping a
11808 priority cache and is used to directly set string priorities to a
11809 TLS session.  For documentation check the <code>gnutls_priority_init()</code>.
11810 </p>
11811 <p><strong>Returns:</strong> On syntax error <code>GNUTLS_E_INVALID_REQUEST</code> is returned,
11812 <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
11813 </p></dd></dl>
11814
11815 <a name="gnutls_005fpriority_005fset-1"></a>
11816 <h4 class="subheading">gnutls_priority_set</h4>
11817 <a name="gnutls_005fpriority_005fset"></a><dl>
11818 <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>
11819 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
11820 </p>
11821 <p><var>priority</var>: is a <code>gnutls_priority_t</code> structure.
11822 </p>
11823 <p>Sets the priorities to use on the ciphers, key exchange methods,
11824 macs and compression methods.
11825 </p>
11826 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
11827 </p></dd></dl>
11828
11829 <a name="gnutls_005fprivkey_005fdecrypt_005fdata-1"></a>
11830 <h4 class="subheading">gnutls_privkey_decrypt_data</h4>
11831 <a name="gnutls_005fprivkey_005fdecrypt_005fdata"></a><dl>
11832 <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>
11833 <dd><p><var>key</var>: Holds the key
11834 </p>
11835 <p><var>flags</var>: zero for now
11836 </p>
11837 <p><var>ciphertext</var>: holds the data to be decrypted
11838 </p>
11839 <p><var>plaintext</var>: will contain the decrypted data, allocated with <code>gnutls_malloc()</code>
11840 </p>
11841 <p>This function will decrypt the given data using the algorithm
11842 supported by the private key.
11843 </p>
11844 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11845 negative error value.
11846 </p></dd></dl>
11847
11848 <a name="gnutls_005fprivkey_005fdeinit-1"></a>
11849 <h4 class="subheading">gnutls_privkey_deinit</h4>
11850 <a name="gnutls_005fprivkey_005fdeinit"></a><dl>
11851 <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>
11852 <dd><p><var>key</var>: The structure to be deinitialized
11853 </p>
11854 <p>This function will deinitialize a private key structure.
11855 </p></dd></dl>
11856
11857 <a name="gnutls_005fprivkey_005fget_005fpk_005falgorithm-1"></a>
11858 <h4 class="subheading">gnutls_privkey_get_pk_algorithm</h4>
11859 <a name="gnutls_005fprivkey_005fget_005fpk_005falgorithm"></a><dl>
11860 <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>
11861 <dd><p><var>key</var>: should contain a <code>gnutls_privkey_t</code> structure
11862 </p>
11863 <p><var>bits</var>: If set will return the number of bits of the parameters (may be NULL)
11864 </p>
11865 <p>This function will return the public key algorithm of a private
11866 key and if possible will return a number of bits that indicates
11867 the security parameter of the key.
11868 </p>
11869 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code> enumeration on
11870 success, or a negative value on error.
11871 </p></dd></dl>
11872
11873 <a name="gnutls_005fprivkey_005fget_005ftype-1"></a>
11874 <h4 class="subheading">gnutls_privkey_get_type</h4>
11875 <a name="gnutls_005fprivkey_005fget_005ftype"></a><dl>
11876 <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>
11877 <dd><p><var>key</var>: should contain a <code>gnutls_privkey_t</code> structure
11878 </p>
11879 <p>This function will return the type of the private key. This is
11880 actually the type of the subsystem used to set this private key.
11881 </p>
11882 <p><strong>Returns:</strong> a member of the <code>gnutls_privkey_type_t</code> enumeration on
11883 success, or a negative value on error.
11884 </p></dd></dl>
11885
11886 <a name="gnutls_005fprivkey_005fimport_005fopenpgp-1"></a>
11887 <h4 class="subheading">gnutls_privkey_import_openpgp</h4>
11888 <a name="gnutls_005fprivkey_005fimport_005fopenpgp"></a><dl>
11889 <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>
11890 <dd><p><var>pkey</var>: The private key
11891 </p>
11892 <p><var>key</var>: The private key to be imported
11893 </p>
11894 <p><var>flags</var>: should be zero
11895 </p>
11896 <p>This function will import the given private key to the abstract
11897 <code>gnutls_privkey_t</code> structure.
11898 </p>
11899 <p>The <code>gnutls_openpgp_privkey_t</code> object must not be deallocated
11900 during the lifetime of this structure. The subkey set as
11901 preferred will be used, or the master key otherwise.
11902 </p>
11903 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11904 negative error value.
11905 </p></dd></dl>
11906
11907 <a name="gnutls_005fprivkey_005fimport_005fpkcs11-1"></a>
11908 <h4 class="subheading">gnutls_privkey_import_pkcs11</h4>
11909 <a name="gnutls_005fprivkey_005fimport_005fpkcs11"></a><dl>
11910 <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>
11911 <dd><p><var>pkey</var>: The private key
11912 </p>
11913 <p><var>key</var>: The private key to be imported
11914 </p>
11915 <p><var>flags</var>: should be zero
11916 </p>
11917 <p>This function will import the given private key to the abstract
11918 <code>gnutls_privkey_t</code> structure.
11919 </p>
11920 <p>The <code>gnutls_pkcs11_privkey_t</code> object must not be deallocated
11921 during the lifetime of this structure.
11922 </p>
11923 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11924 negative error value.
11925 </p></dd></dl>
11926
11927 <a name="gnutls_005fprivkey_005fimport_005fx509-1"></a>
11928 <h4 class="subheading">gnutls_privkey_import_x509</h4>
11929 <a name="gnutls_005fprivkey_005fimport_005fx509"></a><dl>
11930 <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>
11931 <dd><p><var>pkey</var>: The private key
11932 </p>
11933 <p><var>key</var>: The private key to be imported
11934 </p>
11935 <p><var>flags</var>: should be zero
11936 </p>
11937 <p>This function will import the given private key to the abstract
11938 <code>gnutls_privkey_t</code> structure.
11939 </p>
11940 <p>The <code>gnutls_x509_privkey_t</code> object must not be deallocated
11941 during the lifetime of this structure.
11942 </p>
11943 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11944 negative error value.
11945 </p></dd></dl>
11946
11947 <a name="gnutls_005fprivkey_005finit-1"></a>
11948 <h4 class="subheading">gnutls_privkey_init</h4>
11949 <a name="gnutls_005fprivkey_005finit"></a><dl>
11950 <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>
11951 <dd><p><var>key</var>: The structure to be initialized
11952 </p>
11953 <p>This function will initialize an private key structure.
11954 </p>
11955 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11956 negative error value.
11957 </p></dd></dl>
11958
11959 <a name="gnutls_005fprivkey_005fsign_005fdata-1"></a>
11960 <h4 class="subheading">gnutls_privkey_sign_data</h4>
11961 <a name="gnutls_005fprivkey_005fsign_005fdata"></a><dl>
11962 <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>
11963 <dd><p><var>signer</var>: Holds the key
11964 </p>
11965 <p><var>hash</var>: should be a digest algorithm
11966 </p>
11967 <p><var>flags</var>: should be 0 for now
11968 </p>
11969 <p><var>data</var>: holds the data to be signed
11970 </p>
11971 <p><var>signature</var>: will contain the signature allocate with <code>gnutls_malloc()</code>
11972 </p>
11973 <p>This function will sign the given data using a signature algorithm
11974 supported by the private key. Signature algorithms are always used
11975 together with a hash functions.  Different hash functions may be
11976 used for the RSA algorithm, but only SHA-1 for the DSA keys.
11977 </p>
11978 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
11979 negative error value.
11980 </p>
11981 <p><strong>Since:</strong> 2.12.0
11982 </p></dd></dl>
11983
11984 <a name="gnutls_005fprivkey_005fsign_005fhash-1"></a>
11985 <h4 class="subheading">gnutls_privkey_sign_hash</h4>
11986 <a name="gnutls_005fprivkey_005fsign_005fhash"></a><dl>
11987 <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>
11988 <dd><p><var>signer</var>: Holds the signer&rsquo;s key
11989 </p>
11990 <p><var>hash_algo</var>: The hash algorithm used
11991 </p>
11992 <p><var>flags</var>: zero for now
11993 </p>
11994 <p><var>hash_data</var>: holds the data to be signed
11995 </p>
11996 <p><var>signature</var>: will contain newly allocated signature
11997 </p>
11998 <p>This function will sign the given hashed data using a signature algorithm
11999 supported by the private key. Signature algorithms are always used
12000 together with a hash functions.  Different hash functions may be
12001 used for the RSA algorithm, but only SHA-XXX for the DSA keys.
12002 </p>
12003 <p>Use <code>gnutls_x509_crt_get_preferred_hash_algorithm()</code> to determine
12004 the hash algorithm.
12005 </p>
12006 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
12007 negative error value.
12008 </p>
12009 <p><strong>Since:</strong> 2.12.0
12010 </p></dd></dl>
12011
12012 <a name="gnutls_005fprotocol_005fget_005fid-1"></a>
12013 <h4 class="subheading">gnutls_protocol_get_id</h4>
12014 <a name="gnutls_005fprotocol_005fget_005fid"></a><dl>
12015 <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>
12016 <dd><p><var>name</var>: is a protocol name
12017 </p>
12018 <p>The names are compared in a case insensitive way.
12019 </p>
12020 <p><strong>Returns:</strong> an id of the specified protocol, or
12021 <code>GNUTLS_VERSION_UNKNOWN</code> on error.
12022 </p></dd></dl>
12023
12024 <a name="gnutls_005fprotocol_005fget_005fname-1"></a>
12025 <h4 class="subheading">gnutls_protocol_get_name</h4>
12026 <a name="gnutls_005fprotocol_005fget_005fname"></a><dl>
12027 <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>
12028 <dd><p><var>version</var>: is a (gnutls) version number
12029 </p>
12030 <p>Convert a <code>gnutls_protocol_t</code> value to a string.
12031 </p>
12032 <p><strong>Returns:</strong> a string that contains the name of the specified TLS
12033 version (e.g., &quot;TLS1.0&quot;), or <code>NULL</code>.
12034 </p></dd></dl>
12035
12036 <a name="gnutls_005fprotocol_005fget_005fversion-1"></a>
12037 <h4 class="subheading">gnutls_protocol_get_version</h4>
12038 <a name="gnutls_005fprotocol_005fget_005fversion"></a><dl>
12039 <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>
12040 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
12041 </p>
12042 <p>Get TLS version, a <code>gnutls_protocol_t</code> value.
12043 </p>
12044 <p><strong>Returns:</strong> the version of the currently used protocol.
12045 </p></dd></dl>
12046
12047 <a name="gnutls_005fprotocol_005flist-1"></a>
12048 <h4 class="subheading">gnutls_protocol_list</h4>
12049 <a name="gnutls_005fprotocol_005flist"></a><dl>
12050 <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>
12051 <dd>
12052 <p>Get a list of supported protocols, e.g. SSL 3.0, TLS 1.0 etc.
12053 </p>
12054 <p><strong>Returns:</strong> a zero-terminated list of <code>gnutls_protocol_t</code> integers
12055 indicating the available protocols.
12056 </p></dd></dl>
12057
12058 <a name="gnutls_005fprotocol_005fset_005fpriority-1"></a>
12059 <h4 class="subheading">gnutls_protocol_set_priority</h4>
12060 <a name="gnutls_005fprotocol_005fset_005fpriority"></a><dl>
12061 <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>
12062 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
12063 </p>
12064 <p><var>list</var>: is a 0 terminated list of gnutls_protocol_t elements.
12065 </p>
12066 <p>Sets the priority on the protocol versions supported by gnutls.
12067 This function actually enables or disables protocols. Newer protocol
12068 versions always have highest priority.
12069 </p>
12070 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
12071 </p></dd></dl>
12072
12073 <a name="gnutls_005fpsk_005fallocate_005fclient_005fcredentials-1"></a>
12074 <h4 class="subheading">gnutls_psk_allocate_client_credentials</h4>
12075 <a name="gnutls_005fpsk_005fallocate_005fclient_005fcredentials"></a><dl>
12076 <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>
12077 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_psk_server_credentials_t</code> structure.
12078 </p>
12079 <p>This structure is complex enough to manipulate directly thus this
12080 helper function is provided in order to allocate it.
12081 </p>
12082 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
12083 </p></dd></dl>
12084
12085 <a name="gnutls_005fpsk_005fallocate_005fserver_005fcredentials-1"></a>
12086 <h4 class="subheading">gnutls_psk_allocate_server_credentials</h4>
12087 <a name="gnutls_005fpsk_005fallocate_005fserver_005fcredentials"></a><dl>
12088 <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>
12089 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_psk_server_credentials_t</code> structure.
12090 </p>
12091 <p>This structure is complex enough to manipulate directly thus this
12092 helper function is provided in order to allocate it.
12093 </p>
12094 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
12095 </p></dd></dl>
12096
12097 <a name="gnutls_005fpsk_005fclient_005fget_005fhint-1"></a>
12098 <h4 class="subheading">gnutls_psk_client_get_hint</h4>
12099 <a name="gnutls_005fpsk_005fclient_005fget_005fhint"></a><dl>
12100 <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>
12101 <dd><p><var>session</var>: is a gnutls session
12102 </p>
12103 <p>The PSK identity hint may give the client help in deciding which
12104 username to use.  This should only be called in case of PSK
12105 authentication and in case of a client.
12106 </p>
12107 <p><strong>Returns:</strong> the identity hint of the peer, or <code>NULL</code> in case of an error.
12108 </p>
12109 <p><strong>Since:</strong> 2.4.0
12110 </p></dd></dl>
12111
12112 <a name="gnutls_005fpsk_005ffree_005fclient_005fcredentials-1"></a>
12113 <h4 class="subheading">gnutls_psk_free_client_credentials</h4>
12114 <a name="gnutls_005fpsk_005ffree_005fclient_005fcredentials"></a><dl>
12115 <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>
12116 <dd><p><var>sc</var>: is a <code>gnutls_psk_client_credentials_t</code> structure.
12117 </p>
12118 <p>This structure is complex enough to manipulate directly thus this
12119 helper function is provided in order to free (deallocate) it.
12120 </p></dd></dl>
12121
12122 <a name="gnutls_005fpsk_005ffree_005fserver_005fcredentials-1"></a>
12123 <h4 class="subheading">gnutls_psk_free_server_credentials</h4>
12124 <a name="gnutls_005fpsk_005ffree_005fserver_005fcredentials"></a><dl>
12125 <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>
12126 <dd><p><var>sc</var>: is a <code>gnutls_psk_server_credentials_t</code> structure.
12127 </p>
12128 <p>This structure is complex enough to manipulate directly thus this
12129 helper function is provided in order to free (deallocate) it.
12130 </p></dd></dl>
12131
12132 <a name="gnutls_005fpsk_005fnetconf_005fderive_005fkey-1"></a>
12133 <h4 class="subheading">gnutls_psk_netconf_derive_key</h4>
12134 <a name="gnutls_005fpsk_005fnetconf_005fderive_005fkey"></a><dl>
12135 <dt><a name="index-gnutls_005fpsk_005fnetconf_005fderive_005fkey"></a>Function: <em>int</em> <strong>gnutls_psk_netconf_derive_key</strong> <em>(const char * <var>password</var>, const char * <var>psk_identity</var>, const char * <var>psk_identity_hint</var>, gnutls_datum_t * <var>output_key</var>)</em></dt>
12136 <dd><p><var>password</var>: zero terminated string containing password.
12137 </p>
12138 <p><var>psk_identity</var>: zero terminated string with PSK identity.
12139 </p>
12140 <p><var>psk_identity_hint</var>: zero terminated string with PSK identity hint.
12141 </p>
12142 <p><var>output_key</var>: output variable, contains newly allocated *data pointer.
12143 </p>
12144 <p>This function will derive a PSK key from a password, for use with
12145 the Netconf protocol.
12146 </p>
12147 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
12148 </p>
12149 <p><strong>Since:</strong> 2.4.0
12150 </p>
12151 <p><strong>Deprecated:</strong> The need for this interface was dropped from the
12152 standard on publication as a RFC.  The function works now but will
12153 return a hard failure in a future release.
12154 </p></dd></dl>
12155
12156 <a name="gnutls_005fpsk_005fserver_005fget_005fusername-1"></a>
12157 <h4 class="subheading">gnutls_psk_server_get_username</h4>
12158 <a name="gnutls_005fpsk_005fserver_005fget_005fusername"></a><dl>
12159 <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>
12160 <dd><p><var>session</var>: is a gnutls session
12161 </p>
12162 <p>This should only be called in case of PSK authentication and in
12163 case of a server.
12164 </p>
12165 <p><strong>Returns:</strong> the username of the peer, or <code>NULL</code> in case of an error.
12166 </p></dd></dl>
12167
12168 <a name="gnutls_005fpsk_005fset_005fclient_005fcredentials_005ffunction-1"></a>
12169 <h4 class="subheading">gnutls_psk_set_client_credentials_function</h4>
12170 <a name="gnutls_005fpsk_005fset_005fclient_005fcredentials_005ffunction"></a><dl>
12171 <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>
12172 <dd><p><var>cred</var>: is a <code>gnutls_psk_server_credentials_t</code> structure.
12173 </p>
12174 <p><var>func</var>: is the callback function
12175 </p>
12176 <p>This function can be used to set a callback to retrieve the username and
12177 password for client PSK authentication.
12178 The callback&rsquo;s function form is:
12179 int (*callback)(gnutls_session_t, char** username,
12180 gnutls_datum_t* key);
12181 </p>
12182 <p>The <code>username</code> and <code>key</code>-&gt;data must be allocated using <code>gnutls_malloc()</code>.
12183 <code>username</code> should be ASCII strings or UTF-8 strings prepared using
12184 the &quot;SASLprep&quot; profile of &quot;stringprep&quot;.
12185 </p>
12186 <p>The callback function will be called once per handshake.
12187 </p>
12188 <p>The callback function should return 0 on success.
12189 -1 indicates an error.
12190 </p></dd></dl>
12191
12192 <a name="gnutls_005fpsk_005fset_005fclient_005fcredentials-1"></a>
12193 <h4 class="subheading">gnutls_psk_set_client_credentials</h4>
12194 <a name="gnutls_005fpsk_005fset_005fclient_005fcredentials"></a><dl>
12195 <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>
12196 <dd><p><var>res</var>: is a <code>gnutls_psk_client_credentials_t</code> structure.
12197 </p>
12198 <p><var>username</var>: is the user&rsquo;s zero-terminated userid
12199 </p>
12200 <p><var>key</var>: is the user&rsquo;s key
12201 </p>
12202 <p>This function sets the username and password, in a
12203 gnutls_psk_client_credentials_t structure.  Those will be used in
12204 PSK authentication.  <code>username</code> should be an ASCII string or UTF-8
12205 strings prepared using the &quot;SASLprep&quot; profile of &quot;stringprep&quot;.  The
12206 key can be either in raw byte format or in Hex format (without the
12207 0x prefix).
12208 </p>
12209 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
12210 </p></dd></dl>
12211
12212 <a name="gnutls_005fpsk_005fset_005fparams_005ffunction-1"></a>
12213 <h4 class="subheading">gnutls_psk_set_params_function</h4>
12214 <a name="gnutls_005fpsk_005fset_005fparams_005ffunction"></a><dl>
12215 <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>
12216 <dd><p><var>res</var>: is a gnutls_psk_server_credentials_t structure
12217 </p>
12218 <p><var>func</var>: is the function to be called
12219 </p>
12220 <p>This function will set a callback in order for the server to get
12221 the Diffie-Hellman or RSA parameters for PSK authentication.  The
12222 callback should return zero on success.
12223 </p></dd></dl>
12224
12225 <a name="gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffile-1"></a>
12226 <h4 class="subheading">gnutls_psk_set_server_credentials_file</h4>
12227 <a name="gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffile"></a><dl>
12228 <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>
12229 <dd><p><var>res</var>: is a <code>gnutls_psk_server_credentials_t</code> structure.
12230 </p>
12231 <p><var>password_file</var>: is the PSK password file (passwd.psk)
12232 </p>
12233 <p>This function sets the password file, in a
12234 <code>gnutls_psk_server_credentials_t</code> structure.  This password file
12235 holds usernames and keys and will be used for PSK authentication.
12236 </p>
12237 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
12238 </p></dd></dl>
12239
12240 <a name="gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffunction-1"></a>
12241 <h4 class="subheading">gnutls_psk_set_server_credentials_function</h4>
12242 <a name="gnutls_005fpsk_005fset_005fserver_005fcredentials_005ffunction"></a><dl>
12243 <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>
12244 <dd><p><var>cred</var>: is a <code>gnutls_psk_server_credentials_t</code> structure.
12245 </p>
12246 <p><var>func</var>: is the callback function
12247 </p>
12248 <p>This function can be used to set a callback to retrieve the user&rsquo;s PSK credentials.
12249 The callback&rsquo;s function form is:
12250 int (*callback)(gnutls_session_t, const char* username,
12251 gnutls_datum_t* key);
12252 </p>
12253 <p><code>username</code> contains the actual username.
12254 The <code>key</code> must be filled in using the <code>gnutls_malloc()</code>.
12255 </p>
12256 <p>In case the callback returned a negative number then gnutls will
12257 assume that the username does not exist.
12258 </p>
12259 <p>The callback function will only be called once per handshake.  The
12260 callback function should return 0 on success, while -1 indicates
12261 an error.
12262 </p></dd></dl>
12263
12264 <a name="gnutls_005fpsk_005fset_005fserver_005fcredentials_005fhint-1"></a>
12265 <h4 class="subheading">gnutls_psk_set_server_credentials_hint</h4>
12266 <a name="gnutls_005fpsk_005fset_005fserver_005fcredentials_005fhint"></a><dl>
12267 <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>
12268 <dd><p><var>res</var>: is a <code>gnutls_psk_server_credentials_t</code> structure.
12269 </p>
12270 <p><var>hint</var>: is the PSK identity hint string
12271 </p>
12272 <p>This function sets the identity hint, in a
12273 <code>gnutls_psk_server_credentials_t</code> structure.  This hint is sent to
12274 the client to help it chose a good PSK credential (i.e., username
12275 and password).
12276 </p>
12277 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
12278 </p>
12279 <p><strong>Since:</strong> 2.4.0
12280 </p></dd></dl>
12281
12282 <a name="gnutls_005fpsk_005fset_005fserver_005fdh_005fparams-1"></a>
12283 <h4 class="subheading">gnutls_psk_set_server_dh_params</h4>
12284 <a name="gnutls_005fpsk_005fset_005fserver_005fdh_005fparams"></a><dl>
12285 <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>
12286 <dd><p><var>res</var>: is a gnutls_psk_server_credentials_t structure
12287 </p>
12288 <p><var>dh_params</var>: is a structure that holds Diffie-Hellman parameters.
12289 </p>
12290 <p>This function will set the Diffie-Hellman parameters for an
12291 anonymous server to use. These parameters will be used in
12292 Diffie-Hellman exchange with PSK cipher suites.
12293 </p></dd></dl>
12294
12295 <a name="gnutls_005fpsk_005fset_005fserver_005fparams_005ffunction-1"></a>
12296 <h4 class="subheading">gnutls_psk_set_server_params_function</h4>
12297 <a name="gnutls_005fpsk_005fset_005fserver_005fparams_005ffunction"></a><dl>
12298 <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>
12299 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code> structure
12300 </p>
12301 <p><var>func</var>: is the function to be called
12302 </p>
12303 <p>This function will set a callback in order for the server to get
12304 the Diffie-Hellman parameters for PSK authentication.  The callback
12305 should return zero on success.
12306 </p></dd></dl>
12307
12308 <a name="gnutls_005fpubkey_005fdeinit-1"></a>
12309 <h4 class="subheading">gnutls_pubkey_deinit</h4>
12310 <a name="gnutls_005fpubkey_005fdeinit"></a><dl>
12311 <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>
12312 <dd><p><var>key</var>: The structure to be deinitialized
12313 </p>
12314 <p>This function will deinitialize a public key structure.
12315 </p></dd></dl>
12316
12317 <a name="gnutls_005fpubkey_005fexport-1"></a>
12318 <h4 class="subheading">gnutls_pubkey_export</h4>
12319 <a name="gnutls_005fpubkey_005fexport"></a><dl>
12320 <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>
12321 <dd><p><var>key</var>: Holds the certificate
12322 </p>
12323 <p><var>format</var>: the format of output params. One of PEM or DER.
12324 </p>
12325 <p><var>output_data</var>: will contain a certificate PEM or DER encoded
12326 </p>
12327 <p><var>output_data_size</var>: holds the size of output_data (and will be
12328 replaced by the actual size of parameters)
12329 </p>
12330 <p>This function will export the certificate to DER or PEM format.
12331 </p>
12332 <p>If the buffer provided is not long enough to hold the output, then
12333 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
12334 be returned.
12335 </p>
12336 <p>If the structure is PEM encoded, it will have a header
12337 of &quot;BEGIN CERTIFICATE&quot;.
12338 </p>
12339 <p><strong>Return value:</strong> In case of failure a negative value will be
12340 returned, and 0 on success.
12341 </p></dd></dl>
12342
12343 <a name="gnutls_005fpubkey_005fget_005fkey_005fid-1"></a>
12344 <h4 class="subheading">gnutls_pubkey_get_key_id</h4>
12345 <a name="gnutls_005fpubkey_005fget_005fkey_005fid"></a><dl>
12346 <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>
12347 <dd><p><var>key</var>: Holds the public key
12348 </p>
12349 <p><var>flags</var>: should be 0 for now
12350 </p>
12351 <p><var>output_data</var>: will contain the key ID
12352 </p>
12353 <p><var>output_data_size</var>: holds the size of output_data (and will be
12354 replaced by the actual size of parameters)
12355 </p>
12356 <p>This function will return a unique ID the depends on the public
12357 key parameters. This ID can be used in checking whether a
12358 certificate corresponds to the given public key.
12359 </p>
12360 <p>If the buffer provided is not long enough to hold the output, then
12361 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
12362 be returned.  The output will normally be a SHA-1 hash output,
12363 which is 20 bytes.
12364 </p>
12365 <p><strong>Return value:</strong> In case of failure a negative value will be
12366 returned, and 0 on success.
12367 </p></dd></dl>
12368
12369 <a name="gnutls_005fpubkey_005fget_005fkey_005fusage-1"></a>
12370 <h4 class="subheading">gnutls_pubkey_get_key_usage</h4>
12371 <a name="gnutls_005fpubkey_005fget_005fkey_005fusage"></a><dl>
12372 <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>
12373 <dd><p><var>key</var>: should contain a <code>gnutls_pubkey_t</code> structure
12374 </p>
12375 <p><var>usage</var>: If set will return the number of bits of the parameters (may be NULL)
12376 </p>
12377 <p>This function will return the key usage of the public key.
12378 </p>
12379 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
12380 negative error value.
12381 </p></dd></dl>
12382
12383 <a name="gnutls_005fpubkey_005fget_005fpk_005falgorithm-1"></a>
12384 <h4 class="subheading">gnutls_pubkey_get_pk_algorithm</h4>
12385 <a name="gnutls_005fpubkey_005fget_005fpk_005falgorithm"></a><dl>
12386 <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>
12387 <dd><p><var>key</var>: should contain a <code>gnutls_pubkey_t</code> structure
12388 </p>
12389 <p><var>bits</var>: If set will return the number of bits of the parameters (may be NULL)
12390 </p>
12391 <p>This function will return the public key algorithm of a public
12392 key and if possible will return a number of bits that indicates
12393 the security parameter of the key.
12394 </p>
12395 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code> enumeration on
12396 success, or a negative value on error.
12397 </p></dd></dl>
12398
12399 <a name="gnutls_005fpubkey_005fget_005fpk_005fdsa_005fraw-1"></a>
12400 <h4 class="subheading">gnutls_pubkey_get_pk_dsa_raw</h4>
12401 <a name="gnutls_005fpubkey_005fget_005fpk_005fdsa_005fraw"></a><dl>
12402 <dt><a name="index-gnutls_005fpubkey_005fget_005fpk_005fdsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_pubkey_get_pk_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>
12403 <dd><p><var>key</var>: Holds the public key
12404 </p>
12405 <p><var>p</var>: will hold the p
12406 </p>
12407 <p><var>q</var>: will hold the q
12408 </p>
12409 <p><var>g</var>: will hold the g
12410 </p>
12411 <p><var>y</var>: will hold the y
12412 </p>
12413 <p>This function will export the DSA public key&rsquo;s parameters found in
12414 the given certificate.  The new parameters will be allocated using
12415 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
12416 </p>
12417 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
12418 </p></dd></dl>
12419
12420 <a name="gnutls_005fpubkey_005fget_005fpk_005frsa_005fraw-1"></a>
12421 <h4 class="subheading">gnutls_pubkey_get_pk_rsa_raw</h4>
12422 <a name="gnutls_005fpubkey_005fget_005fpk_005frsa_005fraw"></a><dl>
12423 <dt><a name="index-gnutls_005fpubkey_005fget_005fpk_005frsa_005fraw"></a>Function: <em>int</em> <strong>gnutls_pubkey_get_pk_rsa_raw</strong> <em>(gnutls_pubkey_t <var>key</var>, gnutls_datum_t * <var>m</var>, gnutls_datum_t * <var>e</var>)</em></dt>
12424 <dd><p><var>key</var>: Holds the certificate
12425 </p>
12426 <p><var>m</var>: will hold the modulus
12427 </p>
12428 <p><var>e</var>: will hold the public exponent
12429 </p>
12430 <p>This function will export the RSA public key&rsquo;s parameters found in
12431 the given structure.  The new parameters will be allocated using
12432 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
12433 </p>
12434 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
12435 </p></dd></dl>
12436
12437 <a name="gnutls_005fpubkey_005fget_005fpreferred_005fhash_005falgorithm-1"></a>
12438 <h4 class="subheading">gnutls_pubkey_get_preferred_hash_algorithm</h4>
12439 <a name="gnutls_005fpubkey_005fget_005fpreferred_005fhash_005falgorithm"></a><dl>
12440 <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>
12441 <dd><p><var>key</var>: Holds the certificate
12442 </p>
12443 <p><var>hash</var>: The result of the call with the hash algorithm used for signature
12444 </p>
12445 <p><var>mand</var>: If non zero it means that the algorithm MUST use this hash. May be NULL.
12446 </p>
12447 <p>This function will read the certifcate and return the appropriate digest
12448 algorithm to use for signing with this certificate. Some certificates (i.e.
12449 DSA might not be able to sign without the preferred algorithm).
12450 </p>
12451 <p><strong>Returns:</strong> the 0 if the hash algorithm is found. A negative value is
12452 returned on error.
12453 </p>
12454 <p><strong>Since:</strong> 2.11.0
12455 </p></dd></dl>
12456
12457 <a name="gnutls_005fpubkey_005fget_005fverify_005falgorithm-1"></a>
12458 <h4 class="subheading">gnutls_pubkey_get_verify_algorithm</h4>
12459 <a name="gnutls_005fpubkey_005fget_005fverify_005falgorithm"></a><dl>
12460 <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>
12461 <dd><p><var>key</var>: Holds the certificate
12462 </p>
12463 <p><var>signature</var>: contains the signature
12464 </p>
12465 <p><var>hash</var>: The result of the call with the hash algorithm used for signature
12466 </p>
12467 <p>This function will read the certifcate and the signed data to
12468 determine the hash algorithm used to generate the signature.
12469 </p>
12470 <p><strong>Returns:</strong> the 0 if the hash algorithm is found. A negative value is
12471 returned on error.
12472 </p></dd></dl>
12473
12474 <a name="gnutls_005fpubkey_005fimport_005fdsa_005fraw-1"></a>
12475 <h4 class="subheading">gnutls_pubkey_import_dsa_raw</h4>
12476 <a name="gnutls_005fpubkey_005fimport_005fdsa_005fraw"></a><dl>
12477 <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>
12478 <dd><p><var>key</var>: The structure to store the parsed key
12479 </p>
12480 <p><var>p</var>: holds the p
12481 </p>
12482 <p><var>q</var>: holds the q
12483 </p>
12484 <p><var>g</var>: holds the g
12485 </p>
12486 <p><var>y</var>: holds the y
12487 </p>
12488 <p>This function will convert the given DSA raw parameters to the
12489 native <code>gnutls_pubkey_t</code> format.  The output will be stored
12490 in <code>key</code>.
12491 </p>
12492 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
12493 negative error value.
12494 </p></dd></dl>
12495
12496 <a name="gnutls_005fpubkey_005fimport_005fopenpgp-1"></a>
12497 <h4 class="subheading">gnutls_pubkey_import_openpgp</h4>
12498 <a name="gnutls_005fpubkey_005fimport_005fopenpgp"></a><dl>
12499 <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>
12500 <dd><p><var>key</var>: The public key
12501 </p>
12502 <p><var>crt</var>: The certificate to be imported
12503 </p>
12504 <p><var>flags</var>: should be zero
12505 </p>
12506 <p>This function will import the given public key to the abstract
12507 <code>gnutls_pubkey_t</code> structure. The subkey set as preferred will be
12508 imported or the master key otherwise.
12509 </p>
12510 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
12511 negative error value.
12512 </p></dd></dl>
12513
12514 <a name="gnutls_005fpubkey_005fimport_005fpkcs11_005furl-1"></a>
12515 <h4 class="subheading">gnutls_pubkey_import_pkcs11_url</h4>
12516 <a name="gnutls_005fpubkey_005fimport_005fpkcs11_005furl"></a><dl>
12517 <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>
12518 <dd><p><var>key</var>: A key of type <code>gnutls_pubkey_t</code>
12519 </p>
12520 <p><var>url</var>: A PKCS 11 url
12521 </p>
12522 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
12523 </p>
12524 <p>This function will import a PKCS 11 certificate to a <code>gnutls_pubkey_t</code>
12525 structure.
12526 </p>
12527 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
12528 negative error value.
12529 </p></dd></dl>
12530
12531 <a name="gnutls_005fpubkey_005fimport_005fpkcs11-1"></a>
12532 <h4 class="subheading">gnutls_pubkey_import_pkcs11</h4>
12533 <a name="gnutls_005fpubkey_005fimport_005fpkcs11"></a><dl>
12534 <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>
12535 <dd><p><var>key</var>: The public key
12536 </p>
12537 <p><var>obj</var>: The parameters to be imported
12538 </p>
12539 <p><var>flags</var>: should be zero
12540 </p>
12541 <p>This function will import the given public key to the abstract
12542 <code>gnutls_pubkey_t</code> structure.
12543 </p>
12544 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
12545 negative error value.
12546 </p></dd></dl>
12547
12548 <a name="gnutls_005fpubkey_005fimport_005fprivkey-1"></a>
12549 <h4 class="subheading">gnutls_pubkey_import_privkey</h4>
12550 <a name="gnutls_005fpubkey_005fimport_005fprivkey"></a><dl>
12551 <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>
12552 <dd><p><var>key</var>: The public key
12553 </p>
12554 <p><var>pkey</var>: The private key
12555 </p>
12556 <p><var>usage</var>: GNUTLS_KEY_* key usage flags.
12557 </p>
12558 <p><var>flags</var>: should be zero
12559 </p>
12560 <p>This function will import the given public key to the abstract
12561 <code>gnutls_pubkey_t</code> structure.
12562 </p>
12563 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
12564 negative error value.
12565 </p>
12566 <p><strong>Since:</strong> 2.12.0
12567 </p></dd></dl>
12568
12569 <a name="gnutls_005fpubkey_005fimport_005frsa_005fraw-1"></a>
12570 <h4 class="subheading">gnutls_pubkey_import_rsa_raw</h4>
12571 <a name="gnutls_005fpubkey_005fimport_005frsa_005fraw"></a><dl>
12572 <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>
12573 <dd><p><var>key</var>: Is a structure will hold the parameters
12574 </p>
12575 <p><var>m</var>: holds the modulus
12576 </p>
12577 <p><var>e</var>: holds the public exponent
12578 </p>
12579 <p>This function will replace the parameters in the given structure.
12580 The new parameters should be stored in the appropriate
12581 gnutls_datum.
12582 </p>
12583 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an negative error code.
12584 </p></dd></dl>
12585
12586 <a name="gnutls_005fpubkey_005fimport_005fx509-1"></a>
12587 <h4 class="subheading">gnutls_pubkey_import_x509</h4>
12588 <a name="gnutls_005fpubkey_005fimport_005fx509"></a><dl>
12589 <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>
12590 <dd><p><var>key</var>: The public key
12591 </p>
12592 <p><var>crt</var>: The certificate to be imported
12593 </p>
12594 <p><var>flags</var>: should be zero
12595 </p>
12596 <p>This function will import the given public key to the abstract
12597 <code>gnutls_pubkey_t</code> structure.
12598 </p>
12599 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
12600 negative error value.
12601 </p></dd></dl>
12602
12603 <a name="gnutls_005fpubkey_005fimport-1"></a>
12604 <h4 class="subheading">gnutls_pubkey_import</h4>
12605 <a name="gnutls_005fpubkey_005fimport"></a><dl>
12606 <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>
12607 <dd><p><var>key</var>: The structure to store the parsed public key.
12608 </p>
12609 <p><var>data</var>: The DER or PEM encoded certificate.
12610 </p>
12611 <p><var>format</var>: One of DER or PEM
12612 </p>
12613 <p>This function will convert the given DER or PEM encoded Public key
12614 to the native gnutls_pubkey_t format.The output will be stored * in &nbsp;key.
12615 If the Certificate is PEM encoded it should have a header of &quot;PUBLIC KEY&quot;.
12616 </p>
12617 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
12618 negative error value.
12619 </p></dd></dl>
12620
12621 <a name="gnutls_005fpubkey_005finit-1"></a>
12622 <h4 class="subheading">gnutls_pubkey_init</h4>
12623 <a name="gnutls_005fpubkey_005finit"></a><dl>
12624 <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>
12625 <dd><p><var>key</var>: The structure to be initialized
12626 </p>
12627 <p>This function will initialize an public key structure.
12628 </p>
12629 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
12630 negative error value.
12631 </p></dd></dl>
12632
12633 <a name="gnutls_005fpubkey_005fset_005fkey_005fusage-1"></a>
12634 <h4 class="subheading">gnutls_pubkey_set_key_usage</h4>
12635 <a name="gnutls_005fpubkey_005fset_005fkey_005fusage"></a><dl>
12636 <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>
12637 <dd><p><var>key</var>: a certificate of type <code>gnutls_x509_crt_t</code>
12638 </p>
12639 <p><var>usage</var>: an ORed sequence of the GNUTLS_KEY_* elements.
12640 </p>
12641 <p>This function will set the key usage flags of the public key. This
12642 is only useful if the key is to be exported to a certificate or
12643 certificate request.
12644 </p>
12645 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
12646 negative error value.
12647 </p></dd></dl>
12648
12649 <a name="gnutls_005fpubkey_005fverify_005fdata-1"></a>
12650 <h4 class="subheading">gnutls_pubkey_verify_data</h4>
12651 <a name="gnutls_005fpubkey_005fverify_005fdata"></a><dl>
12652 <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>
12653 <dd><p><var>pubkey</var>: Holds the public key
12654 </p>
12655 <p><var>flags</var>: should be 0 for now
12656 </p>
12657 <p><var>data</var>: holds the data to be signed
12658 </p>
12659 <p><var>signature</var>: contains the signature
12660 </p>
12661 <p>This function will verify the given signed data, using the
12662 parameters from the certificate.
12663 </p>
12664 <p><strong>Returns:</strong> In case of a verification failure
12665 <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code> is returned, and a positive code
12666 on success.
12667 </p>
12668 <p><strong>Since:</strong> 2.12.0
12669 </p></dd></dl>
12670
12671 <a name="gnutls_005fpubkey_005fverify_005fhash-1"></a>
12672 <h4 class="subheading">gnutls_pubkey_verify_hash</h4>
12673 <a name="gnutls_005fpubkey_005fverify_005fhash"></a><dl>
12674 <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>
12675 <dd><p><var>key</var>: Holds the certificate
12676 </p>
12677 <p><var>flags</var>: should be 0 for now
12678 </p>
12679 <p><var>hash</var>: holds the hash digest to be verified
12680 </p>
12681 <p><var>signature</var>: contains the signature
12682 </p>
12683 <p>This function will verify the given signed digest, using the
12684 parameters from the certificate.
12685 </p>
12686 <p><strong>Returns:</strong> In case of a verification failure <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
12687 is returned, and a positive code on success.
12688 </p></dd></dl>
12689
12690 <a name="gnutls_005frecord_005fcheck_005fpending-1"></a>
12691 <h4 class="subheading">gnutls_record_check_pending</h4>
12692 <a name="gnutls_005frecord_005fcheck_005fpending"></a><dl>
12693 <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>
12694 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
12695 </p>
12696 <p>This function checks if there are any data to receive in the gnutls
12697 buffers.
12698 </p>
12699 <p><strong>Returns:</strong> the size of that data or 0.
12700 </p></dd></dl>
12701
12702 <a name="gnutls_005frecord_005fdisable_005fpadding-1"></a>
12703 <h4 class="subheading">gnutls_record_disable_padding</h4>
12704 <a name="gnutls_005frecord_005fdisable_005fpadding"></a><dl>
12705 <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>
12706 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
12707 </p>
12708 <p>Used to disabled padding in TLS 1.0 and above.  Normally you do not
12709 need to use this function, but there are buggy clients that
12710 complain if a server pads the encrypted data.  This of course will
12711 disable protection against statistical attacks on the data.
12712 </p>
12713 <p>Normally only servers that require maximum compatibility with everything
12714 out there, need to call this function.
12715 </p></dd></dl>
12716
12717 <a name="gnutls_005frecord_005fget_005fdirection-1"></a>
12718 <h4 class="subheading">gnutls_record_get_direction</h4>
12719 <a name="gnutls_005frecord_005fget_005fdirection"></a><dl>
12720 <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>
12721 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
12722 </p>
12723 <p>This function provides information about the internals of the
12724 record protocol and is only useful if a prior gnutls function call
12725 (e.g.  <code>gnutls_handshake()</code>) was interrupted for some reason, that
12726 is, if a function returned <code>GNUTLS_E_INTERRUPTED</code> or
12727 <code>GNUTLS_E_AGAIN</code>.  In such a case, you might want to call <code>select()</code>
12728 or <code>poll()</code> before calling the interrupted gnutls function again.  To
12729 tell you whether a file descriptor should be selected for either
12730 reading or writing, <code>gnutls_record_get_direction()</code> returns 0 if the
12731 interrupted function was trying to read data, and 1 if it was
12732 trying to write data.
12733 </p>
12734 <p><strong>Returns:</strong> 0 if trying to read data, 1 if trying to write data.
12735 </p></dd></dl>
12736
12737 <a name="gnutls_005frecord_005fget_005fmax_005fsize-1"></a>
12738 <h4 class="subheading">gnutls_record_get_max_size</h4>
12739 <a name="gnutls_005frecord_005fget_005fmax_005fsize"></a><dl>
12740 <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>
12741 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
12742 </p>
12743 <p>Get the record size.  The maximum record size is negotiated by the
12744 client after the first handshake message.
12745 </p>
12746 <p><strong>Returns:</strong> The maximum record packet size in this connection.
12747 </p></dd></dl>
12748
12749 <a name="gnutls_005frecord_005frecv-1"></a>
12750 <h4 class="subheading">gnutls_record_recv</h4>
12751 <a name="gnutls_005frecord_005frecv"></a><dl>
12752 <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>sizeofdata</var>)</em></dt>
12753 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
12754 </p>
12755 <p><var>data</var>: the buffer that the data will be read into
12756 </p>
12757 <p><var>sizeofdata</var>: the number of requested bytes
12758 </p>
12759 <p>This function has the similar semantics with <code>recv()</code>.  The only
12760 difference is that it accepts a GnuTLS session, and uses different
12761 error codes.
12762 </p>
12763 <p>In the special case that a server requests a renegotiation, the
12764 client may receive an error code of <code>GNUTLS_E_REHANDSHAKE</code>.  This
12765 message may be simply ignored, replied with an alert
12766 <code>GNUTLS_A_NO_RENEGOTIATION</code>, or replied with a new handshake,
12767 depending on the client&rsquo;s will.
12768 </p>
12769 <p>If <code>EINTR</code> is returned by the internal push function (the default
12770 is <code>recv()</code>) then <code>GNUTLS_E_INTERRUPTED</code> will be returned.  If
12771 <code>GNUTLS_E_INTERRUPTED</code> or <code>GNUTLS_E_AGAIN</code> is returned, you must
12772 call this function again to get the data.  See also
12773 <code>gnutls_record_get_direction()</code>.
12774 </p>
12775 <p>A server may also receive <code>GNUTLS_E_REHANDSHAKE</code> when a client has
12776 initiated a handshake. In that case the server can only initiate a
12777 handshake or terminate the connection.
12778 </p>
12779 <p><strong>Returns:</strong> the number of bytes received and zero on EOF.  A negative
12780 error code is returned in case of an error.  The number of bytes
12781 received might be less than <code>sizeofdata</code>.
12782 </p></dd></dl>
12783
12784 <a name="gnutls_005frecord_005fsend-1"></a>
12785 <h4 class="subheading">gnutls_record_send</h4>
12786 <a name="gnutls_005frecord_005fsend"></a><dl>
12787 <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>sizeofdata</var>)</em></dt>
12788 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
12789 </p>
12790 <p><var>data</var>: contains the data to send
12791 </p>
12792 <p><var>sizeofdata</var>: is the length of the data
12793 </p>
12794 <p>This function has the similar semantics with <code>send()</code>.  The only
12795 difference is that it accepts a GnuTLS session, and uses different
12796 error codes.
12797 </p>
12798 <p>Note that if the send buffer is full, <code>send()</code> will block this
12799 function.  See the <code>send()</code> documentation for full information.  You
12800 can replace the default push function by using
12801 <code>gnutls_transport_set_ptr2()</code> with a call to <code>send()</code> with a
12802 MSG_DONTWAIT flag if blocking is a problem.
12803 </p>
12804 <p>If the EINTR is returned by the internal push function (the
12805 default is <code>send()</code>} then <code>GNUTLS_E_INTERRUPTED</code> will be returned. If
12806 <code>GNUTLS_E_INTERRUPTED</code> or <code>GNUTLS_E_AGAIN</code> is returned, you must
12807 call this function again, with the same parameters; alternatively
12808 you could provide a <code>NULL</code> pointer for data, and 0 for
12809 size. cf. <code>gnutls_record_get_direction()</code>.
12810 </p>
12811 <p><strong>Returns:</strong> the number of bytes sent, or a negative error code.  The
12812 number of bytes sent might be less than <code>sizeofdata</code>.  The maximum
12813 number of bytes this function can send in a single call depends
12814 on the negotiated maximum record size.
12815 </p></dd></dl>
12816
12817 <a name="gnutls_005frecord_005fset_005fmax_005fsize-1"></a>
12818 <h4 class="subheading">gnutls_record_set_max_size</h4>
12819 <a name="gnutls_005frecord_005fset_005fmax_005fsize"></a><dl>
12820 <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>
12821 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
12822 </p>
12823 <p><var>size</var>: is the new size
12824 </p>
12825 <p>This function sets the maximum record packet size in this
12826 connection.  This property can only be set to clients.  The server
12827 may choose not to accept the requested size.
12828 </p>
12829 <p>Acceptable values are 512(=2^9), 1024(=2^10), 2048(=2^11) and
12830 4096(=2^12).  The requested record size does get in effect
12831 immediately only while sending data. The receive part will take
12832 effect after a successful handshake.
12833 </p>
12834 <p>This function uses a TLS extension called &rsquo;max record size&rsquo;.  Not
12835 all TLS implementations use or even understand this extension.
12836 </p>
12837 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
12838 otherwise an error code is returned.
12839 </p></dd></dl>
12840
12841 <a name="gnutls_005frehandshake-1"></a>
12842 <h4 class="subheading">gnutls_rehandshake</h4>
12843 <a name="gnutls_005frehandshake"></a><dl>
12844 <dt><a name="index-gnutls_005frehandshake"></a>Function: <em>int</em> <strong>gnutls_rehandshake</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
12845 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
12846 </p>
12847 <p>This function will renegotiate security parameters with the
12848 client.  This should only be called in case of a server.
12849 </p>
12850 <p>This message informs the peer that we want to renegotiate
12851 parameters (perform a handshake).
12852 </p>
12853 <p>If this function succeeds (returns 0), you must call the
12854 <code>gnutls_handshake()</code> function in order to negotiate the new
12855 parameters.
12856 </p>
12857 <p>Since TLS is full duplex some application data might have been
12858 sent during peer&rsquo;s processing of this message. In that case
12859 one should call <code>gnutls_record_recv()</code> until GNUTLS_E_REHANDSHAKE
12860 is returned to clear any pending data. Care must be taken if
12861 rehandshake is mandatory to terminate if it does not start after
12862 some threshold.
12863 </p>
12864 <p>If the client does not wish to renegotiate parameters he will
12865 should with an alert message, thus the return code will be
12866 <code>GNUTLS_E_WARNING_ALERT_RECEIVED</code> and the alert will be
12867 <code>GNUTLS_A_NO_RENEGOTIATION</code>.  A client may also choose to ignore
12868 this message.
12869 </p>
12870 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
12871 </p></dd></dl>
12872
12873 <a name="gnutls_005frnd-1"></a>
12874 <h4 class="subheading">gnutls_rnd</h4>
12875 <a name="gnutls_005frnd"></a><dl>
12876 <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>
12877 <dd><p><var>level</var>: a security level
12878 </p>
12879 <p><var>data</var>: place to store random bytes
12880 </p>
12881 <p><var>len</var>: The requested size
12882 </p>
12883 <p>This function will generate random data and store it
12884 to output buffer.
12885 </p>
12886 <p><strong>Returns:</strong> Zero or a negative value on error.
12887 </p></dd></dl>
12888
12889 <a name="gnutls_005frsa_005fexport_005fget_005fmodulus_005fbits-1"></a>
12890 <h4 class="subheading">gnutls_rsa_export_get_modulus_bits</h4>
12891 <a name="gnutls_005frsa_005fexport_005fget_005fmodulus_005fbits"></a><dl>
12892 <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>
12893 <dd><p><var>session</var>: is a gnutls session
12894 </p>
12895 <p>Get the export RSA parameter&rsquo;s modulus size.
12896 </p>
12897 <p><strong>Returns:</strong> the bits used in the last RSA-EXPORT key exchange with the
12898 peer, or a negative value in case of error.
12899 </p></dd></dl>
12900
12901 <a name="gnutls_005frsa_005fexport_005fget_005fpubkey-1"></a>
12902 <h4 class="subheading">gnutls_rsa_export_get_pubkey</h4>
12903 <a name="gnutls_005frsa_005fexport_005fget_005fpubkey"></a><dl>
12904 <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>
12905 <dd><p><var>session</var>: is a gnutls session
12906 </p>
12907 <p><var>exponent</var>: will hold the exponent.
12908 </p>
12909 <p><var>modulus</var>: will hold the modulus.
12910 </p>
12911 <p>This function will return the peer&rsquo;s public key exponent and
12912 modulus used in the last RSA-EXPORT authentication.  The output
12913 parameters must be freed with <code>gnutls_free()</code>.
12914 </p>
12915 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
12916 an error code is returned.
12917 </p></dd></dl>
12918
12919 <a name="gnutls_005frsa_005fparams_005fcpy-1"></a>
12920 <h4 class="subheading">gnutls_rsa_params_cpy</h4>
12921 <a name="gnutls_005frsa_005fparams_005fcpy"></a><dl>
12922 <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>
12923 <dd><p><var>dst</var>: Is the destination structure, which should be initialized.
12924 </p>
12925 <p><var>src</var>: Is the source structure
12926 </p>
12927 <p>This function will copy the RSA parameters structure from source
12928 to destination.
12929 </p>
12930 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an negative error code.
12931 </p></dd></dl>
12932
12933 <a name="gnutls_005frsa_005fparams_005fdeinit-1"></a>
12934 <h4 class="subheading">gnutls_rsa_params_deinit</h4>
12935 <a name="gnutls_005frsa_005fparams_005fdeinit"></a><dl>
12936 <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>
12937 <dd><p><var>rsa_params</var>: Is a structure that holds the parameters
12938 </p>
12939 <p>This function will deinitialize the RSA parameters structure.
12940 </p></dd></dl>
12941
12942 <a name="gnutls_005frsa_005fparams_005fexport_005fpkcs1-1"></a>
12943 <h4 class="subheading">gnutls_rsa_params_export_pkcs1</h4>
12944 <a name="gnutls_005frsa_005fparams_005fexport_005fpkcs1"></a><dl>
12945 <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>
12946 <dd><p><var>params</var>: Holds the RSA parameters
12947 </p>
12948 <p><var>format</var>: the format of output params. One of PEM or DER.
12949 </p>
12950 <p><var>params_data</var>: will contain a PKCS1 RSAPublicKey structure PEM or DER encoded
12951 </p>
12952 <p><var>params_data_size</var>: holds the size of params_data (and will be replaced by the actual size of parameters)
12953 </p>
12954 <p>This function will export the given RSA parameters to a PKCS1
12955 RSAPublicKey structure. If the buffer provided is not long enough to
12956 hold the output, then GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
12957 </p>
12958 <p>If the structure is PEM encoded, it will have a header
12959 of &quot;BEGIN RSA PRIVATE KEY&quot;.
12960 </p>
12961 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an negative error code.
12962 </p></dd></dl>
12963
12964 <a name="gnutls_005frsa_005fparams_005fexport_005fraw-1"></a>
12965 <h4 class="subheading">gnutls_rsa_params_export_raw</h4>
12966 <a name="gnutls_005frsa_005fparams_005fexport_005fraw"></a><dl>
12967 <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>params</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>
12968 <dd><p><var>params</var>: a structure that holds the rsa parameters
12969 </p>
12970 <p><var>m</var>: will hold the modulus
12971 </p>
12972 <p><var>e</var>: will hold the public exponent
12973 </p>
12974 <p><var>d</var>: will hold the private exponent
12975 </p>
12976 <p><var>p</var>: will hold the first prime (p)
12977 </p>
12978 <p><var>q</var>: will hold the second prime (q)
12979 </p>
12980 <p><var>u</var>: will hold the coefficient
12981 </p>
12982 <p><var>bits</var>: if non null will hold the prime&rsquo;s number of bits
12983 </p>
12984 <p>This function will export the RSA parameters found in the given
12985 structure. The new parameters will be allocated using
12986 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
12987 </p>
12988 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an negative error code.
12989 </p></dd></dl>
12990
12991 <a name="gnutls_005frsa_005fparams_005fgenerate2-1"></a>
12992 <h4 class="subheading">gnutls_rsa_params_generate2</h4>
12993 <a name="gnutls_005frsa_005fparams_005fgenerate2"></a><dl>
12994 <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>
12995 <dd><p><var>params</var>: The structure where the parameters will be stored
12996 </p>
12997 <p><var>bits</var>: is the prime&rsquo;s number of bits
12998 </p>
12999 <p>This function will generate new temporary RSA parameters for use in
13000 RSA-EXPORT ciphersuites.  This function is normally slow.
13001 </p>
13002 <p>Note that if the parameters are to be used in export cipher suites the
13003 bits value should be 512 or less.
13004 Also note that the generation of new RSA parameters is only useful
13005 to servers. Clients use the parameters sent by the server, thus it&rsquo;s
13006 no use calling this in client side.
13007 </p>
13008 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an negative error code.
13009 </p></dd></dl>
13010
13011 <a name="gnutls_005frsa_005fparams_005fimport_005fpkcs1-1"></a>
13012 <h4 class="subheading">gnutls_rsa_params_import_pkcs1</h4>
13013 <a name="gnutls_005frsa_005fparams_005fimport_005fpkcs1"></a><dl>
13014 <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>
13015 <dd><p><var>params</var>: A structure where the parameters will be copied to
13016 </p>
13017 <p><var>pkcs1_params</var>: should contain a PKCS1 RSAPublicKey structure PEM or DER encoded
13018 </p>
13019 <p><var>format</var>: the format of params. PEM or DER.
13020 </p>
13021 <p>This function will extract the RSAPublicKey found in a PKCS1 formatted
13022 structure.
13023 </p>
13024 <p>If the structure is PEM encoded, it should have a header
13025 of &quot;BEGIN RSA PRIVATE KEY&quot;.
13026 </p>
13027 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an negative error code.
13028 </p></dd></dl>
13029
13030 <a name="gnutls_005frsa_005fparams_005fimport_005fraw-1"></a>
13031 <h4 class="subheading">gnutls_rsa_params_import_raw</h4>
13032 <a name="gnutls_005frsa_005fparams_005fimport_005fraw"></a><dl>
13033 <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>
13034 <dd><p><var>rsa_params</var>: Is a structure will hold the parameters
13035 </p>
13036 <p><var>m</var>: holds the modulus
13037 </p>
13038 <p><var>e</var>: holds the public exponent
13039 </p>
13040 <p><var>d</var>: holds the private exponent
13041 </p>
13042 <p><var>p</var>: holds the first prime (p)
13043 </p>
13044 <p><var>q</var>: holds the second prime (q)
13045 </p>
13046 <p><var>u</var>: holds the coefficient
13047 </p>
13048 <p>This function will replace the parameters in the given structure.
13049 The new parameters should be stored in the appropriate
13050 gnutls_datum.
13051 </p>
13052 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an negative error code.
13053 </p></dd></dl>
13054
13055 <a name="gnutls_005frsa_005fparams_005finit-1"></a>
13056 <h4 class="subheading">gnutls_rsa_params_init</h4>
13057 <a name="gnutls_005frsa_005fparams_005finit"></a><dl>
13058 <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>
13059 <dd><p><var>rsa_params</var>: Is a structure that will hold the parameters
13060 </p>
13061 <p>This function will initialize the temporary RSA parameters structure.
13062 </p>
13063 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an negative error code.
13064 </p></dd></dl>
13065
13066 <a name="gnutls_005fsafe_005frenegotiation_005fstatus-1"></a>
13067 <h4 class="subheading">gnutls_safe_renegotiation_status</h4>
13068 <a name="gnutls_005fsafe_005frenegotiation_005fstatus"></a><dl>
13069 <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>
13070 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13071 </p>
13072 <p>Can be used to check whether safe renegotiation is being used
13073 in the current session.
13074 </p>
13075 <p><strong>Returns:</strong> 0 when safe renegotiation is not used and non zero when
13076 safe renegotiation is used.
13077 </p>
13078 <p><strong>Since:</strong> 2.10.0
13079 </p></dd></dl>
13080
13081 <a name="gnutls_005fsec_005fparam_005fget_005fname-1"></a>
13082 <h4 class="subheading">gnutls_sec_param_get_name</h4>
13083 <a name="gnutls_005fsec_005fparam_005fget_005fname"></a><dl>
13084 <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>
13085 <dd><p><var>param</var>: is a security parameter
13086 </p>
13087 <p>Convert a <code>gnutls_sec_param_t</code> value to a string.
13088 </p>
13089 <p><strong>Returns:</strong> a pointer to a string that contains the name of the
13090 specified public key algorithm, or <code>NULL</code>.
13091 </p></dd></dl>
13092
13093 <a name="gnutls_005fsec_005fparam_005fto_005fpk_005fbits-1"></a>
13094 <h4 class="subheading">gnutls_sec_param_to_pk_bits</h4>
13095 <a name="gnutls_005fsec_005fparam_005fto_005fpk_005fbits"></a><dl>
13096 <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>
13097 <dd><p><var>algo</var>: is a public key algorithm
13098 </p>
13099 <p><var>param</var>: is a security parameter
13100 </p>
13101 <p>When generating private and public key pairs a difficult question
13102 is which size of &quot;bits&quot; the modulus will be in RSA and the group size
13103 in DSA. The easy answer is 1024, which is also wrong. This function
13104 will convert a human understandable security parameter to an
13105 appropriate size for the specific algorithm.
13106 </p>
13107 <p><strong>Returns:</strong> The number of bits, or zero.
13108 </p></dd></dl>
13109
13110 <a name="gnutls_005fserver_005fname_005fget-1"></a>
13111 <h4 class="subheading">gnutls_server_name_get</h4>
13112 <a name="gnutls_005fserver_005fname_005fget"></a><dl>
13113 <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>
13114 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13115 </p>
13116 <p><var>data</var>: will hold the data
13117 </p>
13118 <p><var>data_length</var>: will hold the data length. Must hold the maximum size of data.
13119 </p>
13120 <p><var>type</var>: will hold the server name indicator type
13121 </p>
13122 <p><var>indx</var>: is the index of the server_name
13123 </p>
13124 <p>This function will allow you to get the name indication (if any), a
13125 client has sent.  The name indication may be any of the enumeration
13126 gnutls_server_name_type_t.
13127 </p>
13128 <p>If <code>type</code> is GNUTLS_NAME_DNS, then this function is to be used by
13129 servers that support virtual hosting, and the data will be a null
13130 terminated UTF-8 string.
13131 </p>
13132 <p>If <code>data</code> has not enough size to hold the server name
13133 GNUTLS_E_SHORT_MEMORY_BUFFER is returned, and <code>data_length</code> will
13134 hold the required size.
13135 </p>
13136 <p><code>index</code> is used to retrieve more than one server names (if sent by
13137 the client).  The first server name has an index of 0, the second 1
13138 and so on.  If no name with the given index exists
13139 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE is returned.
13140 </p>
13141 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
13142 otherwise an error code is returned.
13143 </p></dd></dl>
13144
13145 <a name="gnutls_005fserver_005fname_005fset-1"></a>
13146 <h4 class="subheading">gnutls_server_name_set</h4>
13147 <a name="gnutls_005fserver_005fname_005fset"></a><dl>
13148 <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>
13149 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13150 </p>
13151 <p><var>type</var>: specifies the indicator type
13152 </p>
13153 <p><var>name</var>: is a string that contains the server name.
13154 </p>
13155 <p><var>name_length</var>: holds the length of name
13156 </p>
13157 <p>This function is to be used by clients that want to inform (via a
13158 TLS extension mechanism) the server of the name they connected to.
13159 This should be used by clients that connect to servers that do
13160 virtual hosting.
13161 </p>
13162 <p>The value of <code>name</code> depends on the <code>type</code> type.  In case of
13163 <code>GNUTLS_NAME_DNS</code>, an ASCII zero-terminated domain name string,
13164 without the trailing dot, is expected.  IPv4 or IPv6 addresses are
13165 not permitted.
13166 </p>
13167 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
13168 otherwise an error code is returned.
13169 </p></dd></dl>
13170
13171 <a name="gnutls_005fsession_005fchannel_005fbinding-1"></a>
13172 <h4 class="subheading">gnutls_session_channel_binding</h4>
13173 <a name="gnutls_005fsession_005fchannel_005fbinding"></a><dl>
13174 <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>
13175 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13176 </p>
13177 <p><var>cbtype</var>: an <code>gnutls_channel_binding_t</code> enumeration type
13178 </p>
13179 <p><var>cb</var>: output buffer array with data
13180 </p>
13181 <p>Extract given channel binding data of the <code>cbtype</code> (e.g.,
13182 <code>GNUTLS_CB_TLS_UNIQUE</code>) type.
13183 </p>
13184 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success,
13185 <code>GNUTLS_E_UNIMPLEMENTED_FEATURE</code> if the <code>cbtype</code> is unsupported,
13186 <code>GNUTLS_E_CHANNEL_BINDING_NOT_AVAILABLE</code> if the data is not
13187 currently available, or an error code.
13188 </p>
13189 <p><strong>Since:</strong> 2.12.0
13190 </p></dd></dl>
13191
13192 <a name="gnutls_005fsession_005fenable_005fcompatibility_005fmode-1"></a>
13193 <h4 class="subheading">gnutls_session_enable_compatibility_mode</h4>
13194 <a name="gnutls_005fsession_005fenable_005fcompatibility_005fmode"></a><dl>
13195 <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>
13196 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13197 </p>
13198 <p>This function can be used to disable certain (security) features in
13199 TLS in order to maintain maximum compatibility with buggy
13200 clients. It is equivalent to calling:
13201 <code>gnutls_record_disable_padding()</code>
13202 </p>
13203 <p>Normally only servers that require maximum compatibility with
13204 everything out there, need to call this function.
13205 </p></dd></dl>
13206
13207 <a name="gnutls_005fsession_005fget_005fdata2-1"></a>
13208 <h4 class="subheading">gnutls_session_get_data2</h4>
13209 <a name="gnutls_005fsession_005fget_005fdata2"></a><dl>
13210 <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>
13211 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13212 </p>
13213 <p><var>data</var>: is a pointer to a datum that will hold the session.
13214 </p>
13215 <p>Returns all session parameters, in order to support resuming.  The
13216 client should call this, and keep the returned session, if he wants
13217 to resume that current version later by calling
13218 <code>gnutls_session_set_data()</code>.  This function must be called after a
13219 successful handshake.  The returned datum must be freed with
13220 <code>gnutls_free()</code>.
13221 </p>
13222 <p>Resuming sessions is really useful and speedups connections after
13223 a successful one.
13224 </p>
13225 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
13226 an error code is returned.
13227 </p></dd></dl>
13228
13229 <a name="gnutls_005fsession_005fget_005fdata-1"></a>
13230 <h4 class="subheading">gnutls_session_get_data</h4>
13231 <a name="gnutls_005fsession_005fget_005fdata"></a><dl>
13232 <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>
13233 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13234 </p>
13235 <p><var>session_data</var>: is a pointer to space to hold the session.
13236 </p>
13237 <p><var>session_data_size</var>: is the session_data&rsquo;s size, or it will be set by the function.
13238 </p>
13239 <p>Returns all session parameters, in order to support resuming.  The
13240 client should call this, and keep the returned session, if he
13241 wants to resume that current version later by calling
13242 <code>gnutls_session_set_data()</code> This function must be called after a
13243 successful handshake.
13244 </p>
13245 <p>Resuming sessions is really useful and speedups connections after
13246 a successful one.
13247 </p>
13248 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
13249 an error code is returned.
13250 </p></dd></dl>
13251
13252 <a name="gnutls_005fsession_005fget_005fid-1"></a>
13253 <h4 class="subheading">gnutls_session_get_id</h4>
13254 <a name="gnutls_005fsession_005fget_005fid"></a><dl>
13255 <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>
13256 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13257 </p>
13258 <p><var>session_id</var>: is a pointer to space to hold the session id.
13259 </p>
13260 <p><var>session_id_size</var>: is the session id&rsquo;s size, or it will be set by the function.
13261 </p>
13262 <p>Returns the current session id. This can be used if you want to
13263 check if the next session you tried to resume was actually
13264 resumed.  This is because resumed sessions have the same sessionID
13265 with the original session.
13266 </p>
13267 <p>Session id is some data set by the server, that identify the
13268 current session.  In TLS 1.0 and SSL 3.0 session id is always less
13269 than 32 bytes.
13270 </p>
13271 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
13272 an error code is returned.
13273 </p></dd></dl>
13274
13275 <a name="gnutls_005fsession_005fget_005fptr-1"></a>
13276 <h4 class="subheading">gnutls_session_get_ptr</h4>
13277 <a name="gnutls_005fsession_005fget_005fptr"></a><dl>
13278 <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>
13279 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13280 </p>
13281 <p>Get user pointer for session.  Useful in callbacks.  This is the
13282 pointer set with <code>gnutls_session_set_ptr()</code>.
13283 </p>
13284 <p><strong>Returns:</strong> the user given pointer from the session structure, or
13285 <code>NULL</code> if it was never set.
13286 </p></dd></dl>
13287
13288 <a name="gnutls_005fsession_005fis_005fresumed-1"></a>
13289 <h4 class="subheading">gnutls_session_is_resumed</h4>
13290 <a name="gnutls_005fsession_005fis_005fresumed"></a><dl>
13291 <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>
13292 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13293 </p>
13294 <p>Check whether session is resumed or not.
13295 </p>
13296 <p><strong>Returns:</strong> non zero if this session is resumed, or a zero if this is
13297 a new session.
13298 </p></dd></dl>
13299
13300 <a name="gnutls_005fsession_005fset_005fdata-1"></a>
13301 <h4 class="subheading">gnutls_session_set_data</h4>
13302 <a name="gnutls_005fsession_005fset_005fdata"></a><dl>
13303 <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>
13304 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13305 </p>
13306 <p><var>session_data</var>: is a pointer to space to hold the session.
13307 </p>
13308 <p><var>session_data_size</var>: is the session&rsquo;s size
13309 </p>
13310 <p>Sets all session parameters, in order to resume a previously
13311 established session.  The session data given must be the one
13312 returned by <code>gnutls_session_get_data()</code>.  This function should be
13313 called before <code>gnutls_handshake()</code>.
13314 </p>
13315 <p>Keep in mind that session resuming is advisory. The server may
13316 choose not to resume the session, thus a full handshake will be
13317 performed.
13318 </p>
13319 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
13320 an error code is returned.
13321 </p></dd></dl>
13322
13323 <a name="gnutls_005fsession_005fset_005fptr-1"></a>
13324 <h4 class="subheading">gnutls_session_set_ptr</h4>
13325 <a name="gnutls_005fsession_005fset_005fptr"></a><dl>
13326 <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>
13327 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13328 </p>
13329 <p><var>ptr</var>: is the user pointer
13330 </p>
13331 <p>This function will set (associate) the user given pointer <code>ptr</code> to
13332 the session structure.  This is pointer can be accessed with
13333 <code>gnutls_session_get_ptr()</code>.
13334 </p></dd></dl>
13335
13336 <a name="gnutls_005fsession_005fticket_005fenable_005fclient-1"></a>
13337 <h4 class="subheading">gnutls_session_ticket_enable_client</h4>
13338 <a name="gnutls_005fsession_005fticket_005fenable_005fclient"></a><dl>
13339 <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>
13340 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13341 </p>
13342 <p>Request that the client should attempt session resumption using
13343 SessionTicket.
13344 </p>
13345 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, or an
13346 error code.
13347 </p>
13348 <p><strong>Since:</strong> 2.10.0
13349 </p></dd></dl>
13350
13351 <a name="gnutls_005fsession_005fticket_005fenable_005fserver-1"></a>
13352 <h4 class="subheading">gnutls_session_ticket_enable_server</h4>
13353 <a name="gnutls_005fsession_005fticket_005fenable_005fserver"></a><dl>
13354 <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>
13355 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13356 </p>
13357 <p><var>key</var>: key to encrypt session parameters.
13358 </p>
13359 <p>Request that the server should attempt session resumption using
13360 SessionTicket.  <code>key</code> must be initialized with
13361 <code>gnutls_session_ticket_key_generate()</code>.
13362 </p>
13363 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, or an
13364 error code.
13365 </p>
13366 <p><strong>Since:</strong> 2.10.0
13367 </p></dd></dl>
13368
13369 <a name="gnutls_005fsession_005fticket_005fkey_005fgenerate-1"></a>
13370 <h4 class="subheading">gnutls_session_ticket_key_generate</h4>
13371 <a name="gnutls_005fsession_005fticket_005fkey_005fgenerate"></a><dl>
13372 <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>
13373 <dd><p><var>key</var>: is a pointer to a <code>gnutls_datum_t</code> which will contain a newly
13374 created key.
13375 </p>
13376 <p>Generate a random key to encrypt security parameters within
13377 SessionTicket.
13378 </p>
13379 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, or an
13380 error code.
13381 </p>
13382 <p><strong>Since:</strong> 2.10.0
13383 </p></dd></dl>
13384
13385 <a name="gnutls_005fset_005fdefault_005fexport_005fpriority-1"></a>
13386 <h4 class="subheading">gnutls_set_default_export_priority</h4>
13387 <a name="gnutls_005fset_005fdefault_005fexport_005fpriority"></a><dl>
13388 <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>
13389 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13390 </p>
13391 <p>Sets some default priority on the ciphers, key exchange methods, macs
13392 and compression methods.  This function also includes weak algorithms.
13393 </p>
13394 <p><strong>This is the same as calling:</strong>
13395 gnutls_priority_set_direct (session, &quot;EXPORT&quot;, NULL);
13396 </p>
13397 <p>This function is kept around for backwards compatibility, but
13398 because of its wide use it is still fully supported.  If you wish
13399 to allow users to provide a string that specify which ciphers to
13400 use (which is recommended), you should use
13401 <code>gnutls_priority_set_direct()</code> or <code>gnutls_priority_set()</code> instead.
13402 </p>
13403 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
13404 </p></dd></dl>
13405
13406 <a name="gnutls_005fset_005fdefault_005fpriority-1"></a>
13407 <h4 class="subheading">gnutls_set_default_priority</h4>
13408 <a name="gnutls_005fset_005fdefault_005fpriority"></a><dl>
13409 <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>
13410 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13411 </p>
13412 <p>Sets some default priority on the ciphers, key exchange methods,
13413 macs and compression methods.
13414 </p>
13415 <p><strong>This is the same as calling:</strong>
13416 gnutls_priority_set_direct (session, &quot;NORMAL&quot;, NULL);
13417 </p>
13418 <p>This function is kept around for backwards compatibility, but
13419 because of its wide use it is still fully supported.  If you wish
13420 to allow users to provide a string that specify which ciphers to
13421 use (which is recommended), you should use
13422 <code>gnutls_priority_set_direct()</code> or <code>gnutls_priority_set()</code> instead.
13423 </p>
13424 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
13425 </p></dd></dl>
13426
13427 <a name="gnutls_005fsign_005falgorithm_005fget_005fname-1"></a>
13428 <h4 class="subheading">gnutls_sign_algorithm_get_name</h4>
13429 <a name="gnutls_005fsign_005falgorithm_005fget_005fname"></a><dl>
13430 <dt><a name="index-gnutls_005fsign_005falgorithm_005fget_005fname"></a>Function: <em>const char *</em> <strong>gnutls_sign_algorithm_get_name</strong> <em>(gnutls_sign_algorithm_t <var>sign</var>)</em></dt>
13431 <dd><p><var>sign</var>: is a sign algorithm
13432 </p>
13433 <p>Convert a <code>gnutls_sign_algorithm_t</code> value to a string.
13434 </p>
13435 <p><strong>Returns:</strong> a string that contains the name of the specified sign
13436 algorithm, or <code>NULL</code>.
13437 </p></dd></dl>
13438
13439 <a name="gnutls_005fsign_005falgorithm_005fget_005frequested-1"></a>
13440 <h4 class="subheading">gnutls_sign_algorithm_get_requested</h4>
13441 <a name="gnutls_005fsign_005falgorithm_005fget_005frequested"></a><dl>
13442 <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>
13443 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13444 </p>
13445 <p><var>indx</var>: is an index of the signature algorithm to return
13446 </p>
13447 <p><var>algo</var>: the returned certificate type will be stored there
13448 </p>
13449 <p>Returns the signature algorithm specified by index that was
13450 requested by the peer. If the specified index has no data available
13451 this function returns <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>.  If
13452 the negotiated TLS version does not support signature algorithms
13453 then <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> will be returned even
13454 for the first index.  The first index is 0.
13455 </p>
13456 <p>This function is useful in the certificate callback functions
13457 to assist in selecting the correct certificate.
13458 </p>
13459 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
13460 an error code is returned.
13461 </p>
13462 <p><strong>Since:</strong> 2.10.0
13463 </p></dd></dl>
13464
13465 <a name="gnutls_005fsign_005fcallback_005fget-1"></a>
13466 <h4 class="subheading">gnutls_sign_callback_get</h4>
13467 <a name="gnutls_005fsign_005fcallback_005fget"></a><dl>
13468 <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>
13469 <dd><p><var>session</var>: is a gnutls session
13470 </p>
13471 <p><var>userdata</var>: if non-<code>NULL</code>, will be set to abstract callback pointer.
13472 </p>
13473 <p>Retrieve the callback function, and its userdata pointer.
13474 </p>
13475 <p><strong>Returns:</strong> The function pointer set by <code>gnutls_sign_callback_set()</code>, or
13476 if not set, <code>NULL</code>.
13477 </p>
13478 <p><strong>Deprecated:</strong> Use the PKCS 11 interfaces instead.
13479 </p></dd></dl>
13480
13481 <a name="gnutls_005fsign_005fcallback_005fset-1"></a>
13482 <h4 class="subheading">gnutls_sign_callback_set</h4>
13483 <a name="gnutls_005fsign_005fcallback_005fset"></a><dl>
13484 <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>
13485 <dd><p><var>session</var>: is a gnutls session
13486 </p>
13487 <p><var>sign_func</var>: function pointer to application&rsquo;s sign callback.
13488 </p>
13489 <p><var>userdata</var>: void pointer that will be passed to sign callback.
13490 </p>
13491 <p>Set the callback function.  The function must have this prototype:
13492 </p>
13493 <p>typedef int (*gnutls_sign_func) (gnutls_session_t session,
13494 void *userdata,
13495 gnutls_certificate_type_t cert_type,
13496 const gnutls_datum_t * cert,
13497 const gnutls_datum_t * hash,
13498 gnutls_datum_t * signature);
13499 </p>
13500 <p>The <code>userdata</code> parameter is passed to the <code>sign_func</code> verbatim, and
13501 can be used to store application-specific data needed in the
13502 callback function.  See also <code>gnutls_sign_callback_get()</code>.
13503 </p>
13504 <p><strong>Deprecated:</strong> Use the PKCS 11 interfaces instead.
13505 </p></dd></dl>
13506
13507 <a name="gnutls_005fsign_005fget_005fid-1"></a>
13508 <h4 class="subheading">gnutls_sign_get_id</h4>
13509 <a name="gnutls_005fsign_005fget_005fid"></a><dl>
13510 <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>
13511 <dd><p><var>name</var>: is a MAC algorithm name
13512 </p>
13513 <p>The names are compared in a case insensitive way.
13514 </p>
13515 <p><strong>Returns:</strong> return a <code>gnutls_sign_algorithm_t</code> value corresponding to
13516 the specified cipher, or <code>GNUTLS_SIGN_UNKNOWN</code> on error.
13517 </p></dd></dl>
13518
13519 <a name="gnutls_005fsign_005fget_005fname-1"></a>
13520 <h4 class="subheading">gnutls_sign_get_name</h4>
13521 <a name="gnutls_005fsign_005fget_005fname"></a><dl>
13522 <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>
13523 <dd><p><var>algorithm</var>: is a public key signature algorithm
13524 </p>
13525 <p>Convert a <code>gnutls_sign_algorithm_t</code> value to a string.
13526 </p>
13527 <p><strong>Returns:</strong> a pointer to a string that contains the name of the
13528 specified public key signature algorithm, or <code>NULL</code>.
13529 </p>
13530 <p><strong>Since:</strong> 2.6.0
13531 </p></dd></dl>
13532
13533 <a name="gnutls_005fsign_005flist-1"></a>
13534 <h4 class="subheading">gnutls_sign_list</h4>
13535 <a name="gnutls_005fsign_005flist"></a><dl>
13536 <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>
13537 <dd>
13538 <p>Get a list of supported public key signature algorithms.
13539 </p>
13540 <p><strong>Returns:</strong> a zero-terminated list of <code>gnutls_sign_algorithm_t</code>
13541 integers indicating the available ciphers.
13542 </p></dd></dl>
13543
13544 <a name="gnutls_005fsrp_005fallocate_005fclient_005fcredentials-1"></a>
13545 <h4 class="subheading">gnutls_srp_allocate_client_credentials</h4>
13546 <a name="gnutls_005fsrp_005fallocate_005fclient_005fcredentials"></a><dl>
13547 <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>
13548 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_srp_server_credentials_t</code> structure.
13549 </p>
13550 <p>This structure is complex enough to manipulate directly thus
13551 this helper function is provided in order to allocate it.
13552 </p>
13553 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, or an
13554 error code.
13555 </p></dd></dl>
13556
13557 <a name="gnutls_005fsrp_005fallocate_005fserver_005fcredentials-1"></a>
13558 <h4 class="subheading">gnutls_srp_allocate_server_credentials</h4>
13559 <a name="gnutls_005fsrp_005fallocate_005fserver_005fcredentials"></a><dl>
13560 <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>
13561 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_srp_server_credentials_t</code> structure.
13562 </p>
13563 <p>This structure is complex enough to manipulate directly thus this
13564 helper function is provided in order to allocate it.
13565 </p>
13566 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, or an
13567 error code.
13568 </p></dd></dl>
13569
13570 <a name="gnutls_005fsrp_005fbase64_005fdecode_005falloc-1"></a>
13571 <h4 class="subheading">gnutls_srp_base64_decode_alloc</h4>
13572 <a name="gnutls_005fsrp_005fbase64_005fdecode_005falloc"></a><dl>
13573 <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>
13574 <dd><p><var>b64_data</var>: contains the encoded data
13575 </p>
13576 <p><var>result</var>: the place where decoded data lie
13577 </p>
13578 <p>This function will decode the given encoded data. The decoded data
13579 will be allocated, and stored into result.  It will decode using
13580 the base64 algorithm as used in libsrp.
13581 </p>
13582 <p>You should use <code>gnutls_free()</code> to free the returned data.
13583 </p>
13584 <p>Warning!  This base64 encoding is not the &quot;standard&quot; encoding, so
13585 do not use it for non-SRP purposes.
13586 </p>
13587 <p><strong>Returns:</strong> 0 on success, or an error code.
13588 </p></dd></dl>
13589
13590 <a name="gnutls_005fsrp_005fbase64_005fdecode-1"></a>
13591 <h4 class="subheading">gnutls_srp_base64_decode</h4>
13592 <a name="gnutls_005fsrp_005fbase64_005fdecode"></a><dl>
13593 <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>
13594 <dd><p><var>b64_data</var>: contain the encoded data
13595 </p>
13596 <p><var>result</var>: the place where decoded data will be copied
13597 </p>
13598 <p><var>result_size</var>: holds the size of the result
13599 </p>
13600 <p>This function will decode the given encoded data, using the base64
13601 encoding found in libsrp.
13602 </p>
13603 <p>Note that <code>b64_data</code> should be null terminated.
13604 </p>
13605 <p>Warning!  This base64 encoding is not the &quot;standard&quot; encoding, so
13606 do not use it for non-SRP purposes.
13607 </p>
13608 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the buffer given is not
13609 long enough, or 0 on success.
13610 </p></dd></dl>
13611
13612 <a name="gnutls_005fsrp_005fbase64_005fencode_005falloc-1"></a>
13613 <h4 class="subheading">gnutls_srp_base64_encode_alloc</h4>
13614 <a name="gnutls_005fsrp_005fbase64_005fencode_005falloc"></a><dl>
13615 <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>
13616 <dd><p><var>data</var>: contains the raw data
13617 </p>
13618 <p><var>result</var>: will hold the newly allocated encoded data
13619 </p>
13620 <p>This function will convert the given data to printable data, using
13621 the base64 encoding.  This is the encoding used in SRP password
13622 files.  This function will allocate the required memory to hold
13623 the encoded data.
13624 </p>
13625 <p>You should use <code>gnutls_free()</code> to free the returned data.
13626 </p>
13627 <p>Warning!  This base64 encoding is not the &quot;standard&quot; encoding, so
13628 do not use it for non-SRP purposes.
13629 </p>
13630 <p><strong>Returns:</strong> 0 on success, or an error code.
13631 </p></dd></dl>
13632 <a name="gnutls_005fsrp_005fbase64_005fencode-1"></a>
13633 <h4 class="subheading">gnutls_srp_base64_encode</h4>
13634 <a name="gnutls_005fsrp_005fbase64_005fencode"></a><dl>
13635 <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>
13636 <dd><p><var>data</var>: contain the raw data
13637 </p>
13638 <p><var>result</var>: the place where base64 data will be copied
13639 </p>
13640 <p><var>result_size</var>: holds the size of the result
13641 </p>
13642 <p>This function will convert the given data to printable data, using
13643 the base64 encoding, as used in the libsrp.  This is the encoding
13644 used in SRP password files.  If the provided buffer is not long
13645 enough GNUTLS_E_SHORT_MEMORY_BUFFER is returned.
13646 </p>
13647 <p>Warning!  This base64 encoding is not the &quot;standard&quot; encoding, so
13648 do not use it for non-SRP purposes.
13649 </p>
13650 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the buffer given is not
13651 long enough, or 0 on success.
13652 </p></dd></dl>
13653
13654 <a name="gnutls_005fsrp_005ffree_005fclient_005fcredentials-1"></a>
13655 <h4 class="subheading">gnutls_srp_free_client_credentials</h4>
13656 <a name="gnutls_005fsrp_005ffree_005fclient_005fcredentials"></a><dl>
13657 <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>
13658 <dd><p><var>sc</var>: is a <code>gnutls_srp_client_credentials_t</code> structure.
13659 </p>
13660 <p>This structure is complex enough to manipulate directly thus
13661 this helper function is provided in order to free (deallocate) it.
13662 </p></dd></dl>
13663
13664 <a name="gnutls_005fsrp_005ffree_005fserver_005fcredentials-1"></a>
13665 <h4 class="subheading">gnutls_srp_free_server_credentials</h4>
13666 <a name="gnutls_005fsrp_005ffree_005fserver_005fcredentials"></a><dl>
13667 <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>
13668 <dd><p><var>sc</var>: is a <code>gnutls_srp_server_credentials_t</code> structure.
13669 </p>
13670 <p>This structure is complex enough to manipulate directly thus
13671 this helper function is provided in order to free (deallocate) it.
13672 </p></dd></dl>
13673
13674 <a name="gnutls_005fsrp_005fserver_005fget_005fusername-1"></a>
13675 <h4 class="subheading">gnutls_srp_server_get_username</h4>
13676 <a name="gnutls_005fsrp_005fserver_005fget_005fusername"></a><dl>
13677 <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>
13678 <dd><p><var>session</var>: is a gnutls session
13679 </p>
13680 <p>This function will return the username of the peer.  This should
13681 only be called in case of SRP authentication and in case of a
13682 server.  Returns NULL in case of an error.
13683 </p>
13684 <p><strong>Returns:</strong> SRP username of the peer, or NULL in case of error.
13685 </p></dd></dl>
13686
13687 <a name="gnutls_005fsrp_005fset_005fclient_005fcredentials_005ffunction-1"></a>
13688 <h4 class="subheading">gnutls_srp_set_client_credentials_function</h4>
13689 <a name="gnutls_005fsrp_005fset_005fclient_005fcredentials_005ffunction"></a><dl>
13690 <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>
13691 <dd><p><var>cred</var>: is a <code>gnutls_srp_server_credentials_t</code> structure.
13692 </p>
13693 <p><var>func</var>: is the callback function
13694 </p>
13695 <p>This function can be used to set a callback to retrieve the
13696 username and password for client SRP authentication.  The
13697 callback&rsquo;s function form is:
13698 </p>
13699 <p>int (*callback)(gnutls_session_t, char** username, char**password);
13700 </p>
13701 <p>The <code>username</code> and <code>password</code> must be allocated using
13702 <code>gnutls_malloc()</code>.  <code>username</code> and <code>password</code> should be ASCII strings
13703 or UTF-8 strings prepared using the &quot;SASLprep&quot; profile of
13704 &quot;stringprep&quot;.
13705 </p>
13706 <p>The callback function will be called once per handshake before the
13707 initial hello message is sent.
13708 </p>
13709 <p>The callback should not return a negative error code the second
13710 time called, since the handshake procedure will be aborted.
13711 </p>
13712 <p>The callback function should return 0 on success.
13713 -1 indicates an error.
13714 </p></dd></dl>
13715
13716 <a name="gnutls_005fsrp_005fset_005fclient_005fcredentials-1"></a>
13717 <h4 class="subheading">gnutls_srp_set_client_credentials</h4>
13718 <a name="gnutls_005fsrp_005fset_005fclient_005fcredentials"></a><dl>
13719 <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>
13720 <dd><p><var>res</var>: is a <code>gnutls_srp_client_credentials_t</code> structure.
13721 </p>
13722 <p><var>username</var>: is the user&rsquo;s userid
13723 </p>
13724 <p><var>password</var>: is the user&rsquo;s password
13725 </p>
13726 <p>This function sets the username and password, in a
13727 <code>gnutls_srp_client_credentials_t</code> structure.  Those will be used in
13728 SRP authentication.  <code>username</code> and <code>password</code> should be ASCII
13729 strings or UTF-8 strings prepared using the &quot;SASLprep&quot; profile of
13730 &quot;stringprep&quot;.
13731 </p>
13732 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, or an
13733 error code.
13734 </p></dd></dl>
13735
13736 <a name="gnutls_005fsrp_005fset_005fprime_005fbits-1"></a>
13737 <h4 class="subheading">gnutls_srp_set_prime_bits</h4>
13738 <a name="gnutls_005fsrp_005fset_005fprime_005fbits"></a><dl>
13739 <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>
13740 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13741 </p>
13742 <p><var>bits</var>: is the number of bits
13743 </p>
13744 <p>This function sets the minimum accepted number of bits, for use in
13745 an SRP key exchange.  If zero, the default 2048 bits will be used.
13746 </p>
13747 <p>In the client side it sets the minimum accepted number of bits.  If
13748 a server sends a prime with less bits than that
13749 <code>GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER</code> will be returned by the
13750 handshake.
13751 </p>
13752 <p>This function has no effect in server side.
13753 </p>
13754 <p><strong>Since:</strong> 2.6.0
13755 </p></dd></dl>
13756
13757 <a name="gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffile-1"></a>
13758 <h4 class="subheading">gnutls_srp_set_server_credentials_file</h4>
13759 <a name="gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffile"></a><dl>
13760 <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>
13761 <dd><p><var>res</var>: is a <code>gnutls_srp_server_credentials_t</code> structure.
13762 </p>
13763 <p><var>password_file</var>: is the SRP password file (tpasswd)
13764 </p>
13765 <p><var>password_conf_file</var>: is the SRP password conf file (tpasswd.conf)
13766 </p>
13767 <p>This function sets the password files, in a
13768 <code>gnutls_srp_server_credentials_t</code> structure.  Those password files
13769 hold usernames and verifiers and will be used for SRP
13770 authentication.
13771 </p>
13772 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, or an
13773 error code.
13774 </p></dd></dl>
13775
13776 <a name="gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffunction-1"></a>
13777 <h4 class="subheading">gnutls_srp_set_server_credentials_function</h4>
13778 <a name="gnutls_005fsrp_005fset_005fserver_005fcredentials_005ffunction"></a><dl>
13779 <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>
13780 <dd><p><var>cred</var>: is a <code>gnutls_srp_server_credentials_t</code> structure.
13781 </p>
13782 <p><var>func</var>: is the callback function
13783 </p>
13784 <p>This function can be used to set a callback to retrieve the user&rsquo;s
13785 SRP credentials.  The callback&rsquo;s function form is:
13786 </p>
13787 <p>int (*callback)(gnutls_session_t, const char* username,
13788 gnutls_datum_t* salt, gnutls_datum_t *verifier, gnutls_datum_t* g,
13789 gnutls_datum_t* n);
13790 </p>
13791 <p><code>username</code> contains the actual username.
13792 The <code>salt</code>, <code>verifier</code>, <code>generator</code> and <code>prime</code> must be filled
13793 in using the <code>gnutls_malloc()</code>. For convenience <code>prime</code> and <code>generator</code>
13794 may also be one of the static parameters defined in extra.h.
13795 </p>
13796 <p>In case the callback returned a negative number then gnutls will
13797 assume that the username does not exist.
13798 </p>
13799 <p>In order to prevent attackers from guessing valid usernames,
13800 if a user does not exist, g and n values should be filled in
13801 using a random user&rsquo;s parameters. In that case the callback must
13802 return the special value (1).
13803 </p>
13804 <p>The callback function will only be called once per handshake.
13805 The callback function should return 0 on success, while
13806 -1 indicates an error.
13807 </p></dd></dl>
13808
13809 <a name="gnutls_005fsrp_005fverifier-1"></a>
13810 <h4 class="subheading">gnutls_srp_verifier</h4>
13811 <a name="gnutls_005fsrp_005fverifier"></a><dl>
13812 <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>
13813 <dd><p><var>username</var>: is the user&rsquo;s name
13814 </p>
13815 <p><var>password</var>: is the user&rsquo;s password
13816 </p>
13817 <p><var>salt</var>: should be some randomly generated bytes
13818 </p>
13819 <p><var>generator</var>: is the generator of the group
13820 </p>
13821 <p><var>prime</var>: is the group&rsquo;s prime
13822 </p>
13823 <p><var>res</var>: where the verifier will be stored.
13824 </p>
13825 <p>This function will create an SRP verifier, as specified in
13826 RFC2945.  The <code>prime</code> and <code>generator</code> should be one of the static
13827 parameters defined in gnutls/extra.h or may be generated using the
13828 libgcrypt functions <code>gcry_prime_generate()</code> and
13829 <code>gcry_prime_group_generator()</code>.
13830 </p>
13831 <p>The verifier will be allocated with <code>malloc</code> and will be stored in
13832 <code>res</code> using binary format.
13833 </p>
13834 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, or an
13835 error code.
13836 </p></dd></dl>
13837
13838 <a name="gnutls_005fstrerror_005fname-1"></a>
13839 <h4 class="subheading">gnutls_strerror_name</h4>
13840 <a name="gnutls_005fstrerror_005fname"></a><dl>
13841 <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>
13842 <dd><p><var>error</var>: is an error returned by a gnutls function.
13843 </p>
13844 <p>Return the GnuTLS error code define as a string.  For example,
13845 gnutls_strerror_name (GNUTLS_E_DH_PRIME_UNACCEPTABLE) will return
13846 the string &quot;GNUTLS_E_DH_PRIME_UNACCEPTABLE&quot;.
13847 </p>
13848 <p><strong>Returns:</strong> A string corresponding to the symbol name of the error
13849 code.
13850 </p>
13851 <p><strong>Since:</strong> 2.6.0
13852 </p></dd></dl>
13853
13854 <a name="gnutls_005fstrerror-1"></a>
13855 <h4 class="subheading">gnutls_strerror</h4>
13856 <a name="gnutls_005fstrerror"></a><dl>
13857 <dt><a name="index-gnutls_005fstrerror"></a>Function: <em>const char *</em> <strong>gnutls_strerror</strong> <em>(int <var>error</var>)</em></dt>
13858 <dd><p><var>error</var>: is a GnuTLS error code, a negative value
13859 </p>
13860 <p>This function is similar to strerror.  The difference is that it
13861 accepts an error number returned by a gnutls function; In case of
13862 an unknown error a descriptive string is sent instead of <code>NULL</code>.
13863 </p>
13864 <p>Error codes are always a negative value.
13865 </p>
13866 <p><strong>Returns:</strong> A string explaining the GnuTLS error message.
13867 </p></dd></dl>
13868
13869 <a name="gnutls_005fsupplemental_005fget_005fname-1"></a>
13870 <h4 class="subheading">gnutls_supplemental_get_name</h4>
13871 <a name="gnutls_005fsupplemental_005fget_005fname"></a><dl>
13872 <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>
13873 <dd><p><var>type</var>: is a supplemental data format type
13874 </p>
13875 <p>Convert a <code>gnutls_supplemental_data_format_type_t</code> value to a
13876 string.
13877 </p>
13878 <p><strong>Returns:</strong> a string that contains the name of the specified
13879 supplemental data format type, or <code>NULL</code> for unknown types.
13880 </p></dd></dl>
13881
13882 <a name="gnutls_005ftransport_005fget_005fptr2-1"></a>
13883 <h4 class="subheading">gnutls_transport_get_ptr2</h4>
13884 <a name="gnutls_005ftransport_005fget_005fptr2"></a><dl>
13885 <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>
13886 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13887 </p>
13888 <p><var>recv_ptr</var>: will hold the value for the pull function
13889 </p>
13890 <p><var>send_ptr</var>: will hold the value for the push function
13891 </p>
13892 <p>Used to get the arguments of the transport functions (like PUSH
13893 and PULL).  These should have been set using
13894 <code>gnutls_transport_set_ptr2()</code>.
13895 </p></dd></dl>
13896
13897 <a name="gnutls_005ftransport_005fget_005fptr-1"></a>
13898 <h4 class="subheading">gnutls_transport_get_ptr</h4>
13899 <a name="gnutls_005ftransport_005fget_005fptr"></a><dl>
13900 <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>
13901 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13902 </p>
13903 <p>Used to get the first argument of the transport function (like
13904 PUSH and PULL).  This must have been set using
13905 <code>gnutls_transport_set_ptr()</code>.
13906 </p>
13907 <p><strong>Returns:</strong> first argument of the transport function.
13908 </p></dd></dl>
13909
13910 <a name="gnutls_005ftransport_005fset_005ferrno_005ffunction-1"></a>
13911 <h4 class="subheading">gnutls_transport_set_errno_function</h4>
13912 <a name="gnutls_005ftransport_005fset_005ferrno_005ffunction"></a><dl>
13913 <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>
13914 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13915 </p>
13916 <p><var>errno_func</var>: a callback function similar to <code>write()</code>
13917 </p>
13918 <p>This is the function where you set a function to retrieve errno
13919 after a failed push or pull operation.
13920 </p>
13921 <p>errno_func is of the form,
13922 int (*gnutls_errno_func)(gnutls_transport_ptr_t);
13923 and should return the errno.
13924 </p></dd></dl>
13925
13926 <a name="gnutls_005ftransport_005fset_005ferrno-1"></a>
13927 <h4 class="subheading">gnutls_transport_set_errno</h4>
13928 <a name="gnutls_005ftransport_005fset_005ferrno"></a><dl>
13929 <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>
13930 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13931 </p>
13932 <p><var>err</var>: error value to store in session-specific errno variable.
13933 </p>
13934 <p>Store <code>err</code> in the session-specific errno variable.  Useful values
13935 for <code>err</code> is EAGAIN and EINTR, other values are treated will be
13936 treated as real errors in the push/pull function.
13937 </p>
13938 <p>This function is useful in replacement push/pull functions set by
13939 gnutls_transport_set_push_function and
13940 gnutls_transport_set_pullpush_function under Windows, where the
13941 replacement push/pull may not have access to the same <code>errno</code>
13942 variable that is used by GnuTLS (e.g., the application is linked to
13943 msvcr71.dll and gnutls is linked to msvcrt.dll).
13944 </p>
13945 <p>If you don&rsquo;t have the <code>session</code> variable easily accessible from the
13946 push/pull function, and don&rsquo;t worry about thread conflicts, you can
13947 also use <code>gnutls_transport_set_global_errno()</code>.
13948 </p></dd></dl>
13949
13950 <a name="gnutls_005ftransport_005fset_005fglobal_005ferrno-1"></a>
13951 <h4 class="subheading">gnutls_transport_set_global_errno</h4>
13952 <a name="gnutls_005ftransport_005fset_005fglobal_005ferrno"></a><dl>
13953 <dt><a name="index-gnutls_005ftransport_005fset_005fglobal_005ferrno"></a>Function: <em>void</em> <strong>gnutls_transport_set_global_errno</strong> <em>(int <var>err</var>)</em></dt>
13954 <dd><p><var>err</var>: error value to store in global errno variable.
13955 </p>
13956 <p>Store <code>err</code> in the global errno variable.  Useful values for <code>err</code> is
13957 EAGAIN and EINTR, other values are treated will be treated as real
13958 errors in the push/pull function.
13959 </p>
13960 <p>This function is useful in replacement push/pull functions set by
13961 gnutls_transport_set_push_function and
13962 gnutls_transport_set_pullpush_function under Windows, where the
13963 replacement push/pull may not have access to the same <code>errno</code>
13964 variable that is used by GnuTLS (e.g., the application is linked to
13965 msvcr71.dll and gnutls is linked to msvcrt.dll).
13966 </p>
13967 <p>Whether this function is thread safe or not depends on whether the
13968 global variable errno is thread safe, some system libraries make it
13969 a thread-local variable.  When feasible, using the guaranteed
13970 thread-safe <code>gnutls_transport_set_errno()</code> may be better.
13971 </p></dd></dl>
13972
13973 <a name="gnutls_005ftransport_005fset_005flowat-1"></a>
13974 <h4 class="subheading">gnutls_transport_set_lowat</h4>
13975 <a name="gnutls_005ftransport_005fset_005flowat"></a><dl>
13976 <dt><a name="index-gnutls_005ftransport_005fset_005flowat"></a>Function: <em>void</em> <strong>gnutls_transport_set_lowat</strong> <em>(gnutls_session_t <var>session</var>, int <var>num</var>)</em></dt>
13977 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13978 </p>
13979 <p><var>num</var>: is the low water value.
13980 </p>
13981 <p>Used to set the lowat value in order for select to check if there
13982 are pending data to socket buffer. Used only if you have changed
13983 the default low water value (default is 1).  Normally you will not
13984 need that function.  This function is only useful if using
13985 berkeley style sockets.  Otherwise it must be called and set lowat
13986 to zero.
13987 </p></dd></dl>
13988
13989 <a name="gnutls_005ftransport_005fset_005fptr2-1"></a>
13990 <h4 class="subheading">gnutls_transport_set_ptr2</h4>
13991 <a name="gnutls_005ftransport_005fset_005fptr2"></a><dl>
13992 <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>
13993 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
13994 </p>
13995 <p><var>recv_ptr</var>: is the value for the pull function
13996 </p>
13997 <p><var>send_ptr</var>: is the value for the push function
13998 </p>
13999 <p>Used to set the first argument of the transport function (like PUSH
14000 and PULL). In berkeley style sockets this function will set the
14001 connection handle.  With this function you can use two different
14002 pointers for receiving and sending.
14003 </p></dd></dl>
14004
14005 <a name="gnutls_005ftransport_005fset_005fptr-1"></a>
14006 <h4 class="subheading">gnutls_transport_set_ptr</h4>
14007 <a name="gnutls_005ftransport_005fset_005fptr"></a><dl>
14008 <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>
14009 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
14010 </p>
14011 <p><var>ptr</var>: is the value.
14012 </p>
14013 <p>Used to set the first argument of the transport function (like PUSH
14014 and PULL).  In berkeley style sockets this function will set the
14015 connection handle.
14016 </p></dd></dl>
14017
14018 <a name="gnutls_005ftransport_005fset_005fpull_005ffunction-1"></a>
14019 <h4 class="subheading">gnutls_transport_set_pull_function</h4>
14020 <a name="gnutls_005ftransport_005fset_005fpull_005ffunction"></a><dl>
14021 <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>
14022 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
14023 </p>
14024 <p><var>pull_func</var>: a callback function similar to <code>read()</code>
14025 </p>
14026 <p>This is the function where you set a function for gnutls to receive
14027 data.  Normally, if you use berkeley style sockets, do not need to
14028 use this function since the default (recv(2)) will probably be ok.
14029 </p>
14030 <p>PULL_FUNC is of the form,
14031 ssize_t (*gnutls_pull_func)(gnutls_transport_ptr_t, void*, size_t);
14032 </p></dd></dl>
14033
14034 <a name="gnutls_005ftransport_005fset_005fpush_005ffunction-1"></a>
14035 <h4 class="subheading">gnutls_transport_set_push_function</h4>
14036 <a name="gnutls_005ftransport_005fset_005fpush_005ffunction"></a><dl>
14037 <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>
14038 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
14039 </p>
14040 <p><var>push_func</var>: a callback function similar to <code>write()</code>
14041 </p>
14042 <p>This is the function where you set a push function for gnutls to
14043 use in order to send data.  If you are going to use berkeley style
14044 sockets, you do not need to use this function since the default
14045 (send(2)) will probably be ok.  Otherwise you should specify this
14046 function for gnutls to be able to send data.
14047 </p>
14048 <p>PUSH_FUNC is of the form,
14049 ssize_t (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t);
14050 </p></dd></dl>
14051
14052 <a name="gnutls_005ftransport_005fset_005fvec_005fpush_005ffunction-1"></a>
14053 <h4 class="subheading">gnutls_transport_set_vec_push_function</h4>
14054 <a name="gnutls_005ftransport_005fset_005fvec_005fpush_005ffunction"></a><dl>
14055 <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>
14056 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
14057 </p>
14058 <p><var>vec_func</var>: a callback function similar to <code>writev()</code>
14059 </p>
14060 <p>This is the function where you set a push function for gnutls to
14061 use in order to send data.  If you are going to use berkeley style
14062 sockets, you do not need to use this function since the default
14063 (send(2)) will probably be ok.  Otherwise you should specify this
14064 function for gnutls to be able to send data.
14065 </p>
14066 <p>PUSH_FUNC is of the form,
14067 ssize_t (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t);
14068 </p></dd></dl>
14069
14070 <a name="gnutls_005fx509_005fcrq_005fset_005fpubkey-1"></a>
14071 <h4 class="subheading">gnutls_x509_crq_set_pubkey</h4>
14072 <a name="gnutls_005fx509_005fcrq_005fset_005fpubkey"></a><dl>
14073 <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>
14074 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
14075 </p>
14076 <p><var>key</var>: holds a public key
14077 </p>
14078 <p>This function will set the public parameters from the given public
14079 key to the request.
14080 </p>
14081 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14082 negative error value.
14083 </p></dd></dl>
14084
14085 <a name="gnutls_005fx509_005fcrt_005fimport_005fpkcs11_005furl-1"></a>
14086 <h4 class="subheading">gnutls_x509_crt_import_pkcs11_url</h4>
14087 <a name="gnutls_005fx509_005fcrt_005fimport_005fpkcs11_005furl"></a><dl>
14088 <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>
14089 <dd><p><var>crt</var>: A certificate of type <code>gnutls_x509_crt_t</code>
14090 </p>
14091 <p><var>url</var>: A PKCS 11 url
14092 </p>
14093 <p><var>flags</var>: One of GNUTLS_PKCS11_OBJ_* flags
14094 </p>
14095 <p>This function will import a PKCS 11 certificate directly from a token
14096 without involving the <code>gnutls_pkcs11_obj_t</code> structure. This function will
14097 fail if the certificate stored is not of X.509 type.
14098 </p>
14099 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14100 negative error value.
14101 </p></dd></dl>
14102
14103 <a name="gnutls_005fx509_005fcrt_005fimport_005fpkcs11-1"></a>
14104 <h4 class="subheading">gnutls_x509_crt_import_pkcs11</h4>
14105 <a name="gnutls_005fx509_005fcrt_005fimport_005fpkcs11"></a><dl>
14106 <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>
14107 <dd><p><var>crt</var>: A certificate of type <code>gnutls_x509_crt_t</code>
14108 </p>
14109 <p><var>pkcs11_crt</var>: A PKCS 11 object that contains a certificate
14110 </p>
14111 <p>This function will import a PKCS 11 certificate to a <code>gnutls_x509_crt_t</code>
14112 structure.
14113 </p>
14114 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14115 negative error value.
14116 </p></dd></dl>
14117
14118 <a name="gnutls_005fx509_005fcrt_005flist_005fimport_005fpkcs11-1"></a>
14119 <h4 class="subheading">gnutls_x509_crt_list_import_pkcs11</h4>
14120 <a name="gnutls_005fx509_005fcrt_005flist_005fimport_005fpkcs11"></a><dl>
14121 <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>
14122 <dd><p><var>certs</var>: A list of certificates of type <code>gnutls_x509_crt_t</code>
14123 </p>
14124 <p><var>cert_max</var>: The maximum size of the list
14125 </p>
14126 <p><var>objs</var>: A list of PKCS 11 objects
14127 </p>
14128 <p><var>flags</var>: 0 for now
14129 </p>
14130 <p>This function will import a PKCS 11 certificate list to a list of
14131 <code>gnutls_x509_crt_t</code> structure. These must not be initialized.
14132 </p>
14133 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14134 negative error value.
14135 </p></dd></dl>
14136
14137 <a name="gnutls_005fx509_005fcrt_005fset_005fpubkey-1"></a>
14138 <h4 class="subheading">gnutls_x509_crt_set_pubkey</h4>
14139 <a name="gnutls_005fx509_005fcrt_005fset_005fpubkey"></a><dl>
14140 <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>
14141 <dd><p><var>crt</var>: should contain a <code>gnutls_x509_crt_t</code> structure
14142 </p>
14143 <p><var>key</var>: holds a public key
14144 </p>
14145 <p>This function will set the public parameters from the given public
14146 key to the request.
14147 </p>
14148 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14149 negative error value.
14150 </p></dd></dl>
14151 <hr>
14152 <a name="X_002e509-certificate-functions"></a>
14153 <div class="header">
14154 <p>
14155 Next: <a href="#GnuTLS_002dextra-functions" accesskey="n" rel="next">GnuTLS-extra functions</a>, Previous: <a href="#Core-functions" accesskey="p" rel="previous">Core functions</a>, Up: <a href="#Function-reference" accesskey="u" rel="up">Function 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>
14156 </div>
14157 <a name="X_002e509-Certificate-Functions"></a>
14158 <h3 class="section">9.2 <acronym>X.509</acronym> Certificate Functions</h3>
14159 <a name="sec_003ax509api"></a><a name="index-X_002e509-Functions"></a>
14160
14161 <p>The following functions are to be used for <acronym>X.509</acronym> certificate handling.
14162 Their prototypes lie in &lsquo;<tt>gnutls/x509.h</tt>&rsquo;.
14163 </p>
14164
14165
14166
14167
14168 <a name="gnutls_005fpkcs12_005fbag_005fdecrypt-1"></a>
14169 <h4 class="subheading">gnutls_pkcs12_bag_decrypt</h4>
14170 <a name="gnutls_005fpkcs12_005fbag_005fdecrypt"></a><dl>
14171 <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>
14172 <dd><p><var>bag</var>: The bag
14173 </p>
14174 <p><var>pass</var>: The password used for encryption, must be ASCII.
14175 </p>
14176 <p>This function will decrypt the given encrypted bag and return 0 on
14177 success.
14178 </p>
14179 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
14180 otherwise an error code is returned.
14181 </p></dd></dl>
14182
14183 <a name="gnutls_005fpkcs12_005fbag_005fdeinit-1"></a>
14184 <h4 class="subheading">gnutls_pkcs12_bag_deinit</h4>
14185 <a name="gnutls_005fpkcs12_005fbag_005fdeinit"></a><dl>
14186 <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>
14187 <dd><p><var>bag</var>: The structure to be initialized
14188 </p>
14189 <p>This function will deinitialize a PKCS12 Bag structure.
14190 </p></dd></dl>
14191
14192 <a name="gnutls_005fpkcs12_005fbag_005fencrypt-1"></a>
14193 <h4 class="subheading">gnutls_pkcs12_bag_encrypt</h4>
14194 <a name="gnutls_005fpkcs12_005fbag_005fencrypt"></a><dl>
14195 <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>
14196 <dd><p><var>bag</var>: The bag
14197 </p>
14198 <p><var>pass</var>: The password used for encryption, must be ASCII
14199 </p>
14200 <p><var>flags</var>: should be one of <code>gnutls_pkcs_encrypt_flags_t</code> elements bitwise or&rsquo;d
14201 </p>
14202 <p>This function will encrypt the given bag.
14203 </p>
14204 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
14205 otherwise an error code is returned.
14206 </p></dd></dl>
14207
14208 <a name="gnutls_005fpkcs12_005fbag_005fget_005fcount-1"></a>
14209 <h4 class="subheading">gnutls_pkcs12_bag_get_count</h4>
14210 <a name="gnutls_005fpkcs12_005fbag_005fget_005fcount"></a><dl>
14211 <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>
14212 <dd><p><var>bag</var>: The bag
14213 </p>
14214 <p>This function will return the number of the elements withing the bag.
14215 </p>
14216 <p><strong>Returns:</strong> Number of elements in bag, or an negative error code on
14217 error.
14218 </p></dd></dl>
14219
14220 <a name="gnutls_005fpkcs12_005fbag_005fget_005fdata-1"></a>
14221 <h4 class="subheading">gnutls_pkcs12_bag_get_data</h4>
14222 <a name="gnutls_005fpkcs12_005fbag_005fget_005fdata"></a><dl>
14223 <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>
14224 <dd><p><var>bag</var>: The bag
14225 </p>
14226 <p><var>indx</var>: The element of the bag to get the data from
14227 </p>
14228 <p><var>data</var>: where the bag&rsquo;s data will be. Should be treated as constant.
14229 </p>
14230 <p>This function will return the bag&rsquo;s data. The data is a constant
14231 that is stored into the bag.  Should not be accessed after the bag
14232 is deleted.
14233 </p>
14234 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14235 negative error value.
14236 </p></dd></dl>
14237
14238 <a name="gnutls_005fpkcs12_005fbag_005fget_005ffriendly_005fname-1"></a>
14239 <h4 class="subheading">gnutls_pkcs12_bag_get_friendly_name</h4>
14240 <a name="gnutls_005fpkcs12_005fbag_005fget_005ffriendly_005fname"></a><dl>
14241 <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>
14242 <dd><p><var>bag</var>: The bag
14243 </p>
14244 <p><var>indx</var>: The bag&rsquo;s element to add the id
14245 </p>
14246 <p><var>name</var>: will hold a pointer to the name (to be treated as const)
14247 </p>
14248 <p>This function will return the friendly name, of the specified bag
14249 element.  The key ID is usually used to distinguish the local
14250 private key and the certificate pair.
14251 </p>
14252 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14253 negative error value. or a negative value on error.
14254 </p></dd></dl>
14255
14256 <a name="gnutls_005fpkcs12_005fbag_005fget_005fkey_005fid-1"></a>
14257 <h4 class="subheading">gnutls_pkcs12_bag_get_key_id</h4>
14258 <a name="gnutls_005fpkcs12_005fbag_005fget_005fkey_005fid"></a><dl>
14259 <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>
14260 <dd><p><var>bag</var>: The bag
14261 </p>
14262 <p><var>indx</var>: The bag&rsquo;s element to add the id
14263 </p>
14264 <p><var>id</var>: where the ID will be copied (to be treated as const)
14265 </p>
14266 <p>This function will return the key ID, of the specified bag element.
14267 The key ID is usually used to distinguish the local private key and
14268 the certificate pair.
14269 </p>
14270 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14271 negative error value. or a negative value on error.
14272 </p></dd></dl>
14273
14274 <a name="gnutls_005fpkcs12_005fbag_005fget_005ftype-1"></a>
14275 <h4 class="subheading">gnutls_pkcs12_bag_get_type</h4>
14276 <a name="gnutls_005fpkcs12_005fbag_005fget_005ftype"></a><dl>
14277 <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>
14278 <dd><p><var>bag</var>: The bag
14279 </p>
14280 <p><var>indx</var>: The element of the bag to get the type
14281 </p>
14282 <p>This function will return the bag&rsquo;s type.
14283 </p>
14284 <p><strong>Returns:</strong> One of the <code>gnutls_pkcs12_bag_type_t</code> enumerations.
14285 </p></dd></dl>
14286
14287 <a name="gnutls_005fpkcs12_005fbag_005finit-1"></a>
14288 <h4 class="subheading">gnutls_pkcs12_bag_init</h4>
14289 <a name="gnutls_005fpkcs12_005fbag_005finit"></a><dl>
14290 <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>
14291 <dd><p><var>bag</var>: The structure to be initialized
14292 </p>
14293 <p>This function will initialize a PKCS12 bag structure. PKCS12 Bags
14294 usually contain private keys, lists of X.509 Certificates and X.509
14295 Certificate revocation lists.
14296 </p>
14297 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14298 negative error value.
14299 </p></dd></dl>
14300
14301 <a name="gnutls_005fpkcs12_005fbag_005fset_005fcrl-1"></a>
14302 <h4 class="subheading">gnutls_pkcs12_bag_set_crl</h4>
14303 <a name="gnutls_005fpkcs12_005fbag_005fset_005fcrl"></a><dl>
14304 <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>
14305 <dd><p><var>bag</var>: The bag
14306 </p>
14307 <p><var>crl</var>: the CRL to be copied.
14308 </p>
14309 <p>This function will insert the given CRL into the
14310 bag. This is just a wrapper over <code>gnutls_pkcs12_bag_set_data()</code>.
14311 </p>
14312 <p><strong>Returns:</strong> the index of the added bag on success, or a negative value
14313 on failure.
14314 </p></dd></dl>
14315
14316 <a name="gnutls_005fpkcs12_005fbag_005fset_005fcrt-1"></a>
14317 <h4 class="subheading">gnutls_pkcs12_bag_set_crt</h4>
14318 <a name="gnutls_005fpkcs12_005fbag_005fset_005fcrt"></a><dl>
14319 <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>
14320 <dd><p><var>bag</var>: The bag
14321 </p>
14322 <p><var>crt</var>: the certificate to be copied.
14323 </p>
14324 <p>This function will insert the given certificate into the
14325 bag. This is just a wrapper over <code>gnutls_pkcs12_bag_set_data()</code>.
14326 </p>
14327 <p><strong>Returns:</strong> the index of the added bag on success, or a negative
14328 value on failure.
14329 </p></dd></dl>
14330
14331 <a name="gnutls_005fpkcs12_005fbag_005fset_005fdata-1"></a>
14332 <h4 class="subheading">gnutls_pkcs12_bag_set_data</h4>
14333 <a name="gnutls_005fpkcs12_005fbag_005fset_005fdata"></a><dl>
14334 <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>
14335 <dd><p><var>bag</var>: The bag
14336 </p>
14337 <p><var>type</var>: The data&rsquo;s type
14338 </p>
14339 <p><var>data</var>: the data to be copied.
14340 </p>
14341 <p>This function will insert the given data of the given type into
14342 the bag.
14343 </p>
14344 <p><strong>Returns:</strong> the index of the added bag on success, or a negative
14345 value on error.
14346 </p></dd></dl>
14347
14348 <a name="gnutls_005fpkcs12_005fbag_005fset_005ffriendly_005fname-1"></a>
14349 <h4 class="subheading">gnutls_pkcs12_bag_set_friendly_name</h4>
14350 <a name="gnutls_005fpkcs12_005fbag_005fset_005ffriendly_005fname"></a><dl>
14351 <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>
14352 <dd><p><var>bag</var>: The bag
14353 </p>
14354 <p><var>indx</var>: The bag&rsquo;s element to add the id
14355 </p>
14356 <p><var>name</var>: the name
14357 </p>
14358 <p>This function will add the given key friendly name, to the
14359 specified, by the index, bag element. The name will be encoded as
14360 a &rsquo;Friendly name&rsquo; bag attribute, which is usually used to set a
14361 user name to the local private key and the certificate pair.
14362 </p>
14363 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14364 negative error value. or a negative value on error.
14365 </p></dd></dl>
14366
14367 <a name="gnutls_005fpkcs12_005fbag_005fset_005fkey_005fid-1"></a>
14368 <h4 class="subheading">gnutls_pkcs12_bag_set_key_id</h4>
14369 <a name="gnutls_005fpkcs12_005fbag_005fset_005fkey_005fid"></a><dl>
14370 <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>
14371 <dd><p><var>bag</var>: The bag
14372 </p>
14373 <p><var>indx</var>: The bag&rsquo;s element to add the id
14374 </p>
14375 <p><var>id</var>: the ID
14376 </p>
14377 <p>This function will add the given key ID, to the specified, by the
14378 index, bag element. The key ID will be encoded as a &rsquo;Local key
14379 identifier&rsquo; bag attribute, which is usually used to distinguish
14380 the local private key and the certificate pair.
14381 </p>
14382 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14383 negative error value. or a negative value on error.
14384 </p></dd></dl>
14385
14386 <a name="gnutls_005fpkcs12_005fdeinit-1"></a>
14387 <h4 class="subheading">gnutls_pkcs12_deinit</h4>
14388 <a name="gnutls_005fpkcs12_005fdeinit"></a><dl>
14389 <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>
14390 <dd><p><var>pkcs12</var>: The structure to be initialized
14391 </p>
14392 <p>This function will deinitialize a PKCS12 structure.
14393 </p></dd></dl>
14394
14395 <a name="gnutls_005fpkcs12_005fexport-1"></a>
14396 <h4 class="subheading">gnutls_pkcs12_export</h4>
14397 <a name="gnutls_005fpkcs12_005fexport"></a><dl>
14398 <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>
14399 <dd><p><var>pkcs12</var>: Holds the pkcs12 structure
14400 </p>
14401 <p><var>format</var>: the format of output params. One of PEM or DER.
14402 </p>
14403 <p><var>output_data</var>: will contain a structure PEM or DER encoded
14404 </p>
14405 <p><var>output_data_size</var>: holds the size of output_data (and will be
14406 replaced by the actual size of parameters)
14407 </p>
14408 <p>This function will export the pkcs12 structure to DER or PEM format.
14409 </p>
14410 <p>If the buffer provided is not long enough to hold the output, then
14411 *output_data_size will be updated and GNUTLS_E_SHORT_MEMORY_BUFFER
14412 will be returned.
14413 </p>
14414 <p>If the structure is PEM encoded, it will have a header
14415 of &quot;BEGIN PKCS12&quot;.
14416 </p>
14417 <p><strong>Return value:</strong> In case of failure a negative value will be
14418 returned, and 0 on success.
14419 </p></dd></dl>
14420
14421 <a name="gnutls_005fpkcs12_005fgenerate_005fmac-1"></a>
14422 <h4 class="subheading">gnutls_pkcs12_generate_mac</h4>
14423 <a name="gnutls_005fpkcs12_005fgenerate_005fmac"></a><dl>
14424 <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>
14425 <dd><p><var>pkcs12</var>: should contain a gnutls_pkcs12_t structure
14426 </p>
14427 <p><var>pass</var>: The password for the MAC
14428 </p>
14429 <p>This function will generate a MAC for the PKCS12 structure.
14430 </p>
14431 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14432 negative error value.
14433 </p></dd></dl>
14434
14435 <a name="gnutls_005fpkcs12_005fget_005fbag-1"></a>
14436 <h4 class="subheading">gnutls_pkcs12_get_bag</h4>
14437 <a name="gnutls_005fpkcs12_005fget_005fbag"></a><dl>
14438 <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>
14439 <dd><p><var>pkcs12</var>: should contain a gnutls_pkcs12_t structure
14440 </p>
14441 <p><var>indx</var>: contains the index of the bag to extract
14442 </p>
14443 <p><var>bag</var>: An initialized bag, where the contents of the bag will be copied
14444 </p>
14445 <p>This function will return a Bag from the PKCS12 structure.
14446 </p>
14447 <p>After the last Bag has been read
14448 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> will be returned.
14449 </p>
14450 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14451 negative error value.
14452 </p></dd></dl>
14453
14454 <a name="gnutls_005fpkcs12_005fimport-1"></a>
14455 <h4 class="subheading">gnutls_pkcs12_import</h4>
14456 <a name="gnutls_005fpkcs12_005fimport"></a><dl>
14457 <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>
14458 <dd><p><var>pkcs12</var>: The structure to store the parsed PKCS12.
14459 </p>
14460 <p><var>data</var>: The DER or PEM encoded PKCS12.
14461 </p>
14462 <p><var>format</var>: One of DER or PEM
14463 </p>
14464 <p><var>flags</var>: an ORed sequence of gnutls_privkey_pkcs8_flags
14465 </p>
14466 <p>This function will convert the given DER or PEM encoded PKCS12
14467 to the native gnutls_pkcs12_t format. The output will be stored in &rsquo;pkcs12&rsquo;.
14468 </p>
14469 <p>If the PKCS12 is PEM encoded it should have a header of &quot;PKCS12&quot;.
14470 </p>
14471 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14472 negative error value.
14473 </p></dd></dl>
14474
14475 <a name="gnutls_005fpkcs12_005finit-1"></a>
14476 <h4 class="subheading">gnutls_pkcs12_init</h4>
14477 <a name="gnutls_005fpkcs12_005finit"></a><dl>
14478 <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>
14479 <dd><p><var>pkcs12</var>: The structure to be initialized
14480 </p>
14481 <p>This function will initialize a PKCS12 structure. PKCS12 structures
14482 usually contain lists of X.509 Certificates and X.509 Certificate
14483 revocation lists.
14484 </p>
14485 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14486 negative error value.
14487 </p></dd></dl>
14488
14489 <a name="gnutls_005fpkcs12_005fset_005fbag-1"></a>
14490 <h4 class="subheading">gnutls_pkcs12_set_bag</h4>
14491 <a name="gnutls_005fpkcs12_005fset_005fbag"></a><dl>
14492 <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>
14493 <dd><p><var>pkcs12</var>: should contain a gnutls_pkcs12_t structure
14494 </p>
14495 <p><var>bag</var>: An initialized bag
14496 </p>
14497 <p>This function will insert a Bag into the PKCS12 structure.
14498 </p>
14499 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14500 negative error value.
14501 </p></dd></dl>
14502
14503 <a name="gnutls_005fpkcs12_005fverify_005fmac-1"></a>
14504 <h4 class="subheading">gnutls_pkcs12_verify_mac</h4>
14505 <a name="gnutls_005fpkcs12_005fverify_005fmac"></a><dl>
14506 <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>
14507 <dd><p><var>pkcs12</var>: should contain a gnutls_pkcs12_t structure
14508 </p>
14509 <p><var>pass</var>: The password for the MAC
14510 </p>
14511 <p>This function will verify the MAC for the PKCS12 structure.
14512 </p>
14513 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14514 negative error value.
14515 </p></dd></dl>
14516
14517 <a name="gnutls_005fpkcs7_005fdeinit-1"></a>
14518 <h4 class="subheading">gnutls_pkcs7_deinit</h4>
14519 <a name="gnutls_005fpkcs7_005fdeinit"></a><dl>
14520 <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>
14521 <dd><p><var>pkcs7</var>: The structure to be initialized
14522 </p>
14523 <p>This function will deinitialize a PKCS7 structure.
14524 </p></dd></dl>
14525
14526 <a name="gnutls_005fpkcs7_005fdelete_005fcrl-1"></a>
14527 <h4 class="subheading">gnutls_pkcs7_delete_crl</h4>
14528 <a name="gnutls_005fpkcs7_005fdelete_005fcrl"></a><dl>
14529 <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>
14530 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code> structure
14531 </p>
14532 <p><var>indx</var>: the index of the crl to delete
14533 </p>
14534 <p>This function will delete a crl from a PKCS7 or RFC2630 crl set.
14535 Index starts from 0. Returns 0 on success.
14536 </p>
14537 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14538 negative error value.
14539 </p></dd></dl>
14540
14541 <a name="gnutls_005fpkcs7_005fdelete_005fcrt-1"></a>
14542 <h4 class="subheading">gnutls_pkcs7_delete_crt</h4>
14543 <a name="gnutls_005fpkcs7_005fdelete_005fcrt"></a><dl>
14544 <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>
14545 <dd><p><var>pkcs7</var>: should contain a gnutls_pkcs7_t structure
14546 </p>
14547 <p><var>indx</var>: the index of the certificate to delete
14548 </p>
14549 <p>This function will delete a certificate from a PKCS7 or RFC2630
14550 certificate set.  Index starts from 0. Returns 0 on success.
14551 </p>
14552 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14553 negative error value.
14554 </p></dd></dl>
14555
14556 <a name="gnutls_005fpkcs7_005fexport-1"></a>
14557 <h4 class="subheading">gnutls_pkcs7_export</h4>
14558 <a name="gnutls_005fpkcs7_005fexport"></a><dl>
14559 <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>
14560 <dd><p><var>pkcs7</var>: Holds the pkcs7 structure
14561 </p>
14562 <p><var>format</var>: the format of output params. One of PEM or DER.
14563 </p>
14564 <p><var>output_data</var>: will contain a structure PEM or DER encoded
14565 </p>
14566 <p><var>output_data_size</var>: holds the size of output_data (and will be
14567 replaced by the actual size of parameters)
14568 </p>
14569 <p>This function will export the pkcs7 structure to DER or PEM format.
14570 </p>
14571 <p>If the buffer provided is not long enough to hold the output, then
14572 *<code>output_data_size</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>
14573 will be returned.
14574 </p>
14575 <p>If the structure is PEM encoded, it will have a header
14576 of &quot;BEGIN PKCS7&quot;.
14577 </p>
14578 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14579 negative error value.
14580 </p></dd></dl>
14581
14582 <a name="gnutls_005fpkcs7_005fget_005fcrl_005fcount-1"></a>
14583 <h4 class="subheading">gnutls_pkcs7_get_crl_count</h4>
14584 <a name="gnutls_005fpkcs7_005fget_005fcrl_005fcount"></a><dl>
14585 <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>
14586 <dd><p><var>pkcs7</var>: should contain a gnutls_pkcs7_t structure
14587 </p>
14588 <p>This function will return the number of certifcates in the PKCS7
14589 or RFC2630 crl set.
14590 </p>
14591 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14592 negative error value.
14593 </p></dd></dl>
14594
14595 <a name="gnutls_005fpkcs7_005fget_005fcrl_005fraw-1"></a>
14596 <h4 class="subheading">gnutls_pkcs7_get_crl_raw</h4>
14597 <a name="gnutls_005fpkcs7_005fget_005fcrl_005fraw"></a><dl>
14598 <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>
14599 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code> structure
14600 </p>
14601 <p><var>indx</var>: contains the index of the crl to extract
14602 </p>
14603 <p><var>crl</var>: the contents of the crl will be copied there (may be null)
14604 </p>
14605 <p><var>crl_size</var>: should hold the size of the crl
14606 </p>
14607 <p>This function will return a crl of the PKCS7 or RFC2630 crl set.
14608 </p>
14609 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14610 negative error value.  If the provided buffer is not long enough,
14611 then <code>crl_size</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> is
14612 returned.  After the last crl has been read
14613 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> will be returned.
14614 </p></dd></dl>
14615
14616 <a name="gnutls_005fpkcs7_005fget_005fcrt_005fcount-1"></a>
14617 <h4 class="subheading">gnutls_pkcs7_get_crt_count</h4>
14618 <a name="gnutls_005fpkcs7_005fget_005fcrt_005fcount"></a><dl>
14619 <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>
14620 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code> structure
14621 </p>
14622 <p>This function will return the number of certifcates in the PKCS7
14623 or RFC2630 certificate set.
14624 </p>
14625 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14626 negative error value.
14627 </p></dd></dl>
14628
14629 <a name="gnutls_005fpkcs7_005fget_005fcrt_005fraw-1"></a>
14630 <h4 class="subheading">gnutls_pkcs7_get_crt_raw</h4>
14631 <a name="gnutls_005fpkcs7_005fget_005fcrt_005fraw"></a><dl>
14632 <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>
14633 <dd><p><var>pkcs7</var>: should contain a gnutls_pkcs7_t structure
14634 </p>
14635 <p><var>indx</var>: contains the index of the certificate to extract
14636 </p>
14637 <p><var>certificate</var>: the contents of the certificate will be copied
14638 there (may be null)
14639 </p>
14640 <p><var>certificate_size</var>: should hold the size of the certificate
14641 </p>
14642 <p>This function will return a certificate of the PKCS7 or RFC2630
14643 certificate set.
14644 </p>
14645 <p>After the last certificate has been read
14646 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> will be returned.
14647 </p>
14648 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14649 negative error value.  If the provided buffer is not long enough,
14650 then <code>certificate_size</code> is updated and
14651 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> is returned.
14652 </p></dd></dl>
14653
14654 <a name="gnutls_005fpkcs7_005fimport-1"></a>
14655 <h4 class="subheading">gnutls_pkcs7_import</h4>
14656 <a name="gnutls_005fpkcs7_005fimport"></a><dl>
14657 <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>
14658 <dd><p><var>pkcs7</var>: The structure to store the parsed PKCS7.
14659 </p>
14660 <p><var>data</var>: The DER or PEM encoded PKCS7.
14661 </p>
14662 <p><var>format</var>: One of DER or PEM
14663 </p>
14664 <p>This function will convert the given DER or PEM encoded PKCS7 to
14665 the native <code>gnutls_pkcs7_t</code> format.  The output will be stored in
14666 <code>pkcs7</code>.
14667 </p>
14668 <p>If the PKCS7 is PEM encoded it should have a header of &quot;PKCS7&quot;.
14669 </p>
14670 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14671 negative error value.
14672 </p></dd></dl>
14673
14674 <a name="gnutls_005fpkcs7_005finit-1"></a>
14675 <h4 class="subheading">gnutls_pkcs7_init</h4>
14676 <a name="gnutls_005fpkcs7_005finit"></a><dl>
14677 <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>
14678 <dd><p><var>pkcs7</var>: The structure to be initialized
14679 </p>
14680 <p>This function will initialize a PKCS7 structure. PKCS7 structures
14681 usually contain lists of X.509 Certificates and X.509 Certificate
14682 revocation lists.
14683 </p>
14684 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14685 negative error value.
14686 </p></dd></dl>
14687
14688 <a name="gnutls_005fpkcs7_005fset_005fcrl_005fraw-1"></a>
14689 <h4 class="subheading">gnutls_pkcs7_set_crl_raw</h4>
14690 <a name="gnutls_005fpkcs7_005fset_005fcrl_005fraw"></a><dl>
14691 <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>
14692 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code> structure
14693 </p>
14694 <p><var>crl</var>: the DER encoded crl to be added
14695 </p>
14696 <p>This function will add a crl to the PKCS7 or RFC2630 crl set.
14697 </p>
14698 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14699 negative error value.
14700 </p></dd></dl>
14701
14702 <a name="gnutls_005fpkcs7_005fset_005fcrl-1"></a>
14703 <h4 class="subheading">gnutls_pkcs7_set_crl</h4>
14704 <a name="gnutls_005fpkcs7_005fset_005fcrl"></a><dl>
14705 <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>
14706 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code> structure
14707 </p>
14708 <p><var>crl</var>: the DER encoded crl to be added
14709 </p>
14710 <p>This function will add a parsed CRL to the PKCS7 or RFC2630 crl
14711 set.
14712 </p>
14713 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14714 negative error value.
14715 </p></dd></dl>
14716
14717 <a name="gnutls_005fpkcs7_005fset_005fcrt_005fraw-1"></a>
14718 <h4 class="subheading">gnutls_pkcs7_set_crt_raw</h4>
14719 <a name="gnutls_005fpkcs7_005fset_005fcrt_005fraw"></a><dl>
14720 <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>
14721 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code> structure
14722 </p>
14723 <p><var>crt</var>: the DER encoded certificate to be added
14724 </p>
14725 <p>This function will add a certificate to the PKCS7 or RFC2630
14726 certificate set.
14727 </p>
14728 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14729 negative error value.
14730 </p></dd></dl>
14731
14732 <a name="gnutls_005fpkcs7_005fset_005fcrt-1"></a>
14733 <h4 class="subheading">gnutls_pkcs7_set_crt</h4>
14734 <a name="gnutls_005fpkcs7_005fset_005fcrt"></a><dl>
14735 <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>
14736 <dd><p><var>pkcs7</var>: should contain a <code>gnutls_pkcs7_t</code> structure
14737 </p>
14738 <p><var>crt</var>: the certificate to be copied.
14739 </p>
14740 <p>This function will add a parsed certificate to the PKCS7 or
14741 RFC2630 certificate set.  This is a wrapper function over
14742 <code>gnutls_pkcs7_set_crt_raw()</code> .
14743 </p>
14744 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14745 negative error value.
14746 </p></dd></dl>
14747
14748 <a name="gnutls_005fx509_005fcrl_005fcheck_005fissuer-1"></a>
14749 <h4 class="subheading">gnutls_x509_crl_check_issuer</h4>
14750 <a name="gnutls_005fx509_005fcrl_005fcheck_005fissuer"></a><dl>
14751 <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>cert</var>, gnutls_x509_crt_t <var>issuer</var>)</em></dt>
14752 <dd><p><var>issuer</var>: is the certificate of a possible issuer
14753 </p>
14754 <p>This function will check if the given CRL was issued by the given
14755 issuer certificate.  It will return true (1) if the given CRL was
14756 issued by the given issuer, and false (0) if not.
14757 </p>
14758 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14759 negative error value.
14760 </p></dd></dl>
14761
14762 <a name="gnutls_005fx509_005fcrl_005fdeinit-1"></a>
14763 <h4 class="subheading">gnutls_x509_crl_deinit</h4>
14764 <a name="gnutls_005fx509_005fcrl_005fdeinit"></a><dl>
14765 <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>
14766 <dd><p><var>crl</var>: The structure to be initialized
14767 </p>
14768 <p>This function will deinitialize a CRL structure.
14769 </p></dd></dl>
14770
14771 <a name="gnutls_005fx509_005fcrl_005fexport-1"></a>
14772 <h4 class="subheading">gnutls_x509_crl_export</h4>
14773 <a name="gnutls_005fx509_005fcrl_005fexport"></a><dl>
14774 <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>
14775 <dd><p><var>crl</var>: Holds the revocation list
14776 </p>
14777 <p><var>format</var>: the format of output params. One of PEM or DER.
14778 </p>
14779 <p><var>output_data</var>: will contain a private key PEM or DER encoded
14780 </p>
14781 <p><var>output_data_size</var>: holds the size of output_data (and will
14782 be replaced by the actual size of parameters)
14783 </p>
14784 <p>This function will export the revocation list to DER or PEM format.
14785 </p>
14786 <p>If the buffer provided is not long enough to hold the output, then
14787 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> will be returned.
14788 </p>
14789 <p>If the structure is PEM encoded, it will have a header
14790 of &quot;BEGIN X509 CRL&quot;.
14791 </p>
14792 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14793 negative error value. and a negative value on failure.
14794 </p></dd></dl>
14795
14796 <a name="gnutls_005fx509_005fcrl_005fget_005fauthority_005fkey_005fid-1"></a>
14797 <h4 class="subheading">gnutls_x509_crl_get_authority_key_id</h4>
14798 <a name="gnutls_005fx509_005fcrl_005fget_005fauthority_005fkey_005fid"></a><dl>
14799 <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>ret</var>, size_t * <var>ret_size</var>, unsigned int * <var>critical</var>)</em></dt>
14800 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code> structure
14801 </p>
14802 <p><var>ret</var>: The place where the identifier will be copied
14803 </p>
14804 <p><var>ret_size</var>: Holds the size of the result field.
14805 </p>
14806 <p><var>critical</var>: will be non zero if the extension is marked as critical
14807 (may be null)
14808 </p>
14809 <p>This function will return the CRL authority&rsquo;s key identifier.  This
14810 is obtained by the X.509 Authority Key identifier extension field
14811 (2.5.29.35).  Note that this function only returns the
14812 keyIdentifier field of the extension.
14813 </p>
14814 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14815 negative value in case of an error.
14816 </p>
14817 <p><strong>Since:</strong> 2.8.0
14818 </p></dd></dl>
14819
14820 <a name="gnutls_005fx509_005fcrl_005fget_005fcrt_005fcount-1"></a>
14821 <h4 class="subheading">gnutls_x509_crl_get_crt_count</h4>
14822 <a name="gnutls_005fx509_005fcrl_005fget_005fcrt_005fcount"></a><dl>
14823 <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>
14824 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code> structure
14825 </p>
14826 <p>This function will return the number of revoked certificates in the
14827 given CRL.
14828 </p>
14829 <p><strong>Returns:</strong> number of certificates, a negative value on failure.
14830 </p></dd></dl>
14831
14832 <a name="gnutls_005fx509_005fcrl_005fget_005fcrt_005fserial-1"></a>
14833 <h4 class="subheading">gnutls_x509_crl_get_crt_serial</h4>
14834 <a name="gnutls_005fx509_005fcrl_005fget_005fcrt_005fserial"></a><dl>
14835 <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>
14836 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code> structure
14837 </p>
14838 <p><var>indx</var>: the index of the certificate to extract (starting from 0)
14839 </p>
14840 <p><var>serial</var>: where the serial number will be copied
14841 </p>
14842 <p><var>serial_size</var>: initially holds the size of serial
14843 </p>
14844 <p><var>t</var>: if non null, will hold the time this certificate was revoked
14845 </p>
14846 <p>This function will retrieve the serial number of the specified, by
14847 the index, revoked certificate.
14848 </p>
14849 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14850 negative error value. and a negative value on error.
14851 </p></dd></dl>
14852
14853 <a name="gnutls_005fx509_005fcrl_005fget_005fdn_005foid-1"></a>
14854 <h4 class="subheading">gnutls_x509_crl_get_dn_oid</h4>
14855 <a name="gnutls_005fx509_005fcrl_005fget_005fdn_005foid"></a><dl>
14856 <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>
14857 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
14858 </p>
14859 <p><var>indx</var>: Specifies which DN OID to send. Use zero to get the first one.
14860 </p>
14861 <p><var>oid</var>: a pointer to a structure to hold the name (may be null)
14862 </p>
14863 <p><var>sizeof_oid</var>: initially holds the size of &rsquo;oid&rsquo;
14864 </p>
14865 <p>This function will extract the requested OID of the name of the CRL
14866 issuer, specified by the given index.
14867 </p>
14868 <p>If oid is null then only the size will be filled.
14869 </p>
14870 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the provided buffer is
14871 not long enough, and in that case the sizeof_oid will be updated
14872 with the required size.  On success 0 is returned.
14873 </p></dd></dl>
14874
14875 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005fdata-1"></a>
14876 <h4 class="subheading">gnutls_x509_crl_get_extension_data</h4>
14877 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005fdata"></a><dl>
14878 <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>
14879 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code> structure
14880 </p>
14881 <p><var>indx</var>: Specifies which extension OID to send. Use zero to get the first one.
14882 </p>
14883 <p><var>data</var>: a pointer to a structure to hold the data (may be null)
14884 </p>
14885 <p><var>sizeof_data</var>: initially holds the size of <code>oid</code>
14886 </p>
14887 <p>This function will return the requested extension data in the CRL.
14888 The extension data will be stored as a string in the provided
14889 buffer.
14890 </p>
14891 <p>Use <code>gnutls_x509_crl_get_extension_info()</code> to extract the OID and
14892 critical flag.  Use <code>gnutls_x509_crl_get_extension_info()</code> instead,
14893 if you want to get data indexed by the extension OID rather than
14894 sequence.
14895 </p>
14896 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14897 negative value in case of an error.  If your have reached the
14898 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
14899 will be returned.
14900 </p>
14901 <p><strong>Since:</strong> 2.8.0
14902 </p></dd></dl>
14903
14904 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005finfo-1"></a>
14905 <h4 class="subheading">gnutls_x509_crl_get_extension_info</h4>
14906 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005finfo"></a><dl>
14907 <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>, int * <var>critical</var>)</em></dt>
14908 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code> structure
14909 </p>
14910 <p><var>indx</var>: Specifies which extension OID to send, use zero to get the first one.
14911 </p>
14912 <p><var>oid</var>: a pointer to a structure to hold the OID
14913 </p>
14914 <p><var>sizeof_oid</var>: initially holds the maximum size of <code>oid</code>, on return
14915 holds actual size of <code>oid</code>.
14916 </p>
14917 <p><var>critical</var>: output variable with critical flag, may be NULL.
14918 </p>
14919 <p>This function will return the requested extension OID in the CRL,
14920 and the critical flag for it.  The extension OID will be stored as
14921 a string in the provided buffer.  Use
14922 <code>gnutls_x509_crl_get_extension_data()</code> to extract the data.
14923 </p>
14924 <p>If the buffer provided is not long enough to hold the output, then
14925 *<code>sizeof_oid</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> will be
14926 returned.
14927 </p>
14928 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14929 negative value in case of an error.  If your have reached the
14930 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
14931 will be returned.
14932 </p>
14933 <p><strong>Since:</strong> 2.8.0
14934 </p></dd></dl>
14935
14936 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005foid-1"></a>
14937 <h4 class="subheading">gnutls_x509_crl_get_extension_oid</h4>
14938 <a name="gnutls_005fx509_005fcrl_005fget_005fextension_005foid"></a><dl>
14939 <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>
14940 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code> structure
14941 </p>
14942 <p><var>indx</var>: Specifies which extension OID to send, use zero to get the first one.
14943 </p>
14944 <p><var>oid</var>: a pointer to a structure to hold the OID (may be null)
14945 </p>
14946 <p><var>sizeof_oid</var>: initially holds the size of <code>oid</code>
14947 </p>
14948 <p>This function will return the requested extension OID in the CRL.
14949 The extension OID will be stored as a string in the provided
14950 buffer.
14951 </p>
14952 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
14953 negative value in case of an error.  If your have reached the
14954 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
14955 will be returned.
14956 </p>
14957 <p><strong>Since:</strong> 2.8.0
14958 </p></dd></dl>
14959
14960 <a name="gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn_005fby_005foid-1"></a>
14961 <h4 class="subheading">gnutls_x509_crl_get_issuer_dn_by_oid</h4>
14962 <a name="gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn_005fby_005foid"></a><dl>
14963 <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>
14964 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
14965 </p>
14966 <p><var>oid</var>: holds an Object Identified in null terminated string
14967 </p>
14968 <p><var>indx</var>: In case multiple same OIDs exist in the RDN, this specifies which to send. Use zero to get the first one.
14969 </p>
14970 <p><var>raw_flag</var>: If non zero returns the raw DER data of the DN part.
14971 </p>
14972 <p><var>buf</var>: a pointer to a structure to hold the peer&rsquo;s name (may be null)
14973 </p>
14974 <p><var>sizeof_buf</var>: initially holds the size of <code>buf</code>
14975 </p>
14976 <p>This function will extract the part of the name of the CRL issuer
14977 specified by the given OID. The output will be encoded as described
14978 in RFC2253. The output string will be ASCII or UTF-8 encoded,
14979 depending on the certificate data.
14980 </p>
14981 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
14982 If raw flag is zero, this function will only return known OIDs as
14983 text. Other OIDs will be DER encoded, as described in RFC2253 &ndash; in
14984 hex format with a &rsquo;\#&rsquo; prefix.  You can check about known OIDs
14985 using <code>gnutls_x509_dn_oid_known()</code>.
14986 </p>
14987 <p>If buf is null then only the size will be filled.
14988 </p>
14989 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the provided buffer is
14990 not long enough, and in that case the sizeof_buf will be updated
14991 with the required size, and 0 on success.
14992 </p></dd></dl>
14993
14994 <a name="gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn-1"></a>
14995 <h4 class="subheading">gnutls_x509_crl_get_issuer_dn</h4>
14996 <a name="gnutls_005fx509_005fcrl_005fget_005fissuer_005fdn"></a><dl>
14997 <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>
14998 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
14999 </p>
15000 <p><var>buf</var>: a pointer to a structure to hold the peer&rsquo;s name (may be null)
15001 </p>
15002 <p><var>sizeof_buf</var>: initially holds the size of <code>buf</code>
15003 </p>
15004 <p>This function will copy the name of the CRL issuer in the provided
15005 buffer. The name will be in the form &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as
15006 described in RFC2253. The output string will be ASCII or UTF-8
15007 encoded, depending on the certificate data.
15008 </p>
15009 <p>If buf is <code>NULL</code> then only the size will be filled.
15010 </p>
15011 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the provided buffer is
15012 not long enough, and in that case the sizeof_buf will be updated
15013 with the required size, and 0 on success.
15014 </p></dd></dl>
15015
15016 <a name="gnutls_005fx509_005fcrl_005fget_005fnext_005fupdate-1"></a>
15017 <h4 class="subheading">gnutls_x509_crl_get_next_update</h4>
15018 <a name="gnutls_005fx509_005fcrl_005fget_005fnext_005fupdate"></a><dl>
15019 <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>
15020 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code> structure
15021 </p>
15022 <p>This function will return the time the next CRL will be issued.
15023 This field is optional in a CRL so it might be normal to get an
15024 error instead.
15025 </p>
15026 <p><strong>Returns:</strong> when the next CRL will be issued, or (time_t)-1 on error.
15027 </p></dd></dl>
15028
15029 <a name="gnutls_005fx509_005fcrl_005fget_005fnumber-1"></a>
15030 <h4 class="subheading">gnutls_x509_crl_get_number</h4>
15031 <a name="gnutls_005fx509_005fcrl_005fget_005fnumber"></a><dl>
15032 <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>
15033 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code> structure
15034 </p>
15035 <p><var>ret</var>: The place where the number will be copied
15036 </p>
15037 <p><var>ret_size</var>: Holds the size of the result field.
15038 </p>
15039 <p><var>critical</var>: will be non zero if the extension is marked as critical
15040 (may be null)
15041 </p>
15042 <p>This function will return the CRL number extension.  This is
15043 obtained by the CRL Number extension field (2.5.29.20).
15044 </p>
15045 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15046 negative value in case of an error.
15047 </p>
15048 <p><strong>Since:</strong> 2.8.0
15049 </p></dd></dl>
15050
15051 <a name="gnutls_005fx509_005fcrl_005fget_005fraw_005fissuer_005fdn-1"></a>
15052 <h4 class="subheading">gnutls_x509_crl_get_raw_issuer_dn</h4>
15053 <a name="gnutls_005fx509_005fcrl_005fget_005fraw_005fissuer_005fdn"></a><dl>
15054 <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>
15055 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
15056 </p>
15057 <p><var>dn</var>: will hold the starting point of the DN
15058 </p>
15059 <p>This function will return a pointer to the DER encoded DN structure
15060 and the length.
15061 </p>
15062 <p><strong>Returns:</strong> a negative value on error, and zero on success.
15063 </p>
15064 <p><strong>Since:</strong> 2.12.0
15065 </p></dd></dl>
15066
15067 <a name="gnutls_005fx509_005fcrl_005fget_005fsignature_005falgorithm-1"></a>
15068 <h4 class="subheading">gnutls_x509_crl_get_signature_algorithm</h4>
15069 <a name="gnutls_005fx509_005fcrl_005fget_005fsignature_005falgorithm"></a><dl>
15070 <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>
15071 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code> structure
15072 </p>
15073 <p>This function will return a value of the <code>gnutls_sign_algorithm_t</code>
15074 enumeration that is the signature algorithm.
15075 </p>
15076 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15077 negative error value.
15078 </p></dd></dl>
15079
15080 <a name="gnutls_005fx509_005fcrl_005fget_005fsignature-1"></a>
15081 <h4 class="subheading">gnutls_x509_crl_get_signature</h4>
15082 <a name="gnutls_005fx509_005fcrl_005fget_005fsignature"></a><dl>
15083 <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>
15084 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
15085 </p>
15086 <p><var>sig</var>: a pointer where the signature part will be copied (may be null).
15087 </p>
15088 <p><var>sizeof_sig</var>: initially holds the size of <code>sig</code>
15089 </p>
15090 <p>This function will extract the signature field of a CRL.
15091 </p>
15092 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15093 negative error value. and a negative value on error.
15094 </p></dd></dl>
15095
15096 <a name="gnutls_005fx509_005fcrl_005fget_005fthis_005fupdate-1"></a>
15097 <h4 class="subheading">gnutls_x509_crl_get_this_update</h4>
15098 <a name="gnutls_005fx509_005fcrl_005fget_005fthis_005fupdate"></a><dl>
15099 <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>
15100 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code> structure
15101 </p>
15102 <p>This function will return the time this CRL was issued.
15103 </p>
15104 <p><strong>Returns:</strong> when the CRL was issued, or (time_t)-1 on error.
15105 </p></dd></dl>
15106
15107 <a name="gnutls_005fx509_005fcrl_005fget_005fversion-1"></a>
15108 <h4 class="subheading">gnutls_x509_crl_get_version</h4>
15109 <a name="gnutls_005fx509_005fcrl_005fget_005fversion"></a><dl>
15110 <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>
15111 <dd><p><var>crl</var>: should contain a <code>gnutls_x509_crl_t</code> structure
15112 </p>
15113 <p>This function will return the version of the specified CRL.
15114 </p>
15115 <p><strong>Returns:</strong> The version number, or a negative value on error.
15116 </p></dd></dl>
15117
15118 <a name="gnutls_005fx509_005fcrl_005fimport-1"></a>
15119 <h4 class="subheading">gnutls_x509_crl_import</h4>
15120 <a name="gnutls_005fx509_005fcrl_005fimport"></a><dl>
15121 <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>
15122 <dd><p><var>crl</var>: The structure to store the parsed CRL.
15123 </p>
15124 <p><var>data</var>: The DER or PEM encoded CRL.
15125 </p>
15126 <p><var>format</var>: One of DER or PEM
15127 </p>
15128 <p>This function will convert the given DER or PEM encoded CRL
15129 to the native <code>gnutls_x509_crl_t</code> format. The output will be stored in &rsquo;crl&rsquo;.
15130 </p>
15131 <p>If the CRL is PEM encoded it should have a header of &quot;X509 CRL&quot;.
15132 </p>
15133 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15134 negative error value.
15135 </p></dd></dl>
15136
15137 <a name="gnutls_005fx509_005fcrl_005finit-1"></a>
15138 <h4 class="subheading">gnutls_x509_crl_init</h4>
15139 <a name="gnutls_005fx509_005fcrl_005finit"></a><dl>
15140 <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>
15141 <dd><p><var>crl</var>: The structure to be initialized
15142 </p>
15143 <p>This function will initialize a CRL structure. CRL stands for
15144 Certificate Revocation List. A revocation list usually contains
15145 lists of certificate serial numbers that have been revoked by an
15146 Authority. The revocation lists are always signed with the
15147 authority&rsquo;s private key.
15148 </p>
15149 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15150 negative error value.
15151 </p></dd></dl>
15152
15153 <a name="gnutls_005fx509_005fcrl_005fprint-1"></a>
15154 <h4 class="subheading">gnutls_x509_crl_print</h4>
15155 <a name="gnutls_005fx509_005fcrl_005fprint"></a><dl>
15156 <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>
15157 <dd><p><var>crl</var>: The structure to be printed
15158 </p>
15159 <p><var>format</var>: Indicate the format to use
15160 </p>
15161 <p><var>out</var>: Newly allocated datum with zero terminated string.
15162 </p>
15163 <p>This function will pretty print a X.509 certificate revocation
15164 list, suitable for display to a human.
15165 </p>
15166 <p>The output <code>out</code> needs to be deallocate using <code>gnutls_free()</code>.
15167 </p>
15168 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15169 negative error value.
15170 </p></dd></dl>
15171
15172 <a name="gnutls_005fx509_005fcrl_005fprivkey_005fsign-1"></a>
15173 <h4 class="subheading">gnutls_x509_crl_privkey_sign</h4>
15174 <a name="gnutls_005fx509_005fcrl_005fprivkey_005fsign"></a><dl>
15175 <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>
15176 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
15177 </p>
15178 <p><var>issuer</var>: is the certificate of the certificate issuer
15179 </p>
15180 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
15181 </p>
15182 <p><var>dig</var>: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you&rsquo;re doing.
15183 </p>
15184 <p><var>flags</var>: must be 0
15185 </p>
15186 <p>This function will sign the CRL with the issuer&rsquo;s private key, and
15187 will copy the issuer&rsquo;s information into the CRL.
15188 </p>
15189 <p>This must be the last step in a certificate CRL since all
15190 the previously set parameters are now signed.
15191 </p>
15192 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15193 negative error value.
15194 </p></dd></dl>
15195
15196 <a name="gnutls_005fx509_005fcrl_005fset_005fauthority_005fkey_005fid-1"></a>
15197 <h4 class="subheading">gnutls_x509_crl_set_authority_key_id</h4>
15198 <a name="gnutls_005fx509_005fcrl_005fset_005fauthority_005fkey_005fid"></a><dl>
15199 <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>
15200 <dd><p><var>crl</var>: a CRL of type <code>gnutls_x509_crl_t</code>
15201 </p>
15202 <p><var>id</var>: The key ID
15203 </p>
15204 <p><var>id_size</var>: Holds the size of the serial field.
15205 </p>
15206 <p>This function will set the CRL&rsquo;s authority key ID extension.  Only
15207 the keyIdentifier field can be set with this function.
15208 </p>
15209 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15210 negative error value.
15211 </p>
15212 <p><strong>Since:</strong> 2.8.0
15213 </p></dd></dl>
15214
15215 <a name="gnutls_005fx509_005fcrl_005fset_005fcrt_005fserial-1"></a>
15216 <h4 class="subheading">gnutls_x509_crl_set_crt_serial</h4>
15217 <a name="gnutls_005fx509_005fcrl_005fset_005fcrt_005fserial"></a><dl>
15218 <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>
15219 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
15220 </p>
15221 <p><var>serial</var>: The revoked certificate&rsquo;s serial number
15222 </p>
15223 <p><var>serial_size</var>: Holds the size of the serial field.
15224 </p>
15225 <p><var>revocation_time</var>: The time this certificate was revoked
15226 </p>
15227 <p>This function will set a revoked certificate&rsquo;s serial number to the CRL.
15228 </p>
15229 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15230 negative error value.
15231 </p></dd></dl>
15232
15233 <a name="gnutls_005fx509_005fcrl_005fset_005fcrt-1"></a>
15234 <h4 class="subheading">gnutls_x509_crl_set_crt</h4>
15235 <a name="gnutls_005fx509_005fcrl_005fset_005fcrt"></a><dl>
15236 <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>
15237 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
15238 </p>
15239 <p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code> with the revoked certificate
15240 </p>
15241 <p><var>revocation_time</var>: The time this certificate was revoked
15242 </p>
15243 <p>This function will set a revoked certificate&rsquo;s serial number to the CRL.
15244 </p>
15245 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15246 negative error value.
15247 </p></dd></dl>
15248
15249 <a name="gnutls_005fx509_005fcrl_005fset_005fnext_005fupdate-1"></a>
15250 <h4 class="subheading">gnutls_x509_crl_set_next_update</h4>
15251 <a name="gnutls_005fx509_005fcrl_005fset_005fnext_005fupdate"></a><dl>
15252 <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>
15253 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
15254 </p>
15255 <p><var>exp_time</var>: The actual time
15256 </p>
15257 <p>This function will set the time this CRL will be updated.
15258 </p>
15259 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15260 negative error value.
15261 </p></dd></dl>
15262
15263 <a name="gnutls_005fx509_005fcrl_005fset_005fnumber-1"></a>
15264 <h4 class="subheading">gnutls_x509_crl_set_number</h4>
15265 <a name="gnutls_005fx509_005fcrl_005fset_005fnumber"></a><dl>
15266 <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>
15267 <dd><p><var>crl</var>: a CRL of type <code>gnutls_x509_crl_t</code>
15268 </p>
15269 <p><var>nr</var>: The CRL number
15270 </p>
15271 <p><var>nr_size</var>: Holds the size of the nr field.
15272 </p>
15273 <p>This function will set the CRL&rsquo;s number extension.
15274 </p>
15275 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15276 negative error value.
15277 </p>
15278 <p><strong>Since:</strong> 2.8.0
15279 </p></dd></dl>
15280
15281 <a name="gnutls_005fx509_005fcrl_005fset_005fthis_005fupdate-1"></a>
15282 <h4 class="subheading">gnutls_x509_crl_set_this_update</h4>
15283 <a name="gnutls_005fx509_005fcrl_005fset_005fthis_005fupdate"></a><dl>
15284 <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>
15285 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
15286 </p>
15287 <p><var>act_time</var>: The actual time
15288 </p>
15289 <p>This function will set the time this CRL was issued.
15290 </p>
15291 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15292 negative error value.
15293 </p></dd></dl>
15294
15295 <a name="gnutls_005fx509_005fcrl_005fset_005fversion-1"></a>
15296 <h4 class="subheading">gnutls_x509_crl_set_version</h4>
15297 <a name="gnutls_005fx509_005fcrl_005fset_005fversion"></a><dl>
15298 <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>
15299 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
15300 </p>
15301 <p><var>version</var>: holds the version number. For CRLv1 crls must be 1.
15302 </p>
15303 <p>This function will set the version of the CRL. This
15304 must be one for CRL version 1, and so on. The CRLs generated
15305 by gnutls should have a version number of 2.
15306 </p>
15307 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15308 negative error value.
15309 </p></dd></dl>
15310
15311 <a name="gnutls_005fx509_005fcrl_005fsign2-1"></a>
15312 <h4 class="subheading">gnutls_x509_crl_sign2</h4>
15313 <a name="gnutls_005fx509_005fcrl_005fsign2"></a><dl>
15314 <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>
15315 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
15316 </p>
15317 <p><var>issuer</var>: is the certificate of the certificate issuer
15318 </p>
15319 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
15320 </p>
15321 <p><var>dig</var>: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you&rsquo;re doing.
15322 </p>
15323 <p><var>flags</var>: must be 0
15324 </p>
15325 <p>This function will sign the CRL with the issuer&rsquo;s private key, and
15326 will copy the issuer&rsquo;s information into the CRL.
15327 </p>
15328 <p>This must be the last step in a certificate CRL since all
15329 the previously set parameters are now signed.
15330 </p>
15331 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15332 negative error value.
15333 </p>
15334 <p><strong>Deprecated:</strong> Use <code>gnutls_x509_crl_privkey_sign()</code> instead.
15335 </p></dd></dl>
15336
15337 <a name="gnutls_005fx509_005fcrl_005fsign-1"></a>
15338 <h4 class="subheading">gnutls_x509_crl_sign</h4>
15339 <a name="gnutls_005fx509_005fcrl_005fsign"></a><dl>
15340 <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>
15341 <dd><p><var>crl</var>: should contain a gnutls_x509_crl_t structure
15342 </p>
15343 <p><var>issuer</var>: is the certificate of the certificate issuer
15344 </p>
15345 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
15346 </p>
15347 <p>This function is the same a <code>gnutls_x509_crl_sign2()</code> with no flags, and
15348 SHA1 as the hash algorithm.
15349 </p>
15350 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15351 negative error value.
15352 </p>
15353 <p><strong>Deprecated:</strong> Use <code>gnutls_x509_crl_privkey_sign()</code>.
15354 </p></dd></dl>
15355
15356 <a name="gnutls_005fx509_005fcrl_005fverify-1"></a>
15357 <h4 class="subheading">gnutls_x509_crl_verify</h4>
15358 <a name="gnutls_005fx509_005fcrl_005fverify"></a><dl>
15359 <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>CA_list</var>, int <var>CA_list_length</var>, unsigned int <var>flags</var>, unsigned int * <var>verify</var>)</em></dt>
15360 <dd><p><var>crl</var>: is the crl to be verified
15361 </p>
15362 <p><var>CA_list</var>: is a certificate list that is considered to be trusted one
15363 </p>
15364 <p><var>CA_list_length</var>: holds the number of CA certificates in CA_list
15365 </p>
15366 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
15367 </p>
15368 <p><var>verify</var>: will hold the crl verification output.
15369 </p>
15370 <p>This function will try to verify the given crl and return its status.
15371 See <code>gnutls_x509_crt_list_verify()</code> for a detailed description of
15372 return values.
15373 </p>
15374 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15375 negative error value.
15376 </p></dd></dl>
15377
15378 <a name="gnutls_005fx509_005fcrq_005fdeinit-1"></a>
15379 <h4 class="subheading">gnutls_x509_crq_deinit</h4>
15380 <a name="gnutls_005fx509_005fcrq_005fdeinit"></a><dl>
15381 <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>
15382 <dd><p><var>crq</var>: The structure to be initialized
15383 </p>
15384 <p>This function will deinitialize a PKCS<code>10</code> certificate request
15385 structure.
15386 </p></dd></dl>
15387
15388 <a name="gnutls_005fx509_005fcrq_005fexport-1"></a>
15389 <h4 class="subheading">gnutls_x509_crq_export</h4>
15390 <a name="gnutls_005fx509_005fcrq_005fexport"></a><dl>
15391 <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>
15392 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15393 </p>
15394 <p><var>format</var>: the format of output params. One of PEM or DER.
15395 </p>
15396 <p><var>output_data</var>: will contain a certificate request PEM or DER encoded
15397 </p>
15398 <p><var>output_data_size</var>: holds the size of output_data (and will be
15399 replaced by the actual size of parameters)
15400 </p>
15401 <p>This function will export the certificate request to a PEM or DER
15402 encoded PKCS10 structure.
15403 </p>
15404 <p>If the buffer provided is not long enough to hold the output, then
15405 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> will be returned and
15406 *<code>output_data_size</code> will be updated.
15407 </p>
15408 <p>If the structure is PEM encoded, it will have a header of &quot;BEGIN
15409 NEW CERTIFICATE REQUEST&quot;.
15410 </p>
15411 <p><strong>Return value:</strong> In case of failure a negative value will be
15412 returned, and 0 on success.
15413 </p></dd></dl>
15414
15415 <a name="gnutls_005fx509_005fcrq_005fget_005fattribute_005fby_005foid-1"></a>
15416 <h4 class="subheading">gnutls_x509_crq_get_attribute_by_oid</h4>
15417 <a name="gnutls_005fx509_005fcrq_005fget_005fattribute_005fby_005foid"></a><dl>
15418 <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>sizeof_buf</var>)</em></dt>
15419 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15420 </p>
15421 <p><var>oid</var>: holds an Object Identified in zero-terminated string
15422 </p>
15423 <p><var>indx</var>: In case multiple same OIDs exist in the attribute list, this
15424 specifies which to send, use zero to get the first one
15425 </p>
15426 <p><var>buf</var>: a pointer to a structure to hold the attribute data (may be <code>NULL</code>)
15427 </p>
15428 <p><var>sizeof_buf</var>: initially holds the size of <code>buf</code>
15429 </p>
15430 <p>This function will return the attribute in the certificate request
15431 specified by the given Object ID.  The attribute will be DER
15432 encoded.
15433 </p>
15434 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15435 negative error value.
15436 </p></dd></dl>
15437
15438 <a name="gnutls_005fx509_005fcrq_005fget_005fattribute_005fdata-1"></a>
15439 <h4 class="subheading">gnutls_x509_crq_get_attribute_data</h4>
15440 <a name="gnutls_005fx509_005fcrq_005fget_005fattribute_005fdata"></a><dl>
15441 <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>
15442 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15443 </p>
15444 <p><var>indx</var>: Specifies which attribute OID to send. Use zero to get the first one.
15445 </p>
15446 <p><var>data</var>: a pointer to a structure to hold the data (may be null)
15447 </p>
15448 <p><var>sizeof_data</var>: initially holds the size of <code>oid</code>
15449 </p>
15450 <p>This function will return the requested attribute data in the
15451 certificate request.  The attribute data will be stored as a string in the
15452 provided buffer.
15453 </p>
15454 <p>Use <code>gnutls_x509_crq_get_attribute_info()</code> to extract the OID.
15455 Use <code>gnutls_x509_crq_get_attribute_by_oid()</code> instead,
15456 if you want to get data indexed by the attribute OID rather than
15457 sequence.
15458 </p>
15459 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15460 negative value in case of an error.  If your have reached the
15461 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
15462 will be returned.
15463 </p>
15464 <p><strong>Since:</strong> 2.8.0
15465 </p></dd></dl>
15466
15467 <a name="gnutls_005fx509_005fcrq_005fget_005fattribute_005finfo-1"></a>
15468 <h4 class="subheading">gnutls_x509_crq_get_attribute_info</h4>
15469 <a name="gnutls_005fx509_005fcrq_005fget_005fattribute_005finfo"></a><dl>
15470 <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>
15471 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15472 </p>
15473 <p><var>indx</var>: Specifies which attribute OID to send. Use zero to get the first one.
15474 </p>
15475 <p><var>oid</var>: a pointer to a structure to hold the OID
15476 </p>
15477 <p><var>sizeof_oid</var>: initially holds the maximum size of <code>oid</code>, on return
15478 holds actual size of <code>oid</code>.
15479 </p>
15480 <p>This function will return the requested attribute OID in the
15481 certificate, and the critical flag for it.  The attribute OID will
15482 be stored as a string in the provided buffer.  Use
15483 <code>gnutls_x509_crq_get_attribute_data()</code> to extract the data.
15484 </p>
15485 <p>If the buffer provided is not long enough to hold the output, then
15486 *<code>sizeof_oid</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> will be
15487 returned.
15488 </p>
15489 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15490 negative value in case of an error.  If your have reached the
15491 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
15492 will be returned.
15493 </p>
15494 <p><strong>Since:</strong> 2.8.0
15495 </p></dd></dl>
15496
15497 <a name="gnutls_005fx509_005fcrq_005fget_005fbasic_005fconstraints-1"></a>
15498 <h4 class="subheading">gnutls_x509_crq_get_basic_constraints</h4>
15499 <a name="gnutls_005fx509_005fcrq_005fget_005fbasic_005fconstraints"></a><dl>
15500 <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>, int * <var>ca</var>, int * <var>pathlen</var>)</em></dt>
15501 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15502 </p>
15503 <p><var>critical</var>: will be non zero if the extension is marked as critical
15504 </p>
15505 <p><var>ca</var>: pointer to output integer indicating CA status, may be NULL,
15506 value is 1 if the certificate CA flag is set, 0 otherwise.
15507 </p>
15508 <p><var>pathlen</var>: pointer to output integer indicating path length (may be
15509 NULL), non-negative values indicate a present pathLenConstraint
15510 field and the actual value, -1 indicate that the field is absent.
15511 </p>
15512 <p>This function will read the certificate&rsquo;s basic constraints, and
15513 return the certificates CA status.  It reads the basicConstraints
15514 X.509 extension (2.5.29.19).
15515 </p>
15516 <p><strong>Return value:</strong> If the certificate is a CA a positive value will be
15517 returned, or zero if the certificate does not have CA flag set.
15518 A negative value may be returned in case of errors.  If the
15519 certificate does not contain the basicConstraints extension
15520 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> will be returned.
15521 </p>
15522 <p><strong>Since:</strong> 2.8.0
15523 </p></dd></dl>
15524
15525 <a name="gnutls_005fx509_005fcrq_005fget_005fchallenge_005fpassword-1"></a>
15526 <h4 class="subheading">gnutls_x509_crq_get_challenge_password</h4>
15527 <a name="gnutls_005fx509_005fcrq_005fget_005fchallenge_005fpassword"></a><dl>
15528 <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>sizeof_pass</var>)</em></dt>
15529 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15530 </p>
15531 <p><var>pass</var>: will hold a zero-terminated password string
15532 </p>
15533 <p><var>sizeof_pass</var>: Initially holds the size of <code>pass</code>.
15534 </p>
15535 <p>This function will return the challenge password in the request.
15536 The challenge password is intended to be used for requesting a
15537 revocation of the certificate.
15538 </p>
15539 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15540 negative error value.
15541 </p></dd></dl>
15542
15543 <a name="gnutls_005fx509_005fcrq_005fget_005fdn_005fby_005foid-1"></a>
15544 <h4 class="subheading">gnutls_x509_crq_get_dn_by_oid</h4>
15545 <a name="gnutls_005fx509_005fcrq_005fget_005fdn_005fby_005foid"></a><dl>
15546 <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>sizeof_buf</var>)</em></dt>
15547 <dd><p><var>crq</var>: should contain a gnutls_x509_crq_t structure
15548 </p>
15549 <p><var>oid</var>: holds an Object Identified in null terminated string
15550 </p>
15551 <p><var>indx</var>: In case multiple same OIDs exist in the RDN, this specifies
15552 which to send. Use zero to get the first one.
15553 </p>
15554 <p><var>raw_flag</var>: If non zero returns the raw DER data of the DN part.
15555 </p>
15556 <p><var>buf</var>: a pointer to a structure to hold the name (may be <code>NULL</code>)
15557 </p>
15558 <p><var>sizeof_buf</var>: initially holds the size of <code>buf</code>
15559 </p>
15560 <p>This function will extract the part of the name of the Certificate
15561 request subject, specified by the given OID. The output will be
15562 encoded as described in RFC2253. The output string will be ASCII
15563 or UTF-8 encoded, depending on the certificate data.
15564 </p>
15565 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
15566 If raw flag is zero, this function will only return known OIDs as
15567 text. Other OIDs will be DER encoded, as described in RFC2253 &ndash;
15568 in hex format with a &rsquo;\#&rsquo; prefix.  You can check about known OIDs
15569 using <code>gnutls_x509_dn_oid_known()</code>.
15570 </p>
15571 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the provided buffer is
15572 not long enough, and in that case the *<code>sizeof_buf</code> will be
15573 updated with the required size.  On success 0 is returned.
15574 </p></dd></dl>
15575
15576 <a name="gnutls_005fx509_005fcrq_005fget_005fdn_005foid-1"></a>
15577 <h4 class="subheading">gnutls_x509_crq_get_dn_oid</h4>
15578 <a name="gnutls_005fx509_005fcrq_005fget_005fdn_005foid"></a><dl>
15579 <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>
15580 <dd><p><var>crq</var>: should contain a gnutls_x509_crq_t structure
15581 </p>
15582 <p><var>indx</var>: Specifies which DN OID to send. Use zero to get the first one.
15583 </p>
15584 <p><var>oid</var>: a pointer to a structure to hold the name (may be <code>NULL</code>)
15585 </p>
15586 <p><var>sizeof_oid</var>: initially holds the size of <code>oid</code>
15587 </p>
15588 <p>This function will extract the requested OID of the name of the
15589 certificate request subject, specified by the given index.
15590 </p>
15591 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the provided buffer is
15592 not long enough, and in that case the *<code>sizeof_oid</code> will be
15593 updated with the required size.  On success 0 is returned.
15594 </p></dd></dl>
15595
15596 <a name="gnutls_005fx509_005fcrq_005fget_005fdn-1"></a>
15597 <h4 class="subheading">gnutls_x509_crq_get_dn</h4>
15598 <a name="gnutls_005fx509_005fcrq_005fget_005fdn"></a><dl>
15599 <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>sizeof_buf</var>)</em></dt>
15600 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15601 </p>
15602 <p><var>buf</var>: a pointer to a structure to hold the name (may be <code>NULL</code>)
15603 </p>
15604 <p><var>sizeof_buf</var>: initially holds the size of <code>buf</code>
15605 </p>
15606 <p>This function will copy the name of the Certificate request subject
15607 to the provided buffer.  The name will be in the form
15608 &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as described in RFC 2253. The output string
15609 <code>buf</code> will be ASCII or UTF-8 encoded, depending on the certificate
15610 data.
15611 </p>
15612 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the provided buffer is not
15613 long enough, and in that case the *<code>sizeof_buf</code> will be updated with
15614 the required size.  On success 0 is returned.
15615 </p></dd></dl>
15616
15617 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005fby_005foid-1"></a>
15618 <h4 class="subheading">gnutls_x509_crq_get_extension_by_oid</h4>
15619 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005fby_005foid"></a><dl>
15620 <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>sizeof_buf</var>, unsigned int * <var>critical</var>)</em></dt>
15621 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15622 </p>
15623 <p><var>oid</var>: holds an Object Identified in null terminated string
15624 </p>
15625 <p><var>indx</var>: In case multiple same OIDs exist in the extensions, this
15626 specifies which to send. Use zero to get the first one.
15627 </p>
15628 <p><var>buf</var>: a pointer to a structure to hold the name (may be null)
15629 </p>
15630 <p><var>sizeof_buf</var>: initially holds the size of <code>buf</code>
15631 </p>
15632 <p><var>critical</var>: will be non zero if the extension is marked as critical
15633 </p>
15634 <p>This function will return the extension specified by the OID in
15635 the certificate.  The extensions will be returned as binary data
15636 DER encoded, in the provided buffer.
15637 </p>
15638 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15639 negative value in case of an error.  If the certificate does not
15640 contain the specified extension
15641 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> will be returned.
15642 </p>
15643 <p><strong>Since:</strong> 2.8.0
15644 </p></dd></dl>
15645
15646 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005fdata-1"></a>
15647 <h4 class="subheading">gnutls_x509_crq_get_extension_data</h4>
15648 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005fdata"></a><dl>
15649 <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>
15650 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15651 </p>
15652 <p><var>indx</var>: Specifies which extension OID to send. Use zero to get the first one.
15653 </p>
15654 <p><var>data</var>: a pointer to a structure to hold the data (may be null)
15655 </p>
15656 <p><var>sizeof_data</var>: initially holds the size of <code>oid</code>
15657 </p>
15658 <p>This function will return the requested extension data in the
15659 certificate.  The extension data will be stored as a string in the
15660 provided buffer.
15661 </p>
15662 <p>Use <code>gnutls_x509_crq_get_extension_info()</code> to extract the OID and
15663 critical flag.  Use <code>gnutls_x509_crq_get_extension_by_oid()</code> instead,
15664 if you want to get data indexed by the extension OID rather than
15665 sequence.
15666 </p>
15667 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15668 negative value in case of an error.  If your have reached the
15669 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
15670 will be returned.
15671 </p>
15672 <p><strong>Since:</strong> 2.8.0
15673 </p></dd></dl>
15674
15675 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005finfo-1"></a>
15676 <h4 class="subheading">gnutls_x509_crq_get_extension_info</h4>
15677 <a name="gnutls_005fx509_005fcrq_005fget_005fextension_005finfo"></a><dl>
15678 <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>, int * <var>critical</var>)</em></dt>
15679 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15680 </p>
15681 <p><var>indx</var>: Specifies which extension OID to send. Use zero to get the first one.
15682 </p>
15683 <p><var>oid</var>: a pointer to a structure to hold the OID
15684 </p>
15685 <p><var>sizeof_oid</var>: initially holds the maximum size of <code>oid</code>, on return
15686 holds actual size of <code>oid</code>.
15687 </p>
15688 <p><var>critical</var>: output variable with critical flag, may be NULL.
15689 </p>
15690 <p>This function will return the requested extension OID in the
15691 certificate, and the critical flag for it.  The extension OID will
15692 be stored as a string in the provided buffer.  Use
15693 <code>gnutls_x509_crq_get_extension_data()</code> to extract the data.
15694 </p>
15695 <p>If the buffer provided is not long enough to hold the output, then
15696 *<code>sizeof_oid</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> will be
15697 returned.
15698 </p>
15699 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15700 negative value in case of an error.  If your have reached the
15701 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
15702 will be returned.
15703 </p>
15704 <p><strong>Since:</strong> 2.8.0
15705 </p></dd></dl>
15706
15707 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005fid-1"></a>
15708 <h4 class="subheading">gnutls_x509_crq_get_key_id</h4>
15709 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005fid"></a><dl>
15710 <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>
15711 <dd><p><var>crq</var>: a certificate of type <code>gnutls_x509_crq_t</code>
15712 </p>
15713 <p><var>flags</var>: should be 0 for now
15714 </p>
15715 <p><var>output_data</var>: will contain the key ID
15716 </p>
15717 <p><var>output_data_size</var>: holds the size of output_data (and will be
15718 replaced by the actual size of parameters)
15719 </p>
15720 <p>This function will return a unique ID the depends on the public key
15721 parameters.  This ID can be used in checking whether a certificate
15722 corresponds to the given private key.
15723 </p>
15724 <p>If the buffer provided is not long enough to hold the output, then
15725 *<code>output_data_size</code> is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
15726 be returned.  The output will normally be a SHA-1 hash output,
15727 which is 20 bytes.
15728 </p>
15729 <p><strong>Return value:</strong> In case of failure a negative value will be
15730 returned, and 0 on success.
15731 </p>
15732 <p><strong>Since:</strong> 2.8.0
15733 </p></dd></dl>
15734
15735 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005fpurpose_005foid-1"></a>
15736 <h4 class="subheading">gnutls_x509_crq_get_key_purpose_oid</h4>
15737 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005fpurpose_005foid"></a><dl>
15738 <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>
15739 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15740 </p>
15741 <p><var>indx</var>: This specifies which OID to return, use zero to get the first one
15742 </p>
15743 <p><var>oid</var>: a pointer to a buffer to hold the OID (may be <code>NULL</code>)
15744 </p>
15745 <p><var>sizeof_oid</var>: initially holds the size of <code>oid</code>
15746 </p>
15747 <p><var>critical</var>: output variable with critical flag, may be <code>NULL</code>.
15748 </p>
15749 <p>This function will extract the key purpose OIDs of the Certificate
15750 specified by the given index.  These are stored in the Extended Key
15751 Usage extension (2.5.29.37).  See the GNUTLS_KP_* definitions for
15752 human readable names.
15753 </p>
15754 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the provided buffer is
15755 not long enough, and in that case the *<code>sizeof_oid</code> will be
15756 updated with the required size.  On success 0 is returned.
15757 </p>
15758 <p><strong>Since:</strong> 2.8.0
15759 </p></dd></dl>
15760
15761 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005frsa_005fraw-1"></a>
15762 <h4 class="subheading">gnutls_x509_crq_get_key_rsa_raw</h4>
15763 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005frsa_005fraw"></a><dl>
15764 <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>
15765 <dd><p><var>crq</var>: Holds the certificate
15766 </p>
15767 <p><var>m</var>: will hold the modulus
15768 </p>
15769 <p><var>e</var>: will hold the public exponent
15770 </p>
15771 <p>This function will export the RSA public key&rsquo;s parameters found in
15772 the given structure.  The new parameters will be allocated using
15773 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
15774 </p>
15775 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15776 negative error value.
15777 </p>
15778 <p><strong>Since:</strong> 2.8.0
15779 </p></dd></dl>
15780
15781 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005fusage-1"></a>
15782 <h4 class="subheading">gnutls_x509_crq_get_key_usage</h4>
15783 <a name="gnutls_005fx509_005fcrq_005fget_005fkey_005fusage"></a><dl>
15784 <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>
15785 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15786 </p>
15787 <p><var>key_usage</var>: where the key usage bits will be stored
15788 </p>
15789 <p><var>critical</var>: will be non zero if the extension is marked as critical
15790 </p>
15791 <p>This function will return certificate&rsquo;s key usage, by reading the
15792 keyUsage X.509 extension (2.5.29.15).  The key usage value will
15793 </p>
15794 <p><strong>ORed values of the:</strong> <code>GNUTLS_KEY_DIGITAL_SIGNATURE</code>,
15795 <code>GNUTLS_KEY_NON_REPUDIATION</code>, <code>GNUTLS_KEY_KEY_ENCIPHERMENT</code>,
15796 <code>GNUTLS_KEY_DATA_ENCIPHERMENT</code>, <code>GNUTLS_KEY_KEY_AGREEMENT</code>,
15797 <code>GNUTLS_KEY_KEY_CERT_SIGN</code>, <code>GNUTLS_KEY_CRL_SIGN</code>,
15798 <code>GNUTLS_KEY_ENCIPHER_ONLY</code>, <code>GNUTLS_KEY_DECIPHER_ONLY</code>.
15799 </p>
15800 <p><strong>Returns:</strong> the certificate key usage, or a negative value in case of
15801 parsing error.  If the certificate does not contain the keyUsage
15802 extension <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> will be
15803 returned.
15804 </p>
15805 <p><strong>Since:</strong> 2.8.0
15806 </p></dd></dl>
15807
15808 <a name="gnutls_005fx509_005fcrq_005fget_005fpk_005falgorithm-1"></a>
15809 <h4 class="subheading">gnutls_x509_crq_get_pk_algorithm</h4>
15810 <a name="gnutls_005fx509_005fcrq_005fget_005fpk_005falgorithm"></a><dl>
15811 <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>
15812 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15813 </p>
15814 <p><var>bits</var>: if bits is non-<code>NULL</code> it will hold the size of the parameters&rsquo; in bits
15815 </p>
15816 <p>This function will return the public key algorithm of a PKCS<code>10</code>
15817 certificate request.
15818 </p>
15819 <p>If bits is non-<code>NULL</code>, it should have enough size to hold the
15820 parameters size in bits.  For RSA the bits returned is the modulus.
15821 For DSA the bits returned are of the public exponent.
15822 </p>
15823 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code> enumeration on
15824 success, or a negative value on error.
15825 </p></dd></dl>
15826
15827 <a name="gnutls_005fx509_005fcrq_005fget_005fsubject_005falt_005fname-1"></a>
15828 <h4 class="subheading">gnutls_x509_crq_get_subject_alt_name</h4>
15829 <a name="gnutls_005fx509_005fcrq_005fget_005fsubject_005falt_005fname"></a><dl>
15830 <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>
15831 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15832 </p>
15833 <p><var>seq</var>: specifies the sequence number of the alt name, 0 for the
15834 first one, 1 for the second etc.
15835 </p>
15836 <p><var>ret</var>: is the place where the alternative name will be copied to
15837 </p>
15838 <p><var>ret_size</var>: holds the size of ret.
15839 </p>
15840 <p><var>ret_type</var>: holds the <code>gnutls_x509_subject_alt_name_t</code> name type
15841 </p>
15842 <p><var>critical</var>: will be non zero if the extension is marked as critical
15843 (may be null)
15844 </p>
15845 <p>This function will return the alternative names, contained in the
15846 given certificate.  It is the same as
15847 <code>gnutls_x509_crq_get_subject_alt_name()</code> except for the fact that it
15848 will return the type of the alternative name in <code>ret_type</code> even if
15849 the function fails for some reason (i.e.  the buffer provided is
15850 not enough).
15851 </p>
15852 <p><strong>Returns:</strong> the alternative subject name type on success, one of the
15853 enumerated <code>gnutls_x509_subject_alt_name_t</code>.  It will return
15854 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if <code>ret_size</code> is not large enough to
15855 hold the value.  In that case <code>ret_size</code> will be updated with the
15856 required size.  If the certificate request does not have an
15857 Alternative name with the specified sequence number then
15858 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> is returned.
15859 </p>
15860 <p><strong>Since:</strong> 2.8.0
15861 </p></dd></dl>
15862
15863 <a name="gnutls_005fx509_005fcrq_005fget_005fsubject_005falt_005fothername_005foid-1"></a>
15864 <h4 class="subheading">gnutls_x509_crq_get_subject_alt_othername_oid</h4>
15865 <a name="gnutls_005fx509_005fcrq_005fget_005fsubject_005falt_005fothername_005foid"></a><dl>
15866 <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>
15867 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15868 </p>
15869 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
15870 </p>
15871 <p><var>ret</var>: is the place where the otherName OID will be copied to
15872 </p>
15873 <p><var>ret_size</var>: holds the size of ret.
15874 </p>
15875 <p>This function will extract the type OID of an otherName Subject
15876 Alternative Name, contained in the given certificate, and return
15877 the type as an enumerated element.
15878 </p>
15879 <p>This function is only useful if
15880 <code>gnutls_x509_crq_get_subject_alt_name()</code> returned
15881 <code>GNUTLS_SAN_OTHERNAME</code>.
15882 </p>
15883 <p><strong>Returns:</strong> the alternative subject name type on success, one of the
15884 enumerated gnutls_x509_subject_alt_name_t.  For supported OIDs,
15885 it will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
15886 e.g. <code>GNUTLS_SAN_OTHERNAME_XMPP</code>, and <code>GNUTLS_SAN_OTHERNAME</code> for
15887 unknown OIDs.  It will return <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if
15888 <code>ret_size</code> is not large enough to hold the value.  In that case
15889 <code>ret_size</code> will be updated with the required size.  If the
15890 certificate does not have an Alternative name with the specified
15891 sequence number and with the otherName type then
15892 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> is returned.
15893 </p>
15894 <p><strong>Since:</strong> 2.8.0
15895 </p></dd></dl>
15896
15897 <a name="gnutls_005fx509_005fcrq_005fget_005fversion-1"></a>
15898 <h4 class="subheading">gnutls_x509_crq_get_version</h4>
15899 <a name="gnutls_005fx509_005fcrq_005fget_005fversion"></a><dl>
15900 <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>
15901 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15902 </p>
15903 <p>This function will return the version of the specified Certificate
15904 request.
15905 </p>
15906 <p><strong>Returns:</strong> version of certificate request, or a negative value on
15907 error.
15908 </p></dd></dl>
15909
15910 <a name="gnutls_005fx509_005fcrq_005fimport-1"></a>
15911 <h4 class="subheading">gnutls_x509_crq_import</h4>
15912 <a name="gnutls_005fx509_005fcrq_005fimport"></a><dl>
15913 <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>
15914 <dd><p><var>crq</var>: The structure to store the parsed certificate request.
15915 </p>
15916 <p><var>data</var>: The DER or PEM encoded certificate.
15917 </p>
15918 <p><var>format</var>: One of DER or PEM
15919 </p>
15920 <p>This function will convert the given DER or PEM encoded certificate
15921 request to a <code>gnutls_x509_crq_t</code> structure.  The output will be
15922 stored in <code>crq</code>.
15923 </p>
15924 <p>If the Certificate is PEM encoded it should have a header of &quot;NEW
15925 CERTIFICATE REQUEST&quot;.
15926 </p>
15927 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15928 negative error value.
15929 </p></dd></dl>
15930
15931 <a name="gnutls_005fx509_005fcrq_005finit-1"></a>
15932 <h4 class="subheading">gnutls_x509_crq_init</h4>
15933 <a name="gnutls_005fx509_005fcrq_005finit"></a><dl>
15934 <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>
15935 <dd><p><var>crq</var>: The structure to be initialized
15936 </p>
15937 <p>This function will initialize a PKCS<code>10</code> certificate request
15938 structure.
15939 </p>
15940 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15941 negative error value.
15942 </p></dd></dl>
15943
15944 <a name="gnutls_005fx509_005fcrq_005fprint-1"></a>
15945 <h4 class="subheading">gnutls_x509_crq_print</h4>
15946 <a name="gnutls_005fx509_005fcrq_005fprint"></a><dl>
15947 <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>
15948 <dd><p><var>crq</var>: The structure to be printed
15949 </p>
15950 <p><var>format</var>: Indicate the format to use
15951 </p>
15952 <p><var>out</var>: Newly allocated datum with zero terminated string.
15953 </p>
15954 <p>This function will pretty print a certificate request, suitable for
15955 display to a human.
15956 </p>
15957 <p>The output <code>out</code> needs to be deallocate using <code>gnutls_free()</code>.
15958 </p>
15959 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
15960 negative error value.
15961 </p>
15962 <p><strong>Since:</strong> 2.8.0
15963 </p></dd></dl>
15964
15965 <a name="gnutls_005fx509_005fcrq_005fprivkey_005fsign-1"></a>
15966 <h4 class="subheading">gnutls_x509_crq_privkey_sign</h4>
15967 <a name="gnutls_005fx509_005fcrq_005fprivkey_005fsign"></a><dl>
15968 <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>
15969 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15970 </p>
15971 <p><var>key</var>: holds a private key
15972 </p>
15973 <p><var>dig</var>: The message digest to use, i.e., <code>GNUTLS_DIG_SHA1</code>
15974 </p>
15975 <p><var>flags</var>: must be 0
15976 </p>
15977 <p>This function will sign the certificate request with a private key.
15978 This must be the same key as the one used in
15979 <code>gnutls_x509_crt_set_key()</code> since a certificate request is self
15980 signed.
15981 </p>
15982 <p>This must be the last step in a certificate request generation
15983 since all the previously set parameters are now signed.
15984 </p>
15985 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
15986 <code>GNUTLS_E_ASN1_VALUE_NOT_FOUND</code> is returned if you didn&rsquo;t set all
15987 information in the certificate request (e.g., the version using
15988 <code>gnutls_x509_crq_set_version()</code>).
15989 </p></dd></dl>
15990
15991 <a name="gnutls_005fx509_005fcrq_005fset_005fattribute_005fby_005foid-1"></a>
15992 <h4 class="subheading">gnutls_x509_crq_set_attribute_by_oid</h4>
15993 <a name="gnutls_005fx509_005fcrq_005fset_005fattribute_005fby_005foid"></a><dl>
15994 <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>sizeof_buf</var>)</em></dt>
15995 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
15996 </p>
15997 <p><var>oid</var>: holds an Object Identified in zero-terminated string
15998 </p>
15999 <p><var>buf</var>: a pointer to a structure that holds the attribute data
16000 </p>
16001 <p><var>sizeof_buf</var>: holds the size of <code>buf</code>
16002 </p>
16003 <p>This function will set the attribute in the certificate request
16004 specified by the given Object ID.  The attribute must be be DER
16005 encoded.
16006 </p>
16007 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
16008 negative error value.
16009 </p></dd></dl>
16010
16011 <a name="gnutls_005fx509_005fcrq_005fset_005fbasic_005fconstraints-1"></a>
16012 <h4 class="subheading">gnutls_x509_crq_set_basic_constraints</h4>
16013 <a name="gnutls_005fx509_005fcrq_005fset_005fbasic_005fconstraints"></a><dl>
16014 <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>
16015 <dd><p><var>crq</var>: a certificate request of type <code>gnutls_x509_crq_t</code>
16016 </p>
16017 <p><var>ca</var>: true(1) or false(0) depending on the Certificate authority status.
16018 </p>
16019 <p><var>pathLenConstraint</var>: non-negative values indicate maximum length of path,
16020 and negative values indicate that the pathLenConstraints field should
16021 not be present.
16022 </p>
16023 <p>This function will set the basicConstraints certificate extension.
16024 </p>
16025 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
16026 negative error value.
16027 </p>
16028 <p><strong>Since:</strong> 2.8.0
16029 </p></dd></dl>
16030
16031 <a name="gnutls_005fx509_005fcrq_005fset_005fchallenge_005fpassword-1"></a>
16032 <h4 class="subheading">gnutls_x509_crq_set_challenge_password</h4>
16033 <a name="gnutls_005fx509_005fcrq_005fset_005fchallenge_005fpassword"></a><dl>
16034 <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>
16035 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
16036 </p>
16037 <p><var>pass</var>: holds a zero-terminated password
16038 </p>
16039 <p>This function will set a challenge password to be used when
16040 revoking the request.
16041 </p>
16042 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
16043 negative error value.
16044 </p></dd></dl>
16045
16046 <a name="gnutls_005fx509_005fcrq_005fset_005fdn_005fby_005foid-1"></a>
16047 <h4 class="subheading">gnutls_x509_crq_set_dn_by_oid</h4>
16048 <a name="gnutls_005fx509_005fcrq_005fset_005fdn_005fby_005foid"></a><dl>
16049 <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>
16050 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
16051 </p>
16052 <p><var>oid</var>: holds an Object Identifier in a zero-terminated string
16053 </p>
16054 <p><var>raw_flag</var>: must be 0, or 1 if the data are DER encoded
16055 </p>
16056 <p><var>data</var>: a pointer to the input data
16057 </p>
16058 <p><var>sizeof_data</var>: holds the size of <code>data</code>
16059 </p>
16060 <p>This function will set the part of the name of the Certificate
16061 request subject, specified by the given OID.  The input string
16062 should be ASCII or UTF-8 encoded.
16063 </p>
16064 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
16065 With this function you can only set the known OIDs.  You can test
16066 for known OIDs using <code>gnutls_x509_dn_oid_known()</code>.  For OIDs that are
16067 not known (by gnutls) you should properly DER encode your data, and
16068 call this function with raw_flag set.
16069 </p>
16070 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
16071 negative error value.
16072 </p></dd></dl>
16073
16074 <a name="gnutls_005fx509_005fcrq_005fset_005fkey_005fpurpose_005foid-1"></a>
16075 <h4 class="subheading">gnutls_x509_crq_set_key_purpose_oid</h4>
16076 <a name="gnutls_005fx509_005fcrq_005fset_005fkey_005fpurpose_005foid"></a><dl>
16077 <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>
16078 <dd><p><var>crq</var>: a certificate of type <code>gnutls_x509_crq_t</code>
16079 </p>
16080 <p><var>oid</var>: a pointer to a zero-terminated string that holds the OID
16081 </p>
16082 <p><var>critical</var>: Whether this extension will be critical or not
16083 </p>
16084 <p>This function will set the key purpose OIDs of the Certificate.
16085 These are stored in the Extended Key Usage extension (2.5.29.37)
16086 See the GNUTLS_KP_* definitions for human readable names.
16087 </p>
16088 <p>Subsequent calls to this function will append OIDs to the OID list.
16089 </p>
16090 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
16091 negative error value.
16092 </p>
16093 <p><strong>Since:</strong> 2.8.0
16094 </p></dd></dl>
16095
16096 <a name="gnutls_005fx509_005fcrq_005fset_005fkey_005frsa_005fraw-1"></a>
16097 <h4 class="subheading">gnutls_x509_crq_set_key_rsa_raw</h4>
16098 <a name="gnutls_005fx509_005fcrq_005fset_005fkey_005frsa_005fraw"></a><dl>
16099 <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>
16100 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
16101 </p>
16102 <p><var>m</var>: holds the modulus
16103 </p>
16104 <p><var>e</var>: holds the public exponent
16105 </p>
16106 <p>This function will set the public parameters from the given private
16107 key to the request. Only RSA keys are currently supported.
16108 </p>
16109 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
16110 negative error value.
16111 </p>
16112 <p><strong>Since:</strong> 2.6.0
16113 </p></dd></dl>
16114
16115 <a name="gnutls_005fx509_005fcrq_005fset_005fkey_005fusage-1"></a>
16116 <h4 class="subheading">gnutls_x509_crq_set_key_usage</h4>
16117 <a name="gnutls_005fx509_005fcrq_005fset_005fkey_005fusage"></a><dl>
16118 <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>
16119 <dd><p><var>crq</var>: a certificate request of type <code>gnutls_x509_crq_t</code>
16120 </p>
16121 <p><var>usage</var>: an ORed sequence of the GNUTLS_KEY_* elements.
16122 </p>
16123 <p>This function will set the keyUsage certificate extension.
16124 </p>
16125 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
16126 negative error value.
16127 </p>
16128 <p><strong>Since:</strong> 2.8.0
16129 </p></dd></dl>
16130
16131 <a name="gnutls_005fx509_005fcrq_005fset_005fkey-1"></a>
16132 <h4 class="subheading">gnutls_x509_crq_set_key</h4>
16133 <a name="gnutls_005fx509_005fcrq_005fset_005fkey"></a><dl>
16134 <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>
16135 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
16136 </p>
16137 <p><var>key</var>: holds a private key
16138 </p>
16139 <p>This function will set the public parameters from the given private
16140 key to the request.  Only RSA keys are currently supported.
16141 </p>
16142 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
16143 negative error value.
16144 </p></dd></dl>
16145
16146 <a name="gnutls_005fx509_005fcrq_005fset_005fsubject_005falt_005fname-1"></a>
16147 <h4 class="subheading">gnutls_x509_crq_set_subject_alt_name</h4>
16148 <a name="gnutls_005fx509_005fcrq_005fset_005fsubject_005falt_005fname"></a><dl>
16149 <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>
16150 <dd><p><var>crq</var>: a certificate request of type <code>gnutls_x509_crq_t</code>
16151 </p>
16152 <p><var>nt</var>: is one of the <code>gnutls_x509_subject_alt_name_t</code> enumerations
16153 </p>
16154 <p><var>data</var>: The data to be set
16155 </p>
16156 <p><var>data_size</var>: The size of data to be set
16157 </p>
16158 <p><var>flags</var>: <code>GNUTLS_FSAN_SET</code> to clear previous data or
16159 <code>GNUTLS_FSAN_APPEND</code> to append.
16160 </p>
16161 <p>This function will set the subject alternative name certificate
16162 extension.  It can set the following types:
16163 </p>
16164 <p>&amp;GNUTLS_SAN_DNSNAME: as a text string
16165 </p>
16166 <p>&amp;GNUTLS_SAN_RFC822NAME: as a text string
16167 </p>
16168 <p>&amp;GNUTLS_SAN_URI: as a text string
16169 </p>
16170 <p>&amp;GNUTLS_SAN_IPADDRESS: as a binary IP address (4 or 16 bytes)
16171 </p>
16172 <p>Other values can be set as binary values with the proper DER encoding.
16173 </p>
16174 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
16175 negative error value.
16176 </p>
16177 <p><strong>Since:</strong> 2.8.0
16178 </p></dd></dl>
16179
16180 <a name="gnutls_005fx509_005fcrq_005fset_005fversion-1"></a>
16181 <h4 class="subheading">gnutls_x509_crq_set_version</h4>
16182 <a name="gnutls_005fx509_005fcrq_005fset_005fversion"></a><dl>
16183 <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>
16184 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
16185 </p>
16186 <p><var>version</var>: holds the version number, for v1 Requests must be 1
16187 </p>
16188 <p>This function will set the version of the certificate request.  For
16189 version 1 requests this must be one.
16190 </p>
16191 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
16192 negative error value.
16193 </p></dd></dl>
16194
16195 <a name="gnutls_005fx509_005fcrq_005fsign2-1"></a>
16196 <h4 class="subheading">gnutls_x509_crq_sign2</h4>
16197 <a name="gnutls_005fx509_005fcrq_005fsign2"></a><dl>
16198 <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>
16199 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
16200 </p>
16201 <p><var>key</var>: holds a private key
16202 </p>
16203 <p><var>dig</var>: The message digest to use, i.e., <code>GNUTLS_DIG_SHA1</code>
16204 </p>
16205 <p><var>flags</var>: must be 0
16206 </p>
16207 <p>This function will sign the certificate request with a private key.
16208 This must be the same key as the one used in
16209 <code>gnutls_x509_crt_set_key()</code> since a certificate request is self
16210 signed.
16211 </p>
16212 <p>This must be the last step in a certificate request generation
16213 since all the previously set parameters are now signed.
16214 </p>
16215 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
16216 <code>GNUTLS_E_ASN1_VALUE_NOT_FOUND</code> is returned if you didn&rsquo;t set all
16217 information in the certificate request (e.g., the version using
16218 <code>gnutls_x509_crq_set_version()</code>).
16219 </p>
16220 <p><strong>Deprecated:</strong> Use <code>gnutls_x509_crq_privkey_sign()</code> instead.
16221 </p></dd></dl>
16222
16223 <a name="gnutls_005fx509_005fcrq_005fsign-1"></a>
16224 <h4 class="subheading">gnutls_x509_crq_sign</h4>
16225 <a name="gnutls_005fx509_005fcrq_005fsign"></a><dl>
16226 <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>
16227 <dd><p><var>crq</var>: should contain a <code>gnutls_x509_crq_t</code> structure
16228 </p>
16229 <p><var>key</var>: holds a private key
16230 </p>
16231 <p>This function is the same a <code>gnutls_x509_crq_sign2()</code> with no flags,
16232 and SHA1 as the hash algorithm.
16233 </p>
16234 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
16235 negative error value.
16236 </p>
16237 <p><strong>Deprecated:</strong> Use <code>gnutls_x509_crq_privkey_sign()</code> instead.
16238 </p></dd></dl>
16239
16240 <a name="gnutls_005fx509_005fcrq_005fverify-1"></a>
16241 <h4 class="subheading">gnutls_x509_crq_verify</h4>
16242 <a name="gnutls_005fx509_005fcrq_005fverify"></a><dl>
16243 <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>
16244 <dd><p><var>crq</var>: is the crq to be verified
16245 </p>
16246 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
16247 </p>
16248 <p>This function will verify self signature in the certificate
16249 request and return its status.
16250 </p>
16251 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
16252 if verification failed, otherwise a negative error value.
16253 </p></dd></dl>
16254
16255 <a name="gnutls_005fx509_005fcrt_005fcheck_005fhostname-1"></a>
16256 <h4 class="subheading">gnutls_x509_crt_check_hostname</h4>
16257 <a name="gnutls_005fx509_005fcrt_005fcheck_005fhostname"></a><dl>
16258 <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>
16259 <dd><p><var>cert</var>: should contain an gnutls_x509_crt_t structure
16260 </p>
16261 <p><var>hostname</var>: A null terminated string that contains a DNS name
16262 </p>
16263 <p>This function will check if the given certificate&rsquo;s subject matches
16264 the given hostname.  This is a basic implementation of the matching
16265 described in RFC2818 (HTTPS), which takes into account wildcards,
16266 and the DNSName/IPAddress subject alternative name PKIX extension.
16267 </p>
16268 <p><strong>Returns:</strong> non zero for a successful match, and zero on failure.
16269 </p></dd></dl>
16270
16271 <a name="gnutls_005fx509_005fcrt_005fcheck_005fissuer-1"></a>
16272 <h4 class="subheading">gnutls_x509_crt_check_issuer</h4>
16273 <a name="gnutls_005fx509_005fcrt_005fcheck_005fissuer"></a><dl>
16274 <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>
16275 <dd><p><var>cert</var>: is the certificate to be checked
16276 </p>
16277 <p><var>issuer</var>: is the certificate of a possible issuer
16278 </p>
16279 <p>This function will check if the given certificate was issued by the
16280 given issuer. It checks the DN fields and the authority
16281 key identifier and subject key identifier fields match.
16282 </p>
16283 <p><strong>Returns:</strong> It will return true (1) if the given certificate is issued
16284 by the given issuer, and false (0) if not.  A negative value is
16285 returned in case of an error.
16286 </p></dd></dl>
16287
16288 <a name="gnutls_005fx509_005fcrt_005fcheck_005frevocation-1"></a>
16289 <h4 class="subheading">gnutls_x509_crt_check_revocation</h4>
16290 <a name="gnutls_005fx509_005fcrt_005fcheck_005frevocation"></a><dl>
16291 <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>
16292 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16293 </p>
16294 <p><var>crl_list</var>: should contain a list of gnutls_x509_crl_t structures
16295 </p>
16296 <p><var>crl_list_length</var>: the length of the crl_list
16297 </p>
16298 <p>This function will return check if the given certificate is
16299 revoked.  It is assumed that the CRLs have been verified before.
16300 </p>
16301 <p><strong>Returns:</strong> 0 if the certificate is NOT revoked, and 1 if it is.  A
16302 negative value is returned on error.
16303 </p></dd></dl>
16304
16305 <a name="gnutls_005fx509_005fcrt_005fcpy_005fcrl_005fdist_005fpoints-1"></a>
16306 <h4 class="subheading">gnutls_x509_crt_cpy_crl_dist_points</h4>
16307 <a name="gnutls_005fx509_005fcrt_005fcpy_005fcrl_005fdist_005fpoints"></a><dl>
16308 <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>
16309 <dd><p><var>dst</var>: a certificate of type <code>gnutls_x509_crt_t</code>
16310 </p>
16311 <p><var>src</var>: the certificate where the dist points will be copied from
16312 </p>
16313 <p>This function will copy the CRL distribution points certificate
16314 extension, from the source to the destination certificate.
16315 This may be useful to copy from a CA certificate to issued ones.
16316 </p>
16317 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
16318 negative error value.
16319 </p></dd></dl>
16320
16321 <a name="gnutls_005fx509_005fcrt_005fdeinit-1"></a>
16322 <h4 class="subheading">gnutls_x509_crt_deinit</h4>
16323 <a name="gnutls_005fx509_005fcrt_005fdeinit"></a><dl>
16324 <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>
16325 <dd><p><var>cert</var>: The structure to be deinitialized
16326 </p>
16327 <p>This function will deinitialize a certificate structure.
16328 </p></dd></dl>
16329
16330 <a name="gnutls_005fx509_005fcrt_005fexport-1"></a>
16331 <h4 class="subheading">gnutls_x509_crt_export</h4>
16332 <a name="gnutls_005fx509_005fcrt_005fexport"></a><dl>
16333 <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>
16334 <dd><p><var>cert</var>: Holds the certificate
16335 </p>
16336 <p><var>format</var>: the format of output params. One of PEM or DER.
16337 </p>
16338 <p><var>output_data</var>: will contain a certificate PEM or DER encoded
16339 </p>
16340 <p><var>output_data_size</var>: holds the size of output_data (and will be
16341 replaced by the actual size of parameters)
16342 </p>
16343 <p>This function will export the certificate to DER or PEM format.
16344 </p>
16345 <p>If the buffer provided is not long enough to hold the output, then
16346 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
16347 be returned.
16348 </p>
16349 <p>If the structure is PEM encoded, it will have a header
16350 of &quot;BEGIN CERTIFICATE&quot;.
16351 </p>
16352 <p><strong>Return value:</strong> In case of failure a negative value will be
16353 returned, and 0 on success.
16354 </p></dd></dl>
16355
16356 <a name="gnutls_005fx509_005fcrt_005fget_005factivation_005ftime-1"></a>
16357 <h4 class="subheading">gnutls_x509_crt_get_activation_time</h4>
16358 <a name="gnutls_005fx509_005fcrt_005fget_005factivation_005ftime"></a><dl>
16359 <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>
16360 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16361 </p>
16362 <p>This function will return the time this Certificate was or will be
16363 activated.
16364 </p>
16365 <p><strong>Returns:</strong> activation time, or (time_t)-1 on error.
16366 </p></dd></dl>
16367
16368 <a name="gnutls_005fx509_005fcrt_005fget_005fauthority_005fkey_005fid-1"></a>
16369 <h4 class="subheading">gnutls_x509_crt_get_authority_key_id</h4>
16370 <a name="gnutls_005fx509_005fcrt_005fget_005fauthority_005fkey_005fid"></a><dl>
16371 <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>ret</var>, size_t * <var>ret_size</var>, unsigned int * <var>critical</var>)</em></dt>
16372 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16373 </p>
16374 <p><var>ret</var>: The place where the identifier will be copied
16375 </p>
16376 <p><var>ret_size</var>: Holds the size of the result field.
16377 </p>
16378 <p><var>critical</var>: will be non zero if the extension is marked as critical (may be null)
16379 </p>
16380 <p>This function will return the X.509v3 certificate authority&rsquo;s key
16381 identifier.  This is obtained by the X.509 Authority Key
16382 identifier extension field (2.5.29.35). Note that this function
16383 only returns the keyIdentifier field of the extension.
16384 </p>
16385 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
16386 negative error value.
16387 </p></dd></dl>
16388
16389 <a name="gnutls_005fx509_005fcrt_005fget_005fbasic_005fconstraints-1"></a>
16390 <h4 class="subheading">gnutls_x509_crt_get_basic_constraints</h4>
16391 <a name="gnutls_005fx509_005fcrt_005fget_005fbasic_005fconstraints"></a><dl>
16392 <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>, int * <var>ca</var>, int * <var>pathlen</var>)</em></dt>
16393 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16394 </p>
16395 <p><var>critical</var>: will be non zero if the extension is marked as critical
16396 </p>
16397 <p><var>ca</var>: pointer to output integer indicating CA status, may be NULL,
16398 value is 1 if the certificate CA flag is set, 0 otherwise.
16399 </p>
16400 <p><var>pathlen</var>: pointer to output integer indicating path length (may be
16401 NULL), non-negative values indicate a present pathLenConstraint
16402 field and the actual value, -1 indicate that the field is absent.
16403 </p>
16404 <p>This function will read the certificate&rsquo;s basic constraints, and
16405 return the certificates CA status.  It reads the basicConstraints
16406 X.509 extension (2.5.29.19).
16407 </p>
16408 <p><strong>Return value:</strong> If the certificate is a CA a positive value will be
16409 returned, or zero if the certificate does not have CA flag set.  A
16410 negative value may be returned in case of errors.  If the
16411 certificate does not contain the basicConstraints extension
16412 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
16413 </p></dd></dl>
16414
16415 <a name="gnutls_005fx509_005fcrt_005fget_005fca_005fstatus-1"></a>
16416 <h4 class="subheading">gnutls_x509_crt_get_ca_status</h4>
16417 <a name="gnutls_005fx509_005fcrt_005fget_005fca_005fstatus"></a><dl>
16418 <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>
16419 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16420 </p>
16421 <p><var>critical</var>: will be non zero if the extension is marked as critical
16422 </p>
16423 <p>This function will return certificates CA status, by reading the
16424 basicConstraints X.509 extension (2.5.29.19). If the certificate is
16425 a CA a positive value will be returned, or zero if the certificate
16426 does not have CA flag set.
16427 </p>
16428 <p>Use <code>gnutls_x509_crt_get_basic_constraints()</code> if you want to read the
16429 pathLenConstraint field too.
16430 </p>
16431 <p><strong>Returns:</strong> A negative value may be returned in case of parsing error.
16432 If the certificate does not contain the basicConstraints extension
16433 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> will be returned.
16434 </p></dd></dl>
16435
16436 <a name="gnutls_005fx509_005fcrt_005fget_005fcrl_005fdist_005fpoints-1"></a>
16437 <h4 class="subheading">gnutls_x509_crt_get_crl_dist_points</h4>
16438 <a name="gnutls_005fx509_005fcrt_005fget_005fcrl_005fdist_005fpoints"></a><dl>
16439 <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>ret</var>, size_t * <var>ret_size</var>, unsigned int * <var>reason_flags</var>, unsigned int * <var>critical</var>)</em></dt>
16440 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16441 </p>
16442 <p><var>seq</var>: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.)
16443 </p>
16444 <p><var>ret</var>: is the place where the distribution point will be copied to
16445 </p>
16446 <p><var>ret_size</var>: holds the size of ret.
16447 </p>
16448 <p><var>reason_flags</var>: Revocation reasons flags.
16449 </p>
16450 <p><var>critical</var>: will be non zero if the extension is marked as critical (may be null)
16451 </p>
16452 <p>This function retrieves the CRL distribution points (2.5.29.31),
16453 contained in the given certificate in the X509v3 Certificate
16454 Extensions.
16455 </p>
16456 <p><code>reason_flags</code> should be an ORed sequence of
16457 <code>GNUTLS_CRL_REASON_UNUSED</code>, <code>GNUTLS_CRL_REASON_KEY_COMPROMISE</code>,
16458 <code>GNUTLS_CRL_REASON_CA_COMPROMISE</code>,
16459 <code>GNUTLS_CRL_REASON_AFFILIATION_CHANGED</code>,
16460 <code>GNUTLS_CRL_REASON_SUPERSEEDED</code>,
16461 <code>GNUTLS_CRL_REASON_CESSATION_OF_OPERATION</code>,
16462 <code>GNUTLS_CRL_REASON_CERTIFICATE_HOLD</code>,
16463 <code>GNUTLS_CRL_REASON_PRIVILEGE_WITHDRAWN</code>,
16464 <code>GNUTLS_CRL_REASON_AA_COMPROMISE</code>, or zero for all possible reasons.
16465 </p>
16466 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> and updates &amp;<code>ret_size</code> if
16467 &amp;<code>ret_size</code> is not enough to hold the distribution point, or the
16468 type of the distribution point if everything was ok. The type is
16469 one of the enumerated <code>gnutls_x509_subject_alt_name_t</code>.  If the
16470 certificate does not have an Alternative name with the specified
16471 sequence number then <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> is
16472 returned.
16473 </p></dd></dl>
16474
16475 <a name="gnutls_005fx509_005fcrt_005fget_005fdn_005fby_005foid-1"></a>
16476 <h4 class="subheading">gnutls_x509_crt_get_dn_by_oid</h4>
16477 <a name="gnutls_005fx509_005fcrt_005fget_005fdn_005fby_005foid"></a><dl>
16478 <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>sizeof_buf</var>)</em></dt>
16479 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16480 </p>
16481 <p><var>oid</var>: holds an Object Identified in null terminated string
16482 </p>
16483 <p><var>indx</var>: In case multiple same OIDs exist in the RDN, this specifies which to send. Use zero to get the first one.
16484 </p>
16485 <p><var>raw_flag</var>: If non zero returns the raw DER data of the DN part.
16486 </p>
16487 <p><var>buf</var>: a pointer where the DN part will be copied (may be null).
16488 </p>
16489 <p><var>sizeof_buf</var>: initially holds the size of <code>buf</code>
16490 </p>
16491 <p>This function will extract the part of the name of the Certificate
16492 subject specified by the given OID. The output, if the raw flag is
16493 not used, will be encoded as described in RFC2253. Thus a string
16494 that is ASCII or UTF-8 encoded, depending on the certificate data.
16495 </p>
16496 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
16497 If raw flag is zero, this function will only return known OIDs as
16498 text. Other OIDs will be DER encoded, as described in RFC2253 &ndash;
16499 in hex format with a &rsquo;\#&rsquo; prefix.  You can check about known OIDs
16500 using <code>gnutls_x509_dn_oid_known()</code>.
16501 </p>
16502 <p>If <code>buf</code> is null then only the size will be filled.
16503 </p>
16504 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the provided buffer is
16505 not long enough, and in that case the *sizeof_buf will be updated
16506 with the required size.  On success 0 is returned.
16507 </p></dd></dl>
16508
16509 <a name="gnutls_005fx509_005fcrt_005fget_005fdn_005foid-1"></a>
16510 <h4 class="subheading">gnutls_x509_crt_get_dn_oid</h4>
16511 <a name="gnutls_005fx509_005fcrt_005fget_005fdn_005foid"></a><dl>
16512 <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>sizeof_oid</var>)</em></dt>
16513 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16514 </p>
16515 <p><var>indx</var>: This specifies which OID to return. Use zero to get the first one.
16516 </p>
16517 <p><var>oid</var>: a pointer to a buffer to hold the OID (may be null)
16518 </p>
16519 <p><var>sizeof_oid</var>: initially holds the size of <code>oid</code>
16520 </p>
16521 <p>This function will extract the OIDs of the name of the Certificate
16522 subject specified by the given index.
16523 </p>
16524 <p>If oid is null then only the size will be filled.
16525 </p>
16526 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the provided buffer is
16527 not long enough, and in that case the *sizeof_oid will be updated
16528 with the required size.  On success 0 is returned.
16529 </p></dd></dl>
16530
16531 <a name="gnutls_005fx509_005fcrt_005fget_005fdn-1"></a>
16532 <h4 class="subheading">gnutls_x509_crt_get_dn</h4>
16533 <a name="gnutls_005fx509_005fcrt_005fget_005fdn"></a><dl>
16534 <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>sizeof_buf</var>)</em></dt>
16535 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16536 </p>
16537 <p><var>buf</var>: a pointer to a structure to hold the name (may be null)
16538 </p>
16539 <p><var>sizeof_buf</var>: initially holds the size of <code>buf</code>
16540 </p>
16541 <p>This function will copy the name of the Certificate in the provided
16542 buffer. The name will be in the form &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as
16543 described in RFC2253. The output string will be ASCII or UTF-8
16544 encoded, depending on the certificate data.
16545 </p>
16546 <p>If <code>buf</code> is null then only the size will be filled.
16547 </p>
16548 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the provided buffer is not
16549 long enough, and in that case the *sizeof_buf will be updated
16550 with the required size.  On success 0 is returned.
16551 </p></dd></dl>
16552
16553 <a name="gnutls_005fx509_005fcrt_005fget_005fexpiration_005ftime-1"></a>
16554 <h4 class="subheading">gnutls_x509_crt_get_expiration_time</h4>
16555 <a name="gnutls_005fx509_005fcrt_005fget_005fexpiration_005ftime"></a><dl>
16556 <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>
16557 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16558 </p>
16559 <p>This function will return the time this Certificate was or will be
16560 expired.
16561 </p>
16562 <p><strong>Returns:</strong> expiration time, or (time_t)-1 on error.
16563 </p></dd></dl>
16564
16565 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005fby_005foid-1"></a>
16566 <h4 class="subheading">gnutls_x509_crt_get_extension_by_oid</h4>
16567 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005fby_005foid"></a><dl>
16568 <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>sizeof_buf</var>, unsigned int * <var>critical</var>)</em></dt>
16569 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16570 </p>
16571 <p><var>oid</var>: holds an Object Identified in null terminated string
16572 </p>
16573 <p><var>indx</var>: In case multiple same OIDs exist in the extensions, this specifies which to send. Use zero to get the first one.
16574 </p>
16575 <p><var>buf</var>: a pointer to a structure to hold the name (may be null)
16576 </p>
16577 <p><var>sizeof_buf</var>: initially holds the size of <code>buf</code>
16578 </p>
16579 <p><var>critical</var>: will be non zero if the extension is marked as critical
16580 </p>
16581 <p>This function will return the extension specified by the OID in the
16582 certificate.  The extensions will be returned as binary data DER
16583 encoded, in the provided buffer.
16584 </p>
16585 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
16586 otherwise an error code is returned. If the certificate does not
16587 contain the specified extension
16588 GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
16589 </p></dd></dl>
16590
16591 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005fdata-1"></a>
16592 <h4 class="subheading">gnutls_x509_crt_get_extension_data</h4>
16593 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005fdata"></a><dl>
16594 <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>
16595 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16596 </p>
16597 <p><var>indx</var>: Specifies which extension OID to send. Use zero to get the first one.
16598 </p>
16599 <p><var>data</var>: a pointer to a structure to hold the data (may be null)
16600 </p>
16601 <p><var>sizeof_data</var>: initially holds the size of <code>oid</code>
16602 </p>
16603 <p>This function will return the requested extension data in the
16604 certificate.  The extension data will be stored as a string in the
16605 provided buffer.
16606 </p>
16607 <p>Use <code>gnutls_x509_crt_get_extension_info()</code> to extract the OID and
16608 critical flag.  Use <code>gnutls_x509_crt_get_extension_by_oid()</code> instead,
16609 if you want to get data indexed by the extension OID rather than
16610 sequence.
16611 </p>
16612 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
16613 otherwise an error code is returned.  If you have reached the
16614 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
16615 will be returned.
16616 </p></dd></dl>
16617
16618 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005finfo-1"></a>
16619 <h4 class="subheading">gnutls_x509_crt_get_extension_info</h4>
16620 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005finfo"></a><dl>
16621 <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>sizeof_oid</var>, int * <var>critical</var>)</em></dt>
16622 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16623 </p>
16624 <p><var>indx</var>: Specifies which extension OID to send. Use zero to get the first one.
16625 </p>
16626 <p><var>oid</var>: a pointer to a structure to hold the OID
16627 </p>
16628 <p><var>sizeof_oid</var>: initially holds the maximum size of <code>oid</code>, on return
16629 holds actual size of <code>oid</code>.
16630 </p>
16631 <p><var>critical</var>: output variable with critical flag, may be NULL.
16632 </p>
16633 <p>This function will return the requested extension OID in the
16634 certificate, and the critical flag for it.  The extension OID will
16635 be stored as a string in the provided buffer.  Use
16636 <code>gnutls_x509_crt_get_extension_data()</code> to extract the data.
16637 </p>
16638 <p>If the buffer provided is not long enough to hold the output, then
16639 *<code>sizeof_oid</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> will be
16640 returned.
16641 </p>
16642 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
16643 otherwise an error code is returned.  If you have reached the
16644 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
16645 will be returned.
16646 </p></dd></dl>
16647
16648 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005foid-1"></a>
16649 <h4 class="subheading">gnutls_x509_crt_get_extension_oid</h4>
16650 <a name="gnutls_005fx509_005fcrt_005fget_005fextension_005foid"></a><dl>
16651 <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>sizeof_oid</var>)</em></dt>
16652 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16653 </p>
16654 <p><var>indx</var>: Specifies which extension OID to send. Use zero to get the first one.
16655 </p>
16656 <p><var>oid</var>: a pointer to a structure to hold the OID (may be null)
16657 </p>
16658 <p><var>sizeof_oid</var>: initially holds the size of <code>oid</code>
16659 </p>
16660 <p>This function will return the requested extension OID in the certificate.
16661 The extension OID will be stored as a string in the provided buffer.
16662 </p>
16663 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
16664 otherwise an error code is returned.  If you have reached the
16665 last extension available <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>
16666 will be returned.
16667 </p></dd></dl>
16668
16669 <a name="gnutls_005fx509_005fcrt_005fget_005ffingerprint-1"></a>
16670 <h4 class="subheading">gnutls_x509_crt_get_fingerprint</h4>
16671 <a name="gnutls_005fx509_005fcrt_005fget_005ffingerprint"></a><dl>
16672 <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>sizeof_buf</var>)</em></dt>
16673 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16674 </p>
16675 <p><var>algo</var>: is a digest algorithm
16676 </p>
16677 <p><var>buf</var>: a pointer to a structure to hold the fingerprint (may be null)
16678 </p>
16679 <p><var>sizeof_buf</var>: initially holds the size of <code>buf</code>
16680 </p>
16681 <p>This function will calculate and copy the certificate&rsquo;s fingerprint
16682 in the provided buffer.
16683 </p>
16684 <p>If the buffer is null then only the size will be filled.
16685 </p>
16686 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the provided buffer is
16687 not long enough, and in that case the *sizeof_buf will be updated
16688 with the required size.  On success 0 is returned.
16689 </p></dd></dl>
16690
16691 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fname2-1"></a>
16692 <h4 class="subheading">gnutls_x509_crt_get_issuer_alt_name2</h4>
16693 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fname2"></a><dl>
16694 <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>ret</var>, size_t * <var>ret_size</var>, unsigned int * <var>ret_type</var>, unsigned int * <var>critical</var>)</em></dt>
16695 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16696 </p>
16697 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
16698 </p>
16699 <p><var>ret</var>: is the place where the alternative name will be copied to
16700 </p>
16701 <p><var>ret_size</var>: holds the size of ret.
16702 </p>
16703 <p><var>ret_type</var>: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
16704 </p>
16705 <p><var>critical</var>: will be non zero if the extension is marked as critical (may be null)
16706 </p>
16707 <p>This function will return the alternative names, contained in the
16708 given certificate. It is the same as
16709 <code>gnutls_x509_crt_get_issuer_alt_name()</code> except for the fact that it
16710 will return the type of the alternative name in <code>ret_type</code> even if
16711 the function fails for some reason (i.e.  the buffer provided is
16712 not enough).
16713 </p>
16714 <p><strong>Returns:</strong> the alternative issuer name type on success, one of the
16715 enumerated <code>gnutls_x509_subject_alt_name_t</code>.  It will return
16716 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if <code>ret_size</code> is not large enough
16717 to hold the value.  In that case <code>ret_size</code> will be updated with
16718 the required size.  If the certificate does not have an
16719 Alternative name with the specified sequence number then
16720 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> is returned.
16721 </p>
16722 <p><strong>Since:</strong> 2.10.0
16723 </p></dd></dl>
16724
16725 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fname-1"></a>
16726 <h4 class="subheading">gnutls_x509_crt_get_issuer_alt_name</h4>
16727 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fname"></a><dl>
16728 <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>ret</var>, size_t * <var>ret_size</var>, unsigned int * <var>critical</var>)</em></dt>
16729 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16730 </p>
16731 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
16732 </p>
16733 <p><var>ret</var>: is the place where the alternative name will be copied to
16734 </p>
16735 <p><var>ret_size</var>: holds the size of ret.
16736 </p>
16737 <p><var>critical</var>: will be non zero if the extension is marked as critical (may be null)
16738 </p>
16739 <p>This function retrieves the Issuer Alternative Name (2.5.29.18),
16740 contained in the given certificate in the X509v3 Certificate
16741 Extensions.
16742 </p>
16743 <p>When the SAN type is otherName, it will extract the data in the
16744 otherName&rsquo;s value field, and <code>GNUTLS_SAN_OTHERNAME</code> is returned.
16745 You may use <code>gnutls_x509_crt_get_subject_alt_othername_oid()</code> to get
16746 the corresponding OID and the &quot;virtual&quot; SAN types (e.g.,
16747 <code>GNUTLS_SAN_OTHERNAME_XMPP</code>).
16748 </p>
16749 <p>If an otherName OID is known, the data will be decoded.  Otherwise
16750 the returned data will be DER encoded, and you will have to decode
16751 it yourself.  Currently, only the RFC 3920 id-on-xmppAddr Issuer
16752 AltName is recognized.
16753 </p>
16754 <p><strong>Returns:</strong> the alternative issuer name type on success, one of the
16755 enumerated <code>gnutls_x509_subject_alt_name_t</code>.  It will return
16756 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if <code>ret_size</code> is not large enough
16757 to hold the value.  In that case <code>ret_size</code> will be updated with
16758 the required size.  If the certificate does not have an
16759 Alternative name with the specified sequence number then
16760 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> is returned.
16761 </p>
16762 <p><strong>Since:</strong> 2.10.0
16763 </p></dd></dl>
16764
16765 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fothername_005foid-1"></a>
16766 <h4 class="subheading">gnutls_x509_crt_get_issuer_alt_othername_oid</h4>
16767 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005falt_005fothername_005foid"></a><dl>
16768 <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>
16769 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16770 </p>
16771 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
16772 </p>
16773 <p><var>ret</var>: is the place where the otherName OID will be copied to
16774 </p>
16775 <p><var>ret_size</var>: holds the size of ret.
16776 </p>
16777 <p>This function will extract the type OID of an otherName Subject
16778 Alternative Name, contained in the given certificate, and return
16779 the type as an enumerated element.
16780 </p>
16781 <p>This function is only useful if
16782 <code>gnutls_x509_crt_get_issuer_alt_name()</code> returned
16783 <code>GNUTLS_SAN_OTHERNAME</code>.
16784 </p>
16785 <p><strong>Returns:</strong> the alternative issuer name type on success, one of the
16786 enumerated gnutls_x509_subject_alt_name_t.  For supported OIDs, it
16787 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
16788 e.g. <code>GNUTLS_SAN_OTHERNAME_XMPP</code>, and <code>GNUTLS_SAN_OTHERNAME</code> for
16789 unknown OIDs.  It will return <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if
16790 <code>ret_size</code> is not large enough to hold the value.  In that case
16791 <code>ret_size</code> will be updated with the required size.  If the
16792 certificate does not have an Alternative name with the specified
16793 sequence number and with the otherName type then
16794 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> is returned.
16795 </p>
16796 <p><strong>Since:</strong> 2.10.0
16797 </p></dd></dl>
16798
16799 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005fby_005foid-1"></a>
16800 <h4 class="subheading">gnutls_x509_crt_get_issuer_dn_by_oid</h4>
16801 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005fby_005foid"></a><dl>
16802 <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>sizeof_buf</var>)</em></dt>
16803 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16804 </p>
16805 <p><var>oid</var>: holds an Object Identified in null terminated string
16806 </p>
16807 <p><var>indx</var>: In case multiple same OIDs exist in the RDN, this specifies which to send. Use zero to get the first one.
16808 </p>
16809 <p><var>raw_flag</var>: If non zero returns the raw DER data of the DN part.
16810 </p>
16811 <p><var>buf</var>: a pointer to a structure to hold the name (may be null)
16812 </p>
16813 <p><var>sizeof_buf</var>: initially holds the size of <code>buf</code>
16814 </p>
16815 <p>This function will extract the part of the name of the Certificate
16816 issuer specified by the given OID. The output, if the raw flag is not
16817 used, will be encoded as described in RFC2253. Thus a string that is
16818 ASCII or UTF-8 encoded, depending on the certificate data.
16819 </p>
16820 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
16821 If raw flag is zero, this function will only return known OIDs as
16822 text. Other OIDs will be DER encoded, as described in RFC2253 &ndash;
16823 in hex format with a &rsquo;\#&rsquo; prefix.  You can check about known OIDs
16824 using <code>gnutls_x509_dn_oid_known()</code>.
16825 </p>
16826 <p>If <code>buf</code> is null then only the size will be filled.
16827 </p>
16828 <p><strong>Returns:</strong> GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
16829 long enough, and in that case the *sizeof_buf will be updated
16830 with the required size.  On success 0 is returned.
16831 </p></dd></dl>
16832
16833 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005foid-1"></a>
16834 <h4 class="subheading">gnutls_x509_crt_get_issuer_dn_oid</h4>
16835 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn_005foid"></a><dl>
16836 <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>sizeof_oid</var>)</em></dt>
16837 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16838 </p>
16839 <p><var>indx</var>: This specifies which OID to return. Use zero to get the first one.
16840 </p>
16841 <p><var>oid</var>: a pointer to a buffer to hold the OID (may be null)
16842 </p>
16843 <p><var>sizeof_oid</var>: initially holds the size of <code>oid</code>
16844 </p>
16845 <p>This function will extract the OIDs of the name of the Certificate
16846 issuer specified by the given index.
16847 </p>
16848 <p>If <code>oid</code> is null then only the size will be filled.
16849 </p>
16850 <p><strong>Returns:</strong> GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
16851 long enough, and in that case the *sizeof_oid will be updated
16852 with the required size.  On success 0 is returned.
16853 </p></dd></dl>
16854
16855 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn-1"></a>
16856 <h4 class="subheading">gnutls_x509_crt_get_issuer_dn</h4>
16857 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005fdn"></a><dl>
16858 <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>sizeof_buf</var>)</em></dt>
16859 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16860 </p>
16861 <p><var>buf</var>: a pointer to a structure to hold the name (may be null)
16862 </p>
16863 <p><var>sizeof_buf</var>: initially holds the size of <code>buf</code>
16864 </p>
16865 <p>This function will copy the name of the Certificate issuer in the
16866 provided buffer. The name will be in the form
16867 &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as described in RFC2253. The output string
16868 will be ASCII or UTF-8 encoded, depending on the certificate data.
16869 </p>
16870 <p>If <code>buf</code> is null then only the size will be filled.
16871 </p>
16872 <p><strong>Returns:</strong> GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
16873 long enough, and in that case the *sizeof_buf will be updated with
16874 the required size.  On success 0 is returned.
16875 </p></dd></dl>
16876
16877 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005funique_005fid-1"></a>
16878 <h4 class="subheading">gnutls_x509_crt_get_issuer_unique_id</h4>
16879 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer_005funique_005fid"></a><dl>
16880 <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>sizeof_buf</var>)</em></dt>
16881 <dd><p><var>crt</var>: Holds the certificate
16882 </p>
16883 <p><var>buf</var>: user allocated memory buffer, will hold the unique id
16884 </p>
16885 <p><var>sizeof_buf</var>: size of user allocated memory buffer (on input), will hold
16886 actual size of the unique ID on return.
16887 </p>
16888 <p>This function will extract the issuerUniqueID value (if present) for
16889 the given certificate.
16890 </p>
16891 <p>If the user allocated memory buffer is not large enough to hold the
16892 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
16893 returned, and sizeof_buf will be set to the actual length.
16894 </p>
16895 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
16896 </p></dd></dl>
16897
16898 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer-1"></a>
16899 <h4 class="subheading">gnutls_x509_crt_get_issuer</h4>
16900 <a name="gnutls_005fx509_005fcrt_005fget_005fissuer"></a><dl>
16901 <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>
16902 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16903 </p>
16904 <p><var>dn</var>: output variable with pointer to opaque DN
16905 </p>
16906 <p>Return the Certificate&rsquo;s Issuer DN as an opaque data type.  You may
16907 use <code>gnutls_x509_dn_get_rdn_ava()</code> to decode the DN.
16908 </p>
16909 <p>Note that <code>dn</code> should be treated as constant. Because points
16910 into the <code>cert</code> object, you may not deallocate <code>cert</code>
16911 and continue to access <code>dn</code>.
16912 </p>
16913 <p><strong>Returns:</strong> Returns 0 on success, or an error code.
16914 </p></dd></dl>
16915
16916 <a name="gnutls_005fx509_005fcrt_005fget_005fkey_005fid-1"></a>
16917 <h4 class="subheading">gnutls_x509_crt_get_key_id</h4>
16918 <a name="gnutls_005fx509_005fcrt_005fget_005fkey_005fid"></a><dl>
16919 <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>
16920 <dd><p><var>crt</var>: Holds the certificate
16921 </p>
16922 <p><var>flags</var>: should be 0 for now
16923 </p>
16924 <p><var>output_data</var>: will contain the key ID
16925 </p>
16926 <p><var>output_data_size</var>: holds the size of output_data (and will be
16927 replaced by the actual size of parameters)
16928 </p>
16929 <p>This function will return a unique ID the depends on the public
16930 key parameters. This ID can be used in checking whether a
16931 certificate corresponds to the given private key.
16932 </p>
16933 <p>If the buffer provided is not long enough to hold the output, then
16934 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
16935 be returned.  The output will normally be a SHA-1 hash output,
16936 which is 20 bytes.
16937 </p>
16938 <p><strong>Return value:</strong> In case of failure a negative value will be
16939 returned, and 0 on success.
16940 </p></dd></dl>
16941
16942 <a name="gnutls_005fx509_005fcrt_005fget_005fkey_005fpurpose_005foid-1"></a>
16943 <h4 class="subheading">gnutls_x509_crt_get_key_purpose_oid</h4>
16944 <a name="gnutls_005fx509_005fcrt_005fget_005fkey_005fpurpose_005foid"></a><dl>
16945 <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>sizeof_oid</var>, unsigned int * <var>critical</var>)</em></dt>
16946 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16947 </p>
16948 <p><var>indx</var>: This specifies which OID to return. Use zero to get the first one.
16949 </p>
16950 <p><var>oid</var>: a pointer to a buffer to hold the OID (may be null)
16951 </p>
16952 <p><var>sizeof_oid</var>: initially holds the size of <code>oid</code>
16953 </p>
16954 <p><var>critical</var>: output flag to indicate criticality of extension
16955 </p>
16956 <p>This function will extract the key purpose OIDs of the Certificate
16957 specified by the given index.  These are stored in the Extended Key
16958 Usage extension (2.5.29.37) See the GNUTLS_KP_* definitions for
16959 human readable names.
16960 </p>
16961 <p>If <code>oid</code> is null then only the size will be filled.
16962 </p>
16963 <p><strong>Returns:</strong> <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if the provided buffer is
16964 not long enough, and in that case the *sizeof_oid will be updated
16965 with the required size.  On success 0 is returned.
16966 </p></dd></dl>
16967
16968 <a name="gnutls_005fx509_005fcrt_005fget_005fkey_005fusage-1"></a>
16969 <h4 class="subheading">gnutls_x509_crt_get_key_usage</h4>
16970 <a name="gnutls_005fx509_005fcrt_005fget_005fkey_005fusage"></a><dl>
16971 <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>
16972 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16973 </p>
16974 <p><var>key_usage</var>: where the key usage bits will be stored
16975 </p>
16976 <p><var>critical</var>: will be non zero if the extension is marked as critical
16977 </p>
16978 <p>This function will return certificate&rsquo;s key usage, by reading the
16979 keyUsage X.509 extension (2.5.29.15). The key usage value will ORed
16980 values of the: <code>GNUTLS_KEY_DIGITAL_SIGNATURE</code>,
16981 <code>GNUTLS_KEY_NON_REPUDIATION</code>, <code>GNUTLS_KEY_KEY_ENCIPHERMENT</code>,
16982 <code>GNUTLS_KEY_DATA_ENCIPHERMENT</code>, <code>GNUTLS_KEY_KEY_AGREEMENT</code>,
16983 <code>GNUTLS_KEY_KEY_CERT_SIGN</code>, <code>GNUTLS_KEY_CRL_SIGN</code>,
16984 <code>GNUTLS_KEY_ENCIPHER_ONLY</code>, <code>GNUTLS_KEY_DECIPHER_ONLY</code>.
16985 </p>
16986 <p><strong>Returns:</strong> the certificate key usage, or a negative value in case of
16987 parsing error.  If the certificate does not contain the keyUsage
16988 extension <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> will be
16989 returned.
16990 </p></dd></dl>
16991
16992 <a name="gnutls_005fx509_005fcrt_005fget_005fpk_005falgorithm-1"></a>
16993 <h4 class="subheading">gnutls_x509_crt_get_pk_algorithm</h4>
16994 <a name="gnutls_005fx509_005fcrt_005fget_005fpk_005falgorithm"></a><dl>
16995 <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>
16996 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
16997 </p>
16998 <p><var>bits</var>: if bits is non null it will hold the size of the parameters&rsquo; in bits
16999 </p>
17000 <p>This function will return the public key algorithm of an X.509
17001 certificate.
17002 </p>
17003 <p>If bits is non null, it should have enough size to hold the parameters
17004 size in bits. For RSA the bits returned is the modulus.
17005 For DSA the bits returned are of the public
17006 exponent.
17007 </p>
17008 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code> enumeration on
17009 success, or a negative value on error.
17010 </p></dd></dl>
17011
17012 <a name="gnutls_005fx509_005fcrt_005fget_005fpk_005fdsa_005fraw-1"></a>
17013 <h4 class="subheading">gnutls_x509_crt_get_pk_dsa_raw</h4>
17014 <a name="gnutls_005fx509_005fcrt_005fget_005fpk_005fdsa_005fraw"></a><dl>
17015 <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>
17016 <dd><p><var>crt</var>: Holds the certificate
17017 </p>
17018 <p><var>p</var>: will hold the p
17019 </p>
17020 <p><var>q</var>: will hold the q
17021 </p>
17022 <p><var>g</var>: will hold the g
17023 </p>
17024 <p><var>y</var>: will hold the y
17025 </p>
17026 <p>This function will export the DSA public key&rsquo;s parameters found in
17027 the given certificate.  The new parameters will be allocated using
17028 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
17029 </p>
17030 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
17031 </p></dd></dl>
17032
17033 <a name="gnutls_005fx509_005fcrt_005fget_005fpk_005frsa_005fraw-1"></a>
17034 <h4 class="subheading">gnutls_x509_crt_get_pk_rsa_raw</h4>
17035 <a name="gnutls_005fx509_005fcrt_005fget_005fpk_005frsa_005fraw"></a><dl>
17036 <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>
17037 <dd><p><var>crt</var>: Holds the certificate
17038 </p>
17039 <p><var>m</var>: will hold the modulus
17040 </p>
17041 <p><var>e</var>: will hold the public exponent
17042 </p>
17043 <p>This function will export the RSA public key&rsquo;s parameters found in
17044 the given structure.  The new parameters will be allocated using
17045 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
17046 </p>
17047 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
17048 </p></dd></dl>
17049
17050 <a name="gnutls_005fx509_005fcrt_005fget_005fpreferred_005fhash_005falgorithm-1"></a>
17051 <h4 class="subheading">gnutls_x509_crt_get_preferred_hash_algorithm</h4>
17052 <a name="gnutls_005fx509_005fcrt_005fget_005fpreferred_005fhash_005falgorithm"></a><dl>
17053 <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>
17054 <dd><p><var>crt</var>: Holds the certificate
17055 </p>
17056 <p><var>hash</var>: The result of the call with the hash algorithm used for signature
17057 </p>
17058 <p><var>mand</var>: If non zero it means that the algorithm MUST use this hash. May be NULL.
17059 </p>
17060 <p>This function will read the certifcate and return the appropriate digest
17061 algorithm to use for signing with this certificate. Some certificates (i.e.
17062 DSA might not be able to sign without the preferred algorithm).
17063 </p>
17064 <p><strong>Deprecated:</strong> Please use <code>gnutls_pubkey_get_preferred_hash_algorithm()</code>.
17065 </p>
17066 <p><strong>Returns:</strong> the 0 if the hash algorithm is found. A negative value is
17067 returned on error.
17068 </p>
17069 <p><strong>Since:</strong> 2.11.0
17070 </p></dd></dl>
17071
17072 <a name="gnutls_005fx509_005fcrt_005fget_005fproxy-1"></a>
17073 <h4 class="subheading">gnutls_x509_crt_get_proxy</h4>
17074 <a name="gnutls_005fx509_005fcrt_005fget_005fproxy"></a><dl>
17075 <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>
17076 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
17077 </p>
17078 <p><var>critical</var>: will be non zero if the extension is marked as critical
17079 </p>
17080 <p><var>pathlen</var>: pointer to output integer indicating path length (may be
17081 NULL), non-negative values indicate a present pCPathLenConstraint
17082 field and the actual value, -1 indicate that the field is absent.
17083 </p>
17084 <p><var>policyLanguage</var>: output variable with OID of policy language
17085 </p>
17086 <p><var>policy</var>: output variable with policy data
17087 </p>
17088 <p><var>sizeof_policy</var>: output variable size of policy data
17089 </p>
17090 <p>This function will get information from a proxy certificate.  It
17091 reads the ProxyCertInfo X.509 extension (1.3.6.1.5.5.7.1.14).
17092 </p>
17093 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
17094 otherwise an error code is returned.
17095 </p></dd></dl>
17096
17097 <a name="gnutls_005fx509_005fcrt_005fget_005fraw_005fdn-1"></a>
17098 <h4 class="subheading">gnutls_x509_crt_get_raw_dn</h4>
17099 <a name="gnutls_005fx509_005fcrt_005fget_005fraw_005fdn"></a><dl>
17100 <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>start</var>)</em></dt>
17101 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
17102 </p>
17103 <p><var>start</var>: will hold the starting point of the DN
17104 </p>
17105 <p>This function will return a pointer to the DER encoded DN structure and
17106 the length.
17107 </p>
17108 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17109 negative error value. or a negative value on error.
17110 </p></dd></dl>
17111
17112 <a name="gnutls_005fx509_005fcrt_005fget_005fraw_005fissuer_005fdn-1"></a>
17113 <h4 class="subheading">gnutls_x509_crt_get_raw_issuer_dn</h4>
17114 <a name="gnutls_005fx509_005fcrt_005fget_005fraw_005fissuer_005fdn"></a><dl>
17115 <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>start</var>)</em></dt>
17116 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
17117 </p>
17118 <p><var>start</var>: will hold the starting point of the DN
17119 </p>
17120 <p>This function will return a pointer to the DER encoded DN structure
17121 and the length.
17122 </p>
17123 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17124 negative error value.or a negative value on error.
17125 </p></dd></dl>
17126
17127 <a name="gnutls_005fx509_005fcrt_005fget_005fserial-1"></a>
17128 <h4 class="subheading">gnutls_x509_crt_get_serial</h4>
17129 <a name="gnutls_005fx509_005fcrt_005fget_005fserial"></a><dl>
17130 <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>
17131 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
17132 </p>
17133 <p><var>result</var>: The place where the serial number will be copied
17134 </p>
17135 <p><var>result_size</var>: Holds the size of the result field.
17136 </p>
17137 <p>This function will return the X.509 certificate&rsquo;s serial number.
17138 This is obtained by the X509 Certificate serialNumber field. Serial
17139 is not always a 32 or 64bit number. Some CAs use large serial
17140 numbers, thus it may be wise to handle it as something opaque.
17141 </p>
17142 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17143 negative error value.
17144 </p></dd></dl>
17145
17146 <a name="gnutls_005fx509_005fcrt_005fget_005fsignature_005falgorithm-1"></a>
17147 <h4 class="subheading">gnutls_x509_crt_get_signature_algorithm</h4>
17148 <a name="gnutls_005fx509_005fcrt_005fget_005fsignature_005falgorithm"></a><dl>
17149 <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>
17150 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
17151 </p>
17152 <p>This function will return a value of the <code>gnutls_sign_algorithm_t</code>
17153 enumeration that is the signature algorithm that has been used to
17154 sign this certificate.
17155 </p>
17156 <p><strong>Returns:</strong> a <code>gnutls_sign_algorithm_t</code> value, or a negative value on
17157 error.
17158 </p></dd></dl>
17159
17160 <a name="gnutls_005fx509_005fcrt_005fget_005fsignature-1"></a>
17161 <h4 class="subheading">gnutls_x509_crt_get_signature</h4>
17162 <a name="gnutls_005fx509_005fcrt_005fget_005fsignature"></a><dl>
17163 <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>sizeof_sig</var>)</em></dt>
17164 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
17165 </p>
17166 <p><var>sig</var>: a pointer where the signature part will be copied (may be null).
17167 </p>
17168 <p><var>sizeof_sig</var>: initially holds the size of <code>sig</code>
17169 </p>
17170 <p>This function will extract the signature field of a certificate.
17171 </p>
17172 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17173 negative error value. and a negative value on error.
17174 </p></dd></dl>
17175
17176 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fname2-1"></a>
17177 <h4 class="subheading">gnutls_x509_crt_get_subject_alt_name2</h4>
17178 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fname2"></a><dl>
17179 <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>ret</var>, size_t * <var>ret_size</var>, unsigned int * <var>ret_type</var>, unsigned int * <var>critical</var>)</em></dt>
17180 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
17181 </p>
17182 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
17183 </p>
17184 <p><var>ret</var>: is the place where the alternative name will be copied to
17185 </p>
17186 <p><var>ret_size</var>: holds the size of ret.
17187 </p>
17188 <p><var>ret_type</var>: holds the type of the alternative name (one of gnutls_x509_subject_alt_name_t).
17189 </p>
17190 <p><var>critical</var>: will be non zero if the extension is marked as critical (may be null)
17191 </p>
17192 <p>This function will return the alternative names, contained in the
17193 given certificate. It is the same as
17194 <code>gnutls_x509_crt_get_subject_alt_name()</code> except for the fact that it
17195 will return the type of the alternative name in <code>ret_type</code> even if
17196 the function fails for some reason (i.e.  the buffer provided is
17197 not enough).
17198 </p>
17199 <p><strong>Returns:</strong> the alternative subject name type on success, one of the
17200 enumerated <code>gnutls_x509_subject_alt_name_t</code>.  It will return
17201 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if <code>ret_size</code> is not large enough
17202 to hold the value.  In that case <code>ret_size</code> will be updated with
17203 the required size.  If the certificate does not have an
17204 Alternative name with the specified sequence number then
17205 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> is returned.
17206 </p></dd></dl>
17207
17208 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fname-1"></a>
17209 <h4 class="subheading">gnutls_x509_crt_get_subject_alt_name</h4>
17210 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fname"></a><dl>
17211 <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>ret</var>, size_t * <var>ret_size</var>, unsigned int * <var>critical</var>)</em></dt>
17212 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
17213 </p>
17214 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
17215 </p>
17216 <p><var>ret</var>: is the place where the alternative name will be copied to
17217 </p>
17218 <p><var>ret_size</var>: holds the size of ret.
17219 </p>
17220 <p><var>critical</var>: will be non zero if the extension is marked as critical (may be null)
17221 </p>
17222 <p>This function retrieves the Alternative Name (2.5.29.17), contained
17223 in the given certificate in the X509v3 Certificate Extensions.
17224 </p>
17225 <p>When the SAN type is otherName, it will extract the data in the
17226 otherName&rsquo;s value field, and <code>GNUTLS_SAN_OTHERNAME</code> is returned.
17227 You may use <code>gnutls_x509_crt_get_subject_alt_othername_oid()</code> to get
17228 the corresponding OID and the &quot;virtual&quot; SAN types (e.g.,
17229 <code>GNUTLS_SAN_OTHERNAME_XMPP</code>).
17230 </p>
17231 <p>If an otherName OID is known, the data will be decoded.  Otherwise
17232 the returned data will be DER encoded, and you will have to decode
17233 it yourself.  Currently, only the RFC 3920 id-on-xmppAddr SAN is
17234 recognized.
17235 </p>
17236 <p><strong>Returns:</strong> the alternative subject name type on success, one of the
17237 enumerated <code>gnutls_x509_subject_alt_name_t</code>.  It will return
17238 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if <code>ret_size</code> is not large enough to
17239 hold the value.  In that case <code>ret_size</code> will be updated with the
17240 required size.  If the certificate does not have an Alternative
17241 name with the specified sequence number then
17242 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> is returned.
17243 </p></dd></dl>
17244
17245 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fothername_005foid-1"></a>
17246 <h4 class="subheading">gnutls_x509_crt_get_subject_alt_othername_oid</h4>
17247 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005falt_005fothername_005foid"></a><dl>
17248 <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>ret</var>, size_t * <var>ret_size</var>)</em></dt>
17249 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
17250 </p>
17251 <p><var>seq</var>: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
17252 </p>
17253 <p><var>ret</var>: is the place where the otherName OID will be copied to
17254 </p>
17255 <p><var>ret_size</var>: holds the size of ret.
17256 </p>
17257 <p>This function will extract the type OID of an otherName Subject
17258 Alternative Name, contained in the given certificate, and return
17259 the type as an enumerated element.
17260 </p>
17261 <p>This function is only useful if
17262 <code>gnutls_x509_crt_get_subject_alt_name()</code> returned
17263 <code>GNUTLS_SAN_OTHERNAME</code>.
17264 </p>
17265 <p><strong>Returns:</strong> the alternative subject name type on success, one of the
17266 enumerated gnutls_x509_subject_alt_name_t.  For supported OIDs, it
17267 will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
17268 e.g. <code>GNUTLS_SAN_OTHERNAME_XMPP</code>, and <code>GNUTLS_SAN_OTHERNAME</code> for
17269 unknown OIDs.  It will return <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> if
17270 <code>ret_size</code> is not large enough to hold the value.  In that case
17271 <code>ret_size</code> will be updated with the required size.  If the
17272 certificate does not have an Alternative name with the specified
17273 sequence number and with the otherName type then
17274 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> is returned.
17275 </p></dd></dl>
17276
17277 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005fkey_005fid-1"></a>
17278 <h4 class="subheading">gnutls_x509_crt_get_subject_key_id</h4>
17279 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005fkey_005fid"></a><dl>
17280 <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>
17281 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
17282 </p>
17283 <p><var>ret</var>: The place where the identifier will be copied
17284 </p>
17285 <p><var>ret_size</var>: Holds the size of the result field.
17286 </p>
17287 <p><var>critical</var>: will be non zero if the extension is marked as critical (may be null)
17288 </p>
17289 <p>This function will return the X.509v3 certificate&rsquo;s subject key
17290 identifier.  This is obtained by the X.509 Subject Key identifier
17291 extension field (2.5.29.14).
17292 </p>
17293 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17294 negative error value.
17295 </p></dd></dl>
17296
17297 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005funique_005fid-1"></a>
17298 <h4 class="subheading">gnutls_x509_crt_get_subject_unique_id</h4>
17299 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject_005funique_005fid"></a><dl>
17300 <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>sizeof_buf</var>)</em></dt>
17301 <dd><p><var>crt</var>: Holds the certificate
17302 </p>
17303 <p><var>buf</var>: user allocated memory buffer, will hold the unique id
17304 </p>
17305 <p><var>sizeof_buf</var>: size of user allocated memory buffer (on input), will hold
17306 actual size of the unique ID on return.
17307 </p>
17308 <p>This function will extract the subjectUniqueID value (if present) for
17309 the given certificate.
17310 </p>
17311 <p>If the user allocated memory buffer is not large enough to hold the
17312 full subjectUniqueID, then a GNUTLS_E_SHORT_MEMORY_BUFFER error will be
17313 returned, and sizeof_buf will be set to the actual length.
17314 </p>
17315 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
17316 </p></dd></dl>
17317
17318 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject-1"></a>
17319 <h4 class="subheading">gnutls_x509_crt_get_subject</h4>
17320 <a name="gnutls_005fx509_005fcrt_005fget_005fsubject"></a><dl>
17321 <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>
17322 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
17323 </p>
17324 <p><var>dn</var>: output variable with pointer to opaque DN.
17325 </p>
17326 <p>Return the Certificate&rsquo;s Subject DN as an opaque data type.  You
17327 may use <code>gnutls_x509_dn_get_rdn_ava()</code> to decode the DN.
17328 </p>
17329 <p>Note that <code>dn</code> should be treated as constant. Because points
17330 into the <code>cert</code> object, you may not deallocate <code>cert</code>
17331 and continue to access <code>dn</code>.
17332 </p>
17333 <p><strong>Returns:</strong> Returns 0 on success, or an error code.
17334 </p></dd></dl>
17335
17336 <a name="gnutls_005fx509_005fcrt_005fget_005fverify_005falgorithm-1"></a>
17337 <h4 class="subheading">gnutls_x509_crt_get_verify_algorithm</h4>
17338 <a name="gnutls_005fx509_005fcrt_005fget_005fverify_005falgorithm"></a><dl>
17339 <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>
17340 <dd><p><var>crt</var>: Holds the certificate
17341 </p>
17342 <p><var>signature</var>: contains the signature
17343 </p>
17344 <p><var>hash</var>: The result of the call with the hash algorithm used for signature
17345 </p>
17346 <p>This function will read the certifcate and the signed data to
17347 determine the hash algorithm used to generate the signature.
17348 </p>
17349 <p><strong>Deprecated:</strong> Use <code>gnutls_pubkey_get_verify_algorithm()</code> instead.
17350 </p>
17351 <p><strong>Returns:</strong> the 0 if the hash algorithm is found. A negative value is
17352 returned on error.
17353 </p>
17354 <p><strong>Since:</strong> 2.8.0
17355 </p></dd></dl>
17356
17357 <a name="gnutls_005fx509_005fcrt_005fget_005fversion-1"></a>
17358 <h4 class="subheading">gnutls_x509_crt_get_version</h4>
17359 <a name="gnutls_005fx509_005fcrt_005fget_005fversion"></a><dl>
17360 <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>
17361 <dd><p><var>cert</var>: should contain a <code>gnutls_x509_crt_t</code> structure
17362 </p>
17363 <p>This function will return the version of the specified Certificate.
17364 </p>
17365 <p><strong>Returns:</strong> version of certificate, or a negative value on error.
17366 </p></dd></dl>
17367
17368 <a name="gnutls_005fx509_005fcrt_005fimport-1"></a>
17369 <h4 class="subheading">gnutls_x509_crt_import</h4>
17370 <a name="gnutls_005fx509_005fcrt_005fimport"></a><dl>
17371 <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>
17372 <dd><p><var>cert</var>: The structure to store the parsed certificate.
17373 </p>
17374 <p><var>data</var>: The DER or PEM encoded certificate.
17375 </p>
17376 <p><var>format</var>: One of DER or PEM
17377 </p>
17378 <p>This function will convert the given DER or PEM encoded Certificate
17379 to the native gnutls_x509_crt_t format. The output will be stored
17380 in <code>cert</code>.
17381 </p>
17382 <p>If the Certificate is PEM encoded it should have a header of &quot;X509
17383 CERTIFICATE&quot;, or &quot;CERTIFICATE&quot;.
17384 </p>
17385 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17386 negative error value.
17387 </p></dd></dl>
17388
17389 <a name="gnutls_005fx509_005fcrt_005finit-1"></a>
17390 <h4 class="subheading">gnutls_x509_crt_init</h4>
17391 <a name="gnutls_005fx509_005fcrt_005finit"></a><dl>
17392 <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>
17393 <dd><p><var>cert</var>: The structure to be initialized
17394 </p>
17395 <p>This function will initialize an X.509 certificate structure.
17396 </p>
17397 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17398 negative error value.
17399 </p></dd></dl>
17400
17401 <a name="gnutls_005fx509_005fcrt_005flist_005fimport-1"></a>
17402 <h4 class="subheading">gnutls_x509_crt_list_import</h4>
17403 <a name="gnutls_005fx509_005fcrt_005flist_005fimport"></a><dl>
17404 <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>
17405 <dd><p><var>certs</var>: The structures to store the parsed certificate. Must not be initialized.
17406 </p>
17407 <p><var>cert_max</var>: Initially must hold the maximum number of certs. It will be updated with the number of certs available.
17408 </p>
17409 <p><var>data</var>: The PEM encoded certificate.
17410 </p>
17411 <p><var>format</var>: One of DER or PEM.
17412 </p>
17413 <p><var>flags</var>: must be zero or an OR&rsquo;d sequence of gnutls_certificate_import_flags.
17414 </p>
17415 <p>This function will convert the given PEM encoded certificate list
17416 to the native gnutls_x509_crt_t format. The output will be stored
17417 in <code>certs</code>.  They will be automatically initialized.
17418 </p>
17419 <p>The flag <code>GNUTLS_X509_CRT_LIST_IMPORT_FAIL_IF_EXCEED</code> will cause
17420 import to fail if the certificates in the provided buffer are more
17421 than the available structures. The <code>GNUTLS_X509_CRT_LIST_FAIL_IF_UNSORTED</code>
17422 flag will cause the function to fail if the provided list is not
17423 sorted from subject to issuer.
17424 </p>
17425 <p>If the Certificate is PEM encoded it should have a header of &quot;X509
17426 CERTIFICATE&quot;, or &quot;CERTIFICATE&quot;.
17427 </p>
17428 <p><strong>Returns:</strong> the number of certificates read or a negative error value.
17429 </p></dd></dl>
17430
17431 <a name="gnutls_005fx509_005fcrt_005flist_005fverify-1"></a>
17432 <h4 class="subheading">gnutls_x509_crt_list_verify</h4>
17433 <a name="gnutls_005fx509_005fcrt_005flist_005fverify"></a><dl>
17434 <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>
17435 <dd><p><var>cert_list</var>: is the certificate list to be verified
17436 </p>
17437 <p><var>cert_list_length</var>: holds the number of certificate in cert_list
17438 </p>
17439 <p><var>CA_list</var>: is the CA list which will be used in verification
17440 </p>
17441 <p><var>CA_list_length</var>: holds the number of CA certificate in CA_list
17442 </p>
17443 <p><var>CRL_list</var>: holds a list of CRLs.
17444 </p>
17445 <p><var>CRL_list_length</var>: the length of CRL list.
17446 </p>
17447 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
17448 </p>
17449 <p><var>verify</var>: will hold the certificate verification output.
17450 </p>
17451 <p>This function will try to verify the given certificate list and
17452 return its status.  If no flags are specified (0), this function
17453 will use the basicConstraints (2.5.29.19) PKIX extension. This
17454 means that only a certificate authority is allowed to sign a
17455 certificate.
17456 </p>
17457 <p>You must also check the peer&rsquo;s name in order to check if the verified
17458 certificate belongs to the actual peer.
17459 </p>
17460 <p>The certificate verification output will be put in <code>verify</code> and will
17461 be one or more of the gnutls_certificate_status_t enumerated
17462 elements bitwise or&rsquo;d.  For a more detailed verification status use
17463 <code>gnutls_x509_crt_verify()</code> per list element.
17464 </p>
17465 <p><strong>GNUTLS_CERT_INVALID:</strong> the certificate chain is not valid.
17466 </p>
17467 <p><strong>GNUTLS_CERT_REVOKED:</strong> a certificate in the chain has been revoked.
17468 </p>
17469 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17470 negative error value.
17471 </p></dd></dl>
17472
17473 <a name="gnutls_005fx509_005fcrt_005fprint-1"></a>
17474 <h4 class="subheading">gnutls_x509_crt_print</h4>
17475 <a name="gnutls_005fx509_005fcrt_005fprint"></a><dl>
17476 <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>
17477 <dd><p><var>cert</var>: The structure to be printed
17478 </p>
17479 <p><var>format</var>: Indicate the format to use
17480 </p>
17481 <p><var>out</var>: Newly allocated datum with zero terminated string.
17482 </p>
17483 <p>This function will pretty print a X.509 certificate, suitable for
17484 display to a human.
17485 </p>
17486 <p>If the format is <code>GNUTLS_CRT_PRINT_FULL</code> then all fields of the
17487 certificate will be output, on multiple lines.  The
17488 <code>GNUTLS_CRT_PRINT_ONELINE</code> format will generate one line with some
17489 selected fields, which is useful for logging purposes.
17490 </p>
17491 <p>The output <code>out</code> needs to be deallocate using <code>gnutls_free()</code>.
17492 </p>
17493 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17494 negative error value.
17495 </p></dd></dl>
17496
17497 <a name="gnutls_005fx509_005fcrt_005fprivkey_005fsign-1"></a>
17498 <h4 class="subheading">gnutls_x509_crt_privkey_sign</h4>
17499 <a name="gnutls_005fx509_005fcrt_005fprivkey_005fsign"></a><dl>
17500 <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>
17501 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17502 </p>
17503 <p><var>issuer</var>: is the certificate of the certificate issuer
17504 </p>
17505 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
17506 </p>
17507 <p><var>dig</var>: The message digest to use, <code>GNUTLS_DIG_SHA1</code> is a safe choice
17508 </p>
17509 <p><var>flags</var>: must be 0
17510 </p>
17511 <p>This function will sign the certificate with the issuer&rsquo;s private key, and
17512 will copy the issuer&rsquo;s information into the certificate.
17513 </p>
17514 <p>This must be the last step in a certificate generation since all
17515 the previously set parameters are now signed.
17516 </p>
17517 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17518 negative error value.
17519 </p></dd></dl>
17520
17521 <a name="gnutls_005fx509_005fcrt_005fset_005factivation_005ftime-1"></a>
17522 <h4 class="subheading">gnutls_x509_crt_set_activation_time</h4>
17523 <a name="gnutls_005fx509_005fcrt_005fset_005factivation_005ftime"></a><dl>
17524 <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>
17525 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17526 </p>
17527 <p><var>act_time</var>: The actual time
17528 </p>
17529 <p>This function will set the time this Certificate was or will be
17530 activated.
17531 </p>
17532 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17533 negative error value.
17534 </p></dd></dl>
17535
17536 <a name="gnutls_005fx509_005fcrt_005fset_005fauthority_005fkey_005fid-1"></a>
17537 <h4 class="subheading">gnutls_x509_crt_set_authority_key_id</h4>
17538 <a name="gnutls_005fx509_005fcrt_005fset_005fauthority_005fkey_005fid"></a><dl>
17539 <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>
17540 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17541 </p>
17542 <p><var>id</var>: The key ID
17543 </p>
17544 <p><var>id_size</var>: Holds the size of the serial field.
17545 </p>
17546 <p>This function will set the X.509 certificate&rsquo;s authority key ID extension.
17547 Only the keyIdentifier field can be set with this function.
17548 </p>
17549 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17550 negative error value.
17551 </p></dd></dl>
17552
17553 <a name="gnutls_005fx509_005fcrt_005fset_005fbasic_005fconstraints-1"></a>
17554 <h4 class="subheading">gnutls_x509_crt_set_basic_constraints</h4>
17555 <a name="gnutls_005fx509_005fcrt_005fset_005fbasic_005fconstraints"></a><dl>
17556 <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>
17557 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17558 </p>
17559 <p><var>ca</var>: true(1) or false(0). Depending on the Certificate authority status.
17560 </p>
17561 <p><var>pathLenConstraint</var>: non-negative values indicate maximum length of path,
17562 and negative values indicate that the pathLenConstraints field should
17563 not be present.
17564 </p>
17565 <p>This function will set the basicConstraints certificate extension.
17566 </p>
17567 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17568 negative error value.
17569 </p></dd></dl>
17570
17571 <a name="gnutls_005fx509_005fcrt_005fset_005fca_005fstatus-1"></a>
17572 <h4 class="subheading">gnutls_x509_crt_set_ca_status</h4>
17573 <a name="gnutls_005fx509_005fcrt_005fset_005fca_005fstatus"></a><dl>
17574 <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>
17575 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17576 </p>
17577 <p><var>ca</var>: true(1) or false(0). Depending on the Certificate authority status.
17578 </p>
17579 <p>This function will set the basicConstraints certificate extension.
17580 Use <code>gnutls_x509_crt_set_basic_constraints()</code> if you want to control
17581 the pathLenConstraint field too.
17582 </p>
17583 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17584 negative error value.
17585 </p></dd></dl>
17586
17587 <a name="gnutls_005fx509_005fcrt_005fset_005fcrl_005fdist_005fpoints2-1"></a>
17588 <h4 class="subheading">gnutls_x509_crt_set_crl_dist_points2</h4>
17589 <a name="gnutls_005fx509_005fcrt_005fset_005fcrl_005fdist_005fpoints2"></a><dl>
17590 <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>
17591 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17592 </p>
17593 <p><var>type</var>: is one of the gnutls_x509_subject_alt_name_t enumerations
17594 </p>
17595 <p><var>data</var>: The data to be set
17596 </p>
17597 <p><var>data_size</var>: The data size
17598 </p>
17599 <p><var>reason_flags</var>: revocation reasons
17600 </p>
17601 <p>This function will set the CRL distribution points certificate extension.
17602 </p>
17603 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17604 negative error value.
17605 </p>
17606 <p><strong>Since:</strong> 2.6.0
17607 </p></dd></dl>
17608
17609 <a name="gnutls_005fx509_005fcrt_005fset_005fcrl_005fdist_005fpoints-1"></a>
17610 <h4 class="subheading">gnutls_x509_crt_set_crl_dist_points</h4>
17611 <a name="gnutls_005fx509_005fcrt_005fset_005fcrl_005fdist_005fpoints"></a><dl>
17612 <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>
17613 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17614 </p>
17615 <p><var>type</var>: is one of the gnutls_x509_subject_alt_name_t enumerations
17616 </p>
17617 <p><var>data_string</var>: The data to be set
17618 </p>
17619 <p><var>reason_flags</var>: revocation reasons
17620 </p>
17621 <p>This function will set the CRL distribution points certificate extension.
17622 </p>
17623 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17624 negative error value.
17625 </p></dd></dl>
17626
17627 <a name="gnutls_005fx509_005fcrt_005fset_005fcrq_005fextensions-1"></a>
17628 <h4 class="subheading">gnutls_x509_crt_set_crq_extensions</h4>
17629 <a name="gnutls_005fx509_005fcrt_005fset_005fcrq_005fextensions"></a><dl>
17630 <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>
17631 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17632 </p>
17633 <p><var>crq</var>: holds a certificate request
17634 </p>
17635 <p>This function will set extensions from the given request to the
17636 certificate.
17637 </p>
17638 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17639 negative error value.
17640 </p>
17641 <p><strong>Since:</strong> 2.8.0
17642 </p></dd></dl>
17643
17644 <a name="gnutls_005fx509_005fcrt_005fset_005fcrq-1"></a>
17645 <h4 class="subheading">gnutls_x509_crt_set_crq</h4>
17646 <a name="gnutls_005fx509_005fcrt_005fset_005fcrq"></a><dl>
17647 <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>
17648 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17649 </p>
17650 <p><var>crq</var>: holds a certificate request
17651 </p>
17652 <p>This function will set the name and public parameters as well as
17653 the extensions from the given certificate request to the certificate.
17654 Only RSA keys are currently supported.
17655 </p>
17656 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17657 negative error value.
17658 </p></dd></dl>
17659
17660 <a name="gnutls_005fx509_005fcrt_005fset_005fdn_005fby_005foid-1"></a>
17661 <h4 class="subheading">gnutls_x509_crt_set_dn_by_oid</h4>
17662 <a name="gnutls_005fx509_005fcrt_005fset_005fdn_005fby_005foid"></a><dl>
17663 <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>
17664 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17665 </p>
17666 <p><var>oid</var>: holds an Object Identifier in a null terminated string
17667 </p>
17668 <p><var>raw_flag</var>: must be 0, or 1 if the data are DER encoded
17669 </p>
17670 <p><var>name</var>: a pointer to the name
17671 </p>
17672 <p><var>sizeof_name</var>: holds the size of <code>name</code>
17673 </p>
17674 <p>This function will set the part of the name of the Certificate
17675 subject, specified by the given OID. The input string should be
17676 ASCII or UTF-8 encoded.
17677 </p>
17678 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
17679 With this function you can only set the known OIDs. You can test
17680 for known OIDs using <code>gnutls_x509_dn_oid_known()</code>. For OIDs that are
17681 not known (by gnutls) you should properly DER encode your data,
17682 and call this function with <code>raw_flag</code> set.
17683 </p>
17684 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17685 negative error value.
17686 </p></dd></dl>
17687
17688 <a name="gnutls_005fx509_005fcrt_005fset_005fexpiration_005ftime-1"></a>
17689 <h4 class="subheading">gnutls_x509_crt_set_expiration_time</h4>
17690 <a name="gnutls_005fx509_005fcrt_005fset_005fexpiration_005ftime"></a><dl>
17691 <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>
17692 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17693 </p>
17694 <p><var>exp_time</var>: The actual time
17695 </p>
17696 <p>This function will set the time this Certificate will expire.
17697 </p>
17698 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17699 negative error value.
17700 </p></dd></dl>
17701
17702 <a name="gnutls_005fx509_005fcrt_005fset_005fextension_005fby_005foid-1"></a>
17703 <h4 class="subheading">gnutls_x509_crt_set_extension_by_oid</h4>
17704 <a name="gnutls_005fx509_005fcrt_005fset_005fextension_005fby_005foid"></a><dl>
17705 <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>
17706 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17707 </p>
17708 <p><var>oid</var>: holds an Object Identified in null terminated string
17709 </p>
17710 <p><var>buf</var>: a pointer to a DER encoded data
17711 </p>
17712 <p><var>sizeof_buf</var>: holds the size of <code>buf</code>
17713 </p>
17714 <p><var>critical</var>: should be non zero if the extension is to be marked as critical
17715 </p>
17716 <p>This function will set an the extension, by the specified OID, in
17717 the certificate.  The extension data should be binary data DER
17718 encoded.
17719 </p>
17720 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17721 negative error value.
17722 </p></dd></dl>
17723
17724 <a name="gnutls_005fx509_005fcrt_005fset_005fissuer_005fdn_005fby_005foid-1"></a>
17725 <h4 class="subheading">gnutls_x509_crt_set_issuer_dn_by_oid</h4>
17726 <a name="gnutls_005fx509_005fcrt_005fset_005fissuer_005fdn_005fby_005foid"></a><dl>
17727 <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>
17728 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17729 </p>
17730 <p><var>oid</var>: holds an Object Identifier in a null terminated string
17731 </p>
17732 <p><var>raw_flag</var>: must be 0, or 1 if the data are DER encoded
17733 </p>
17734 <p><var>name</var>: a pointer to the name
17735 </p>
17736 <p><var>sizeof_name</var>: holds the size of <code>name</code>
17737 </p>
17738 <p>This function will set the part of the name of the Certificate
17739 issuer, specified by the given OID.  The input string should be
17740 ASCII or UTF-8 encoded.
17741 </p>
17742 <p>Some helper macros with popular OIDs can be found in gnutls/x509.h
17743 With this function you can only set the known OIDs. You can test
17744 for known OIDs using <code>gnutls_x509_dn_oid_known()</code>. For OIDs that are
17745 not known (by gnutls) you should properly DER encode your data,
17746 and call this function with <code>raw_flag</code> set.
17747 </p>
17748 <p>Normally you do not need to call this function, since the signing
17749 operation will copy the signer&rsquo;s name as the issuer of the
17750 certificate.
17751 </p>
17752 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17753 negative error value.
17754 </p></dd></dl>
17755
17756 <a name="gnutls_005fx509_005fcrt_005fset_005fkey_005fpurpose_005foid-1"></a>
17757 <h4 class="subheading">gnutls_x509_crt_set_key_purpose_oid</h4>
17758 <a name="gnutls_005fx509_005fcrt_005fset_005fkey_005fpurpose_005foid"></a><dl>
17759 <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>
17760 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17761 </p>
17762 <p><var>oid</var>: a pointer to a null terminated string that holds the OID
17763 </p>
17764 <p><var>critical</var>: Whether this extension will be critical or not
17765 </p>
17766 <p>This function will set the key purpose OIDs of the Certificate.
17767 These are stored in the Extended Key Usage extension (2.5.29.37)
17768 See the GNUTLS_KP_* definitions for human readable names.
17769 </p>
17770 <p>Subsequent calls to this function will append OIDs to the OID list.
17771 </p>
17772 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
17773 otherwise an error code is returned.
17774 </p></dd></dl>
17775
17776 <a name="gnutls_005fx509_005fcrt_005fset_005fkey_005fusage-1"></a>
17777 <h4 class="subheading">gnutls_x509_crt_set_key_usage</h4>
17778 <a name="gnutls_005fx509_005fcrt_005fset_005fkey_005fusage"></a><dl>
17779 <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>
17780 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17781 </p>
17782 <p><var>usage</var>: an ORed sequence of the GNUTLS_KEY_* elements.
17783 </p>
17784 <p>This function will set the keyUsage certificate extension.
17785 </p>
17786 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17787 negative error value.
17788 </p></dd></dl>
17789
17790 <a name="gnutls_005fx509_005fcrt_005fset_005fkey-1"></a>
17791 <h4 class="subheading">gnutls_x509_crt_set_key</h4>
17792 <a name="gnutls_005fx509_005fcrt_005fset_005fkey"></a><dl>
17793 <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>
17794 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17795 </p>
17796 <p><var>key</var>: holds a private key
17797 </p>
17798 <p>This function will set the public parameters from the given
17799 private key to the certificate. Only RSA keys are currently
17800 supported.
17801 </p>
17802 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17803 negative error value.
17804 </p></dd></dl>
17805
17806 <a name="gnutls_005fx509_005fcrt_005fset_005fproxy_005fdn-1"></a>
17807 <h4 class="subheading">gnutls_x509_crt_set_proxy_dn</h4>
17808 <a name="gnutls_005fx509_005fcrt_005fset_005fproxy_005fdn"></a><dl>
17809 <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>
17810 <dd><p><var>crt</var>: a gnutls_x509_crt_t structure with the new proxy cert
17811 </p>
17812 <p><var>eecrt</var>: the end entity certificate that will be issuing the proxy
17813 </p>
17814 <p><var>raw_flag</var>: must be 0, or 1 if the CN is DER encoded
17815 </p>
17816 <p><var>name</var>: a pointer to the CN name, may be NULL (but MUST then be added later)
17817 </p>
17818 <p><var>sizeof_name</var>: holds the size of <code>name</code>
17819 </p>
17820 <p>This function will set the subject in <code>crt</code> to the end entity&rsquo;s
17821 <code>eecrt</code> subject name, and add a single Common Name component <code>name</code>
17822 of size <code>sizeof_name</code>.  This corresponds to the required proxy
17823 certificate naming style.  Note that if <code>name</code> is <code>NULL</code>, you MUST
17824 set it later by using <code>gnutls_x509_crt_set_dn_by_oid()</code> or similar.
17825 </p>
17826 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17827 negative error value.
17828 </p></dd></dl>
17829
17830 <a name="gnutls_005fx509_005fcrt_005fset_005fproxy-1"></a>
17831 <h4 class="subheading">gnutls_x509_crt_set_proxy</h4>
17832 <a name="gnutls_005fx509_005fcrt_005fset_005fproxy"></a><dl>
17833 <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>
17834 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17835 </p>
17836 <p><var>pathLenConstraint</var>: non-negative values indicate maximum length of path,
17837 and negative values indicate that the pathLenConstraints field should
17838 not be present.
17839 </p>
17840 <p><var>policyLanguage</var>: OID describing the language of <code>policy</code>.
17841 </p>
17842 <p><var>policy</var>: opaque byte array with policy language, can be <code>NULL</code>
17843 </p>
17844 <p><var>sizeof_policy</var>: size of <code>policy</code>.
17845 </p>
17846 <p>This function will set the proxyCertInfo extension.
17847 </p>
17848 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17849 negative error value.
17850 </p></dd></dl>
17851
17852 <a name="gnutls_005fx509_005fcrt_005fset_005fserial-1"></a>
17853 <h4 class="subheading">gnutls_x509_crt_set_serial</h4>
17854 <a name="gnutls_005fx509_005fcrt_005fset_005fserial"></a><dl>
17855 <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>
17856 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17857 </p>
17858 <p><var>serial</var>: The serial number
17859 </p>
17860 <p><var>serial_size</var>: Holds the size of the serial field.
17861 </p>
17862 <p>This function will set the X.509 certificate&rsquo;s serial number.
17863 Serial is not always a 32 or 64bit number.  Some CAs use large
17864 serial numbers, thus it may be wise to handle it as something
17865 opaque.
17866 </p>
17867 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17868 negative error value.
17869 </p></dd></dl>
17870
17871 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005falt_005fname-1"></a>
17872 <h4 class="subheading">gnutls_x509_crt_set_subject_alt_name</h4>
17873 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005falt_005fname"></a><dl>
17874 <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>
17875 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17876 </p>
17877 <p><var>type</var>: is one of the gnutls_x509_subject_alt_name_t enumerations
17878 </p>
17879 <p><var>data</var>: The data to be set
17880 </p>
17881 <p><var>data_size</var>: The size of data to be set
17882 </p>
17883 <p><var>flags</var>: GNUTLS_FSAN_SET to clear previous data or GNUTLS_FSAN_APPEND to append.
17884 </p>
17885 <p>This function will set the subject alternative name certificate
17886 extension. It can set the following types:
17887 </p>
17888 <p>&amp;GNUTLS_SAN_DNSNAME: as a text string
17889 </p>
17890 <p>&amp;GNUTLS_SAN_RFC822NAME: as a text string
17891 </p>
17892 <p>&amp;GNUTLS_SAN_URI: as a text string
17893 </p>
17894 <p>&amp;GNUTLS_SAN_IPADDRESS: as a binary IP address (4 or 16 bytes)
17895 </p>
17896 <p>Other values can be set as binary values with the proper DER encoding.
17897 </p>
17898 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17899 negative error value.
17900 </p>
17901 <p><strong>Since:</strong> 2.6.0
17902 </p></dd></dl>
17903
17904 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005falternative_005fname-1"></a>
17905 <h4 class="subheading">gnutls_x509_crt_set_subject_alternative_name</h4>
17906 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005falternative_005fname"></a><dl>
17907 <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>
17908 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17909 </p>
17910 <p><var>type</var>: is one of the gnutls_x509_subject_alt_name_t enumerations
17911 </p>
17912 <p><var>data_string</var>: The data to be set, a zero terminated string
17913 </p>
17914 <p>This function will set the subject alternative name certificate
17915 extension. This function assumes that data can be expressed as a null
17916 terminated string.
17917 </p>
17918 <p>The name of the function is unfortunate since it is incosistent with
17919 <code>gnutls_x509_crt_get_subject_alt_name()</code>.
17920 </p>
17921 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17922 negative error value.
17923 </p></dd></dl>
17924
17925 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005fkey_005fid-1"></a>
17926 <h4 class="subheading">gnutls_x509_crt_set_subject_key_id</h4>
17927 <a name="gnutls_005fx509_005fcrt_005fset_005fsubject_005fkey_005fid"></a><dl>
17928 <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>
17929 <dd><p><var>cert</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17930 </p>
17931 <p><var>id</var>: The key ID
17932 </p>
17933 <p><var>id_size</var>: Holds the size of the serial field.
17934 </p>
17935 <p>This function will set the X.509 certificate&rsquo;s subject key ID
17936 extension.
17937 </p>
17938 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17939 negative error value.
17940 </p></dd></dl>
17941
17942 <a name="gnutls_005fx509_005fcrt_005fset_005fversion-1"></a>
17943 <h4 class="subheading">gnutls_x509_crt_set_version</h4>
17944 <a name="gnutls_005fx509_005fcrt_005fset_005fversion"></a><dl>
17945 <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>
17946 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17947 </p>
17948 <p><var>version</var>: holds the version number. For X.509v1 certificates must be 1.
17949 </p>
17950 <p>This function will set the version of the certificate.  This must
17951 be one for X.509 version 1, and so on.  Plain certificates without
17952 extensions must have version set to one.
17953 </p>
17954 <p>To create well-formed certificates, you must specify version 3 if
17955 you use any certificate extensions.  Extensions are created by
17956 functions such as <code>gnutls_x509_crt_set_subject_alt_name()</code>
17957 or <code>gnutls_x509_crt_set_key_usage()</code>.
17958 </p>
17959 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17960 negative error value.
17961 </p></dd></dl>
17962
17963 <a name="gnutls_005fx509_005fcrt_005fsign2-1"></a>
17964 <h4 class="subheading">gnutls_x509_crt_sign2</h4>
17965 <a name="gnutls_005fx509_005fcrt_005fsign2"></a><dl>
17966 <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>
17967 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17968 </p>
17969 <p><var>issuer</var>: is the certificate of the certificate issuer
17970 </p>
17971 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
17972 </p>
17973 <p><var>dig</var>: The message digest to use, <code>GNUTLS_DIG_SHA1</code> is a safe choice
17974 </p>
17975 <p><var>flags</var>: must be 0
17976 </p>
17977 <p>This function will sign the certificate with the issuer&rsquo;s private key, and
17978 will copy the issuer&rsquo;s information into the certificate.
17979 </p>
17980 <p>This must be the last step in a certificate generation since all
17981 the previously set parameters are now signed.
17982 </p>
17983 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
17984 negative error value.
17985 </p></dd></dl>
17986
17987 <a name="gnutls_005fx509_005fcrt_005fsign-1"></a>
17988 <h4 class="subheading">gnutls_x509_crt_sign</h4>
17989 <a name="gnutls_005fx509_005fcrt_005fsign"></a><dl>
17990 <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>
17991 <dd><p><var>crt</var>: a certificate of type <code>gnutls_x509_crt_t</code>
17992 </p>
17993 <p><var>issuer</var>: is the certificate of the certificate issuer
17994 </p>
17995 <p><var>issuer_key</var>: holds the issuer&rsquo;s private key
17996 </p>
17997 <p>This function is the same a <code>gnutls_x509_crt_sign2()</code> with no flags,
17998 and SHA1 as the hash algorithm.
17999 </p>
18000 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18001 negative error value.
18002 </p></dd></dl>
18003
18004 <a name="gnutls_005fx509_005fcrt_005fverify_005fdata-1"></a>
18005 <h4 class="subheading">gnutls_x509_crt_verify_data</h4>
18006 <a name="gnutls_005fx509_005fcrt_005fverify_005fdata"></a><dl>
18007 <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>
18008 <dd><p><var>crt</var>: Holds the certificate
18009 </p>
18010 <p><var>flags</var>: should be 0 for now
18011 </p>
18012 <p><var>data</var>: holds the data to be signed
18013 </p>
18014 <p><var>signature</var>: contains the signature
18015 </p>
18016 <p>This function will verify the given signed data, using the
18017 parameters from the certificate.
18018 </p>
18019 <p>Deprecated. Please use <code>gnutls_pubkey_verify_data()</code>.
18020 </p>
18021 <p><strong>Returns:</strong> In case of a verification failure <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
18022 is returned, and a positive code on success.
18023 </p></dd></dl>
18024
18025 <a name="gnutls_005fx509_005fcrt_005fverify_005fhash-1"></a>
18026 <h4 class="subheading">gnutls_x509_crt_verify_hash</h4>
18027 <a name="gnutls_005fx509_005fcrt_005fverify_005fhash"></a><dl>
18028 <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>
18029 <dd><p><var>crt</var>: Holds the certificate
18030 </p>
18031 <p><var>flags</var>: should be 0 for now
18032 </p>
18033 <p><var>hash</var>: holds the hash digest to be verified
18034 </p>
18035 <p><var>signature</var>: contains the signature
18036 </p>
18037 <p>This function will verify the given signed digest, using the
18038 parameters from the certificate.
18039 </p>
18040 <p>Deprecated. Please use <code>gnutls_pubkey_verify_data()</code>.
18041 </p>
18042 <p><strong>Returns:</strong> In case of a verification failure <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
18043 is returned, and a positive code on success.
18044 </p></dd></dl>
18045
18046 <a name="gnutls_005fx509_005fcrt_005fverify-1"></a>
18047 <h4 class="subheading">gnutls_x509_crt_verify</h4>
18048 <a name="gnutls_005fx509_005fcrt_005fverify"></a><dl>
18049 <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>
18050 <dd><p><var>cert</var>: is the certificate to be verified
18051 </p>
18052 <p><var>CA_list</var>: is one certificate that is considered to be trusted one
18053 </p>
18054 <p><var>CA_list_length</var>: holds the number of CA certificate in CA_list
18055 </p>
18056 <p><var>flags</var>: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
18057 </p>
18058 <p><var>verify</var>: will hold the certificate verification output.
18059 </p>
18060 <p>This function will try to verify the given certificate and return
18061 its status.
18062 </p>
18063 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18064 negative error value.
18065 </p></dd></dl>
18066
18067 <a name="gnutls_005fx509_005fdn_005fdeinit-1"></a>
18068 <h4 class="subheading">gnutls_x509_dn_deinit</h4>
18069 <a name="gnutls_005fx509_005fdn_005fdeinit"></a><dl>
18070 <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>
18071 <dd><p><var>dn</var>: a DN opaque object pointer.
18072 </p>
18073 <p>This function deallocates the DN object as returned by
18074 <code>gnutls_x509_dn_import()</code>.
18075 </p>
18076 <p><strong>Since:</strong> 2.4.0
18077 </p></dd></dl>
18078
18079 <a name="gnutls_005fx509_005fdn_005fexport-1"></a>
18080 <h4 class="subheading">gnutls_x509_dn_export</h4>
18081 <a name="gnutls_005fx509_005fdn_005fexport"></a><dl>
18082 <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>
18083 <dd><p><var>dn</var>: Holds the opaque DN object
18084 </p>
18085 <p><var>format</var>: the format of output params. One of PEM or DER.
18086 </p>
18087 <p><var>output_data</var>: will contain a DN PEM or DER encoded
18088 </p>
18089 <p><var>output_data_size</var>: holds the size of output_data (and will be
18090 replaced by the actual size of parameters)
18091 </p>
18092 <p>This function will export the DN to DER or PEM format.
18093 </p>
18094 <p>If the buffer provided is not long enough to hold the output, then
18095 *<code>output_data_size</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>
18096 will be returned.
18097 </p>
18098 <p>If the structure is PEM encoded, it will have a header
18099 of &quot;BEGIN NAME&quot;.
18100 </p>
18101 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18102 negative error value.
18103 </p></dd></dl>
18104
18105 <a name="gnutls_005fx509_005fdn_005fget_005frdn_005fava-1"></a>
18106 <h4 class="subheading">gnutls_x509_dn_get_rdn_ava</h4>
18107 <a name="gnutls_005fx509_005fdn_005fget_005frdn_005fava"></a><dl>
18108 <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>
18109 <dd><p><var>dn</var>: input variable with opaque DN pointer
18110 </p>
18111 <p><var>irdn</var>: index of RDN
18112 </p>
18113 <p><var>iava</var>: index of AVA.
18114 </p>
18115 <p><var>ava</var>: Pointer to structure which will hold output information.
18116 </p>
18117 <p>Get pointers to data within the DN.
18118 </p>
18119 <p>Note that <code>ava</code> will contain pointers into the <code>dn</code> structure, so you
18120 should not modify any data or deallocate it.  Note also that the DN
18121 in turn points into the original certificate structure, and thus
18122 you may not deallocate the certificate and continue to access <code>dn</code>.
18123 </p>
18124 <p><strong>Returns:</strong> Returns 0 on success, or an error code.
18125 </p></dd></dl>
18126
18127 <a name="gnutls_005fx509_005fdn_005fimport-1"></a>
18128 <h4 class="subheading">gnutls_x509_dn_import</h4>
18129 <a name="gnutls_005fx509_005fdn_005fimport"></a><dl>
18130 <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>
18131 <dd><p><var>dn</var>: the structure that will hold the imported DN
18132 </p>
18133 <p><var>data</var>: should contain a DER encoded RDN sequence
18134 </p>
18135 <p>This function parses an RDN sequence and stores the result to a
18136 <code>gnutls_x509_dn_t</code> structure. The structure must have been initialized
18137 with <code>gnutls_x509_dn_init()</code>. You may use <code>gnutls_x509_dn_get_rdn_ava()</code> to
18138 decode the DN.
18139 </p>
18140 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18141 negative error value.
18142 </p>
18143 <p><strong>Since:</strong> 2.4.0
18144 </p></dd></dl>
18145
18146 <a name="gnutls_005fx509_005fdn_005finit-1"></a>
18147 <h4 class="subheading">gnutls_x509_dn_init</h4>
18148 <a name="gnutls_005fx509_005fdn_005finit"></a><dl>
18149 <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>
18150 <dd><p><var>dn</var>: the object to be initialized
18151 </p>
18152 <p>This function initializes a <code>gnutls_x509_dn_t</code> structure.
18153 </p>
18154 <p>The object returned must be deallocated using
18155 <code>gnutls_x509_dn_deinit()</code>.
18156 </p>
18157 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18158 negative error value.
18159 </p>
18160 <p><strong>Since:</strong> 2.4.0
18161 </p></dd></dl>
18162 <a name="gnutls_005fx509_005fdn_005foid_005fknown-1"></a>
18163 <h4 class="subheading">gnutls_x509_dn_oid_known</h4>
18164 <a name="gnutls_005fx509_005fdn_005foid_005fknown"></a><dl>
18165 <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>
18166 <dd><p><var>oid</var>: holds an Object Identifier in a null terminated string
18167 </p>
18168 <p>This function will inform about known DN OIDs. This is useful since
18169 functions like <code>gnutls_x509_crt_set_dn_by_oid()</code> use the information
18170 on known OIDs to properly encode their input. Object Identifiers
18171 that are not known are not encoded by these functions, and their
18172 input is stored directly into the ASN.1 structure. In that case of
18173 unknown OIDs, you have the responsibility of DER encoding your
18174 data.
18175 </p>
18176 <p><strong>Returns:</strong> 1 on known OIDs and 0 otherwise.
18177 </p></dd></dl>
18178
18179 <a name="gnutls_005fx509_005fprivkey_005fcpy-1"></a>
18180 <h4 class="subheading">gnutls_x509_privkey_cpy</h4>
18181 <a name="gnutls_005fx509_005fprivkey_005fcpy"></a><dl>
18182 <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>
18183 <dd><p><var>dst</var>: The destination key, which should be initialized.
18184 </p>
18185 <p><var>src</var>: The source key
18186 </p>
18187 <p>This function will copy a private key from source to destination
18188 key. Destination has to be initialized.
18189 </p>
18190 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18191 negative error value.
18192 </p></dd></dl>
18193
18194 <a name="gnutls_005fx509_005fprivkey_005fdeinit-1"></a>
18195 <h4 class="subheading">gnutls_x509_privkey_deinit</h4>
18196 <a name="gnutls_005fx509_005fprivkey_005fdeinit"></a><dl>
18197 <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>
18198 <dd><p><var>key</var>: The structure to be deinitialized
18199 </p>
18200 <p>This function will deinitialize a private key structure.
18201 </p></dd></dl>
18202
18203 <a name="gnutls_005fx509_005fprivkey_005fexport_005fdsa_005fraw-1"></a>
18204 <h4 class="subheading">gnutls_x509_privkey_export_dsa_raw</h4>
18205 <a name="gnutls_005fx509_005fprivkey_005fexport_005fdsa_005fraw"></a><dl>
18206 <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>
18207 <dd><p><var>key</var>: a structure that holds the DSA parameters
18208 </p>
18209 <p><var>p</var>: will hold the p
18210 </p>
18211 <p><var>q</var>: will hold the q
18212 </p>
18213 <p><var>g</var>: will hold the g
18214 </p>
18215 <p><var>y</var>: will hold the y
18216 </p>
18217 <p><var>x</var>: will hold the x
18218 </p>
18219 <p>This function will export the DSA private key&rsquo;s parameters found
18220 in the given structure. The new parameters will be allocated using
18221 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
18222 </p>
18223 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18224 negative error value.
18225 </p></dd></dl>
18226
18227 <a name="gnutls_005fx509_005fprivkey_005fexport_005fpkcs8-1"></a>
18228 <h4 class="subheading">gnutls_x509_privkey_export_pkcs8</h4>
18229 <a name="gnutls_005fx509_005fprivkey_005fexport_005fpkcs8"></a><dl>
18230 <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>
18231 <dd><p><var>key</var>: Holds the key
18232 </p>
18233 <p><var>format</var>: the format of output params. One of PEM or DER.
18234 </p>
18235 <p><var>password</var>: the password that will be used to encrypt the key.
18236 </p>
18237 <p><var>flags</var>: an ORed sequence of gnutls_pkcs_encrypt_flags_t
18238 </p>
18239 <p><var>output_data</var>: will contain a private key PEM or DER encoded
18240 </p>
18241 <p><var>output_data_size</var>: holds the size of output_data (and will be
18242 replaced by the actual size of parameters)
18243 </p>
18244 <p>This function will export the private key to a PKCS8 structure.
18245 Both RSA and DSA keys can be exported. For DSA keys we use
18246 PKCS <code>11</code> definitions. If the flags do not specify the encryption
18247 cipher, then the default 3DES (PBES2) will be used.
18248 </p>
18249 <p>The <code>password</code> can be either ASCII or UTF-8 in the default PBES2
18250 encryption schemas, or ASCII for the PKCS12 schemas.
18251 </p>
18252 <p>If the buffer provided is not long enough to hold the output, then
18253 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
18254 be returned.
18255 </p>
18256 <p>If the structure is PEM encoded, it will have a header
18257 of &quot;BEGIN ENCRYPTED PRIVATE KEY&quot; or &quot;BEGIN PRIVATE KEY&quot; if
18258 encryption is not used.
18259 </p>
18260 <p><strong>Return value:</strong> In case of failure a negative value will be
18261 returned, and 0 on success.
18262 </p></dd></dl>
18263
18264 <a name="gnutls_005fx509_005fprivkey_005fexport_005frsa_005fraw2-1"></a>
18265 <h4 class="subheading">gnutls_x509_privkey_export_rsa_raw2</h4>
18266 <a name="gnutls_005fx509_005fprivkey_005fexport_005frsa_005fraw2"></a><dl>
18267 <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>
18268 <dd><p><var>key</var>: a structure that holds the rsa parameters
18269 </p>
18270 <p><var>m</var>: will hold the modulus
18271 </p>
18272 <p><var>e</var>: will hold the public exponent
18273 </p>
18274 <p><var>d</var>: will hold the private exponent
18275 </p>
18276 <p><var>p</var>: will hold the first prime (p)
18277 </p>
18278 <p><var>q</var>: will hold the second prime (q)
18279 </p>
18280 <p><var>u</var>: will hold the coefficient
18281 </p>
18282 <p><var>e1</var>: will hold e1 = d mod (p-1)
18283 </p>
18284 <p><var>e2</var>: will hold e2 = d mod (q-1)
18285 </p>
18286 <p>This function will export the RSA private key&rsquo;s parameters found
18287 in the given structure. The new parameters will be allocated using
18288 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
18289 </p>
18290 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18291 negative error value.
18292 </p></dd></dl>
18293
18294 <a name="gnutls_005fx509_005fprivkey_005fexport_005frsa_005fraw-1"></a>
18295 <h4 class="subheading">gnutls_x509_privkey_export_rsa_raw</h4>
18296 <a name="gnutls_005fx509_005fprivkey_005fexport_005frsa_005fraw"></a><dl>
18297 <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>
18298 <dd><p><var>key</var>: a structure that holds the rsa parameters
18299 </p>
18300 <p><var>m</var>: will hold the modulus
18301 </p>
18302 <p><var>e</var>: will hold the public exponent
18303 </p>
18304 <p><var>d</var>: will hold the private exponent
18305 </p>
18306 <p><var>p</var>: will hold the first prime (p)
18307 </p>
18308 <p><var>q</var>: will hold the second prime (q)
18309 </p>
18310 <p><var>u</var>: will hold the coefficient
18311 </p>
18312 <p>This function will export the RSA private key&rsquo;s parameters found
18313 in the given structure. The new parameters will be allocated using
18314 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
18315 </p>
18316 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18317 negative error value.
18318 </p></dd></dl>
18319
18320 <a name="gnutls_005fx509_005fprivkey_005fexport-1"></a>
18321 <h4 class="subheading">gnutls_x509_privkey_export</h4>
18322 <a name="gnutls_005fx509_005fprivkey_005fexport"></a><dl>
18323 <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>
18324 <dd><p><var>key</var>: Holds the key
18325 </p>
18326 <p><var>format</var>: the format of output params. One of PEM or DER.
18327 </p>
18328 <p><var>output_data</var>: will contain a private key PEM or DER encoded
18329 </p>
18330 <p><var>output_data_size</var>: holds the size of output_data (and will be
18331 replaced by the actual size of parameters)
18332 </p>
18333 <p>This function will export the private key to a PKCS1 structure for
18334 RSA keys, or an integer sequence for DSA keys.  The DSA keys are in
18335 the same format with the parameters used by openssl.
18336 </p>
18337 <p>If the buffer provided is not long enough to hold the output, then
18338 *<code>output_data_size</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code>
18339 will be returned.
18340 </p>
18341 <p>If the structure is PEM encoded, it will have a header
18342 of &quot;BEGIN RSA PRIVATE KEY&quot;.
18343 </p>
18344 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18345 negative error value.
18346 </p></dd></dl>
18347
18348 <a name="gnutls_005fx509_005fprivkey_005ffix-1"></a>
18349 <h4 class="subheading">gnutls_x509_privkey_fix</h4>
18350 <a name="gnutls_005fx509_005fprivkey_005ffix"></a><dl>
18351 <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>
18352 <dd><p><var>key</var>: Holds the key
18353 </p>
18354 <p>This function will recalculate the secondary parameters in a key.
18355 In RSA keys, this can be the coefficient and exponent1,2.
18356 </p>
18357 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18358 negative error value.
18359 </p></dd></dl>
18360
18361 <a name="gnutls_005fx509_005fprivkey_005fgenerate-1"></a>
18362 <h4 class="subheading">gnutls_x509_privkey_generate</h4>
18363 <a name="gnutls_005fx509_005fprivkey_005fgenerate"></a><dl>
18364 <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>
18365 <dd><p><var>key</var>: should contain a <code>gnutls_x509_privkey_t</code> structure
18366 </p>
18367 <p><var>algo</var>: is one of RSA or DSA.
18368 </p>
18369 <p><var>bits</var>: the size of the modulus
18370 </p>
18371 <p><var>flags</var>: unused for now.  Must be 0.
18372 </p>
18373 <p>This function will generate a random private key. Note that this
18374 function must be called on an empty private key.
18375 </p>
18376 <p>Do not set the number of bits directly, use <code>gnutls_sec_param_to_pk_bits()</code>.
18377 </p>
18378 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18379 negative error value.
18380 </p></dd></dl>
18381
18382 <a name="gnutls_005fx509_005fprivkey_005fget_005fkey_005fid-1"></a>
18383 <h4 class="subheading">gnutls_x509_privkey_get_key_id</h4>
18384 <a name="gnutls_005fx509_005fprivkey_005fget_005fkey_005fid"></a><dl>
18385 <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>
18386 <dd><p><var>key</var>: Holds the key
18387 </p>
18388 <p><var>flags</var>: should be 0 for now
18389 </p>
18390 <p><var>output_data</var>: will contain the key ID
18391 </p>
18392 <p><var>output_data_size</var>: holds the size of output_data (and will be
18393 replaced by the actual size of parameters)
18394 </p>
18395 <p>This function will return a unique ID the depends on the public key
18396 parameters. This ID can be used in checking whether a certificate
18397 corresponds to the given key.
18398 </p>
18399 <p>If the buffer provided is not long enough to hold the output, then
18400 *<code>output_data_size</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> will
18401 be returned.  The output will normally be a SHA-1 hash output,
18402 which is 20 bytes.
18403 </p>
18404 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18405 negative error value.
18406 </p></dd></dl>
18407
18408 <a name="gnutls_005fx509_005fprivkey_005fget_005fpk_005falgorithm-1"></a>
18409 <h4 class="subheading">gnutls_x509_privkey_get_pk_algorithm</h4>
18410 <a name="gnutls_005fx509_005fprivkey_005fget_005fpk_005falgorithm"></a><dl>
18411 <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>
18412 <dd><p><var>key</var>: should contain a <code>gnutls_x509_privkey_t</code> structure
18413 </p>
18414 <p>This function will return the public key algorithm of a private
18415 key.
18416 </p>
18417 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code> enumeration on
18418 success, or a negative value on error.
18419 </p></dd></dl>
18420
18421 <a name="gnutls_005fx509_005fprivkey_005fimport_005fdsa_005fraw-1"></a>
18422 <h4 class="subheading">gnutls_x509_privkey_import_dsa_raw</h4>
18423 <a name="gnutls_005fx509_005fprivkey_005fimport_005fdsa_005fraw"></a><dl>
18424 <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>
18425 <dd><p><var>key</var>: The structure to store the parsed key
18426 </p>
18427 <p><var>p</var>: holds the p
18428 </p>
18429 <p><var>q</var>: holds the q
18430 </p>
18431 <p><var>g</var>: holds the g
18432 </p>
18433 <p><var>y</var>: holds the y
18434 </p>
18435 <p><var>x</var>: holds the x
18436 </p>
18437 <p>This function will convert the given DSA raw parameters to the
18438 native <code>gnutls_x509_privkey_t</code> format.  The output will be stored
18439 in <code>key</code>.
18440 </p>
18441 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18442 negative error value.
18443 </p></dd></dl>
18444
18445 <a name="gnutls_005fx509_005fprivkey_005fimport_005fpkcs8-1"></a>
18446 <h4 class="subheading">gnutls_x509_privkey_import_pkcs8</h4>
18447 <a name="gnutls_005fx509_005fprivkey_005fimport_005fpkcs8"></a><dl>
18448 <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>
18449 <dd><p><var>key</var>: The structure to store the parsed key
18450 </p>
18451 <p><var>data</var>: The DER or PEM encoded key.
18452 </p>
18453 <p><var>format</var>: One of DER or PEM
18454 </p>
18455 <p><var>password</var>: the password to decrypt the key (if it is encrypted).
18456 </p>
18457 <p><var>flags</var>: 0 if encrypted or GNUTLS_PKCS_PLAIN if not encrypted.
18458 </p>
18459 <p>This function will convert the given DER or PEM encoded PKCS8 2.0
18460 encrypted key to the native gnutls_x509_privkey_t format. The
18461 output will be stored in <code>key</code>.  Both RSA and DSA keys can be
18462 imported, and flags can only be used to indicate an unencrypted
18463 key.
18464 </p>
18465 <p>The <code>password</code> can be either ASCII or UTF-8 in the default PBES2
18466 encryption schemas, or ASCII for the PKCS12 schemas.
18467 </p>
18468 <p>If the Certificate is PEM encoded it should have a header of
18469 &quot;ENCRYPTED PRIVATE KEY&quot;, or &quot;PRIVATE KEY&quot;. You only need to
18470 specify the flags if the key is DER encoded, since in that case
18471 the encryption status cannot be auto-detected.
18472 </p>
18473 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18474 negative error value.
18475 </p></dd></dl>
18476
18477 <a name="gnutls_005fx509_005fprivkey_005fimport_005frsa_005fraw2-1"></a>
18478 <h4 class="subheading">gnutls_x509_privkey_import_rsa_raw2</h4>
18479 <a name="gnutls_005fx509_005fprivkey_005fimport_005frsa_005fraw2"></a><dl>
18480 <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>
18481 <dd><p><var>key</var>: The structure to store the parsed key
18482 </p>
18483 <p><var>m</var>: holds the modulus
18484 </p>
18485 <p><var>e</var>: holds the public exponent
18486 </p>
18487 <p><var>d</var>: holds the private exponent
18488 </p>
18489 <p><var>p</var>: holds the first prime (p)
18490 </p>
18491 <p><var>q</var>: holds the second prime (q)
18492 </p>
18493 <p><var>u</var>: holds the coefficient
18494 </p>
18495 <p><var>e1</var>: holds e1 = d mod (p-1)
18496 </p>
18497 <p><var>e2</var>: holds e2 = d mod (q-1)
18498 </p>
18499 <p>This function will convert the given RSA raw parameters to the
18500 native <code>gnutls_x509_privkey_t</code> format.  The output will be stored in
18501 <code>key</code>.
18502 </p>
18503 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18504 negative error value.
18505 </p></dd></dl>
18506
18507 <a name="gnutls_005fx509_005fprivkey_005fimport_005frsa_005fraw-1"></a>
18508 <h4 class="subheading">gnutls_x509_privkey_import_rsa_raw</h4>
18509 <a name="gnutls_005fx509_005fprivkey_005fimport_005frsa_005fraw"></a><dl>
18510 <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>
18511 <dd><p><var>key</var>: The structure to store the parsed key
18512 </p>
18513 <p><var>m</var>: holds the modulus
18514 </p>
18515 <p><var>e</var>: holds the public exponent
18516 </p>
18517 <p><var>d</var>: holds the private exponent
18518 </p>
18519 <p><var>p</var>: holds the first prime (p)
18520 </p>
18521 <p><var>q</var>: holds the second prime (q)
18522 </p>
18523 <p><var>u</var>: holds the coefficient
18524 </p>
18525 <p>This function will convert the given RSA raw parameters to the
18526 native <code>gnutls_x509_privkey_t</code> format.  The output will be stored in
18527 <code>key</code>.
18528 </p>
18529 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18530 negative error value.
18531 </p></dd></dl>
18532
18533 <a name="gnutls_005fx509_005fprivkey_005fimport-1"></a>
18534 <h4 class="subheading">gnutls_x509_privkey_import</h4>
18535 <a name="gnutls_005fx509_005fprivkey_005fimport"></a><dl>
18536 <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>
18537 <dd><p><var>key</var>: The structure to store the parsed key
18538 </p>
18539 <p><var>data</var>: The DER or PEM encoded certificate.
18540 </p>
18541 <p><var>format</var>: One of DER or PEM
18542 </p>
18543 <p>This function will convert the given DER or PEM encoded key to the
18544 native <code>gnutls_x509_privkey_t</code> format. The output will be stored in
18545 <code>key</code> .
18546 </p>
18547 <p>If the key is PEM encoded it should have a header of &quot;RSA PRIVATE
18548 KEY&quot;, or &quot;DSA PRIVATE KEY&quot;.
18549 </p>
18550 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18551 negative error value.
18552 </p></dd></dl>
18553
18554 <a name="gnutls_005fx509_005fprivkey_005finit-1"></a>
18555 <h4 class="subheading">gnutls_x509_privkey_init</h4>
18556 <a name="gnutls_005fx509_005fprivkey_005finit"></a><dl>
18557 <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>
18558 <dd><p><var>key</var>: The structure to be initialized
18559 </p>
18560 <p>This function will initialize an private key structure.
18561 </p>
18562 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18563 negative error value.
18564 </p></dd></dl>
18565
18566 <a name="gnutls_005fx509_005fprivkey_005fsec_005fparam-1"></a>
18567 <h4 class="subheading">gnutls_x509_privkey_sec_param</h4>
18568 <a name="gnutls_005fx509_005fprivkey_005fsec_005fparam"></a><dl>
18569 <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>
18570 <dd><p><var>key</var>: a key structure
18571 </p>
18572 <p>This function will return the security parameter appropriate with
18573 this private key.
18574 </p>
18575 <p><strong>Returns:</strong> On success, a valid security parameter is returned otherwise
18576 <code>GNUTLS_SEC_PARAM_UNKNOWN</code> is returned.
18577 </p></dd></dl>
18578
18579 <a name="gnutls_005fx509_005fprivkey_005fsign_005fdata-1"></a>
18580 <h4 class="subheading">gnutls_x509_privkey_sign_data</h4>
18581 <a name="gnutls_005fx509_005fprivkey_005fsign_005fdata"></a><dl>
18582 <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>
18583 <dd><p><var>key</var>: Holds the key
18584 </p>
18585 <p><var>digest</var>: should be MD5 or SHA1
18586 </p>
18587 <p><var>flags</var>: should be 0 for now
18588 </p>
18589 <p><var>data</var>: holds the data to be signed
18590 </p>
18591 <p><var>signature</var>: will contain the signature
18592 </p>
18593 <p><var>signature_size</var>: holds the size of signature (and will be replaced
18594 by the new size)
18595 </p>
18596 <p>This function will sign the given data using a signature algorithm
18597 supported by the private key. Signature algorithms are always used
18598 together with a hash functions.  Different hash functions may be
18599 used for the RSA algorithm, but only SHA-1 for the DSA keys.
18600 </p>
18601 <p>If the buffer provided is not long enough to hold the output, then
18602 *<code>signature_size</code> is updated and <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> will
18603 be returned.
18604 </p>
18605 <p>Use <code>gnutls_x509_crt_get_preferred_hash_algorithm()</code> to determine
18606 the hash algorithm.
18607 </p>
18608 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18609 negative error value.
18610 </p>
18611 <p><strong>Deprecated:</strong> Use <code>gnutls_privkey_sign_data()</code>.
18612 </p></dd></dl>
18613
18614 <a name="gnutls_005fx509_005fprivkey_005fsign_005fhash-1"></a>
18615 <h4 class="subheading">gnutls_x509_privkey_sign_hash</h4>
18616 <a name="gnutls_005fx509_005fprivkey_005fsign_005fhash"></a><dl>
18617 <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>
18618 <dd><p><var>key</var>: Holds the key
18619 </p>
18620 <p><var>hash</var>: holds the data to be signed
18621 </p>
18622 <p><var>signature</var>: will contain newly allocated signature
18623 </p>
18624 <p>This function will sign the given hash using the private key. Do not
18625 use this function directly unless you know what it is. Typical signing
18626 requires the data to be hashed and stored in special formats
18627 (e.g. BER Digest-Info for RSA).
18628 </p>
18629 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18630 negative error value.
18631 </p>
18632 <p><strong>Deprecated in:</strong> 2.12.0
18633 </p></dd></dl>
18634
18635 <a name="gnutls_005fx509_005fprivkey_005fverify_005fdata-1"></a>
18636 <h4 class="subheading">gnutls_x509_privkey_verify_data</h4>
18637 <a name="gnutls_005fx509_005fprivkey_005fverify_005fdata"></a><dl>
18638 <dt><a name="index-gnutls_005fx509_005fprivkey_005fverify_005fdata"></a>Function: <em>int</em> <strong>gnutls_x509_privkey_verify_data</strong> <em>(gnutls_x509_privkey_t <var>key</var>, unsigned int <var>flags</var>, const gnutls_datum_t * <var>data</var>, const gnutls_datum_t * <var>signature</var>)</em></dt>
18639 <dd><p><var>key</var>: Holds the key
18640 </p>
18641 <p><var>flags</var>: should be 0 for now
18642 </p>
18643 <p><var>data</var>: holds the data to be signed
18644 </p>
18645 <p><var>signature</var>: contains the signature
18646 </p>
18647 <p>This function will verify the given signed data, using the
18648 parameters in the private key.
18649 </p>
18650 <p><strong>Returns:</strong> In case of a verification failure <code>GNUTLS_E_PK_SIG_VERIFY_FAILED</code>
18651 is returned, and a positive code on success.
18652 </p>
18653 <p><strong>Deprecated:</strong> Use <code>gnutls_pubkey_verify_data()</code>.
18654 </p></dd></dl>
18655
18656 <a name="gnutls_005fx509_005frdn_005fget_005fby_005foid-1"></a>
18657 <h4 class="subheading">gnutls_x509_rdn_get_by_oid</h4>
18658 <a name="gnutls_005fx509_005frdn_005fget_005fby_005foid"></a><dl>
18659 <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>sizeof_buf</var>)</em></dt>
18660 <dd><p><var>idn</var>: should contain a DER encoded RDN sequence
18661 </p>
18662 <p><var>oid</var>: an Object Identifier
18663 </p>
18664 <p><var>indx</var>: In case multiple same OIDs exist in the RDN indicates which
18665 to send. Use 0 for the first one.
18666 </p>
18667 <p><var>raw_flag</var>: If non zero then the raw DER data are returned.
18668 </p>
18669 <p><var>buf</var>: a pointer to a structure to hold the peer&rsquo;s name
18670 </p>
18671 <p><var>sizeof_buf</var>: holds the size of <code>buf</code>
18672 </p>
18673 <p>This function will return the name of the given Object identifier,
18674 of the RDN sequence.  The name will be encoded using the rules
18675 from RFC2253.
18676 </p>
18677 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, or
18678 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> is returned and *<code>sizeof_buf</code> is
18679 updated if the provided buffer is not long enough, otherwise a
18680 negative error value.
18681 </p></dd></dl>
18682
18683 <a name="gnutls_005fx509_005frdn_005fget_005foid-1"></a>
18684 <h4 class="subheading">gnutls_x509_rdn_get_oid</h4>
18685 <a name="gnutls_005fx509_005frdn_005fget_005foid"></a><dl>
18686 <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>sizeof_buf</var>)</em></dt>
18687 <dd><p><var>idn</var>: should contain a DER encoded RDN sequence
18688 </p>
18689 <p><var>indx</var>: Indicates which OID to return. Use 0 for the first one.
18690 </p>
18691 <p><var>buf</var>: a pointer to a structure to hold the peer&rsquo;s name OID
18692 </p>
18693 <p><var>sizeof_buf</var>: holds the size of <code>buf</code>
18694 </p>
18695 <p>This function will return the specified Object identifier, of the
18696 RDN sequence.
18697 </p>
18698 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, or
18699 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> is returned and *<code>sizeof_buf</code> is
18700 updated if the provided buffer is not long enough, otherwise a
18701 negative error value.
18702 </p>
18703 <p><strong>Since:</strong> 2.4.0
18704 </p></dd></dl>
18705
18706 <a name="gnutls_005fx509_005frdn_005fget-1"></a>
18707 <h4 class="subheading">gnutls_x509_rdn_get</h4>
18708 <a name="gnutls_005fx509_005frdn_005fget"></a><dl>
18709 <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>sizeof_buf</var>)</em></dt>
18710 <dd><p><var>idn</var>: should contain a DER encoded RDN sequence
18711 </p>
18712 <p><var>buf</var>: a pointer to a structure to hold the peer&rsquo;s name
18713 </p>
18714 <p><var>sizeof_buf</var>: holds the size of <code>buf</code>
18715 </p>
18716 <p>This function will return the name of the given RDN sequence.  The
18717 name will be in the form &quot;C=xxxx,O=yyyy,CN=zzzz&quot; as described in
18718 RFC2253.
18719 </p>
18720 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, or
18721 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> is returned and *<code>sizeof_buf</code> is
18722 updated if the provided buffer is not long enough, otherwise a
18723 negative error value.
18724 </p></dd></dl>
18725 <hr>
18726 <a name="GnuTLS_002dextra-functions"></a>
18727 <div class="header">
18728 <p>
18729 Next: <a href="#OpenPGP-functions" accesskey="n" rel="next">OpenPGP functions</a>, Previous: <a href="#X_002e509-certificate-functions" accesskey="p" rel="previous">X.509 certificate functions</a>, Up: <a href="#Function-reference" accesskey="u" rel="up">Function 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>
18730 </div>
18731 <a name="GnuTLS_002dextra-Functions"></a>
18732 <h3 class="section">9.3 <acronym>GnuTLS-extra</acronym> Functions</h3>
18733 <a name="index-GnuTLS_002dextra-functions"></a>
18734
18735 <p>These functions are only available in the GPLv3+ version of the
18736 library called <code>gnutls-extra</code>. The prototypes for this library
18737 lie in &lsquo;<tt>gnutls/extra.h</tt>&rsquo;.
18738 </p>
18739
18740
18741
18742
18743 <a name="gnutls_005fextra_005fcheck_005fversion-1"></a>
18744 <h4 class="subheading">gnutls_extra_check_version</h4>
18745 <a name="gnutls_005fextra_005fcheck_005fversion"></a><dl>
18746 <dt><a name="index-gnutls_005fextra_005fcheck_005fversion"></a>Function: <em>const char *</em> <strong>gnutls_extra_check_version</strong> <em>(const char * <var>req_version</var>)</em></dt>
18747 <dd><p><var>req_version</var>: version string to compare with, or <code>NULL</code>.
18748 </p>
18749 <p>Check GnuTLS Extra Library version.
18750 </p>
18751 <p>See <code>GNUTLS_EXTRA_VERSION</code> for a suitable <code>req_version</code> string.
18752 </p>
18753 <p><strong>Return value:</strong> Check that the version of the library is at
18754 minimum the one given as a string in <code>req_version</code> and return the
18755 actual version string of the library; return <code>NULL</code> if the
18756 condition is not met.  If <code>NULL</code> is passed to this function no
18757 check is done and only the version string is returned.
18758 </p></dd></dl>
18759 <a name="gnutls_005fglobal_005finit_005fextra-1"></a>
18760 <h4 class="subheading">gnutls_global_init_extra</h4>
18761 <a name="gnutls_005fglobal_005finit_005fextra"></a><dl>
18762 <dt><a name="index-gnutls_005fglobal_005finit_005fextra"></a>Function: <em>int</em> <strong>gnutls_global_init_extra</strong> <em>( <var>void</var>)</em></dt>
18763 <dd>
18764 <p>This function initializes the global state of gnutls-extra library
18765 to defaults.
18766 </p>
18767 <p>Note that <code>gnutls_global_init()</code> has to be called before this
18768 function.  If this function is not called then the gnutls-extra
18769 library will not be usable.
18770 </p>
18771 <p>This function is not thread safe, see the discussion for
18772 <code>gnutls_global_init()</code> on how to deal with that.
18773 </p>
18774 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
18775 otherwise an error code is returned.
18776 </p></dd></dl>
18777 <hr>
18778 <a name="OpenPGP-functions"></a>
18779 <div class="header">
18780 <p>
18781 Next: <a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions" accesskey="n" rel="next">TLS Inner Application (TLS/IA) functions</a>, Previous: <a href="#GnuTLS_002dextra-functions" accesskey="p" rel="previous">GnuTLS-extra functions</a>, Up: <a href="#Function-reference" accesskey="u" rel="up">Function 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>
18782 </div>
18783 <a name="OpenPGP-Functions"></a>
18784 <h3 class="section">9.4 <acronym>OpenPGP</acronym> Functions</h3>
18785 <a name="index-OpenPGP-functions"></a>
18786 <a name="sec_003aopenpgpapi"></a>
18787 <p>The following functions are to be used for <acronym>OpenPGP</acronym>
18788 certificate handling.  Their prototypes lie in
18789 &lsquo;<tt>gnutls/openpgp.h</tt>&rsquo;.
18790 </p>
18791
18792
18793
18794
18795 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile2-1"></a>
18796 <h4 class="subheading">gnutls_certificate_set_openpgp_key_file2</h4>
18797 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile2"></a><dl>
18798 <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>
18799 <dd><p><var>res</var>: the destination context to save the data.
18800 </p>
18801 <p><var>certfile</var>: the file that contains the public key.
18802 </p>
18803 <p><var>keyfile</var>: the file that contains the secret key.
18804 </p>
18805 <p><var>subkey_id</var>: a hex encoded subkey id
18806 </p>
18807 <p><var>format</var>: the format of the keys
18808 </p>
18809 <p>This funtion is used to load OpenPGP keys into the GnuTLS credential
18810 structure. The file should contain at least one valid non encrypted subkey.
18811 </p>
18812 <p>The special keyword &quot;auto&quot; is also accepted as <code>subkey_id</code>.  In that
18813 case the <code>gnutls_openpgp_crt_get_auth_subkey()</code> will be used to
18814 retrieve the subkey.
18815 </p>
18816 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18817 negative error value.
18818 </p>
18819 <p><strong>Since:</strong> 2.4.0
18820 </p></dd></dl>
18821
18822 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile-1"></a>
18823 <h4 class="subheading">gnutls_certificate_set_openpgp_key_file</h4>
18824 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005ffile"></a><dl>
18825 <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>
18826 <dd><p><var>res</var>: the destination context to save the data.
18827 </p>
18828 <p><var>certfile</var>: the file that contains the public key.
18829 </p>
18830 <p><var>keyfile</var>: the file that contains the secret key.
18831 </p>
18832 <p><var>format</var>: the format of the keys
18833 </p>
18834 <p>This funtion is used to load OpenPGP keys into the GnuTLS
18835 credentials structure. The file should contain at least one valid non encrypted subkey.
18836 </p>
18837 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18838 negative error value.
18839 </p></dd></dl>
18840
18841 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005fmem2-1"></a>
18842 <h4 class="subheading">gnutls_certificate_set_openpgp_key_mem2</h4>
18843 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005fmem2"></a><dl>
18844 <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>
18845 <dd><p><var>res</var>: the destination context to save the data.
18846 </p>
18847 <p><var>cert</var>: the datum that contains the public key.
18848 </p>
18849 <p><var>key</var>: the datum that contains the secret key.
18850 </p>
18851 <p><var>subkey_id</var>: a hex encoded subkey id
18852 </p>
18853 <p><var>format</var>: the format of the keys
18854 </p>
18855 <p>This funtion is used to load OpenPGP keys into the GnuTLS
18856 credentials structure. The datum should contain at least one valid non encrypted subkey.
18857 </p>
18858 <p>The special keyword &quot;auto&quot; is also accepted as <code>subkey_id</code>.  In that
18859 case the <code>gnutls_openpgp_crt_get_auth_subkey()</code> will be used to
18860 retrieve the subkey.
18861 </p>
18862 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18863 negative error value.
18864 </p>
18865 <p><strong>Since:</strong> 2.4.0
18866 </p></dd></dl>
18867
18868 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005fmem-1"></a>
18869 <h4 class="subheading">gnutls_certificate_set_openpgp_key_mem</h4>
18870 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey_005fmem"></a><dl>
18871 <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>
18872 <dd><p><var>res</var>: the destination context to save the data.
18873 </p>
18874 <p><var>cert</var>: the datum that contains the public key.
18875 </p>
18876 <p><var>key</var>: the datum that contains the secret key.
18877 </p>
18878 <p><var>format</var>: the format of the keys
18879 </p>
18880 <p>This funtion is used to load OpenPGP keys into the GnuTLS credential
18881 structure. The datum should contain at least one valid non encrypted subkey.
18882 </p>
18883 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18884 negative error value.
18885 </p></dd></dl>
18886
18887 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005ffile-1"></a>
18888 <h4 class="subheading">gnutls_certificate_set_openpgp_keyring_file</h4>
18889 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005ffile"></a><dl>
18890 <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>
18891 <dd><p><var>c</var>: A certificate credentials structure
18892 </p>
18893 <p><var>file</var>: filename of the keyring.
18894 </p>
18895 <p><var>format</var>: format of keyring.
18896 </p>
18897 <p>The function is used to set keyrings that will be used internally
18898 by various OpenPGP functions. For example to find a key when it
18899 is needed for an operations. The keyring will also be used at the
18900 verification functions.
18901 </p>
18902 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18903 negative error value.
18904 </p></dd></dl>
18905
18906 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005fmem-1"></a>
18907 <h4 class="subheading">gnutls_certificate_set_openpgp_keyring_mem</h4>
18908 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkeyring_005fmem"></a><dl>
18909 <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 opaque * <var>data</var>, size_t <var>dlen</var>, gnutls_openpgp_crt_fmt_t <var>format</var>)</em></dt>
18910 <dd><p><var>c</var>: A certificate credentials structure
18911 </p>
18912 <p><var>data</var>: buffer with keyring data.
18913 </p>
18914 <p><var>dlen</var>: length of data buffer.
18915 </p>
18916 <p><var>format</var>: the format of the keyring
18917 </p>
18918 <p>The function is used to set keyrings that will be used internally
18919 by various OpenPGP functions. For example to find a key when it
18920 is needed for an operations. The keyring will also be used at the
18921 verification functions.
18922 </p>
18923 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
18924 negative error value.
18925 </p></dd></dl>
18926
18927 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey-1"></a>
18928 <h4 class="subheading">gnutls_certificate_set_openpgp_key</h4>
18929 <a name="gnutls_005fcertificate_005fset_005fopenpgp_005fkey"></a><dl>
18930 <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>
18931 <dd><p><var>res</var>: is a <code>gnutls_certificate_credentials_t</code> structure.
18932 </p>
18933 <p><var>pkey</var>: is an openpgp private key
18934 </p>
18935 <p>This function sets a certificate/private key pair in the
18936 gnutls_certificate_credentials_t structure.  This function may be
18937 called more than once (in case multiple keys/certificates exist
18938 for the server).
18939 </p>
18940 <p>Note that this function requires that the preferred key ids have
18941 been set and be used. See <code>gnutls_openpgp_crt_set_preferred_key_id()</code>.
18942 Otherwise the master key will be used.
18943 </p>
18944 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
18945 otherwise an error code is returned.
18946 </p></dd></dl>
18947
18948 <a name="gnutls_005fopenpgp_005fcrt_005fcheck_005fhostname-1"></a>
18949 <h4 class="subheading">gnutls_openpgp_crt_check_hostname</h4>
18950 <a name="gnutls_005fopenpgp_005fcrt_005fcheck_005fhostname"></a><dl>
18951 <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>
18952 <dd><p><var>key</var>: should contain a <code>gnutls_openpgp_crt_t</code> structure
18953 </p>
18954 <p><var>hostname</var>: A null terminated string that contains a DNS name
18955 </p>
18956 <p>This function will check if the given key&rsquo;s owner matches the
18957 given hostname. This is a basic implementation of the matching
18958 described in RFC2818 (HTTPS), which takes into account wildcards.
18959 </p>
18960 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
18961 </p></dd></dl>
18962
18963 <a name="gnutls_005fopenpgp_005fcrt_005fdeinit-1"></a>
18964 <h4 class="subheading">gnutls_openpgp_crt_deinit</h4>
18965 <a name="gnutls_005fopenpgp_005fcrt_005fdeinit"></a><dl>
18966 <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>
18967 <dd><p><var>key</var>: The structure to be initialized
18968 </p>
18969 <p>This function will deinitialize a key structure.
18970 </p></dd></dl>
18971
18972 <a name="gnutls_005fopenpgp_005fcrt_005fexport-1"></a>
18973 <h4 class="subheading">gnutls_openpgp_crt_export</h4>
18974 <a name="gnutls_005fopenpgp_005fcrt_005fexport"></a><dl>
18975 <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>
18976 <dd><p><var>key</var>: Holds the key.
18977 </p>
18978 <p><var>format</var>: One of gnutls_openpgp_crt_fmt_t elements.
18979 </p>
18980 <p><var>output_data</var>: will contain the key base64 encoded or raw
18981 </p>
18982 <p><var>output_data_size</var>: holds the size of output_data (and will
18983 be replaced by the actual size of parameters)
18984 </p>
18985 <p>This function will convert the given key to RAW or Base64 format.
18986 If the buffer provided is not long enough to hold the output, then
18987 <code>GNUTLS_E_SHORT_MEMORY_BUFFER</code> will be returned.
18988 </p>
18989 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
18990 </p></dd></dl>
18991
18992 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fauth_005fsubkey-1"></a>
18993 <h4 class="subheading">gnutls_openpgp_crt_get_auth_subkey</h4>
18994 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fauth_005fsubkey"></a><dl>
18995 <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>
18996 <dd><p><var>crt</var>: the structure that contains the OpenPGP public key.
18997 </p>
18998 <p><var>keyid</var>: the struct to save the keyid.
18999 </p>
19000 <p><var>flag</var>: Non zero indicates that a valid subkey is always returned.
19001 </p>
19002 <p>Returns the 64-bit keyID of the first valid OpenPGP subkey marked
19003 for authentication.  If flag is non zero and no authentication
19004 subkey exists, then a valid subkey will be returned even if it is
19005 not marked for authentication.
19006 Returns the 64-bit keyID of the first valid OpenPGP subkey marked
19007 for authentication.  If flag is non zero and no authentication
19008 subkey exists, then a valid subkey will be returned even if it is
19009 not marked for authentication.
19010 </p>
19011 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
19012 </p></dd></dl>
19013
19014 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fcreation_005ftime-1"></a>
19015 <h4 class="subheading">gnutls_openpgp_crt_get_creation_time</h4>
19016 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fcreation_005ftime"></a><dl>
19017 <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>
19018 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19019 </p>
19020 <p>Get key creation time.
19021 </p>
19022 <p><strong>Returns:</strong> the timestamp when the OpenPGP key was created.
19023 </p></dd></dl>
19024
19025 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fexpiration_005ftime-1"></a>
19026 <h4 class="subheading">gnutls_openpgp_crt_get_expiration_time</h4>
19027 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fexpiration_005ftime"></a><dl>
19028 <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>
19029 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19030 </p>
19031 <p>Get key expiration time.  A value of &rsquo;0&rsquo; means that the key doesn&rsquo;t
19032 expire at all.
19033 </p>
19034 <p><strong>Returns:</strong> the time when the OpenPGP key expires.
19035 </p></dd></dl>
19036
19037 <a name="gnutls_005fopenpgp_005fcrt_005fget_005ffingerprint-1"></a>
19038 <h4 class="subheading">gnutls_openpgp_crt_get_fingerprint</h4>
19039 <a name="gnutls_005fopenpgp_005fcrt_005fget_005ffingerprint"></a><dl>
19040 <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>
19041 <dd><p><var>key</var>: the raw data that contains the OpenPGP public key.
19042 </p>
19043 <p><var>fpr</var>: the buffer to save the fingerprint, must hold at least 20 bytes.
19044 </p>
19045 <p><var>fprlen</var>: the integer to save the length of the fingerprint.
19046 </p>
19047 <p>Get key fingerprint.  Depending on the algorithm, the fingerprint
19048 can be 16 or 20 bytes.
19049 </p>
19050 <p><strong>Returns:</strong> On success, 0 is returned.  Otherwise, an error code.
19051 </p></dd></dl>
19052
19053 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fkey_005fid-1"></a>
19054 <h4 class="subheading">gnutls_openpgp_crt_get_key_id</h4>
19055 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fkey_005fid"></a><dl>
19056 <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>
19057 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19058 </p>
19059 <p><var>keyid</var>: the buffer to save the keyid.
19060 </p>
19061 <p>Get key id string.
19062 </p>
19063 <p><strong>Returns:</strong> the 64-bit keyID of the OpenPGP key.
19064 </p>
19065 <p><strong>Since:</strong> 2.4.0
19066 </p></dd></dl>
19067
19068 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fkey_005fusage-1"></a>
19069 <h4 class="subheading">gnutls_openpgp_crt_get_key_usage</h4>
19070 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fkey_005fusage"></a><dl>
19071 <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>
19072 <dd><p><var>key</var>: should contain a gnutls_openpgp_crt_t structure
19073 </p>
19074 <p><var>key_usage</var>: where the key usage bits will be stored
19075 </p>
19076 <p>This function will return certificate&rsquo;s key usage, by checking the
19077 key algorithm. The key usage value will ORed values of the:
19078 <code>GNUTLS_KEY_DIGITAL_SIGNATURE</code>, <code>GNUTLS_KEY_KEY_ENCIPHERMENT</code>.
19079 </p>
19080 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
19081 </p></dd></dl>
19082
19083 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fname-1"></a>
19084 <h4 class="subheading">gnutls_openpgp_crt_get_name</h4>
19085 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fname"></a><dl>
19086 <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>
19087 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19088 </p>
19089 <p><var>idx</var>: the index of the ID to extract
19090 </p>
19091 <p><var>buf</var>: a pointer to a structure to hold the name, may be <code>NULL</code>
19092 to only get the <code>sizeof_buf</code>.
19093 </p>
19094 <p><var>sizeof_buf</var>: holds the maximum size of <code>buf</code>, on return hold the
19095 actual/required size of <code>buf</code>.
19096 </p>
19097 <p>Extracts the userID from the parsed OpenPGP key.
19098 </p>
19099 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, and if the index of the ID
19100 does not exist <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code>, or an
19101 error code.
19102 </p></dd></dl>
19103
19104 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpk_005falgorithm-1"></a>
19105 <h4 class="subheading">gnutls_openpgp_crt_get_pk_algorithm</h4>
19106 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpk_005falgorithm"></a><dl>
19107 <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>
19108 <dd><p><var>key</var>: is an OpenPGP key
19109 </p>
19110 <p><var>bits</var>: if bits is non null it will hold the size of the parameters&rsquo; in bits
19111 </p>
19112 <p>This function will return the public key algorithm of an OpenPGP
19113 certificate.
19114 </p>
19115 <p>If bits is non null, it should have enough size to hold the parameters
19116 size in bits. For RSA the bits returned is the modulus.
19117 For DSA the bits returned are of the public exponent.
19118 </p>
19119 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code> enumeration on
19120 success, or GNUTLS_PK_UNKNOWN on error.
19121 </p></dd></dl>
19122
19123 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpk_005fdsa_005fraw-1"></a>
19124 <h4 class="subheading">gnutls_openpgp_crt_get_pk_dsa_raw</h4>
19125 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpk_005fdsa_005fraw"></a><dl>
19126 <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>
19127 <dd><p><var>crt</var>: Holds the certificate
19128 </p>
19129 <p><var>p</var>: will hold the p
19130 </p>
19131 <p><var>q</var>: will hold the q
19132 </p>
19133 <p><var>g</var>: will hold the g
19134 </p>
19135 <p><var>y</var>: will hold the y
19136 </p>
19137 <p>This function will export the DSA public key&rsquo;s parameters found in
19138 the given certificate.  The new parameters will be allocated using
19139 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
19140 </p>
19141 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
19142 </p>
19143 <p><strong>Since:</strong> 2.4.0
19144 </p></dd></dl>
19145
19146 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpk_005frsa_005fraw-1"></a>
19147 <h4 class="subheading">gnutls_openpgp_crt_get_pk_rsa_raw</h4>
19148 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpk_005frsa_005fraw"></a><dl>
19149 <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>
19150 <dd><p><var>crt</var>: Holds the certificate
19151 </p>
19152 <p><var>m</var>: will hold the modulus
19153 </p>
19154 <p><var>e</var>: will hold the public exponent
19155 </p>
19156 <p>This function will export the RSA public key&rsquo;s parameters found in
19157 the given structure.  The new parameters will be allocated using
19158 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
19159 </p>
19160 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
19161 </p>
19162 <p><strong>Since:</strong> 2.4.0
19163 </p></dd></dl>
19164
19165 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpreferred_005fkey_005fid-1"></a>
19166 <h4 class="subheading">gnutls_openpgp_crt_get_preferred_key_id</h4>
19167 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fpreferred_005fkey_005fid"></a><dl>
19168 <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>
19169 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19170 </p>
19171 <p><var>keyid</var>: the struct to save the keyid.
19172 </p>
19173 <p>Get preferred key id.  If it hasn&rsquo;t been set it returns
19174 <code>GNUTLS_E_INVALID_REQUEST</code>.
19175 </p>
19176 <p><strong>Returns:</strong> the 64-bit preferred keyID of the OpenPGP key.
19177 </p></dd></dl>
19178
19179 <a name="gnutls_005fopenpgp_005fcrt_005fget_005frevoked_005fstatus-1"></a>
19180 <h4 class="subheading">gnutls_openpgp_crt_get_revoked_status</h4>
19181 <a name="gnutls_005fopenpgp_005fcrt_005fget_005frevoked_005fstatus"></a><dl>
19182 <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>
19183 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19184 </p>
19185 <p>Get revocation status of key.
19186 </p>
19187 <p><strong>Returns:</strong> true (1) if the key has been revoked, or false (0) if it
19188 has not.
19189 </p>
19190 <p><strong>Since:</strong> 2.4.0
19191 </p></dd></dl>
19192
19193 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fcount-1"></a>
19194 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_count</h4>
19195 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fcount"></a><dl>
19196 <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>
19197 <dd><p><var>key</var>: is an OpenPGP key
19198 </p>
19199 <p>This function will return the number of subkeys present in the
19200 given OpenPGP certificate.
19201 </p>
19202 <p><strong>Returns:</strong> the number of subkeys, or a negative value on error.
19203 </p>
19204 <p><strong>Since:</strong> 2.4.0
19205 </p></dd></dl>
19206
19207 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fcreation_005ftime-1"></a>
19208 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_creation_time</h4>
19209 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fcreation_005ftime"></a><dl>
19210 <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>
19211 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19212 </p>
19213 <p><var>idx</var>: the subkey index
19214 </p>
19215 <p>Get subkey creation time.
19216 </p>
19217 <p><strong>Returns:</strong> the timestamp when the OpenPGP sub-key was created.
19218 </p>
19219 <p><strong>Since:</strong> 2.4.0
19220 </p></dd></dl>
19221
19222 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fexpiration_005ftime-1"></a>
19223 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_expiration_time</h4>
19224 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fexpiration_005ftime"></a><dl>
19225 <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>
19226 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19227 </p>
19228 <p><var>idx</var>: the subkey index
19229 </p>
19230 <p>Get subkey expiration time.  A value of &rsquo;0&rsquo; means that the key
19231 doesn&rsquo;t expire at all.
19232 </p>
19233 <p><strong>Returns:</strong> the time when the OpenPGP key expires.
19234 </p>
19235 <p><strong>Since:</strong> 2.4.0
19236 </p></dd></dl>
19237
19238 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005ffingerprint-1"></a>
19239 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_fingerprint</h4>
19240 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005ffingerprint"></a><dl>
19241 <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>
19242 <dd><p><var>key</var>: the raw data that contains the OpenPGP public key.
19243 </p>
19244 <p><var>idx</var>: the subkey index
19245 </p>
19246 <p><var>fpr</var>: the buffer to save the fingerprint, must hold at least 20 bytes.
19247 </p>
19248 <p><var>fprlen</var>: the integer to save the length of the fingerprint.
19249 </p>
19250 <p>Get key fingerprint of a subkey.  Depending on the algorithm, the
19251 fingerprint can be 16 or 20 bytes.
19252 </p>
19253 <p><strong>Returns:</strong> On success, 0 is returned.  Otherwise, an error code.
19254 </p>
19255 <p><strong>Since:</strong> 2.4.0
19256 </p></dd></dl>
19257
19258 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fidx-1"></a>
19259 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_idx</h4>
19260 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fidx"></a><dl>
19261 <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>
19262 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19263 </p>
19264 <p><var>keyid</var>: the keyid.
19265 </p>
19266 <p>Get subkey&rsquo;s index.
19267 </p>
19268 <p><strong>Returns:</strong> the index of the subkey or a negative error value.
19269 </p>
19270 <p><strong>Since:</strong> 2.4.0
19271 </p></dd></dl>
19272
19273 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fid-1"></a>
19274 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_id</h4>
19275 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fid"></a><dl>
19276 <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>
19277 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19278 </p>
19279 <p><var>idx</var>: the subkey index
19280 </p>
19281 <p><var>keyid</var>: the buffer to save the keyid.
19282 </p>
19283 <p>Get the subkey&rsquo;s key-id.
19284 </p>
19285 <p><strong>Returns:</strong> the 64-bit keyID of the OpenPGP key.
19286 </p></dd></dl>
19287
19288 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005falgorithm-1"></a>
19289 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_pk_algorithm</h4>
19290 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005falgorithm"></a><dl>
19291 <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>
19292 <dd><p><var>key</var>: is an OpenPGP key
19293 </p>
19294 <p><var>idx</var>: is the subkey index
19295 </p>
19296 <p><var>bits</var>: if bits is non null it will hold the size of the parameters&rsquo; in bits
19297 </p>
19298 <p>This function will return the public key algorithm of a subkey of an OpenPGP
19299 certificate.
19300 </p>
19301 <p>If bits is non null, it should have enough size to hold the
19302 parameters size in bits.  For RSA the bits returned is the modulus.
19303 For DSA the bits returned are of the public exponent.
19304 </p>
19305 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code> enumeration on
19306 success, or GNUTLS_PK_UNKNOWN on error.
19307 </p>
19308 <p><strong>Since:</strong> 2.4.0
19309 </p></dd></dl>
19310
19311 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005fdsa_005fraw-1"></a>
19312 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_pk_dsa_raw</h4>
19313 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005fdsa_005fraw"></a><dl>
19314 <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>
19315 <dd><p><var>crt</var>: Holds the certificate
19316 </p>
19317 <p><var>idx</var>: Is the subkey index
19318 </p>
19319 <p><var>p</var>: will hold the p
19320 </p>
19321 <p><var>q</var>: will hold the q
19322 </p>
19323 <p><var>g</var>: will hold the g
19324 </p>
19325 <p><var>y</var>: will hold the y
19326 </p>
19327 <p>This function will export the DSA public key&rsquo;s parameters found in
19328 the given certificate.  The new parameters will be allocated using
19329 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
19330 </p>
19331 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
19332 </p>
19333 <p><strong>Since:</strong> 2.4.0
19334 </p></dd></dl>
19335
19336 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005frsa_005fraw-1"></a>
19337 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_pk_rsa_raw</h4>
19338 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fpk_005frsa_005fraw"></a><dl>
19339 <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>
19340 <dd><p><var>crt</var>: Holds the certificate
19341 </p>
19342 <p><var>idx</var>: Is the subkey index
19343 </p>
19344 <p><var>m</var>: will hold the modulus
19345 </p>
19346 <p><var>e</var>: will hold the public exponent
19347 </p>
19348 <p>This function will export the RSA public key&rsquo;s parameters found in
19349 the given structure.  The new parameters will be allocated using
19350 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
19351 </p>
19352 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
19353 </p>
19354 <p><strong>Since:</strong> 2.4.0
19355 </p></dd></dl>
19356
19357 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005frevoked_005fstatus-1"></a>
19358 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_revoked_status</h4>
19359 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005frevoked_005fstatus"></a><dl>
19360 <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>
19361 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19362 </p>
19363 <p><var>idx</var>: is the subkey index
19364 </p>
19365 <p>Get subkey revocation status.  A negative value indicates an error.
19366 </p>
19367 <p><strong>Returns:</strong> true (1) if the key has been revoked, or false (0) if it
19368 has not.
19369 </p>
19370 <p><strong>Since:</strong> 2.4.0
19371 </p></dd></dl>
19372
19373 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fusage-1"></a>
19374 <h4 class="subheading">gnutls_openpgp_crt_get_subkey_usage</h4>
19375 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fsubkey_005fusage"></a><dl>
19376 <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>
19377 <dd><p><var>key</var>: should contain a gnutls_openpgp_crt_t structure
19378 </p>
19379 <p><var>idx</var>: the subkey index
19380 </p>
19381 <p><var>key_usage</var>: where the key usage bits will be stored
19382 </p>
19383 <p>This function will return certificate&rsquo;s key usage, by checking the
19384 key algorithm.  The key usage value will ORed values of
19385 <code>GNUTLS_KEY_DIGITAL_SIGNATURE</code> or <code>GNUTLS_KEY_KEY_ENCIPHERMENT</code>.
19386 </p>
19387 <p>A negative value may be returned in case of parsing error.
19388 </p>
19389 <p><strong>Returns:</strong> key usage value.
19390 </p>
19391 <p><strong>Since:</strong> 2.4.0
19392 </p></dd></dl>
19393
19394 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fversion-1"></a>
19395 <h4 class="subheading">gnutls_openpgp_crt_get_version</h4>
19396 <a name="gnutls_005fopenpgp_005fcrt_005fget_005fversion"></a><dl>
19397 <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>
19398 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19399 </p>
19400 <p>Extract the version of the OpenPGP key.
19401 </p>
19402 <p><strong>Returns:</strong> the version number is returned, or a negative value on errors.
19403 </p></dd></dl>
19404
19405 <a name="gnutls_005fopenpgp_005fcrt_005fimport-1"></a>
19406 <h4 class="subheading">gnutls_openpgp_crt_import</h4>
19407 <a name="gnutls_005fopenpgp_005fcrt_005fimport"></a><dl>
19408 <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>
19409 <dd><p><var>key</var>: The structure to store the parsed key.
19410 </p>
19411 <p><var>data</var>: The RAW or BASE64 encoded key.
19412 </p>
19413 <p><var>format</var>: One of gnutls_openpgp_crt_fmt_t elements.
19414 </p>
19415 <p>This function will convert the given RAW or Base64 encoded key to
19416 the native <code>gnutls_openpgp_crt_t</code> format. The output will be stored
19417 in &rsquo;key&rsquo;.
19418 </p>
19419 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
19420 </p></dd></dl>
19421
19422 <a name="gnutls_005fopenpgp_005fcrt_005finit-1"></a>
19423 <h4 class="subheading">gnutls_openpgp_crt_init</h4>
19424 <a name="gnutls_005fopenpgp_005fcrt_005finit"></a><dl>
19425 <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>
19426 <dd><p><var>key</var>: The structure to be initialized
19427 </p>
19428 <p>This function will initialize an OpenPGP key structure.
19429 </p>
19430 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
19431 </p></dd></dl>
19432
19433 <a name="gnutls_005fopenpgp_005fcrt_005fprint-1"></a>
19434 <h4 class="subheading">gnutls_openpgp_crt_print</h4>
19435 <a name="gnutls_005fopenpgp_005fcrt_005fprint"></a><dl>
19436 <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>
19437 <dd><p><var>cert</var>: The structure to be printed
19438 </p>
19439 <p><var>format</var>: Indicate the format to use
19440 </p>
19441 <p><var>out</var>: Newly allocated datum with zero terminated string.
19442 </p>
19443 <p>This function will pretty print an OpenPGP certificate, suitable
19444 for display to a human.
19445 </p>
19446 <p>The format should be zero for future compatibility.
19447 </p>
19448 <p>The output <code>out</code> needs to be deallocate using <code>gnutls_free()</code>.
19449 </p>
19450 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
19451 </p></dd></dl>
19452
19453 <a name="gnutls_005fopenpgp_005fcrt_005fset_005fpreferred_005fkey_005fid-1"></a>
19454 <h4 class="subheading">gnutls_openpgp_crt_set_preferred_key_id</h4>
19455 <a name="gnutls_005fopenpgp_005fcrt_005fset_005fpreferred_005fkey_005fid"></a><dl>
19456 <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>
19457 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19458 </p>
19459 <p><var>keyid</var>: the selected keyid
19460 </p>
19461 <p>This allows setting a preferred key id for the given certificate.
19462 This key will be used by functions that involve key handling.
19463 </p>
19464 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
19465 otherwise an error code is returned.
19466 </p></dd></dl>
19467
19468 <a name="gnutls_005fopenpgp_005fcrt_005fverify_005fring-1"></a>
19469 <h4 class="subheading">gnutls_openpgp_crt_verify_ring</h4>
19470 <a name="gnutls_005fopenpgp_005fcrt_005fverify_005fring"></a><dl>
19471 <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>
19472 <dd><p><var>key</var>: the structure that holds the key.
19473 </p>
19474 <p><var>keyring</var>: holds the keyring to check against
19475 </p>
19476 <p><var>flags</var>: unused (should be 0)
19477 </p>
19478 <p><var>verify</var>: will hold the certificate verification output.
19479 </p>
19480 <p>Verify all signatures in the key, using the given set of keys
19481 (keyring).
19482 </p>
19483 <p>The key verification output will be put in <code>verify</code> and will be one
19484 or more of the <code>gnutls_certificate_status_t</code> enumerated elements
19485 bitwise or&rsquo;d.
19486 </p>
19487 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
19488 </p></dd></dl>
19489
19490 <a name="gnutls_005fopenpgp_005fcrt_005fverify_005fself-1"></a>
19491 <h4 class="subheading">gnutls_openpgp_crt_verify_self</h4>
19492 <a name="gnutls_005fopenpgp_005fcrt_005fverify_005fself"></a><dl>
19493 <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>
19494 <dd><p><var>key</var>: the structure that holds the key.
19495 </p>
19496 <p><var>flags</var>: unused (should be 0)
19497 </p>
19498 <p><var>verify</var>: will hold the key verification output.
19499 </p>
19500 <p>Verifies the self signature in the key.  The key verification
19501 output will be put in <code>verify</code> and will be one or more of the
19502 gnutls_certificate_status_t enumerated elements bitwise or&rsquo;d.
19503 </p>
19504 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
19505 </p></dd></dl>
19506
19507 <a name="gnutls_005fopenpgp_005fkeyring_005fcheck_005fid-1"></a>
19508 <h4 class="subheading">gnutls_openpgp_keyring_check_id</h4>
19509 <a name="gnutls_005fopenpgp_005fkeyring_005fcheck_005fid"></a><dl>
19510 <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>
19511 <dd><p><var>ring</var>: holds the keyring to check against
19512 </p>
19513 <p><var>keyid</var>: will hold the keyid to check for.
19514 </p>
19515 <p><var>flags</var>: unused (should be 0)
19516 </p>
19517 <p>Check if a given key ID exists in the keyring.
19518 </p>
19519 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success (if keyid exists) and a
19520 negative error code on failure.
19521 </p></dd></dl>
19522
19523 <a name="gnutls_005fopenpgp_005fkeyring_005fdeinit-1"></a>
19524 <h4 class="subheading">gnutls_openpgp_keyring_deinit</h4>
19525 <a name="gnutls_005fopenpgp_005fkeyring_005fdeinit"></a><dl>
19526 <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>
19527 <dd><p><var>keyring</var>: The structure to be initialized
19528 </p>
19529 <p>This function will deinitialize a keyring structure.
19530 </p></dd></dl>
19531
19532 <a name="gnutls_005fopenpgp_005fkeyring_005fget_005fcrt_005fcount-1"></a>
19533 <h4 class="subheading">gnutls_openpgp_keyring_get_crt_count</h4>
19534 <a name="gnutls_005fopenpgp_005fkeyring_005fget_005fcrt_005fcount"></a><dl>
19535 <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>
19536 <dd><p><var>ring</var>: is an OpenPGP key ring
19537 </p>
19538 <p>This function will return the number of OpenPGP certificates
19539 present in the given keyring.
19540 </p>
19541 <p><strong>Returns:</strong> the number of subkeys, or a negative value on error.
19542 </p></dd></dl>
19543
19544 <a name="gnutls_005fopenpgp_005fkeyring_005fget_005fcrt-1"></a>
19545 <h4 class="subheading">gnutls_openpgp_keyring_get_crt</h4>
19546 <a name="gnutls_005fopenpgp_005fkeyring_005fget_005fcrt"></a><dl>
19547 <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>
19548 <dd><p><var>ring</var>: Holds the keyring.
19549 </p>
19550 <p><var>idx</var>: the index of the certificate to export
19551 </p>
19552 <p><var>cert</var>: An uninitialized <code>gnutls_openpgp_crt_t</code> structure
19553 </p>
19554 <p>This function will extract an OpenPGP certificate from the given
19555 keyring.  If the index given is out of range
19556 <code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE</code> will be returned. The
19557 returned structure needs to be deinited.
19558 </p>
19559 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
19560 </p></dd></dl>
19561
19562 <a name="gnutls_005fopenpgp_005fkeyring_005fimport-1"></a>
19563 <h4 class="subheading">gnutls_openpgp_keyring_import</h4>
19564 <a name="gnutls_005fopenpgp_005fkeyring_005fimport"></a><dl>
19565 <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>
19566 <dd><p><var>keyring</var>: The structure to store the parsed key.
19567 </p>
19568 <p><var>data</var>: The RAW or BASE64 encoded keyring.
19569 </p>
19570 <p><var>format</var>: One of <code>gnutls_openpgp_keyring_fmt</code> elements.
19571 </p>
19572 <p>This function will convert the given RAW or Base64 encoded keyring
19573 to the native <code>gnutls_openpgp_keyring_t</code> format.  The output will be
19574 stored in &rsquo;keyring&rsquo;.
19575 </p>
19576 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
19577 </p></dd></dl>
19578 <a name="gnutls_005fopenpgp_005fkeyring_005finit-1"></a>
19579 <h4 class="subheading">gnutls_openpgp_keyring_init</h4>
19580 <a name="gnutls_005fopenpgp_005fkeyring_005finit"></a><dl>
19581 <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>
19582 <dd><p><var>keyring</var>: The structure to be initialized
19583 </p>
19584 <p>This function will initialize an keyring structure.
19585 </p>
19586 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
19587 </p></dd></dl>
19588
19589 <a name="gnutls_005fopenpgp_005fprivkey_005fdeinit-1"></a>
19590 <h4 class="subheading">gnutls_openpgp_privkey_deinit</h4>
19591 <a name="gnutls_005fopenpgp_005fprivkey_005fdeinit"></a><dl>
19592 <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>
19593 <dd><p><var>key</var>: The structure to be initialized
19594 </p>
19595 <p>This function will deinitialize a key structure.
19596 </p></dd></dl>
19597
19598 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005fdsa_005fraw-1"></a>
19599 <h4 class="subheading">gnutls_openpgp_privkey_export_dsa_raw</h4>
19600 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005fdsa_005fraw"></a><dl>
19601 <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>
19602 <dd><p><var>pkey</var>: Holds the certificate
19603 </p>
19604 <p><var>p</var>: will hold the p
19605 </p>
19606 <p><var>q</var>: will hold the q
19607 </p>
19608 <p><var>g</var>: will hold the g
19609 </p>
19610 <p><var>y</var>: will hold the y
19611 </p>
19612 <p><var>x</var>: will hold the x
19613 </p>
19614 <p>This function will export the DSA private key&rsquo;s parameters found in
19615 the given certificate.  The new parameters will be allocated using
19616 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
19617 </p>
19618 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
19619 </p>
19620 <p><strong>Since:</strong> 2.4.0
19621 </p></dd></dl>
19622
19623 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005frsa_005fraw-1"></a>
19624 <h4 class="subheading">gnutls_openpgp_privkey_export_rsa_raw</h4>
19625 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005frsa_005fraw"></a><dl>
19626 <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>
19627 <dd><p><var>pkey</var>: Holds the certificate
19628 </p>
19629 <p><var>m</var>: will hold the modulus
19630 </p>
19631 <p><var>e</var>: will hold the public exponent
19632 </p>
19633 <p><var>d</var>: will hold the private exponent
19634 </p>
19635 <p><var>p</var>: will hold the first prime (p)
19636 </p>
19637 <p><var>q</var>: will hold the second prime (q)
19638 </p>
19639 <p><var>u</var>: will hold the coefficient
19640 </p>
19641 <p>This function will export the RSA private key&rsquo;s parameters found in
19642 the given structure.  The new parameters will be allocated using
19643 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
19644 </p>
19645 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
19646 </p>
19647 <p><strong>Since:</strong> 2.4.0
19648 </p></dd></dl>
19649
19650 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005fsubkey_005fdsa_005fraw-1"></a>
19651 <h4 class="subheading">gnutls_openpgp_privkey_export_subkey_dsa_raw</h4>
19652 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005fsubkey_005fdsa_005fraw"></a><dl>
19653 <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>
19654 <dd><p><var>pkey</var>: Holds the certificate
19655 </p>
19656 <p><var>idx</var>: Is the subkey index
19657 </p>
19658 <p><var>p</var>: will hold the p
19659 </p>
19660 <p><var>q</var>: will hold the q
19661 </p>
19662 <p><var>g</var>: will hold the g
19663 </p>
19664 <p><var>y</var>: will hold the y
19665 </p>
19666 <p><var>x</var>: will hold the x
19667 </p>
19668 <p>This function will export the DSA private key&rsquo;s parameters found
19669 in the given certificate.  The new parameters will be allocated
19670 using <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
19671 </p>
19672 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
19673 </p>
19674 <p><strong>Since:</strong> 2.4.0
19675 </p></dd></dl>
19676
19677 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005fsubkey_005frsa_005fraw-1"></a>
19678 <h4 class="subheading">gnutls_openpgp_privkey_export_subkey_rsa_raw</h4>
19679 <a name="gnutls_005fopenpgp_005fprivkey_005fexport_005fsubkey_005frsa_005fraw"></a><dl>
19680 <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>
19681 <dd><p><var>pkey</var>: Holds the certificate
19682 </p>
19683 <p><var>idx</var>: Is the subkey index
19684 </p>
19685 <p><var>m</var>: will hold the modulus
19686 </p>
19687 <p><var>e</var>: will hold the public exponent
19688 </p>
19689 <p><var>d</var>: will hold the private exponent
19690 </p>
19691 <p><var>p</var>: will hold the first prime (p)
19692 </p>
19693 <p><var>q</var>: will hold the second prime (q)
19694 </p>
19695 <p><var>u</var>: will hold the coefficient
19696 </p>
19697 <p>This function will export the RSA private key&rsquo;s parameters found in
19698 the given structure.  The new parameters will be allocated using
19699 <code>gnutls_malloc()</code> and will be stored in the appropriate datum.
19700 </p>
19701 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, otherwise an error.
19702 </p>
19703 <p><strong>Since:</strong> 2.4.0
19704 </p></dd></dl>
19705
19706 <a name="gnutls_005fopenpgp_005fprivkey_005fexport-1"></a>
19707 <h4 class="subheading">gnutls_openpgp_privkey_export</h4>
19708 <a name="gnutls_005fopenpgp_005fprivkey_005fexport"></a><dl>
19709 <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>
19710 <dd><p><var>key</var>: Holds the key.
19711 </p>
19712 <p><var>format</var>: One of gnutls_openpgp_crt_fmt_t elements.
19713 </p>
19714 <p><var>password</var>: the password that will be used to encrypt the key. (unused for now)
19715 </p>
19716 <p><var>flags</var>: zero for future compatibility
19717 </p>
19718 <p><var>output_data</var>: will contain the key base64 encoded or raw
19719 </p>
19720 <p><var>output_data_size</var>: holds the size of output_data (and will be
19721 replaced by the actual size of parameters)
19722 </p>
19723 <p>This function will convert the given key to RAW or Base64 format.
19724 If the buffer provided is not long enough to hold the output, then
19725 GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
19726 </p>
19727 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
19728 </p>
19729 <p><strong>Since:</strong> 2.4.0
19730 </p></dd></dl>
19731
19732 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005ffingerprint-1"></a>
19733 <h4 class="subheading">gnutls_openpgp_privkey_get_fingerprint</h4>
19734 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005ffingerprint"></a><dl>
19735 <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>
19736 <dd><p><var>key</var>: the raw data that contains the OpenPGP secret key.
19737 </p>
19738 <p><var>fpr</var>: the buffer to save the fingerprint, must hold at least 20 bytes.
19739 </p>
19740 <p><var>fprlen</var>: the integer to save the length of the fingerprint.
19741 </p>
19742 <p>Get the fingerprint of the OpenPGP key. Depends on the
19743 algorithm, the fingerprint can be 16 or 20 bytes.
19744 </p>
19745 <p><strong>Returns:</strong> On success, 0 is returned, or an error code.
19746 </p>
19747 <p><strong>Since:</strong> 2.4.0
19748 </p></dd></dl>
19749
19750 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fkey_005fid-1"></a>
19751 <h4 class="subheading">gnutls_openpgp_privkey_get_key_id</h4>
19752 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fkey_005fid"></a><dl>
19753 <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>
19754 <dd><p><var>key</var>: the structure that contains the OpenPGP secret key.
19755 </p>
19756 <p><var>keyid</var>: the buffer to save the keyid.
19757 </p>
19758 <p>Get key-id.
19759 </p>
19760 <p><strong>Returns:</strong> the 64-bit keyID of the OpenPGP key.
19761 </p>
19762 <p><strong>Since:</strong> 2.4.0
19763 </p></dd></dl>
19764
19765 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fpk_005falgorithm-1"></a>
19766 <h4 class="subheading">gnutls_openpgp_privkey_get_pk_algorithm</h4>
19767 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fpk_005falgorithm"></a><dl>
19768 <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>
19769 <dd><p><var>key</var>: is an OpenPGP key
19770 </p>
19771 <p><var>bits</var>: if bits is non null it will hold the size of the parameters&rsquo; in bits
19772 </p>
19773 <p>This function will return the public key algorithm of an OpenPGP
19774 certificate.
19775 </p>
19776 <p>If bits is non null, it should have enough size to hold the parameters
19777 size in bits. For RSA the bits returned is the modulus.
19778 For DSA the bits returned are of the public exponent.
19779 </p>
19780 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code> enumeration on
19781 success, or a negative value on error.
19782 </p>
19783 <p><strong>Since:</strong> 2.4.0
19784 </p></dd></dl>
19785
19786 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fpreferred_005fkey_005fid-1"></a>
19787 <h4 class="subheading">gnutls_openpgp_privkey_get_preferred_key_id</h4>
19788 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fpreferred_005fkey_005fid"></a><dl>
19789 <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>
19790 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
19791 </p>
19792 <p><var>keyid</var>: the struct to save the keyid.
19793 </p>
19794 <p>Get the preferred key-id for the key.
19795 </p>
19796 <p><strong>Returns:</strong> the 64-bit preferred keyID of the OpenPGP key, or if it
19797 hasn&rsquo;t been set it returns <code>GNUTLS_E_INVALID_REQUEST</code>.
19798 </p></dd></dl>
19799
19800 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005frevoked_005fstatus-1"></a>
19801 <h4 class="subheading">gnutls_openpgp_privkey_get_revoked_status</h4>
19802 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005frevoked_005fstatus"></a><dl>
19803 <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>
19804 <dd><p><var>key</var>: the structure that contains the OpenPGP private key.
19805 </p>
19806 <p>Get revocation status of key.
19807 </p>
19808 <p><strong>Returns:</strong> true (1) if the key has been revoked, or false (0) if it
19809 has not, or a negative value indicates an error.
19810 </p>
19811 <p><strong>Since:</strong> 2.4.0
19812 </p></dd></dl>
19813
19814 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fcount-1"></a>
19815 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_count</h4>
19816 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fcount"></a><dl>
19817 <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>
19818 <dd><p><var>key</var>: is an OpenPGP key
19819 </p>
19820 <p>This function will return the number of subkeys present in the
19821 given OpenPGP certificate.
19822 </p>
19823 <p><strong>Returns:</strong> the number of subkeys, or a negative value on error.
19824 </p>
19825 <p><strong>Since:</strong> 2.4.0
19826 </p></dd></dl>
19827
19828 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fcreation_005ftime-1"></a>
19829 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_creation_time</h4>
19830 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fcreation_005ftime"></a><dl>
19831 <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>
19832 <dd><p><var>key</var>: the structure that contains the OpenPGP private key.
19833 </p>
19834 <p><var>idx</var>: the subkey index
19835 </p>
19836 <p>Get subkey creation time.
19837 </p>
19838 <p><strong>Returns:</strong> the timestamp when the OpenPGP key was created.
19839 </p>
19840 <p><strong>Since:</strong> 2.4.0
19841 </p></dd></dl>
19842
19843 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fexpiration_005ftime-1"></a>
19844 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_expiration_time</h4>
19845 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fexpiration_005ftime"></a><dl>
19846 <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>
19847 <dd><p><var>key</var>: the structure that contains the OpenPGP private key.
19848 </p>
19849 <p><var>idx</var>: the subkey index
19850 </p>
19851 <p>Get subkey expiration time.  A value of &rsquo;0&rsquo; means that the key
19852 doesn&rsquo;t expire at all.
19853 </p>
19854 <p><strong>Returns:</strong> the time when the OpenPGP key expires.
19855 </p>
19856 <p><strong>Since:</strong> 2.4.0
19857 </p></dd></dl>
19858
19859 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005ffingerprint-1"></a>
19860 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_fingerprint</h4>
19861 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005ffingerprint"></a><dl>
19862 <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>
19863 <dd><p><var>key</var>: the raw data that contains the OpenPGP secret key.
19864 </p>
19865 <p><var>idx</var>: the subkey index
19866 </p>
19867 <p><var>fpr</var>: the buffer to save the fingerprint, must hold at least 20 bytes.
19868 </p>
19869 <p><var>fprlen</var>: the integer to save the length of the fingerprint.
19870 </p>
19871 <p>Get the fingerprint of an OpenPGP subkey.  Depends on the
19872 algorithm, the fingerprint can be 16 or 20 bytes.
19873 </p>
19874 <p><strong>Returns:</strong> On success, 0 is returned, or an error code.
19875 </p>
19876 <p><strong>Since:</strong> 2.4.0
19877 </p></dd></dl>
19878
19879 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fidx-1"></a>
19880 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_idx</h4>
19881 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fidx"></a><dl>
19882 <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>
19883 <dd><p><var>key</var>: the structure that contains the OpenPGP private key.
19884 </p>
19885 <p><var>keyid</var>: the keyid.
19886 </p>
19887 <p>Get index of subkey.
19888 </p>
19889 <p><strong>Returns:</strong> the index of the subkey or a negative error value.
19890 </p>
19891 <p><strong>Since:</strong> 2.4.0
19892 </p></dd></dl>
19893
19894 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fid-1"></a>
19895 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_id</h4>
19896 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fid"></a><dl>
19897 <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>
19898 <dd><p><var>key</var>: the structure that contains the OpenPGP secret key.
19899 </p>
19900 <p><var>idx</var>: the subkey index
19901 </p>
19902 <p><var>keyid</var>: the buffer to save the keyid.
19903 </p>
19904 <p>Get the key-id for the subkey.
19905 </p>
19906 <p><strong>Returns:</strong> the 64-bit keyID of the OpenPGP key.
19907 </p>
19908 <p><strong>Since:</strong> 2.4.0
19909 </p></dd></dl>
19910
19911 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fpk_005falgorithm-1"></a>
19912 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_pk_algorithm</h4>
19913 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005fpk_005falgorithm"></a><dl>
19914 <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>
19915 <dd><p><var>key</var>: is an OpenPGP key
19916 </p>
19917 <p><var>idx</var>: is the subkey index
19918 </p>
19919 <p><var>bits</var>: if bits is non null it will hold the size of the parameters&rsquo; in bits
19920 </p>
19921 <p>This function will return the public key algorithm of a subkey of an OpenPGP
19922 certificate.
19923 </p>
19924 <p>If bits is non null, it should have enough size to hold the parameters
19925 size in bits. For RSA the bits returned is the modulus.
19926 For DSA the bits returned are of the public exponent.
19927 </p>
19928 <p><strong>Returns:</strong> a member of the <code>gnutls_pk_algorithm_t</code> enumeration on
19929 success, or a negative value on error.
19930 </p>
19931 <p><strong>Since:</strong> 2.4.0
19932 </p></dd></dl>
19933
19934 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005frevoked_005fstatus-1"></a>
19935 <h4 class="subheading">gnutls_openpgp_privkey_get_subkey_revoked_status</h4>
19936 <a name="gnutls_005fopenpgp_005fprivkey_005fget_005fsubkey_005frevoked_005fstatus"></a><dl>
19937 <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>
19938 <dd><p><var>key</var>: the structure that contains the OpenPGP private key.
19939 </p>
19940 <p><var>idx</var>: is the subkey index
19941 </p>
19942 <p>Get revocation status of key.
19943 </p>
19944 <p><strong>Returns:</strong> true (1) if the key has been revoked, or false (0) if it
19945 has not, or a negative value indicates an error.
19946 </p>
19947 <p><strong>Since:</strong> 2.4.0
19948 </p></dd></dl>
19949
19950 <a name="gnutls_005fopenpgp_005fprivkey_005fimport-1"></a>
19951 <h4 class="subheading">gnutls_openpgp_privkey_import</h4>
19952 <a name="gnutls_005fopenpgp_005fprivkey_005fimport"></a><dl>
19953 <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>
19954 <dd><p><var>key</var>: The structure to store the parsed key.
19955 </p>
19956 <p><var>data</var>: The RAW or BASE64 encoded key.
19957 </p>
19958 <p><var>format</var>: One of <code>gnutls_openpgp_crt_fmt_t</code> elements.
19959 </p>
19960 <p><var>password</var>: not used for now
19961 </p>
19962 <p><var>flags</var>: should be zero
19963 </p>
19964 <p>This function will convert the given RAW or Base64 encoded key to
19965 the native gnutls_openpgp_privkey_t format.  The output will be
19966 stored in &rsquo;key&rsquo;.
19967 </p>
19968 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
19969 </p></dd></dl>
19970
19971 <a name="gnutls_005fopenpgp_005fprivkey_005finit-1"></a>
19972 <h4 class="subheading">gnutls_openpgp_privkey_init</h4>
19973 <a name="gnutls_005fopenpgp_005fprivkey_005finit"></a><dl>
19974 <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>
19975 <dd><p><var>key</var>: The structure to be initialized
19976 </p>
19977 <p>This function will initialize an OpenPGP key structure.
19978 </p>
19979 <p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code.
19980 </p></dd></dl>
19981
19982 <a name="gnutls_005fopenpgp_005fprivkey_005fsec_005fparam-1"></a>
19983 <h4 class="subheading">gnutls_openpgp_privkey_sec_param</h4>
19984 <a name="gnutls_005fopenpgp_005fprivkey_005fsec_005fparam"></a><dl>
19985 <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>
19986 <dd><p><var>key</var>: a key structure
19987 </p>
19988 <p>This function will return the security parameter appropriate with
19989 this private key.
19990 </p>
19991 <p><strong>Returns:</strong> On success, a valid security parameter is returned otherwise
19992 <code>GNUTLS_SEC_PARAM_UNKNOWN</code> is returned.
19993 </p></dd></dl>
19994
19995 <a name="gnutls_005fopenpgp_005fprivkey_005fset_005fpreferred_005fkey_005fid-1"></a>
19996 <h4 class="subheading">gnutls_openpgp_privkey_set_preferred_key_id</h4>
19997 <a name="gnutls_005fopenpgp_005fprivkey_005fset_005fpreferred_005fkey_005fid"></a><dl>
19998 <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>
19999 <dd><p><var>key</var>: the structure that contains the OpenPGP public key.
20000 </p>
20001 <p><var>keyid</var>: the selected keyid
20002 </p>
20003 <p>This allows setting a preferred key id for the given certificate.
20004 This key will be used by functions that involve key handling.
20005 </p>
20006 <p><strong>Returns:</strong> On success, 0 is returned, or an error code.
20007 </p></dd></dl>
20008
20009 <a name="gnutls_005fopenpgp_005fprivkey_005fsign_005fhash-1"></a>
20010 <h4 class="subheading">gnutls_openpgp_privkey_sign_hash</h4>
20011 <a name="gnutls_005fopenpgp_005fprivkey_005fsign_005fhash"></a><dl>
20012 <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>
20013 <dd><p><var>key</var>: Holds the key
20014 </p>
20015 <p><var>hash</var>: holds the data to be signed
20016 </p>
20017 <p><var>signature</var>: will contain newly allocated signature
20018 </p>
20019 <p>This function will sign the given hash using the private key.  You
20020 should use <code>gnutls_openpgp_privkey_set_preferred_key_id()</code> before
20021 calling this function to set the subkey to use.
20022 </p>
20023 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> is returned, otherwise a
20024 negative error value.
20025 </p>
20026 <p><strong>Deprecated:</strong> Use <code>gnutls_privkey_sign_hash()</code> instead.
20027 </p></dd></dl>
20028
20029 <a name="gnutls_005fopenpgp_005fset_005frecv_005fkey_005ffunction-1"></a>
20030 <h4 class="subheading">gnutls_openpgp_set_recv_key_function</h4>
20031 <a name="gnutls_005fopenpgp_005fset_005frecv_005fkey_005ffunction"></a><dl>
20032 <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>
20033 <dd><p><var>session</var>: a TLS session
20034 </p>
20035 <p><var>func</var>: the callback
20036 </p>
20037 <p>This funtion will set a key retrieval function for OpenPGP keys. This
20038 callback is only useful in server side, and will be used if the peer
20039 sent a key fingerprint instead of a full key.
20040 </p></dd></dl>
20041 <hr>
20042 <a name="TLS-Inner-Application-_0028TLS_002fIA_0029-functions"></a>
20043 <div class="header">
20044 <p>
20045 Next: <a href="#Error-codes-and-descriptions" accesskey="n" rel="next">Error codes and descriptions</a>, Previous: <a href="#OpenPGP-functions" accesskey="p" rel="previous">OpenPGP functions</a>, Up: <a href="#Function-reference" accesskey="u" rel="up">Function 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>
20046 </div>
20047 <a name="TLS-Inner-Application-_0028TLS_002fIA_0029-Functions"></a>
20048 <h3 class="section">9.5 <acronym>TLS</acronym> Inner Application (<acronym>TLS/IA</acronym>) Functions</h3>
20049 <a name="index-TLS-Inner-Application-_0028TLS_002fIA_0029-functions"></a>
20050 <a name="index-Inner-Application-_0028TLS_002fIA_0029-functions"></a>
20051
20052 <p>The following functions are used for <acronym>TLS</acronym> Inner Application
20053 (<acronym>TLS/IA</acronym>).  Their prototypes lie in &lsquo;<tt>gnutls/extra.h</tt>&rsquo;.
20054 You need to link with &lsquo;<tt>libgnutls-extra</tt>&rsquo; to be able to use these
20055 functions (see <a href="#GnuTLS_002dextra-functions">GnuTLS-extra functions</a>).
20056 </p>
20057 <p>The typical control flow in an TLS/IA client (that would not require
20058 an Application Phase for resumed sessions) would be similar to the
20059 following:
20060 </p>
20061 <div class="example">
20062 <pre class="example">int client_avp (gnuls_session_t *session, void *ptr,
20063                 const char *last, size_t lastlen,
20064                 char **new, size_t *newlen)
20065 {
20066 ...
20067 }
20068 ...
20069 int main ()
20070 {
20071   gnutls_ia_client_credentials_t iacred;
20072 ...
20073   gnutls_init (&amp;session, GNUTLS_CLIENT);
20074 ...
20075   /* Enable TLS/IA. */
20076   gnutls_ia_allocate_client_credentials(&amp;iacred);
20077   gnutls_ia_set_client_avp_function(iacred, client_avp);
20078   gnutls_credentials_set (session, GNUTLS_CRD_IA, iacred);
20079 ...
20080   ret = gnutls_handshake (session);
20081   // Error handling...
20082 ...
20083   if (gnutls_ia_handshake_p (session))
20084     {
20085       ret = gnutls_ia_handshake (session);
20086       // Error handling...
20087 ...
20088 </pre></div>
20089
20090 <p>See below for detailed descriptions of all the functions used above.
20091 </p>
20092 <p>The function <code>client_avp</code> would have to be implemented by your
20093 application.  The function is responsible for handling the AVP data.
20094 See <code>gnutls_ia_set_client_avp_function</code> below for more
20095 information on how that function should be implemented.
20096 </p>
20097 <p>The control flow in a typical server is similar to the above, use
20098 <code>gnutls_ia_server_credentials_t</code> instead of
20099 <code>gnutls_ia_client_credentials_t</code>, and replace the call to the
20100 client functions with the corresponding server functions.
20101 </p>
20102
20103
20104
20105
20106 <a name="gnutls_005fia_005fallocate_005fclient_005fcredentials-1"></a>
20107 <h4 class="subheading">gnutls_ia_allocate_client_credentials</h4>
20108 <a name="gnutls_005fia_005fallocate_005fclient_005fcredentials"></a><dl>
20109 <dt><a name="index-gnutls_005fia_005fallocate_005fclient_005fcredentials"></a>Function: <em>int</em> <strong>gnutls_ia_allocate_client_credentials</strong> <em>(gnutls_ia_client_credentials_t * <var>sc</var>)</em></dt>
20110 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_ia_server_credentials_t</code> structure.
20111 </p>
20112 <p>This structure is complex enough to manipulate directly thus this
20113 helper function is provided in order to allocate it.
20114 </p>
20115 <p>Adding this credential to a session will enable TLS/IA, and will
20116 require an Application Phase after the TLS handshake (if the server
20117 support TLS/IA).  Use <code>gnutls_ia_enable()</code> to toggle the TLS/IA mode.
20118 </p>
20119 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
20120 an error code is returned.
20121 </p></dd></dl>
20122
20123 <a name="gnutls_005fia_005fallocate_005fserver_005fcredentials-1"></a>
20124 <h4 class="subheading">gnutls_ia_allocate_server_credentials</h4>
20125 <a name="gnutls_005fia_005fallocate_005fserver_005fcredentials"></a><dl>
20126 <dt><a name="index-gnutls_005fia_005fallocate_005fserver_005fcredentials"></a>Function: <em>int</em> <strong>gnutls_ia_allocate_server_credentials</strong> <em>(gnutls_ia_server_credentials_t * <var>sc</var>)</em></dt>
20127 <dd><p><var>sc</var>: is a pointer to a <code>gnutls_ia_server_credentials_t</code> structure.
20128 </p>
20129 <p>This structure is complex enough to manipulate directly thus this
20130 helper function is provided in order to allocate it.
20131 </p>
20132 <p>Adding this credential to a session will enable TLS/IA, and will
20133 require an Application Phase after the TLS handshake (if the client
20134 support TLS/IA).  Use <code>gnutls_ia_enable()</code> to toggle the TLS/IA mode.
20135 </p>
20136 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (0) is returned, otherwise
20137 an error code is returned.
20138 </p></dd></dl>
20139
20140 <a name="gnutls_005fia_005fenable-1"></a>
20141 <h4 class="subheading">gnutls_ia_enable</h4>
20142 <a name="gnutls_005fia_005fenable"></a><dl>
20143 <dt><a name="index-gnutls_005fia_005fenable"></a>Function: <em>void</em> <strong>gnutls_ia_enable</strong> <em>(gnutls_session_t <var>session</var>, int <var>allow_skip_on_resume</var>)</em></dt>
20144 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
20145 </p>
20146 <p><var>allow_skip_on_resume</var>: non-zero if local party allows one to skip the
20147 TLS/IA application phases for a resumed session.
20148 </p>
20149 <p>Specify whether we must advertise support for the TLS/IA extension
20150 during the handshake.
20151 </p>
20152 <p>At the client side, we always advertise TLS/IA if gnutls_ia_enable
20153 was called before the handshake; at the server side, we also
20154 require that the client has advertised that it wants to run TLS/IA
20155 before including the advertisement, as required by the protocol.
20156 </p>
20157 <p>Similarly, at the client side we always advertise that we allow
20158 TLS/IA to be skipped for resumed sessions if <code>allow_skip_on_resume</code>
20159 is non-zero; at the server side, we also require that the session
20160 is indeed resumable and that the client has also advertised that it
20161 allows TLS/IA to be skipped for resumed sessions.
20162 </p>
20163 <p>After the TLS handshake, call <code>gnutls_ia_handshake_p()</code> to find out
20164 whether both parties agreed to do a TLS/IA handshake, before
20165 calling <code>gnutls_ia_handshake()</code> or one of the lower level gnutls_ia_*
20166 functions.
20167 </p></dd></dl>
20168
20169 <a name="gnutls_005fia_005fendphase_005fsend-1"></a>
20170 <h4 class="subheading">gnutls_ia_endphase_send</h4>
20171 <a name="gnutls_005fia_005fendphase_005fsend"></a><dl>
20172 <dt><a name="index-gnutls_005fia_005fendphase_005fsend"></a>Function: <em>int</em> <strong>gnutls_ia_endphase_send</strong> <em>(gnutls_session_t <var>session</var>, int <var>final_p</var>)</em></dt>
20173 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
20174 </p>
20175 <p><var>final_p</var>: Set iff this should signal the final phase.
20176 </p>
20177 <p>Send a TLS/IA end phase message.
20178 </p>
20179 <p>In the client, this should only be used to acknowledge an end phase
20180 message sent by the server.
20181 </p>
20182 <p>In the server, this can be called instead of <code>gnutls_ia_send()</code> if
20183 the server wishes to end an application phase.
20184 </p>
20185 <p><strong>Return value:</strong> Return 0 on success, or an error code.
20186 </p></dd></dl>
20187
20188 <a name="gnutls_005fia_005fextract_005finner_005fsecret-1"></a>
20189 <h4 class="subheading">gnutls_ia_extract_inner_secret</h4>
20190 <a name="gnutls_005fia_005fextract_005finner_005fsecret"></a><dl>
20191 <dt><a name="index-gnutls_005fia_005fextract_005finner_005fsecret"></a>Function: <em>void</em> <strong>gnutls_ia_extract_inner_secret</strong> <em>(gnutls_session_t <var>session</var>, char * <var>buffer</var>)</em></dt>
20192 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
20193 </p>
20194 <p><var>buffer</var>: pre-allocated buffer to hold 48 bytes of inner secret.
20195 </p>
20196 <p>Copy the 48 bytes large inner secret into the specified buffer
20197 </p>
20198 <p>This function is typically used after the TLS/IA handshake has
20199 concluded.  The TLS/IA inner secret can be used as input to a PRF
20200 to derive session keys.  Do not use the inner secret directly as a
20201 session key, because for a resumed session that does not include an
20202 application phase, the inner secret will be identical to the inner
20203 secret in the original session.  It is important to include, for
20204 example, the client and server randomness when deriving a sesssion
20205 key from the inner secret.
20206 </p></dd></dl>
20207
20208 <a name="gnutls_005fia_005ffree_005fclient_005fcredentials-1"></a>
20209 <h4 class="subheading">gnutls_ia_free_client_credentials</h4>
20210 <a name="gnutls_005fia_005ffree_005fclient_005fcredentials"></a><dl>
20211 <dt><a name="index-gnutls_005fia_005ffree_005fclient_005fcredentials"></a>Function: <em>void</em> <strong>gnutls_ia_free_client_credentials</strong> <em>(gnutls_ia_client_credentials_t <var>sc</var>)</em></dt>
20212 <dd><p><var>sc</var>: is a <code>gnutls_ia_client_credentials_t</code> structure.
20213 </p>
20214 <p>This structure is complex enough to manipulate directly thus this
20215 helper function is provided in order to free (deallocate) it.
20216 </p></dd></dl>
20217
20218 <a name="gnutls_005fia_005ffree_005fserver_005fcredentials-1"></a>
20219 <h4 class="subheading">gnutls_ia_free_server_credentials</h4>
20220 <a name="gnutls_005fia_005ffree_005fserver_005fcredentials"></a><dl>
20221 <dt><a name="index-gnutls_005fia_005ffree_005fserver_005fcredentials"></a>Function: <em>void</em> <strong>gnutls_ia_free_server_credentials</strong> <em>(gnutls_ia_server_credentials_t <var>sc</var>)</em></dt>
20222 <dd><p><var>sc</var>: is a <code>gnutls_ia_server_credentials_t</code> structure.
20223 </p>
20224 <p>This structure is complex enough to manipulate directly thus this
20225 helper function is provided in order to free (deallocate) it.
20226 </p></dd></dl>
20227
20228 <a name="gnutls_005fia_005fgenerate_005fchallenge-1"></a>
20229 <h4 class="subheading">gnutls_ia_generate_challenge</h4>
20230 <a name="gnutls_005fia_005fgenerate_005fchallenge"></a><dl>
20231 <dt><a name="index-gnutls_005fia_005fgenerate_005fchallenge"></a>Function: <em>int</em> <strong>gnutls_ia_generate_challenge</strong> <em>(gnutls_session_t <var>session</var>, size_t <var>buffer_size</var>, char * <var>buffer</var>)</em></dt>
20232 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
20233 </p>
20234 <p><var>buffer_size</var>: size of output buffer.
20235 </p>
20236 <p><var>buffer</var>: pre-allocated buffer to contain <code>buffer_size</code> bytes of output.
20237 </p>
20238 <p>Generate an application challenge that the client cannot control or
20239 predict, based on the TLS/IA inner secret.
20240 </p>
20241 <p><strong>Return value:</strong> Returns 0 on success, or an negative error code.
20242 </p></dd></dl>
20243
20244 <a name="gnutls_005fia_005fget_005fclient_005favp_005fptr-1"></a>
20245 <h4 class="subheading">gnutls_ia_get_client_avp_ptr</h4>
20246 <a name="gnutls_005fia_005fget_005fclient_005favp_005fptr"></a><dl>
20247 <dt><a name="index-gnutls_005fia_005fget_005fclient_005favp_005fptr"></a>Function: <em>void *</em> <strong>gnutls_ia_get_client_avp_ptr</strong> <em>(gnutls_ia_client_credentials_t <var>cred</var>)</em></dt>
20248 <dd><p><var>cred</var>: is a <code>gnutls_ia_client_credentials_t</code> structure.
20249 </p>
20250 <p>Returns the pointer that will be provided to the TLS/IA callback
20251 function as the first argument.
20252 </p>
20253 <p><strong>Returns:</strong> The client callback data pointer.
20254 </p></dd></dl>
20255
20256 <a name="gnutls_005fia_005fget_005fserver_005favp_005fptr-1"></a>
20257 <h4 class="subheading">gnutls_ia_get_server_avp_ptr</h4>
20258 <a name="gnutls_005fia_005fget_005fserver_005favp_005fptr"></a><dl>
20259 <dt><a name="index-gnutls_005fia_005fget_005fserver_005favp_005fptr"></a>Function: <em>void *</em> <strong>gnutls_ia_get_server_avp_ptr</strong> <em>(gnutls_ia_server_credentials_t <var>cred</var>)</em></dt>
20260 <dd><p><var>cred</var>: is a <code>gnutls_ia_client_credentials_t</code> structure.
20261 </p>
20262 <p>Returns the pointer that will be provided to the TLS/IA callback
20263 function as the first argument.
20264 </p>
20265 <p><strong>Returns:</strong> The server callback data pointer.
20266 </p></dd></dl>
20267
20268 <a name="gnutls_005fia_005fhandshake_005fp-1"></a>
20269 <h4 class="subheading">gnutls_ia_handshake_p</h4>
20270 <a name="gnutls_005fia_005fhandshake_005fp"></a><dl>
20271 <dt><a name="index-gnutls_005fia_005fhandshake_005fp"></a>Function: <em>int</em> <strong>gnutls_ia_handshake_p</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
20272 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
20273 </p>
20274 <p>Predicate to be used after <code>gnutls_handshake()</code> to decide whether to
20275 invoke <code>gnutls_ia_handshake()</code>.  Usable by both clients and servers.
20276 </p>
20277 <p><strong>Return value:</strong> non-zero if TLS/IA handshake is expected, zero
20278 otherwise.
20279 </p></dd></dl>
20280
20281 <a name="gnutls_005fia_005fhandshake-1"></a>
20282 <h4 class="subheading">gnutls_ia_handshake</h4>
20283 <a name="gnutls_005fia_005fhandshake"></a><dl>
20284 <dt><a name="index-gnutls_005fia_005fhandshake"></a>Function: <em>int</em> <strong>gnutls_ia_handshake</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
20285 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
20286 </p>
20287 <p>Perform a TLS/IA handshake.  This should be called after
20288 <code>gnutls_handshake()</code> iff <code>gnutls_ia_handshake_p()</code>.
20289 </p>
20290 <p><strong>Returns:</strong> On success, <code>GNUTLS_E_SUCCESS</code> (zero) is returned,
20291 otherwise an error code is returned.
20292 </p></dd></dl>
20293 <a name="gnutls_005fia_005fpermute_005finner_005fsecret-1"></a>
20294 <h4 class="subheading">gnutls_ia_permute_inner_secret</h4>
20295 <a name="gnutls_005fia_005fpermute_005finner_005fsecret"></a><dl>
20296 <dt><a name="index-gnutls_005fia_005fpermute_005finner_005fsecret"></a>Function: <em>int</em> <strong>gnutls_ia_permute_inner_secret</strong> <em>(gnutls_session_t <var>session</var>, size_t <var>session_keys_size</var>, const char * <var>session_keys</var>)</em></dt>
20297 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
20298 </p>
20299 <p><var>session_keys_size</var>: Size of generated session keys (0 if none).
20300 </p>
20301 <p><var>session_keys</var>: Generated session keys, used to permute inner secret
20302 (NULL if none).
20303 </p>
20304 <p>Permute the inner secret using the generated session keys.
20305 </p>
20306 <p>This can be called in the TLS/IA AVP callback to mix any generated
20307 session keys with the TLS/IA inner secret.
20308 </p>
20309 <p><strong>Return value:</strong> Return zero on success, or a negative error code.
20310 </p></dd></dl>
20311
20312 <a name="gnutls_005fia_005frecv-1"></a>
20313 <h4 class="subheading">gnutls_ia_recv</h4>
20314 <a name="gnutls_005fia_005frecv"></a><dl>
20315 <dt><a name="index-gnutls_005fia_005frecv"></a>Function: <em>ssize_t</em> <strong>gnutls_ia_recv</strong> <em>(gnutls_session_t <var>session</var>, char * <var>data</var>, size_t <var>sizeofdata</var>)</em></dt>
20316 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
20317 </p>
20318 <p><var>data</var>: the buffer that the data will be read into, must hold &gt;= 12 bytes.
20319 </p>
20320 <p><var>sizeofdata</var>: the number of requested bytes, must be &gt;= 12.
20321 </p>
20322 <p>Receive TLS/IA data.  This function has the similar semantics with
20323 <code>recv()</code>.  The only difference is that it accepts a GnuTLS session,
20324 and uses different error codes.
20325 </p>
20326 <p>If the server attempt to finish an application phase, this function
20327 will return <code>GNUTLS_E_WARNING_IA_IPHF_RECEIVED</code> or
20328 <code>GNUTLS_E_WARNING_IA_FPHF_RECEIVED</code>.  The caller should then invoke
20329 <code>gnutls_ia_verify_endphase()</code>, and if it runs the client side, also
20330 send an endphase message of its own using gnutls_ia_endphase_send.
20331 </p>
20332 <p>If EINTR is returned by the internal push function (the default is
20333 <code>code</code>{<code>recv()</code>}) then GNUTLS_E_INTERRUPTED will be returned.  If
20334 GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN is returned, you must call
20335 this function again, with the same parameters; alternatively you
20336 could provide a NULL pointer for data, and 0 for size.
20337 </p>
20338 <p><strong>Returns:</strong> The number of bytes received.  A negative error code is
20339 returned in case of an error.  The
20340 <code>GNUTLS_E_WARNING_IA_IPHF_RECEIVED</code> and
20341 <code>GNUTLS_E_WARNING_IA_FPHF_RECEIVED</code> errors are returned when an
20342 application phase finished message has been sent by the server.
20343 </p></dd></dl>
20344
20345 <a name="gnutls_005fia_005fsend-1"></a>
20346 <h4 class="subheading">gnutls_ia_send</h4>
20347 <a name="gnutls_005fia_005fsend"></a><dl>
20348 <dt><a name="index-gnutls_005fia_005fsend"></a>Function: <em>ssize_t</em> <strong>gnutls_ia_send</strong> <em>(gnutls_session_t <var>session</var>, const char * <var>data</var>, size_t <var>sizeofdata</var>)</em></dt>
20349 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
20350 </p>
20351 <p><var>data</var>: contains the data to send
20352 </p>
20353 <p><var>sizeofdata</var>: is the length of the data
20354 </p>
20355 <p>Send TLS/IA application payload data.  This function has the
20356 similar semantics with <code>send()</code>.  The only difference is that it
20357 accepts a GnuTLS session, and uses different error codes.
20358 </p>
20359 <p>The TLS/IA protocol is synchronous, so you cannot send more than
20360 one packet at a time.  The client always send the first packet.
20361 </p>
20362 <p>To finish an application phase in the server, use
20363 <code>gnutls_ia_endphase_send()</code>.  The client cannot end an application
20364 phase unilaterally; rather, a client is required to respond with an
20365 endphase of its own if gnutls_ia_recv indicates that the server has
20366 sent one.
20367 </p>
20368 <p>If the EINTR is returned by the internal push function (the default
20369 is <code>send()</code>} then <code>GNUTLS_E_INTERRUPTED</code> will be returned.  If
20370 <code>GNUTLS_E_INTERRUPTED</code> or <code>GNUTLS_E_AGAIN</code> is returned, you must call
20371 this function again, with the same parameters; alternatively you
20372 could provide a <code>NULL</code> pointer for data, and 0 for size.
20373 </p>
20374 <p><strong>Returns:</strong> The number of bytes sent, or a negative error code.
20375 </p></dd></dl>
20376
20377 <a name="gnutls_005fia_005fset_005fclient_005favp_005ffunction-1"></a>
20378 <h4 class="subheading">gnutls_ia_set_client_avp_function</h4>
20379 <a name="gnutls_005fia_005fset_005fclient_005favp_005ffunction"></a><dl>
20380 <dt><a name="index-gnutls_005fia_005fset_005fclient_005favp_005ffunction"></a>Function: <em>void</em> <strong>gnutls_ia_set_client_avp_function</strong> <em>(gnutls_ia_client_credentials_t <var>cred</var>, gnutls_ia_avp_func <var>avp_func</var>)</em></dt>
20381 <dd><p><var>cred</var>: is a <code>gnutls_ia_client_credentials_t</code> structure.
20382 </p>
20383 <p><var>avp_func</var>: is the callback function
20384 </p>
20385 <p>Set the TLS/IA AVP callback handler used for the session.
20386 </p>
20387 <p>The AVP callback is called to process AVPs received from the
20388 server, and to get a new AVP to send to the server.
20389 </p>
20390 <p>The callback&rsquo;s function form is:
20391 int (*avp_func) (gnutls_session_t session, void *ptr,
20392 const char *last, size_t lastlen,
20393 char **next, size_t *nextlen);
20394 </p>
20395 <p>The <code>session</code> parameter is the <code>gnutls_session_t</code> structure
20396 corresponding to the current session.  The <code>ptr</code> parameter is the
20397 application hook pointer, set through
20398 <code>gnutls_ia_set_client_avp_ptr()</code>.  The AVP received from the server
20399 is present in <code>last</code> of <code>lastlen</code> size, which will be <code>NULL</code> on the
20400 first invocation.  The newly allocated output AVP to send to the
20401 server should be placed in *<code>next</code> of *<code>nextlen</code> size.
20402 </p>
20403 <p>The callback may invoke <code>gnutls_ia_permute_inner_secret()</code> to mix any
20404 generated session keys with the TLS/IA inner secret.
20405 </p>
20406 <p>Return 0 (<code>GNUTLS_IA_APPLICATION_PAYLOAD</code>) on success, or a negative
20407 error code to abort the TLS/IA handshake.
20408 </p>
20409 <p>Note that the callback must use allocate the <code>next</code> parameter using
20410 <code>gnutls_malloc()</code>, because it is released via <code>gnutls_free()</code> by the
20411 TLS/IA handshake function.
20412 </p></dd></dl>
20413
20414 <a name="gnutls_005fia_005fset_005fclient_005favp_005fptr-1"></a>
20415 <h4 class="subheading">gnutls_ia_set_client_avp_ptr</h4>
20416 <a name="gnutls_005fia_005fset_005fclient_005favp_005fptr"></a><dl>
20417 <dt><a name="index-gnutls_005fia_005fset_005fclient_005favp_005fptr"></a>Function: <em>void</em> <strong>gnutls_ia_set_client_avp_ptr</strong> <em>(gnutls_ia_client_credentials_t <var>cred</var>, void * <var>ptr</var>)</em></dt>
20418 <dd><p><var>cred</var>: is a <code>gnutls_ia_client_credentials_t</code> structure.
20419 </p>
20420 <p><var>ptr</var>: is the pointer
20421 </p>
20422 <p>Sets the pointer that will be provided to the TLS/IA callback
20423 function as the first argument.
20424 </p></dd></dl>
20425
20426 <a name="gnutls_005fia_005fset_005fserver_005favp_005ffunction-1"></a>
20427 <h4 class="subheading">gnutls_ia_set_server_avp_function</h4>
20428 <a name="gnutls_005fia_005fset_005fserver_005favp_005ffunction"></a><dl>
20429 <dt><a name="index-gnutls_005fia_005fset_005fserver_005favp_005ffunction"></a>Function: <em>void</em> <strong>gnutls_ia_set_server_avp_function</strong> <em>(gnutls_ia_server_credentials_t <var>cred</var>, gnutls_ia_avp_func <var>avp_func</var>)</em></dt>
20430 <dd><p><var>cred</var>: is a <code>gnutls_ia_server_credentials_t</code> structure.
20431 </p>
20432 <p>Set the TLS/IA AVP callback handler used for the session.
20433 </p>
20434 <p>The callback&rsquo;s function form is:
20435 int (*avp_func) (gnutls_session_t session, void *ptr,
20436 const char *last, size_t lastlen,
20437 char **next, size_t *nextlen);
20438 </p>
20439 <p>The <code>session</code> parameter is the <code>gnutls_session_t</code> structure
20440 corresponding to the current session.  The <code>ptr</code> parameter is the
20441 application hook pointer, set through
20442 <code>gnutls_ia_set_server_avp_ptr()</code>.  The AVP received from the client
20443 is present in <code>last</code> of <code>lastlen</code> size.  The newly allocated output
20444 AVP to send to the client should be placed in *<code>next</code> of *<code>nextlen</code>
20445 size.
20446 </p>
20447 <p>The AVP callback is called to process incoming AVPs from the
20448 client, and to get a new AVP to send to the client.  It can also be
20449 used to instruct the TLS/IA handshake to do go into the
20450 Intermediate or Final phases.  It return a negative error code, or
20451 a <code>gnutls_ia_apptype_t</code> message type.
20452 </p>
20453 <p>The callback may invoke <code>gnutls_ia_permute_inner_secret()</code> to mix any
20454 generated session keys with the TLS/IA inner secret.
20455 </p>
20456 <p>Specifically, return <code>GNUTLS_IA_APPLICATION_PAYLOAD</code> (0) to send
20457 another AVP to the client, return
20458 <code>GNUTLS_IA_INTERMEDIATE_PHASE_FINISHED</code> (1) to indicate that an
20459 IntermediatePhaseFinished message should be sent, and return
20460 <code>GNUTLS_IA_FINAL_PHASE_FINISHED</code> (2) to indicate that an
20461 FinalPhaseFinished message should be sent.  In the last two cases,
20462 the contents of the <code>next</code> and <code>nextlen</code> parameter is not used.
20463 </p>
20464 <p>Note that the callback must use allocate the <code>next</code> parameter using
20465 <code>gnutls_malloc()</code>, because it is released via <code>gnutls_free()</code> by the
20466 TLS/IA handshake function.
20467 </p></dd></dl>
20468
20469 <a name="gnutls_005fia_005fset_005fserver_005favp_005fptr-1"></a>
20470 <h4 class="subheading">gnutls_ia_set_server_avp_ptr</h4>
20471 <a name="gnutls_005fia_005fset_005fserver_005favp_005fptr"></a><dl>
20472 <dt><a name="index-gnutls_005fia_005fset_005fserver_005favp_005fptr"></a>Function: <em>void</em> <strong>gnutls_ia_set_server_avp_ptr</strong> <em>(gnutls_ia_server_credentials_t <var>cred</var>, void * <var>ptr</var>)</em></dt>
20473 <dd><p><var>cred</var>: is a <code>gnutls_ia_client_credentials_t</code> structure.
20474 </p>
20475 <p><var>ptr</var>: is the pointer
20476 </p>
20477 <p>Sets the pointer that will be provided to the TLS/IA callback
20478 function as the first argument.
20479 </p></dd></dl>
20480
20481 <a name="gnutls_005fia_005fverify_005fendphase-1"></a>
20482 <h4 class="subheading">gnutls_ia_verify_endphase</h4>
20483 <a name="gnutls_005fia_005fverify_005fendphase"></a><dl>
20484 <dt><a name="index-gnutls_005fia_005fverify_005fendphase"></a>Function: <em>int</em> <strong>gnutls_ia_verify_endphase</strong> <em>(gnutls_session_t <var>session</var>, const char * <var>checksum</var>)</em></dt>
20485 <dd><p><var>session</var>: is a <code>gnutls_session_t</code> structure.
20486 </p>
20487 <p><var>checksum</var>: 12-byte checksum data, received from <code>gnutls_ia_recv()</code>.
20488 </p>
20489 <p>Verify TLS/IA end phase checksum data.  If verification fails, the
20490 <code>GNUTLS_A_INNER_APPLICATION_VERIFICATION</code> alert is sent to the other
20491 sie.
20492 </p>
20493 <p>This function is called when <code>gnutls_ia_recv()</code> return
20494 <code>GNUTLS_E_WARNING_IA_IPHF_RECEIVED</code> or
20495 <code>GNUTLS_E_WARNING_IA_FPHF_RECEIVED</code>.
20496 </p>
20497 <p><strong>Return value:</strong> Return 0 on successful verification, or an error
20498 code.  If the checksum verification of the end phase message fails,
20499 <code>GNUTLS_E_IA_VERIFY_FAILED</code> is returned.
20500 </p></dd></dl>
20501 <hr>
20502 <a name="Error-codes-and-descriptions"></a>
20503 <div class="header">
20504 <p>
20505 Previous: <a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions" accesskey="p" rel="previous">TLS Inner Application (TLS/IA) functions</a>, Up: <a href="#Function-reference" accesskey="u" rel="up">Function 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>
20506 </div>
20507 <a name="Error-Codes-and-Descriptions"></a>
20508 <h3 class="section">9.6 Error Codes and Descriptions</h3>
20509 <a name="Error-Codes"></a><a name="index-Error-codes"></a>
20510
20511 <p>The error codes used throughout the library are described below.  The
20512 return code <code>GNUTLS_E_SUCCESS</code> indicate successful operation, and
20513 is guaranteed to have the value 0, so you can use it in logical
20514 expressions.
20515 </p>
20516 <dl compact="compact">
20517 <dt><code>GNUTLS_E_AGAIN:</code></dt>
20518 <dd><p>Resource temporarily unavailable, try again.
20519 </p>
20520 </dd>
20521 <dt><code>GNUTLS_E_ASN1_DER_ERROR:</code></dt>
20522 <dd><p>ASN1 parser: Error in DER parsing.
20523 </p>
20524 </dd>
20525 <dt><code>GNUTLS_E_ASN1_DER_OVERFLOW:</code></dt>
20526 <dd><p>ASN1 parser: Overflow in DER parsing.
20527 </p>
20528 </dd>
20529 <dt><code>GNUTLS_E_ASN1_ELEMENT_NOT_FOUND:</code></dt>
20530 <dd><p>ASN1 parser: Element was not found.
20531 </p>
20532 </dd>
20533 <dt><code>GNUTLS_E_ASN1_GENERIC_ERROR:</code></dt>
20534 <dd><p>ASN1 parser: Generic parsing error.
20535 </p>
20536 </dd>
20537 <dt><code>GNUTLS_E_ASN1_IDENTIFIER_NOT_FOUND:</code></dt>
20538 <dd><p>ASN1 parser: Identifier was not found
20539 </p>
20540 </dd>
20541 <dt><code>GNUTLS_E_ASN1_SYNTAX_ERROR:</code></dt>
20542 <dd><p>ASN1 parser: Syntax error.
20543 </p>
20544 </dd>
20545 <dt><code>GNUTLS_E_ASN1_TAG_ERROR:</code></dt>
20546 <dd><p>ASN1 parser: Error in TAG.
20547 </p>
20548 </dd>
20549 <dt><code>GNUTLS_E_ASN1_TAG_IMPLICIT:</code></dt>
20550 <dd><p>ASN1 parser: error in implicit tag
20551 </p>
20552 </dd>
20553 <dt><code>GNUTLS_E_ASN1_TYPE_ANY_ERROR:</code></dt>
20554 <dd><p>ASN1 parser: Error in type &rsquo;ANY&rsquo;.
20555 </p>
20556 </dd>
20557 <dt><code>GNUTLS_E_ASN1_VALUE_NOT_FOUND:</code></dt>
20558 <dd><p>ASN1 parser: Value was not found.
20559 </p>
20560 </dd>
20561 <dt><code>GNUTLS_E_ASN1_VALUE_NOT_VALID:</code></dt>
20562 <dd><p>ASN1 parser: Value is not valid.
20563 </p>
20564 </dd>
20565 <dt><code>GNUTLS_E_BASE64_DECODING_ERROR:</code></dt>
20566 <dd><p>Base64 decoding error.
20567 </p>
20568 </dd>
20569 <dt><code>GNUTLS_E_BASE64_ENCODING_ERROR:</code></dt>
20570 <dd><p>Base64 encoding error.
20571 </p>
20572 </dd>
20573 <dt><code>GNUTLS_E_BASE64_UNEXPECTED_HEADER_ERROR:</code></dt>
20574 <dd><p>Base64 unexpected header error.
20575 </p>
20576 </dd>
20577 <dt><code>GNUTLS_E_CERTIFICATE_ERROR:</code></dt>
20578 <dd><p>Error in the certificate.
20579 </p>
20580 </dd>
20581 <dt><code>GNUTLS_E_CERTIFICATE_KEY_MISMATCH:</code></dt>
20582 <dd><p>The certificate and the given key do not match.
20583 </p>
20584 </dd>
20585 <dt><code>GNUTLS_E_CERTIFICATE_LIST_UNSORTED:</code></dt>
20586 <dd><p>The provided X.509 certificate list is not sorted (in subject to issuer order)
20587 </p>
20588 </dd>
20589 <dt><code>GNUTLS_E_CHANNEL_BINDING_NOT_AVAILABLE:</code></dt>
20590 <dd><p>Channel binding data not available
20591 </p>
20592 </dd>
20593 <dt><code>GNUTLS_E_COMPRESSION_FAILED:</code></dt>
20594 <dd><p>Compression of the TLS record packet has failed.
20595 </p>
20596 </dd>
20597 <dt><code>GNUTLS_E_CONSTRAINT_ERROR:</code></dt>
20598 <dd><p>Some constraint limits were reached.
20599 </p>
20600 </dd>
20601 <dt><code>GNUTLS_E_CRYPTODEV_DEVICE_ERROR:</code></dt>
20602 <dd><p>Error opening /dev/crypto
20603 </p>
20604 </dd>
20605 <dt><code>GNUTLS_E_CRYPTODEV_IOCTL_ERROR:</code></dt>
20606 <dd><p>Error interfacing with /dev/crypto
20607 </p>
20608 </dd>
20609 <dt><code>GNUTLS_E_CRYPTO_ALREADY_REGISTERED:</code></dt>
20610 <dd><p>There is already a crypto algorithm with lower priority.
20611 </p>
20612 </dd>
20613 <dt><code>GNUTLS_E_CRYPTO_INIT_FAILED:</code></dt>
20614 <dd><p>The initialization of crypto backend has failed.
20615 </p>
20616 </dd>
20617 <dt><code>GNUTLS_E_DB_ERROR:</code></dt>
20618 <dd><p>Error in Database backend.
20619 </p>
20620 </dd>
20621 <dt><code>GNUTLS_E_DECOMPRESSION_FAILED:</code></dt>
20622 <dd><p>Decompression of the TLS record packet has failed.
20623 </p>
20624 </dd>
20625 <dt><code>GNUTLS_E_DECRYPTION_FAILED:</code></dt>
20626 <dd><p>Decryption has failed.
20627 </p>
20628 </dd>
20629 <dt><code>GNUTLS_E_DH_PRIME_UNACCEPTABLE:</code></dt>
20630 <dd><p>The Diffie-Hellman prime sent by the server is not acceptable (not long enough).
20631 </p>
20632 </dd>
20633 <dt><code>GNUTLS_E_ENCRYPTION_FAILED:</code></dt>
20634 <dd><p>Encryption has failed.
20635 </p>
20636 </dd>
20637 <dt><code>GNUTLS_E_ERROR_IN_FINISHED_PACKET:</code></dt>
20638 <dd><p>An error was encountered at the TLS Finished packet calculation.
20639 </p>
20640 </dd>
20641 <dt><code>GNUTLS_E_EXPIRED:</code></dt>
20642 <dd><p>The requested session has expired.
20643 </p>
20644 </dd>
20645 <dt><code>GNUTLS_E_FATAL_ALERT_RECEIVED:</code></dt>
20646 <dd><p>A TLS fatal alert has been received.
20647 </p>
20648 </dd>
20649 <dt><code>GNUTLS_E_FILE_ERROR:</code></dt>
20650 <dd><p>Error while reading file.
20651 </p>
20652 </dd>
20653 <dt><code>GNUTLS_E_GOT_APPLICATION_DATA:</code></dt>
20654 <dd><p>TLS Application data were received, while expecting handshake data.
20655 </p>
20656 </dd>
20657 <dt><code>GNUTLS_E_HANDSHAKE_TOO_LARGE:</code></dt>
20658 <dd><p>The handshake data size is too large (DoS?), check gnutls_handshake_set_max_packet_length().
20659 </p>
20660 </dd>
20661 <dt><code>GNUTLS_E_HASH_FAILED:</code></dt>
20662 <dd><p>Hashing has failed.
20663 </p>
20664 </dd>
20665 <dt><code>GNUTLS_E_IA_VERIFY_FAILED:</code></dt>
20666 <dd><p>Verifying TLS/IA phase checksum failed
20667 </p>
20668 </dd>
20669 <dt><code>GNUTLS_E_ILLEGAL_SRP_USERNAME:</code></dt>
20670 <dd><p>The SRP username supplied is illegal.
20671 </p>
20672 </dd>
20673 <dt><code>GNUTLS_E_INCOMPATIBLE_GCRYPT_LIBRARY:</code></dt>
20674 <dd><p>The gcrypt library version is too old.
20675 </p>
20676 </dd>
20677 <dt><code>GNUTLS_E_INCOMPATIBLE_LIBTASN1_LIBRARY:</code></dt>
20678 <dd><p>The tasn1 library version is too old.
20679 </p>
20680 </dd>
20681 <dt><code>GNUTLS_E_INCOMPAT_DSA_KEY_WITH_TLS_PROTOCOL:</code></dt>
20682 <dd><p>The given DSA key is incompatible with the selected TLS protocol.
20683 </p>
20684 </dd>
20685 <dt><code>GNUTLS_E_INIT_LIBEXTRA:</code></dt>
20686 <dd><p>The initialization of GnuTLS-extra has failed.
20687 </p>
20688 </dd>
20689 <dt><code>GNUTLS_E_INSUFFICIENT_CREDENTIALS:</code></dt>
20690 <dd><p>Insufficient credentials for that request.
20691 </p>
20692 </dd>
20693 <dt><code>GNUTLS_E_INTERNAL_ERROR:</code></dt>
20694 <dd><p>GnuTLS internal error.
20695 </p>
20696 </dd>
20697 <dt><code>GNUTLS_E_INTERRUPTED:</code></dt>
20698 <dd><p>Function was interrupted.
20699 </p>
20700 </dd>
20701 <dt><code>GNUTLS_E_INVALID_PASSWORD:</code></dt>
20702 <dd><p>The given password contains invalid characters.
20703 </p>
20704 </dd>
20705 <dt><code>GNUTLS_E_INVALID_REQUEST:</code></dt>
20706 <dd><p>The request is invalid.
20707 </p>
20708 </dd>
20709 <dt><code>GNUTLS_E_INVALID_SESSION:</code></dt>
20710 <dd><p>The specified session has been invalidated for some reason.
20711 </p>
20712 </dd>
20713 <dt><code>GNUTLS_E_KEY_USAGE_VIOLATION:</code></dt>
20714 <dd><p>Key usage violation in certificate has been detected.
20715 </p>
20716 </dd>
20717 <dt><code>GNUTLS_E_LARGE_PACKET:</code></dt>
20718 <dd><p>A large TLS record packet was received.
20719 </p>
20720 </dd>
20721 <dt><code>GNUTLS_E_LIBRARY_VERSION_MISMATCH:</code></dt>
20722 <dd><p>The GnuTLS library version does not match the GnuTLS-extra library version.
20723 </p>
20724 </dd>
20725 <dt><code>GNUTLS_E_LOCKING_ERROR:</code></dt>
20726 <dd><p>Thread locking error
20727 </p>
20728 </dd>
20729 <dt><code>GNUTLS_E_LZO_INIT_FAILED:</code></dt>
20730 <dd><p>The initialization of LZO has failed.
20731 </p>
20732 </dd>
20733 <dt><code>GNUTLS_E_MAC_VERIFY_FAILED:</code></dt>
20734 <dd><p>The Message Authentication Code verification failed.
20735 </p>
20736 </dd>
20737 <dt><code>GNUTLS_E_MEMORY_ERROR:</code></dt>
20738 <dd><p>Internal error in memory allocation.
20739 </p>
20740 </dd>
20741 <dt><code>GNUTLS_E_MPI_PRINT_FAILED:</code></dt>
20742 <dd><p>Could not export a large integer.
20743 </p>
20744 </dd>
20745 <dt><code>GNUTLS_E_MPI_SCAN_FAILED:</code></dt>
20746 <dd><p>The scanning of a large integer has failed.
20747 </p>
20748 </dd>
20749 <dt><code>GNUTLS_E_NO_CERTIFICATE_FOUND:</code></dt>
20750 <dd><p>The peer did not send any certificate.
20751 </p>
20752 </dd>
20753 <dt><code>GNUTLS_E_NO_CIPHER_SUITES:</code></dt>
20754 <dd><p>No supported cipher suites have been found.
20755 </p>
20756 </dd>
20757 <dt><code>GNUTLS_E_NO_COMPRESSION_ALGORITHMS:</code></dt>
20758 <dd><p>No supported compression algorithms have been found.
20759 </p>
20760 </dd>
20761 <dt><code>GNUTLS_E_NO_TEMPORARY_DH_PARAMS:</code></dt>
20762 <dd><p>No temporary DH parameters were found.
20763 </p>
20764 </dd>
20765 <dt><code>GNUTLS_E_NO_TEMPORARY_RSA_PARAMS:</code></dt>
20766 <dd><p>No temporary RSA parameters were found.
20767 </p>
20768 </dd>
20769 <dt><code>GNUTLS_E_OPENPGP_FINGERPRINT_UNSUPPORTED:</code></dt>
20770 <dd><p>The OpenPGP fingerprint is not supported.
20771 </p>
20772 </dd>
20773 <dt><code>GNUTLS_E_OPENPGP_GETKEY_FAILED:</code></dt>
20774 <dd><p>Could not get OpenPGP key.
20775 </p>
20776 </dd>
20777 <dt><code>GNUTLS_E_OPENPGP_KEYRING_ERROR:</code></dt>
20778 <dd><p>Error loading the keyring.
20779 </p>
20780 </dd>
20781 <dt><code>GNUTLS_E_OPENPGP_PREFERRED_KEY_ERROR:</code></dt>
20782 <dd><p>The OpenPGP key has not a preferred key set.
20783 </p>
20784 </dd>
20785 <dt><code>GNUTLS_E_OPENPGP_SUBKEY_ERROR:</code></dt>
20786 <dd><p>Could not find OpenPGP subkey.
20787 </p>
20788 </dd>
20789 <dt><code>GNUTLS_E_OPENPGP_UID_REVOKED:</code></dt>
20790 <dd><p>The OpenPGP User ID is revoked.
20791 </p>
20792 </dd>
20793 <dt><code>GNUTLS_E_PARSING_ERROR:</code></dt>
20794 <dd><p>Error in parsing.
20795 </p>
20796 </dd>
20797 <dt><code>GNUTLS_E_PKCS11_ATTRIBUTE_ERROR:</code></dt>
20798 <dd><p>PKCS #11 error in attribute
20799 </p>
20800 </dd>
20801 <dt><code>GNUTLS_E_PKCS11_DATA_ERROR:</code></dt>
20802 <dd><p>PKCS #11 error in data
20803 </p>
20804 </dd>
20805 <dt><code>GNUTLS_E_PKCS11_DEVICE_ERROR:</code></dt>
20806 <dd><p>PKCS #11 error in device
20807 </p>
20808 </dd>
20809 <dt><code>GNUTLS_E_PKCS11_ERROR:</code></dt>
20810 <dd><p>PKCS #11 error.
20811 </p>
20812 </dd>
20813 <dt><code>GNUTLS_E_PKCS11_KEY_ERROR:</code></dt>
20814 <dd><p>PKCS #11 error in key
20815 </p>
20816 </dd>
20817 <dt><code>GNUTLS_E_PKCS11_LOAD_ERROR:</code></dt>
20818 <dd><p>PKCS #11 initialization error.
20819 </p>
20820 </dd>
20821 <dt><code>GNUTLS_E_PKCS11_PIN_ERROR:</code></dt>
20822 <dd><p>PKCS #11 error in PIN.
20823 </p>
20824 </dd>
20825 <dt><code>GNUTLS_E_PKCS11_PIN_EXPIRED:</code></dt>
20826 <dd><p>PKCS #11 PIN expired
20827 </p>
20828 </dd>
20829 <dt><code>GNUTLS_E_PKCS11_PIN_LOCKED:</code></dt>
20830 <dd><p>PKCS #11 PIN locked
20831 </p>
20832 </dd>
20833 <dt><code>GNUTLS_E_PKCS11_SESSION_ERROR:</code></dt>
20834 <dd><p>PKCS #11 error in session
20835 </p>
20836 </dd>
20837 <dt><code>GNUTLS_E_PKCS11_SIGNATURE_ERROR:</code></dt>
20838 <dd><p>PKCS #11 error in signature
20839 </p>
20840 </dd>
20841 <dt><code>GNUTLS_E_PKCS11_SLOT_ERROR:</code></dt>
20842 <dd><p>PKCS #11 error in slot
20843 </p>
20844 </dd>
20845 <dt><code>GNUTLS_E_PKCS11_TOKEN_ERROR:</code></dt>
20846 <dd><p>PKCS #11 error in token
20847 </p>
20848 </dd>
20849 <dt><code>GNUTLS_E_PKCS11_UNSUPPORTED_FEATURE_ERROR:</code></dt>
20850 <dd><p>PKCS #11 unsupported feature
20851 </p>
20852 </dd>
20853 <dt><code>GNUTLS_E_PKCS11_USER_ERROR:</code></dt>
20854 <dd><p>PKCS #11 user error
20855 </p>
20856 </dd>
20857 <dt><code>GNUTLS_E_PKCS1_WRONG_PAD:</code></dt>
20858 <dd><p>Wrong padding in PKCS1 packet.
20859 </p>
20860 </dd>
20861 <dt><code>GNUTLS_E_PK_DECRYPTION_FAILED:</code></dt>
20862 <dd><p>Public key decryption has failed.
20863 </p>
20864 </dd>
20865 <dt><code>GNUTLS_E_PK_ENCRYPTION_FAILED:</code></dt>
20866 <dd><p>Public key encryption has failed.
20867 </p>
20868 </dd>
20869 <dt><code>GNUTLS_E_PK_SIGN_FAILED:</code></dt>
20870 <dd><p>Public key signing has failed.
20871 </p>
20872 </dd>
20873 <dt><code>GNUTLS_E_PK_SIG_VERIFY_FAILED:</code></dt>
20874 <dd><p>Public key signature verification has failed.
20875 </p>
20876 </dd>
20877 <dt><code>GNUTLS_E_PULL_ERROR:</code></dt>
20878 <dd><p>Error in the pull function.
20879 </p>
20880 </dd>
20881 <dt><code>GNUTLS_E_PUSH_ERROR:</code></dt>
20882 <dd><p>Error in the push function.
20883 </p>
20884 </dd>
20885 <dt><code>GNUTLS_E_RANDOM_FAILED:</code></dt>
20886 <dd><p>Failed to acquire random data.
20887 </p>
20888 </dd>
20889 <dt><code>GNUTLS_E_RECEIVED_ILLEGAL_EXTENSION:</code></dt>
20890 <dd><p>An illegal TLS extension was received.
20891 </p>
20892 </dd>
20893 <dt><code>GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER:</code></dt>
20894 <dd><p>An illegal parameter has been received.
20895 </p>
20896 </dd>
20897 <dt><code>GNUTLS_E_RECORD_LIMIT_REACHED:</code></dt>
20898 <dd><p>The upper limit of record packet sequence numbers has been reached. Wow!
20899 </p>
20900 </dd>
20901 <dt><code>GNUTLS_E_REHANDSHAKE:</code></dt>
20902 <dd><p>Rehandshake was requested by the peer.
20903 </p>
20904 </dd>
20905 <dt><code>GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE:</code></dt>
20906 <dd><p>The requested data were not available.
20907 </p>
20908 </dd>
20909 <dt><code>GNUTLS_E_SAFE_RENEGOTIATION_FAILED:</code></dt>
20910 <dd><p>Safe renegotiation failed.
20911 </p>
20912 </dd>
20913 <dt><code>GNUTLS_E_SHORT_MEMORY_BUFFER:</code></dt>
20914 <dd><p>The given memory buffer is too short to hold parameters.
20915 </p>
20916 </dd>
20917 <dt><code>GNUTLS_E_SRP_PWD_ERROR:</code></dt>
20918 <dd><p>Error in password file.
20919 </p>
20920 </dd>
20921 <dt><code>GNUTLS_E_SRP_PWD_PARSING_ERROR:</code></dt>
20922 <dd><p>Parsing error in password file.
20923 </p>
20924 </dd>
20925 <dt><code>GNUTLS_E_SUCCESS:</code></dt>
20926 <dd><p>Success.
20927 </p>
20928 </dd>
20929 <dt><code>GNUTLS_E_TOO_MANY_EMPTY_PACKETS:</code></dt>
20930 <dd><p>Too many empty record packets have been received.
20931 </p>
20932 </dd>
20933 <dt><code>GNUTLS_E_UNEXPECTED_HANDSHAKE_PACKET:</code></dt>
20934 <dd><p>An unexpected TLS handshake packet was received.
20935 </p>
20936 </dd>
20937 <dt><code>GNUTLS_E_UNEXPECTED_PACKET:</code></dt>
20938 <dd><p>An unexpected TLS packet was received.
20939 </p>
20940 </dd>
20941 <dt><code>GNUTLS_E_UNEXPECTED_PACKET_LENGTH:</code></dt>
20942 <dd><p>A TLS packet with unexpected length was received.
20943 </p>
20944 </dd>
20945 <dt><code>GNUTLS_E_UNKNOWN_ALGORITHM:</code></dt>
20946 <dd><p>The specified algorithm or protocol is unknown.
20947 </p>
20948 </dd>
20949 <dt><code>GNUTLS_E_UNKNOWN_CIPHER_SUITE:</code></dt>
20950 <dd><p>Could not negotiate a supported cipher suite.
20951 </p>
20952 </dd>
20953 <dt><code>GNUTLS_E_UNKNOWN_CIPHER_TYPE:</code></dt>
20954 <dd><p>The cipher type is unsupported.
20955 </p>
20956 </dd>
20957 <dt><code>GNUTLS_E_UNKNOWN_COMPRESSION_ALGORITHM:</code></dt>
20958 <dd><p>Could not negotiate a supported compression method.
20959 </p>
20960 </dd>
20961 <dt><code>GNUTLS_E_UNKNOWN_HASH_ALGORITHM:</code></dt>
20962 <dd><p>The hash algorithm is unknown.
20963 </p>
20964 </dd>
20965 <dt><code>GNUTLS_E_UNKNOWN_PKCS_BAG_TYPE:</code></dt>
20966 <dd><p>The PKCS structure&rsquo;s bag type is unknown.
20967 </p>
20968 </dd>
20969 <dt><code>GNUTLS_E_UNKNOWN_PKCS_CONTENT_TYPE:</code></dt>
20970 <dd><p>The PKCS structure&rsquo;s content type is unknown.
20971 </p>
20972 </dd>
20973 <dt><code>GNUTLS_E_UNKNOWN_PK_ALGORITHM:</code></dt>
20974 <dd><p>An unknown public key algorithm was encountered.
20975 </p>
20976 </dd>
20977 <dt><code>GNUTLS_E_UNKNOWN_SRP_USERNAME:</code></dt>
20978 <dd><p>The SRP username supplied is unknown.
20979 </p>
20980 </dd>
20981 <dt><code>GNUTLS_E_UNSAFE_RENEGOTIATION_DENIED:</code></dt>
20982 <dd><p>Unsafe renegotiation denied.
20983 </p>
20984 </dd>
20985 <dt><code>GNUTLS_E_UNSUPPORTED_CERTIFICATE_TYPE:</code></dt>
20986 <dd><p>The certificate type is not supported.
20987 </p>
20988 </dd>
20989 <dt><code>GNUTLS_E_UNSUPPORTED_SIGNATURE_ALGORITHM:</code></dt>
20990 <dd><p>The signature algorithm is not supported.
20991 </p>
20992 </dd>
20993 <dt><code>GNUTLS_E_UNSUPPORTED_VERSION_PACKET:</code></dt>
20994 <dd><p>A record packet with illegal version was received.
20995 </p>
20996 </dd>
20997 <dt><code>GNUTLS_E_UNWANTED_ALGORITHM:</code></dt>
20998 <dd><p>An algorithm that is not enabled was negotiated.
20999 </p>
21000 </dd>
21001 <dt><code>GNUTLS_E_WARNING_ALERT_RECEIVED:</code></dt>
21002 <dd><p>A TLS warning alert has been received.
21003 </p>
21004 </dd>
21005 <dt><code>GNUTLS_E_WARNING_IA_FPHF_RECEIVED:</code></dt>
21006 <dd><p>Received a TLS/IA Final Phase Finished message
21007 </p>
21008 </dd>
21009 <dt><code>GNUTLS_E_WARNING_IA_IPHF_RECEIVED:</code></dt>
21010 <dd><p>Received a TLS/IA Intermediate Phase Finished message
21011 </p>
21012 </dd>
21013 <dt><code>GNUTLS_E_X509_UNKNOWN_SAN:</code></dt>
21014 <dd><p>Unknown Subject Alternative name in X.509 certificate.
21015 </p>
21016 </dd>
21017 <dt><code>GNUTLS_E_X509_UNSUPPORTED_ATTRIBUTE:</code></dt>
21018 <dd><p>The certificate has unsupported attributes.
21019 </p>
21020 </dd>
21021 <dt><code>GNUTLS_E_X509_UNSUPPORTED_CRITICAL_EXTENSION:</code></dt>
21022 <dd><p>Unsupported critical extension in X.509 certificate.
21023 </p>
21024 </dd>
21025 <dt><code>GNUTLS_E_X509_UNSUPPORTED_OID:</code></dt>
21026 <dd><p>The OID is not supported.
21027 </p>
21028 </dd>
21029 </dl>
21030
21031 <hr>
21032 <a name="All-the-supported-ciphersuites-in-GnuTLS"></a>
21033 <div class="header">
21034 <p>
21035 Next: <a href="#Guile-Bindings" accesskey="n" rel="next">Guile Bindings</a>, Previous: <a href="#Function-reference" accesskey="p" rel="previous">Function 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>
21036 </div>
21037 <a name="All-the-Supported-Ciphersuites-in-GnuTLS"></a>
21038 <h2 class="chapter">10 All the Supported Ciphersuites in <acronym>GnuTLS</acronym></h2>
21039 <a name="ciphersuites"></a><a name="index-Ciphersuites"></a>
21040
21041 <p>Available cipher suites:
21042 </p><table>
21043 <tr><td width="60%">TLS_ANON_DH_ARCFOUR_MD5</td><td width="20%">0x00 0x18</td><td width="20%">SSL3.0</td></tr>
21044 <tr><td width="60%">TLS_ANON_DH_3DES_EDE_CBC_SHA1</td><td width="20%">0x00 0x1b</td><td width="20%">SSL3.0</td></tr>
21045 <tr><td width="60%">TLS_ANON_DH_AES_128_CBC_SHA1</td><td width="20%">0x00 0x34</td><td width="20%">SSL3.0</td></tr>
21046 <tr><td width="60%">TLS_ANON_DH_AES_256_CBC_SHA1</td><td width="20%">0x00 0x3a</td><td width="20%">SSL3.0</td></tr>
21047 <tr><td width="60%">TLS_ANON_DH_CAMELLIA_128_CBC_SHA1</td><td width="20%">0x00 0x46</td><td width="20%">TLS1.0</td></tr>
21048 <tr><td width="60%">TLS_ANON_DH_CAMELLIA_256_CBC_SHA1</td><td width="20%">0x00 0x89</td><td width="20%">TLS1.0</td></tr>
21049 <tr><td width="60%">TLS_ANON_DH_AES_128_CBC_SHA256</td><td width="20%">0x00 0x6c</td><td width="20%">TLS1.2</td></tr>
21050 <tr><td width="60%">TLS_ANON_DH_AES_256_CBC_SHA256</td><td width="20%">0x00 0x6d</td><td width="20%">TLS1.2</td></tr>
21051 <tr><td width="60%">TLS_PSK_SHA_ARCFOUR_SHA1</td><td width="20%">0x00 0x8a</td><td width="20%">TLS1.0</td></tr>
21052 <tr><td width="60%">TLS_PSK_SHA_3DES_EDE_CBC_SHA1</td><td width="20%">0x00 0x8b</td><td width="20%">TLS1.0</td></tr>
21053 <tr><td width="60%">TLS_PSK_SHA_AES_128_CBC_SHA1</td><td width="20%">0x00 0x8c</td><td width="20%">TLS1.0</td></tr>
21054 <tr><td width="60%">TLS_PSK_SHA_AES_256_CBC_SHA1</td><td width="20%">0x00 0x8d</td><td width="20%">TLS1.0</td></tr>
21055 <tr><td width="60%">TLS_DHE_PSK_SHA_ARCFOUR_SHA1</td><td width="20%">0x00 0x8e</td><td width="20%">TLS1.0</td></tr>
21056 <tr><td width="60%">TLS_DHE_PSK_SHA_3DES_EDE_CBC_SHA1</td><td width="20%">0x00 0x8f</td><td width="20%">TLS1.0</td></tr>
21057 <tr><td width="60%">TLS_DHE_PSK_SHA_AES_128_CBC_SHA1</td><td width="20%">0x00 0x90</td><td width="20%">TLS1.0</td></tr>
21058 <tr><td width="60%">TLS_DHE_PSK_SHA_AES_256_CBC_SHA1</td><td width="20%">0x00 0x91</td><td width="20%">TLS1.0</td></tr>
21059 <tr><td width="60%">TLS_SRP_SHA_3DES_EDE_CBC_SHA1</td><td width="20%">0xc0 0x1a</td><td width="20%">TLS1.0</td></tr>
21060 <tr><td width="60%">TLS_SRP_SHA_AES_128_CBC_SHA1</td><td width="20%">0xc0 0x1d</td><td width="20%">TLS1.0</td></tr>
21061 <tr><td width="60%">TLS_SRP_SHA_AES_256_CBC_SHA1</td><td width="20%">0xc0 0x20</td><td width="20%">TLS1.0</td></tr>
21062 <tr><td width="60%">TLS_SRP_SHA_DSS_3DES_EDE_CBC_SHA1</td><td width="20%">0xc0 0x1c</td><td width="20%">TLS1.0</td></tr>
21063 <tr><td width="60%">TLS_SRP_SHA_RSA_3DES_EDE_CBC_SHA1</td><td width="20%">0xc0 0x1b</td><td width="20%">TLS1.0</td></tr>
21064 <tr><td width="60%">TLS_SRP_SHA_DSS_AES_128_CBC_SHA1</td><td width="20%">0xc0 0x1f</td><td width="20%">TLS1.0</td></tr>
21065 <tr><td width="60%">TLS_SRP_SHA_RSA_AES_128_CBC_SHA1</td><td width="20%">0xc0 0x1e</td><td width="20%">TLS1.0</td></tr>
21066 <tr><td width="60%">TLS_SRP_SHA_DSS_AES_256_CBC_SHA1</td><td width="20%">0xc0 0x22</td><td width="20%">TLS1.0</td></tr>
21067 <tr><td width="60%">TLS_SRP_SHA_RSA_AES_256_CBC_SHA1</td><td width="20%">0xc0 0x21</td><td width="20%">TLS1.0</td></tr>
21068 <tr><td width="60%">TLS_DHE_DSS_ARCFOUR_SHA1</td><td width="20%">0x00 0x66</td><td width="20%">TLS1.0</td></tr>
21069 <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>
21070 <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>
21071 <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>
21072 <tr><td width="60%">TLS_DHE_DSS_CAMELLIA_128_CBC_SHA1</td><td width="20%">0x00 0x44</td><td width="20%">TLS1.0</td></tr>
21073 <tr><td width="60%">TLS_DHE_DSS_CAMELLIA_256_CBC_SHA1</td><td width="20%">0x00 0x87</td><td width="20%">TLS1.0</td></tr>
21074 <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>
21075 <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>
21076 <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>
21077 <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>
21078 <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>
21079 <tr><td width="60%">TLS_DHE_RSA_CAMELLIA_128_CBC_SHA1</td><td width="20%">0x00 0x45</td><td width="20%">TLS1.0</td></tr>
21080 <tr><td width="60%">TLS_DHE_RSA_CAMELLIA_256_CBC_SHA1</td><td width="20%">0x00 0x88</td><td width="20%">TLS1.0</td></tr>
21081 <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>
21082 <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>
21083 <tr><td width="60%">TLS_RSA_NULL_MD5</td><td width="20%">0x00 0x01</td><td width="20%">SSL3.0</td></tr>
21084 <tr><td width="60%">TLS_RSA_NULL_SHA1</td><td width="20%">0x00 0x02</td><td width="20%">SSL3.0</td></tr>
21085 <tr><td width="60%">TLS_RSA_NULL_SHA256</td><td width="20%">0x00 0x3b</td><td width="20%">TLS1.2</td></tr>
21086 <tr><td width="60%">TLS_RSA_EXPORT_ARCFOUR_40_MD5</td><td width="20%">0x00 0x03</td><td width="20%">SSL3.0</td></tr>
21087 <tr><td width="60%">TLS_RSA_ARCFOUR_SHA1</td><td width="20%">0x00 0x05</td><td width="20%">SSL3.0</td></tr>
21088 <tr><td width="60%">TLS_RSA_ARCFOUR_MD5</td><td width="20%">0x00 0x04</td><td width="20%">SSL3.0</td></tr>
21089 <tr><td width="60%">TLS_RSA_3DES_EDE_CBC_SHA1</td><td width="20%">0x00 0x0a</td><td width="20%">SSL3.0</td></tr>
21090 <tr><td width="60%">TLS_RSA_AES_128_CBC_SHA1</td><td width="20%">0x00 0x2f</td><td width="20%">SSL3.0</td></tr>
21091 <tr><td width="60%">TLS_RSA_AES_256_CBC_SHA1</td><td width="20%">0x00 0x35</td><td width="20%">SSL3.0</td></tr>
21092 <tr><td width="60%">TLS_RSA_CAMELLIA_128_CBC_SHA1</td><td width="20%">0x00 0x41</td><td width="20%">TLS1.0</td></tr>
21093 <tr><td width="60%">TLS_RSA_CAMELLIA_256_CBC_SHA1</td><td width="20%">0x00 0x84</td><td width="20%">TLS1.0</td></tr>
21094 <tr><td width="60%">TLS_RSA_AES_128_CBC_SHA256</td><td width="20%">0x00 0x3c</td><td width="20%">TLS1.2</td></tr>
21095 <tr><td width="60%">TLS_RSA_AES_256_CBC_SHA256</td><td width="20%">0x00 0x3d</td><td width="20%">TLS1.2</td></tr>
21096 </table>
21097
21098
21099 <p>Available certificate types:
21100 </p><ul>
21101 <li> X.509
21102 </li><li> OPENPGP
21103 </li></ul>
21104
21105 <p>Available protocols:
21106 </p><ul>
21107 <li> SSL3.0
21108 </li><li> TLS1.0
21109 </li><li> TLS1.1
21110 </li><li> TLS1.2
21111 </li></ul>
21112
21113 <p>Available ciphers:
21114 </p><ul>
21115 <li> AES-256-CBC
21116 </li><li> AES-128-CBC
21117 </li><li> 3DES-CBC
21118 </li><li> DES-CBC
21119 </li><li> ARCFOUR-128
21120 </li><li> ARCFOUR-40
21121 </li><li> RC2-40
21122 </li><li> CAMELLIA-256-CBC
21123 </li><li> CAMELLIA-128-CBC
21124 </li><li> NULL
21125 </li></ul>
21126
21127 <p>Available MAC algorithms:
21128 </p><ul>
21129 <li> SHA1
21130 </li><li> MD5
21131 </li><li> SHA256
21132 </li><li> SHA384
21133 </li><li> SHA512
21134 </li><li> MD2
21135 </li><li> RIPEMD160
21136 </li><li> MAC-NULL
21137 </li></ul>
21138
21139 <p>Available key exchange methods:
21140 </p><ul>
21141 <li> ANON-DH
21142 </li><li> RSA
21143 </li><li> RSA-EXPORT
21144 </li><li> DHE-RSA
21145 </li><li> DHE-DSS
21146 </li><li> SRP-DSS
21147 </li><li> SRP-RSA
21148 </li><li> SRP
21149 </li><li> PSK
21150 </li><li> DHE-PSK
21151 </li></ul>
21152
21153 <p>Available public key algorithms:
21154 </p><ul>
21155 <li> RSA
21156 </li><li> DSA
21157 </li></ul>
21158
21159 <p>Available public key signature algorithms:
21160 </p><ul>
21161 <li> RSA-SHA1
21162 </li><li> RSA-SHA224
21163 </li><li> RSA-SHA256
21164 </li><li> RSA-SHA384
21165 </li><li> RSA-SHA512
21166 </li><li> RSA-RMD160
21167 </li><li> DSA-SHA1
21168 </li><li> DSA-SHA224
21169 </li><li> DSA-SHA256
21170 </li><li> RSA-MD5
21171 </li><li> RSA-MD2
21172 </li></ul>
21173
21174 <p>Available compression methods:
21175 </p><ul>
21176 <li> DEFLATE
21177 </li><li> NULL
21178 </li></ul>
21179
21180 <p>Some additional information regarding some of the algorithms:
21181 </p>
21182 <dl compact="compact">
21183 <dt><code>RSA</code></dt>
21184 <dd><p>RSA is public key cryptosystem designed by Ronald Rivest, Adi Shamir
21185 and Leonard Adleman.  It can be used with any hash functions.
21186 </p>
21187 </dd>
21188 <dt><code>DSA</code></dt>
21189 <dd><p>DSA is the USA&rsquo;s Digital Signature Standard.  It uses only the SHA-1
21190 hash algorithm.
21191 </p>
21192 </dd>
21193 <dt><code>MD2</code></dt>
21194 <dd><p>MD2 is a cryptographic hash algorithm designed by Ron Rivest.  It is
21195 optimized for 8-bit processors.  Outputs 128 bits of data.  There are
21196 several known weaknesses of this algorithm and it should not be used.
21197 </p>
21198 </dd>
21199 <dt><code>MD5</code></dt>
21200 <dd><p>MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs
21201 128 bits of data.  It is considered to be broken.
21202 </p>
21203 </dd>
21204 <dt><code>SHA-1</code></dt>
21205 <dd><p>SHA is a cryptographic hash algorithm designed by NSA. Outputs 160
21206 bits of data.  It is also considered to be broken, though no practical
21207 attacks have been found.
21208 </p>
21209 </dd>
21210 <dt><code>RMD160</code></dt>
21211 <dd><p>RIPEMD is a cryptographic hash algorithm developed in the framework of
21212 the EU project RIPE.  Outputs 160 bits of data.
21213 </p>
21214 </dd>
21215 </dl>
21216
21217
21218
21219 <hr>
21220 <a name="Guile-Bindings"></a>
21221 <div class="header">
21222 <p>
21223 Next: <a href="#Internal-architecture-of-GnuTLS" accesskey="n" rel="next">Internal architecture of GnuTLS</a>, Previous: <a href="#All-the-supported-ciphersuites-in-GnuTLS" accesskey="p" rel="previous">All the supported ciphersuites in 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>
21224 </div>
21225 <a name="Guile-Bindings-1"></a>
21226 <h2 class="chapter">11 Guile Bindings</h2>
21227
21228 <p>This chapter describes the <a href="http://www.gnu.org/software/guile/">GNU Guile</a> Scheme programming interface to GnuTLS.  The reader is
21229 assumed to have basic knowledge of the protocol and library.  Details
21230 missing from this chapter may be found in <a href="#Function-reference">the C API reference</a>.
21231 </p>
21232 <p>At this stage, not all the C functions are available from Scheme, but
21233 a large subset thereof is available.
21234 </p>
21235
21236 <table class="menu" border="0" cellspacing="0">
21237 <tr><td align="left" valign="top">&bull; <a href="#Guile-Preparations" accesskey="1">Guile Preparations</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Note on installation and environment.
21238 </td></tr>
21239 <tr><td align="left" valign="top">&bull; <a href="#Guile-API-Conventions" accesskey="2">Guile API Conventions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Naming conventions and other idiosyncrasies.
21240 </td></tr>
21241 <tr><td align="left" valign="top">&bull; <a href="#Guile-Examples" accesskey="3">Guile Examples</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Quick start.
21242 </td></tr>
21243 <tr><td align="left" valign="top">&bull; <a href="#Guile-Reference" accesskey="4">Guile Reference</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">The Scheme GnuTLS programming interface.
21244 </td></tr>
21245 </table>
21246
21247 <hr>
21248 <a name="Guile-Preparations"></a>
21249 <div class="header">
21250 <p>
21251 Next: <a href="#Guile-API-Conventions" accesskey="n" rel="next">Guile API Conventions</a>, Up: <a href="#Guile-Bindings" accesskey="u" rel="up">Guile Bindings</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>
21252 </div>
21253 <a name="Guile-Preparations-1"></a>
21254 <h3 class="section">11.1 Guile Preparations</h3>
21255
21256 <p>The GnuTLS Guile bindings are by default installed under the GnuTLS
21257 installation directory (e.g., typically
21258 &lsquo;<tt>/usr/local/share/guile/site/</tt>&rsquo;).  Normally Guile will not find
21259 the module there without help.  You may experience something like
21260 this:
21261 </p>
21262 <div class="example">
21263 <pre class="example">$ guile
21264 guile&gt; (use-modules (gnutls))
21265 &lt;unnamed port&gt;: no code for module (gnutls)
21266 guile&gt;
21267 </pre></div>
21268
21269 <p>There are two ways to solve this.  The first is to make sure that when
21270 building GnuTLS, the Guile bindings will be installed in the same
21271 place where Guile looks.  You may do this by using the
21272 <code>--with-guile-site-dir</code> parameter as follows:
21273 </p>
21274 <div class="example">
21275 <pre class="example">$ ./configure --with-guile-site-dir=no
21276 </pre></div>
21277
21278 <p>This will instruct GnuTLS to attempt to install the Guile bindings
21279 where Guile will look for them.  It will use <code>guile-config info
21280 pkgdatadir</code> to learn the path to use.
21281 </p>
21282 <p>If Guile was installed into <code>/usr</code>, you may also install GnuTLS
21283 using the same prefix:
21284 </p>
21285 <div class="example">
21286 <pre class="example">$ ./configure --prefix=/usr
21287 </pre></div>
21288
21289 <p>If you want to specify the path to install the Guile bindings you can
21290 also specify the path directly:
21291 </p>
21292 <div class="example">
21293 <pre class="example">$ ./configure --with-guile-site-dir=/opt/guile/share/guile/site
21294 </pre></div>
21295
21296 <p>The second solution requires some more work but may be easier to use
21297 if you do not have system administrator rights to your machine.  You
21298 need to instruct Guile so that it finds the GnuTLS Guile bindings.
21299 Either use the <code>GUILE_LOAD_PATH</code> environment variable as follows:
21300 </p>
21301 <div class="example">
21302 <pre class="example">$ GUILE_LOAD_PATH=&quot;/usr/local/share/guile/site:$GUILE_LOAD_PATH&quot; guile
21303 guile&gt; (use-modules (gnutls))
21304 guile&gt;
21305 </pre></div>
21306
21307 <p>Alternatively, you can modify Guile&rsquo;s <code>%load-path</code> variable
21308 (see <a href="http://www.gnu.org/software/guile/manual/guile.html#Build-Config">Guile&rsquo;s run-time options</a> in <cite>The GNU Guile
21309 Reference Manual</cite>).
21310 </p>
21311 <p>At this point, you might get an error regarding
21312 &lsquo;<tt>libguile-gnutls-v-0</tt>&rsquo; similar to:
21313 </p>
21314 <div class="example">
21315 <pre class="example">gnutls.scm:361:1: In procedure dynamic-link in expression (load-extension &quot;libguile-gnutls-v-0&quot; &quot;scm_init_gnutls&quot;):
21316 gnutls.scm:361:1: file: &quot;libguile-gnutls-v-0&quot;, message: &quot;libguile-gnutls-v-0.so: cannot open shared object file: No such file or directory&quot;
21317 </pre></div>
21318
21319 <p>In this case, you will need to modify the run-time linker path, for
21320 example as follows:
21321 </p>
21322 <div class="example">
21323 <pre class="example">$ LD_LIBRARY_PATH=/usr/local/lib GUILE_LOAD_PATH=/usr/local/share/guile/site guile
21324 guile&gt; (use-modules (gnutls))
21325 guile&gt;
21326 </pre></div>
21327
21328 <p>To check that you got the intended GnuTLS library version, you may
21329 print the version number of the loaded library as follows:
21330 </p>
21331 <div class="example">
21332 <pre class="example">$ guile
21333 guile&gt; (use-modules (gnutls))
21334 guile&gt; (gnutls-version)
21335 &quot;2.12.20&quot;
21336 guile&gt;
21337 </pre></div>
21338
21339
21340 <hr>
21341 <a name="Guile-API-Conventions"></a>
21342 <div class="header">
21343 <p>
21344 Next: <a href="#Guile-Examples" accesskey="n" rel="next">Guile Examples</a>, Previous: <a href="#Guile-Preparations" accesskey="p" rel="previous">Guile Preparations</a>, Up: <a href="#Guile-Bindings" accesskey="u" rel="up">Guile Bindings</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>
21345 </div>
21346 <a name="Guile-API-Conventions-1"></a>
21347 <h3 class="section">11.2 Guile API Conventions</h3>
21348
21349 <p>This chapter details the conventions used by Guile API, as well as
21350 specificities of the mapping of the C API to Scheme.
21351 </p>
21352 <table class="menu" border="0" cellspacing="0">
21353 <tr><td align="left" valign="top">&bull; <a href="#Enumerates-and-Constants" accesskey="1">Enumerates and Constants</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Representation of C-side constants.
21354 </td></tr>
21355 <tr><td align="left" valign="top">&bull; <a href="#Procedure-Names" accesskey="2">Procedure Names</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Naming conventions.
21356 </td></tr>
21357 <tr><td align="left" valign="top">&bull; <a href="#Representation-of-Binary-Data" accesskey="3">Representation of Binary Data</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Binary data buffers.
21358 </td></tr>
21359 <tr><td align="left" valign="top">&bull; <a href="#Input-and-Output" accesskey="4">Input and Output</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Input and output.
21360 </td></tr>
21361 <tr><td align="left" valign="top">&bull; <a href="#Exception-Handling" accesskey="5">Exception Handling</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Exceptions.
21362 </td></tr>
21363 </table>
21364
21365 <hr>
21366 <a name="Enumerates-and-Constants"></a>
21367 <div class="header">
21368 <p>
21369 Next: <a href="#Procedure-Names" accesskey="n" rel="next">Procedure Names</a>, Up: <a href="#Guile-API-Conventions" accesskey="u" rel="up">Guile API Conventions</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>
21370 </div>
21371 <a name="Enumerates-and-Constants-1"></a>
21372 <h4 class="subsection">11.2.1 Enumerates and Constants</h4>
21373
21374 <a name="index-enumerate"></a>
21375 <a name="index-constant"></a>
21376
21377 <p>Lots of enumerates and constants are used in the GnuTLS C API.  For
21378 each C enumerate type, a disjoint Scheme type is used&mdash;thus,
21379 enumerate values and constants are not represented by Scheme symbols
21380 nor by integers.  This makes it impossible to use an enumerate value
21381 of the wrong type on the Scheme side: such errors are automatically
21382 detected by type-checking.
21383 </p>
21384 <p>The enumerate values are bound to variables exported by the
21385 <code>(gnutls)</code> and <code>(gnutls extra)</code> modules.  These variables
21386 are named according to the following convention:
21387 </p>
21388 <ul>
21389 <li> All variable names are lower-case; the underscore <code>_</code>
21390 character used in the C API is replaced by hyphen <code>-</code>.
21391 </li><li> All variable names are prepended by the name of the enumerate
21392 type and the slash <code>/</code> character.
21393 </li><li> In some cases, the variable name is made more explicit than the
21394 one of the C API, e.g., by avoid abbreviations.
21395 </li></ul>
21396
21397 <p>Consider for instance this C-side enumerate:
21398 </p>
21399 <div class="example">
21400 <pre class="example">typedef enum
21401 {
21402   GNUTLS_CRD_CERTIFICATE = 1,
21403   GNUTLS_CRD_ANON,
21404   GNUTLS_CRD_SRP,
21405   GNUTLS_CRD_PSK,
21406   GNUTLS_CRD_IA
21407 } gnutls_credentials_type_t;
21408 </pre></div>
21409
21410 <p>The corresponding Scheme values are bound to the following variables
21411 exported by the <code>(gnutls)</code> module:
21412 </p>
21413 <div class="example">
21414 <pre class="example">credentials/certificate
21415 credentials/anonymous
21416 credentials/srp
21417 credentials/psk
21418 credentials/ia
21419 </pre></div>
21420
21421 <p>Hopefully, most variable names can be deduced from this convention.
21422 </p>
21423 <p>Scheme-side &ldquo;enumerate&rdquo; values can be compared using <code>eq?</code>
21424 (see <a href="http://www.gnu.org/software/guile/manual/guile.html#Equality">equality predicates</a> in <cite>The GNU Guile Reference
21425 Manual</cite>).  Consider the following example:
21426 </p>
21427 <a name="index-session_002dcipher"></a>
21428
21429 <div class="example">
21430 <pre class="example">(let ((session (make-session connection-end/client)))
21431
21432   ;;
21433   ;; ...
21434   ;;
21435
21436   ;; Check the ciphering algorithm currently used by SESSION.
21437   (if (eq? cipher/arcfour (session-cipher session))
21438       (format #t &quot;We're using the ARCFOUR algorithm&quot;)))
21439 </pre></div>
21440
21441 <p>In addition, all enumerate values can be converted to a human-readable
21442 string, in a type-specific way.  For instance, <code>(cipher-&gt;string
21443 cipher/arcfour)</code> yields <code>&quot;ARCFOUR 128&quot;</code>, while
21444 <code>(key-usage-&gt;string key-usage/digital-signature)</code> yields
21445 <code>&quot;digital-signature&quot;</code>.  Note that these strings may not be
21446 sufficient for use in a user interface since they are fairly concise
21447 and not internationalized.
21448 </p>
21449
21450 <hr>
21451 <a name="Procedure-Names"></a>
21452 <div class="header">
21453 <p>
21454 Next: <a href="#Representation-of-Binary-Data" accesskey="n" rel="next">Representation of Binary Data</a>, Previous: <a href="#Enumerates-and-Constants" accesskey="p" rel="previous">Enumerates and Constants</a>, Up: <a href="#Guile-API-Conventions" accesskey="u" rel="up">Guile API Conventions</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>
21455 </div>
21456 <a name="Procedure-Names-1"></a>
21457 <h4 class="subsection">11.2.2 Procedure Names</h4>
21458
21459 <p>Unlike C functions in GnuTLS, the corresponding Scheme procedures are
21460 named in a way that is close to natural English.  Abbreviations are
21461 also avoided.  For instance, the Scheme procedure corresponding to
21462 <code>gnutls_certificate_set_dh_params</code> is named
21463 <code>set-certificate-credentials-dh-parameters!</code>.  The <code>gnutls_</code>
21464 prefix is always omitted from variable names since a similar effect
21465 can be achieved using Guile&rsquo;s nifty binding renaming facilities,
21466 should it be needed (see <a href="http://www.gnu.org/software/guile/manual/guile.html#Using-Guile-Modules">Using Guile Modules</a> in <cite>The GNU
21467 Guile Reference Manual</cite>).
21468 </p>
21469 <p>Often Scheme procedure names differ from C function names in a way
21470 that makes it clearer what objects they operate on.  For example, the
21471 Scheme procedure named <code>set-session-transport-port!</code> corresponds
21472 to <code>gnutls_transport_set_ptr</code>, making it clear that this
21473 procedure applies to session.
21474 </p>
21475 <hr>
21476 <a name="Representation-of-Binary-Data"></a>
21477 <div class="header">
21478 <p>
21479 Next: <a href="#Input-and-Output" accesskey="n" rel="next">Input and Output</a>, Previous: <a href="#Procedure-Names" accesskey="p" rel="previous">Procedure Names</a>, Up: <a href="#Guile-API-Conventions" accesskey="u" rel="up">Guile API Conventions</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>
21480 </div>
21481 <a name="Representation-of-Binary-Data-1"></a>
21482 <h4 class="subsection">11.2.3 Representation of Binary Data</h4>
21483
21484 <p>Many procedures operate on binary data.  For instance,
21485 <code>pkcs3-import-dh-parameters</code> expects binary data as input and,
21486 similarly, procedures like <code>pkcs1-export-rsa-parameters</code> return
21487 binary data.
21488 </p>
21489 <a name="index-SRFI_002d4"></a>
21490 <a name="index-homogeneous-vector"></a>
21491
21492 <p>Binary data is represented on the Scheme side using SRFI-4 homogeneous
21493 vectors (see <a href="http://www.gnu.org/software/guile/manual/guile.html#SRFI_002d4">SRFI-4</a> in <cite>The GNU Guile Reference Manual</cite>).
21494 Although any type of homogeneous vector may be used, <code>u8vector</code>s
21495 (i.e., vectors of bytes) are highly recommended.
21496 </p>
21497 <p>As an example, generating and then exporting RSA parameters in the PEM
21498 format can be done as follows:
21499 </p>
21500 <a name="index-make_002drsa_002dparameters"></a>
21501 <a name="index-pkcs1_002dexport_002drsa_002dparameters"></a>
21502 <a name="index-x509_002dcertificate_002dformat_002fpem"></a>
21503
21504 <div class="example">
21505 <pre class="example">(let* ((rsa-params (make-rsa-parameters 1024))
21506        (raw-data
21507         (pkcs1-export-rsa-parameters rsa-params
21508                                      x509-certificate-format/pem)))
21509   (uniform-vector-write raw-data (open-output-file &quot;some-file.pem&quot;)))
21510 </pre></div>
21511
21512 <p>For an example of OpenPGP key import from a file, see <a href="#Importing-OpenPGP-Keys-Guile-Example">Importing
21513 OpenPGP Keys Guile Example</a>.
21514 </p>
21515
21516 <hr>
21517 <a name="Input-and-Output"></a>
21518 <div class="header">
21519 <p>
21520 Next: <a href="#Exception-Handling" accesskey="n" rel="next">Exception Handling</a>, Previous: <a href="#Representation-of-Binary-Data" accesskey="p" rel="previous">Representation of Binary Data</a>, Up: <a href="#Guile-API-Conventions" accesskey="u" rel="up">Guile API Conventions</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>
21521 </div>
21522 <a name="Input-and-Output-1"></a>
21523 <h4 class="subsection">11.2.4 Input and Output</h4>
21524
21525 <a name="index-set_002dsession_002dtransport_002dport_0021"></a>
21526 <a name="index-set_002dsession_002dtransport_002dfd_0021"></a>
21527
21528 <p>The underlying transport of a TLS session can be any Scheme
21529 input/output port (see <a href="http://www.gnu.org/software/guile/manual/guile.html#Ports-and-File-Descriptors">Ports and File Descriptors</a> in <cite>The GNU
21530 Guile Reference Manual</cite>).  This has to be specified using
21531 <code>set-session-transport-port!</code>.
21532 </p>
21533 <p>However, for better performance, a raw file descriptor can be
21534 specified, using <code>set-session-transport-fd!</code>.  For instance, if
21535 the transport layer is a socket port over an OS-provided socket, you
21536 can use the <code>port-&gt;fdes</code> or <code>fileno</code> procedure to obtain the
21537 underlying file descriptor and pass it to
21538 <code>set-session-transport-fd!</code>  (see <a href="http://www.gnu.org/software/guile/manual/guile.html#Ports-and-File-Descriptors"><code>port-&gt;fdes</code> and <code>fileno</code></a> in <cite>The GNU Guile Reference
21539 Manual</cite>).  This would work as follows:
21540 </p>
21541 <div class="example">
21542 <pre class="example">(let ((socket (socket PF_INET SOCK_STREAM 0))
21543       (session (make-session connection-end/client)))
21544
21545   ;;
21546   ;; Establish a TCP connection...
21547   ;;
21548
21549   ;; Use the file descriptor that underlies SOCKET.
21550   (set-session-transport-fd! session (fileno socket)))
21551 </pre></div>
21552
21553 <a name="index-session_002drecord_002dport"></a>
21554
21555 <p>Once a TLS session is established, data can be communicated through it
21556 (i.e., <em>via</em> the TLS record layer) using the port returned by
21557 <code>session-record-port</code>:
21558 </p>
21559 <div class="example">
21560 <pre class="example">(let ((session (make-session connection-end/client)))
21561
21562   ;;
21563   ;; Initialize the various parameters of SESSION, set up
21564   ;; a network connection, etc...
21565   ;;
21566
21567   (let ((i/o (session-record-port session)))
21568     (write &quot;Hello peer!&quot; i/o)
21569     (let ((greetings (read i/o)))
21570
21571       ;; ...
21572
21573       (bye session close-request/rdwr))))
21574 </pre></div>
21575
21576 <a name="index-record_002dsend"></a>
21577 <a name="index-record_002dreceive_0021"></a>
21578
21579 <p>A lower-level I/O API is provided by <code>record-send</code> and
21580 <code>record-receive!</code> which take an SRFI-4 vector to represent the
21581 data sent or received.  While it might improve performance, it is much
21582 less convenient than the above and should rarely be needed.
21583 </p>
21584
21585 <hr>
21586 <a name="Exception-Handling"></a>
21587 <div class="header">
21588 <p>
21589 Previous: <a href="#Input-and-Output" accesskey="p" rel="previous">Input and Output</a>, Up: <a href="#Guile-API-Conventions" accesskey="u" rel="up">Guile API Conventions</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>
21590 </div>
21591 <a name="Exception-Handling-1"></a>
21592 <h4 class="subsection">11.2.5 Exception Handling</h4>
21593
21594 <a name="index-exceptions"></a>
21595 <a name="index-errors"></a>
21596 <a name="index-gnutls_002derror"></a>
21597 <a name="index-error_002d_003estring"></a>
21598
21599 <p>GnuTLS errors are implemented as Scheme exceptions (see <a href="http://www.gnu.org/software/guile/manual/guile.html#Exceptions">exceptions in Guile</a> in <cite>The GNU Guile Reference Manual</cite>).  Each
21600 time a GnuTLS function returns an error, an exception with key
21601 <code>gnutls-error</code> is raised.  The additional arguments that are
21602 thrown include an error code and the name of the GnuTLS procedure that
21603 raised the exception.  The error code is pretty much like an enumerate
21604 value: it is one of the <code>error/</code> variables exported by the
21605 <code>(gnutls)</code> module (see <a href="#Enumerates-and-Constants">Enumerates and Constants</a>).  Exceptions
21606 can be turned into error messages using the <code>error-&gt;string</code>
21607 procedure.
21608 </p>
21609 <p>The following examples illustrates how GnuTLS exceptions can be
21610 handled:
21611 </p>
21612 <div class="example">
21613 <pre class="example">(let ((session (make-session connection-end/server)))
21614
21615   ;;
21616   ;; ...
21617   ;;
21618
21619   (catch 'gnutls-error
21620     (lambda ()
21621       (handshake session))
21622     (lambda (key err function . currently-unused)
21623       (format (current-error-port)
21624               &quot;a GnuTLS error was raised by `~a': ~a~%&quot;
21625               function (error-&gt;string err)))))
21626 </pre></div>
21627
21628 <p>Again, error values can be compared using <code>eq?</code>:
21629 </p>
21630 <div class="example">
21631 <pre class="example">    ;; `gnutls-error' handler.
21632     (lambda (key err function . currently-unused)
21633       (if (eq? err error/fatal-alert-received)
21634           (format (current-error-port)
21635                   &quot;a fatal alert was caught!~%&quot;)
21636           (format (current-error-port)
21637                   &quot;something bad happened: ~a~%&quot;
21638                   (error-&gt;string err))))
21639 </pre></div>
21640
21641 <p>Note that the <code>catch</code> handler is currently passed only 3
21642 arguments but future versions might provide it with additional
21643 arguments.  Thus, it must be prepared to handle more than 3 arguments,
21644 as in this example.
21645 </p>
21646
21647 <hr>
21648 <a name="Guile-Examples"></a>
21649 <div class="header">
21650 <p>
21651 Next: <a href="#Guile-Reference" accesskey="n" rel="next">Guile Reference</a>, Previous: <a href="#Guile-API-Conventions" accesskey="p" rel="previous">Guile API Conventions</a>, Up: <a href="#Guile-Bindings" accesskey="u" rel="up">Guile Bindings</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>
21652 </div>
21653 <a name="Guile-Examples-1"></a>
21654 <h3 class="section">11.3 Guile Examples</h3>
21655
21656 <p>This chapter provides examples that illustrate common use cases.
21657 </p>
21658 <table class="menu" border="0" cellspacing="0">
21659 <tr><td align="left" valign="top">&bull; <a href="#Anonymous-Authentication-Guile-Example" accesskey="1">Anonymous Authentication Guile Example</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Simplest client and server.
21660 </td></tr>
21661 <tr><td align="left" valign="top">&bull; <a href="#OpenPGP-Authentication-Guile-Example" accesskey="2">OpenPGP Authentication Guile Example</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Using OpenPGP-based authentication.
21662 </td></tr>
21663 <tr><td align="left" valign="top">&bull; <a href="#Importing-OpenPGP-Keys-Guile-Example" accesskey="3">Importing OpenPGP Keys Guile Example</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Importing keys from files.
21664 </td></tr>
21665 </table>
21666
21667 <hr>
21668 <a name="Anonymous-Authentication-Guile-Example"></a>
21669 <div class="header">
21670 <p>
21671 Next: <a href="#OpenPGP-Authentication-Guile-Example" accesskey="n" rel="next">OpenPGP Authentication Guile Example</a>, Up: <a href="#Guile-Examples" accesskey="u" rel="up">Guile 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>
21672 </div>
21673 <a name="Anonymous-Authentication-Guile-Example-1"></a>
21674 <h4 class="subsection">11.3.1 Anonymous Authentication Guile Example</h4>
21675
21676 <p><em>Anonymous authentication</em> is very easy to use.  No certificates
21677 are needed by the communicating parties.  Yet, it allows them to
21678 benefit from end-to-end encryption and integrity checks.
21679 </p>
21680 <p>The client-side code would look like this (assuming <var>some-socket</var>
21681 is bound to an open socket port):
21682 </p>
21683 <a name="index-connection_002dend_002fclient"></a>
21684 <a name="index-kx_002fanon_002ddh"></a>
21685 <a name="index-close_002drequest_002frdwr"></a>
21686
21687 <div class="example">
21688 <pre class="example">;; Client-side.
21689
21690 (let ((client (make-session connection-end/client)))
21691   ;; Use the default settings.
21692   (set-session-default-priority! client)
21693
21694   ;; Don't use certificate-based authentication.
21695   (set-session-certificate-type-priority! client '())
21696
21697   ;; Request the &quot;anonymous Diffie-Hellman&quot; key exchange method.
21698   (set-session-kx-priority! client (list kx/anon-dh))
21699
21700   ;; Specify the underlying socket.
21701   (set-session-transport-fd! client (fileno some-socket))
21702
21703   ;; Create anonymous credentials.
21704   (set-session-credentials! client
21705                             (make-anonymous-client-credentials))
21706
21707   ;; Perform the TLS handshake with the server.
21708   (handshake client)
21709
21710   ;; Send data over the TLS record layer.
21711   (write &quot;hello, world!&quot; (session-record-port client))
21712
21713   ;; Terminate the TLS session.
21714   (bye client close-request/rdwr))
21715 </pre></div>
21716
21717 <p>The corresponding server would look like this (again, assuming
21718 <var>some-socket</var> is bound to a socket port):
21719 </p>
21720 <a name="index-connection_002dend_002fserver"></a>
21721
21722 <div class="example">
21723 <pre class="example">;; Server-side.
21724
21725 (let ((server (make-session connection-end/server)))
21726   (set-session-default-priority! server)
21727   (set-session-certificate-type-priority! server '())
21728   (set-session-kx-priority! server (list kx/anon-dh))
21729
21730   ;; Specify the underlying transport socket.
21731   (set-session-transport-fd! server (fileno some-socket))
21732
21733   ;; Create anonymous credentials.
21734   (let ((cred (make-anonymous-server-credentials))
21735         (dh-params (make-dh-parameters 1024)))
21736     ;; Note: DH parameter generation can take some time.
21737     (set-anonymous-server-dh-parameters! cred dh-params)
21738     (set-session-credentials! server cred))
21739
21740   ;; Perform the TLS handshake with the client.
21741   (handshake server)
21742
21743   ;; Receive data over the TLS record layer.
21744   (let ((message (read (session-record-port server))))
21745     (format #t &quot;received the following message: ~a~%&quot;
21746             message)
21747
21748     (bye server close-request/rdwr)))
21749 </pre></div>
21750
21751 <p>This is it!
21752 </p>
21753
21754 <hr>
21755 <a name="OpenPGP-Authentication-Guile-Example"></a>
21756 <div class="header">
21757 <p>
21758 Next: <a href="#Importing-OpenPGP-Keys-Guile-Example" accesskey="n" rel="next">Importing OpenPGP Keys Guile Example</a>, Previous: <a href="#Anonymous-Authentication-Guile-Example" accesskey="p" rel="previous">Anonymous Authentication Guile Example</a>, Up: <a href="#Guile-Examples" accesskey="u" rel="up">Guile 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>
21759 </div>
21760 <a name="OpenPGP-Authentication-Guile-Example-1"></a>
21761 <h4 class="subsection">11.3.2 OpenPGP Authentication Guile Example</h4>
21762
21763 <p>GnuTLS allows users to authenticate using OpenPGP certificates.  The
21764 relevant procedures are provided by the <code>(gnutls extra)</code> module.
21765 Using OpenPGP-based authentication is not more complicated than using
21766 anonymous authentication.  It requires a bit of extra work, though, to
21767 import the OpenPGP public and private key of the client/server.  Key
21768 import is omitted here and is left as an exercise to the reader
21769 (see <a href="#Importing-OpenPGP-Keys-Guile-Example">Importing OpenPGP Keys Guile Example</a>).
21770 </p>
21771 <p>Assuming <var>some-socket</var> is bound to an open socket port and
21772 <var>pub</var> and <var>sec</var> are bound to the client&rsquo;s OpenPGP public and
21773 secret key, respectively, client-side code would look like this:
21774 </p>
21775 <a name="index-certificate_002dtype_002fopenpgp"></a>
21776
21777 <div class="example">
21778 <pre class="example">;; Client-side.
21779
21780 (define %certs (list certificate-type/openpgp))
21781
21782 (let ((client (make-session connection-end/client))
21783       (cred   (make-certificate-credentials)))
21784   (set-session-default-priority! client)
21785
21786   ;; Choose OpenPGP certificates.
21787   (set-session-certificate-type-priority! client %certs)
21788
21789   ;; Prepare appropriate client credentials.
21790   (set-certificate-credentials-openpgp-keys! cred pub sec)
21791   (set-session-credentials! client cred)
21792
21793   ;; Specify the underlying transport socket.
21794   (set-session-transport-fd! client (fileno some-socket))
21795
21796   (handshake client)
21797   (write &quot;hello, world!&quot; (session-record-port client))
21798   (bye client close-request/rdwr))
21799 </pre></div>
21800
21801 <p>Similarly, server-side code would be along these lines:
21802 </p>
21803 <div class="example">
21804 <pre class="example">;; Server-side.
21805
21806 (define %certs (list certificate-type/openpgp))
21807
21808 (let ((server (make-session connection-end/server))
21809       (rsa    (make-rsa-parameters 1024))
21810       (dh     (make-dh-parameters 1024)))
21811   (set-session-default-priority! server)
21812
21813   ;; Choose OpenPGP certificates.
21814   (set-session-certificate-type-priority! server %certs)
21815
21816   (let ((cred (make-certificate-credentials)))
21817     ;; Prepare credentials with RSA and Diffie-Hellman parameters.
21818     (set-certificate-credentials-dh-parameters! cred dh)
21819     (set-certificate-credentials-rsa-export-parameters! cred rsa)
21820     (set-certificate-credentials-openpgp-keys! cred pub sec)
21821     (set-session-credentials! server cred))
21822
21823   (set-session-transport-fd! server (fileno some-socket))
21824
21825   (handshake server)
21826   (let ((msg (read (session-record-port server))))
21827     (format #t &quot;received: ~a~%&quot; msg)
21828
21829     (bye server close-request/rdwr)))
21830 </pre></div>
21831
21832 <p>In practice, generating RSA parameters (and Diffie-Hellman parameters)
21833 can time a long time.  Thus, you may want to generate them once and
21834 store them in a file for future re-use (see <a href="#Core-Interface"><code>pkcs1-export-rsa-parameters</code> and
21835 <code>pkcs1-import-rsa-parameters</code></a>).
21836 </p>
21837 <hr>
21838 <a name="Importing-OpenPGP-Keys-Guile-Example"></a>
21839 <div class="header">
21840 <p>
21841 Previous: <a href="#OpenPGP-Authentication-Guile-Example" accesskey="p" rel="previous">OpenPGP Authentication Guile Example</a>, Up: <a href="#Guile-Examples" accesskey="u" rel="up">Guile 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>
21842 </div>
21843 <a name="Importing-OpenPGP-Keys-Guile-Example-1"></a>
21844 <h4 class="subsection">11.3.3 Importing OpenPGP Keys Guile Example</h4>
21845
21846 <p>The following example provides a simple way of importing
21847 &ldquo;ASCII-armored&rdquo; OpenPGP keys from files, using the
21848 <code>import-openpgp-certificate</code> and <code>import-openpgp-private-key</code>
21849 procedures provided by the <code>(gnutls extra)</code> module.
21850 </p>
21851 <a name="index-openpgp_002dcertificate_002dformat_002fbase64"></a>
21852 <a name="index-openpgp_002dcertificate_002dformat_002fraw"></a>
21853
21854 <div class="example">
21855 <pre class="example">(use-modules (srfi srfi-4)
21856              (gnutls extra))
21857
21858 (define (import-key-from-file import-proc file)
21859   ;; Import OpenPGP key from FILE using IMPORT-PROC.
21860
21861   ;; Prepare a u8vector large enough to hold the raw
21862   ;; key contents.
21863   (let* ((size (stat:size (stat path)))
21864          (raw  (make-u8vector size)))
21865
21866     ;; Fill in the u8vector with the contents of FILE.
21867     (uniform-vector-read! raw (open-input-file file))
21868
21869     ;; Pass the u8vector to the import procedure.
21870     (import-proc raw openpgp-certificate-format/base64)))
21871
21872
21873 (define (import-public-key-from-file file)
21874   (import-key-from-file import-openpgp-certificate file))
21875
21876 (define (import-private-key-from-file file)
21877   (import-key-from-file import-openpgp-private-key file))
21878 </pre></div>
21879
21880 <p>The procedures <code>import-public-key-from-file</code> and
21881 <code>import-private-key-from-file</code> can be passed a file name.  They
21882 return an OpenPGP public key and private key object, respectively
21883 (see <a href="#Extra-Interface">OpenPGP key objects</a>).
21884 </p>
21885
21886 <hr>
21887 <a name="Guile-Reference"></a>
21888 <div class="header">
21889 <p>
21890 Previous: <a href="#Guile-Examples" accesskey="p" rel="previous">Guile Examples</a>, Up: <a href="#Guile-Bindings" accesskey="u" rel="up">Guile Bindings</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>
21891 </div>
21892 <a name="Guile-Reference-1"></a>
21893 <h3 class="section">11.4 Guile Reference</h3>
21894
21895 <p>This chapter documents GnuTLS Scheme procedures available to Guile
21896 programmers.
21897 </p>
21898 <table class="menu" border="0" cellspacing="0">
21899 <tr><td align="left" valign="top">&bull; <a href="#Core-Interface" accesskey="1">Core Interface</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Bindings for core GnuTLS.
21900 </td></tr>
21901 <tr><td align="left" valign="top">&bull; <a href="#Extra-Interface" accesskey="2">Extra Interface</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Bindings for GnuTLS-Extra.
21902 </td></tr>
21903 </table>
21904
21905 <hr>
21906 <a name="Core-Interface"></a>
21907 <div class="header">
21908 <p>
21909 Next: <a href="#Extra-Interface" accesskey="n" rel="next">Extra Interface</a>, Up: <a href="#Guile-Reference" accesskey="u" rel="up">Guile 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>
21910 </div>
21911 <a name="Core-Interface-1"></a>
21912 <h4 class="subsection">11.4.1 Core Interface</h4>
21913
21914 <p>This section lists the Scheme procedures exported by the
21915 <code>(gnutls)</code> module (see <a href="http://www.gnu.org/software/guile/manual/guile.html#The-Guile-module-system">The Guile module system</a> in <cite>The
21916 GNU Guile Reference Manual</cite>).  This module is licenced under the GNU
21917 Lesser General Public Licence, version 2.1 or later.
21918 </p>
21919
21920 <dl>
21921 <dt><a name="index-set_002dlog_002dlevel_0021"></a>Scheme Procedure: <strong>set-log-level!</strong> <em>level</em></dt>
21922 <dd><p>Enable GnuTLS logging up to <var>level</var> (an integer).
21923 </p></dd></dl>
21924
21925 <dl>
21926 <dt><a name="index-set_002dlog_002dprocedure_0021"></a>Scheme Procedure: <strong>set-log-procedure!</strong> <em>proc</em></dt>
21927 <dd><p>Use <var>proc</var> (a two-argument procedure) as the global GnuTLS log procedure.
21928 </p></dd></dl>
21929
21930 <dl>
21931 <dt><a name="index-x509_002dcertificate_002dsubject_002dalternative_002dname"></a>Scheme Procedure: <strong>x509-certificate-subject-alternative-name</strong> <em>cert index</em></dt>
21932 <dd><p>Return two values: the alternative name type for <var>cert</var> (i.e., one of the <code>x509-subject-alternative-name/</code> values) and the actual subject alternative name (a string) at <var>index</var>. Both values are <code>#f</code> if no alternative name is available at <var>index</var>.
21933 </p></dd></dl>
21934
21935 <dl>
21936 <dt><a name="index-x509_002dcertificate_002dsubject_002dkey_002did"></a>Scheme Procedure: <strong>x509-certificate-subject-key-id</strong> <em>cert</em></dt>
21937 <dd><p>Return the subject key ID (a u8vector) for <var>cert</var>.
21938 </p></dd></dl>
21939
21940 <dl>
21941 <dt><a name="index-x509_002dcertificate_002dauthority_002dkey_002did"></a>Scheme Procedure: <strong>x509-certificate-authority-key-id</strong> <em>cert</em></dt>
21942 <dd><p>Return the key ID (a u8vector) of the X.509 certificate authority of <var>cert</var>.
21943 </p></dd></dl>
21944
21945 <dl>
21946 <dt><a name="index-x509_002dcertificate_002dkey_002did"></a>Scheme Procedure: <strong>x509-certificate-key-id</strong> <em>cert</em></dt>
21947 <dd><p>Return a statistically unique ID (a u8vector) for <var>cert</var> that depends on its public key parameters.  This is normally a 20-byte SHA-1 hash.
21948 </p></dd></dl>
21949
21950 <dl>
21951 <dt><a name="index-x509_002dcertificate_002dversion"></a>Scheme Procedure: <strong>x509-certificate-version</strong> <em>cert</em></dt>
21952 <dd><p>Return the version of <var>cert</var>.
21953 </p></dd></dl>
21954
21955 <dl>
21956 <dt><a name="index-x509_002dcertificate_002dkey_002dusage"></a>Scheme Procedure: <strong>x509-certificate-key-usage</strong> <em>cert</em></dt>
21957 <dd><p>Return the key usage of <var>cert</var> (i.e., a list of <code>key-usage/</code> values), or the empty list if <var>cert</var> does not contain such information.
21958 </p></dd></dl>
21959
21960 <dl>
21961 <dt><a name="index-x509_002dcertificate_002dpublic_002dkey_002dalgorithm"></a>Scheme Procedure: <strong>x509-certificate-public-key-algorithm</strong> <em>cert</em></dt>
21962 <dd><p>Return two values: the public key algorithm (i.e., one of the <code>pk-algorithm/</code> values) of <var>cert</var> and the number of bits used.
21963 </p></dd></dl>
21964
21965 <dl>
21966 <dt><a name="index-x509_002dcertificate_002dsignature_002dalgorithm"></a>Scheme Procedure: <strong>x509-certificate-signature-algorithm</strong> <em>cert</em></dt>
21967 <dd><p>Return the signature algorithm used by <var>cert</var> (i.e., one of the <code>sign-algorithm/</code> values).
21968 </p></dd></dl>
21969
21970 <dl>
21971 <dt><a name="index-x509_002dcertificate_002dmatches_002dhostname_003f"></a>Scheme Procedure: <strong>x509-certificate-matches-hostname?</strong> <em>cert hostname</em></dt>
21972 <dd><p>Return true if <var>cert</var> matches <var>hostname</var>, a string denoting a DNS host name.  This is the basic implementation of <a href="http://tools.ietf.org/html/rfc2818">RFC 2818</a> (aka. HTTPS).
21973 </p></dd></dl>
21974
21975 <dl>
21976 <dt><a name="index-x509_002dcertificate_002dissuer_002ddn_002doid"></a>Scheme Procedure: <strong>x509-certificate-issuer-dn-oid</strong> <em>cert index</em></dt>
21977 <dd><p>Return the OID (a string) at <var>index</var> from <var>cert</var>&rsquo;s issuer DN.  Return <code>#f</code> if no OID is available at <var>index</var>.
21978 </p></dd></dl>
21979
21980 <dl>
21981 <dt><a name="index-x509_002dcertificate_002ddn_002doid"></a>Scheme Procedure: <strong>x509-certificate-dn-oid</strong> <em>cert index</em></dt>
21982 <dd><p>Return OID (a string) at <var>index</var> from <var>cert</var>.  Return <code>#f</code> if no OID is available at <var>index</var>.
21983 </p></dd></dl>
21984
21985 <dl>
21986 <dt><a name="index-x509_002dcertificate_002dissuer_002ddn"></a>Scheme Procedure: <strong>x509-certificate-issuer-dn</strong> <em>cert</em></dt>
21987 <dd><p>Return the distinguished name (DN) of X.509 certificate <var>cert</var>.
21988 </p></dd></dl>
21989
21990 <dl>
21991 <dt><a name="index-x509_002dcertificate_002ddn"></a>Scheme Procedure: <strong>x509-certificate-dn</strong> <em>cert</em></dt>
21992 <dd><p>Return the distinguished name (DN) of X.509 certificate <var>cert</var>.  The form of the DN is as described in <a href="http://tools.ietf.org/html/rfc2253">RFC 2253</a>.
21993 </p></dd></dl>
21994
21995 <dl>
21996 <dt><a name="index-pkcs8_002dimport_002dx509_002dprivate_002dkey"></a>Scheme Procedure: <strong>pkcs8-import-x509-private-key</strong> <em>data format [pass [encrypted]]</em></dt>
21997 <dd><p>Return a new X.509 private key object resulting from the import of <var>data</var> (a uniform array) according to <var>format</var>.  Optionally, if <var>pass</var> is not <code>#f</code>, it should be a string denoting a passphrase.  <var>encrypted</var> tells whether the private key is encrypted (<code>#t</code> by default).
21998 </p></dd></dl>
21999
22000 <dl>
22001 <dt><a name="index-import_002dx509_002dprivate_002dkey"></a>Scheme Procedure: <strong>import-x509-private-key</strong> <em>data format</em></dt>
22002 <dd><p>Return a new X.509 private key object resulting from the import of <var>data</var> (a uniform array) according to <var>format</var>.
22003 </p></dd></dl>
22004
22005 <dl>
22006 <dt><a name="index-import_002dx509_002dcertificate"></a>Scheme Procedure: <strong>import-x509-certificate</strong> <em>data format</em></dt>
22007 <dd><p>Return a new X.509 certificate object resulting from the import of <var>data</var> (a uniform array) according to <var>format</var>.
22008 </p></dd></dl>
22009
22010 <dl>
22011 <dt><a name="index-server_002dsession_002dpsk_002dusername"></a>Scheme Procedure: <strong>server-session-psk-username</strong> <em>session</em></dt>
22012 <dd><p>Return the username associated with PSK server session <var>session</var>.
22013 </p></dd></dl>
22014
22015 <dl>
22016 <dt><a name="index-set_002dpsk_002dclient_002dcredentials_0021"></a>Scheme Procedure: <strong>set-psk-client-credentials!</strong> <em>cred username key key-format</em></dt>
22017 <dd><p>Set the client credentials for <var>cred</var>, a PSK client credentials object.
22018 </p></dd></dl>
22019
22020 <dl>
22021 <dt><a name="index-make_002dpsk_002dclient_002dcredentials"></a>Scheme Procedure: <strong>make-psk-client-credentials</strong></dt>
22022 <dd><p>Return a new PSK client credentials object.
22023 </p></dd></dl>
22024
22025 <dl>
22026 <dt><a name="index-set_002dpsk_002dserver_002dcredentials_002dfile_0021"></a>Scheme Procedure: <strong>set-psk-server-credentials-file!</strong> <em>cred file</em></dt>
22027 <dd><p>Use <var>file</var> as the password file for PSK server credentials <var>cred</var>.
22028 </p></dd></dl>
22029
22030 <dl>
22031 <dt><a name="index-make_002dpsk_002dserver_002dcredentials"></a>Scheme Procedure: <strong>make-psk-server-credentials</strong></dt>
22032 <dd><p>Return new PSK server credentials.
22033 </p></dd></dl>
22034
22035 <dl>
22036 <dt><a name="index-peer_002dcertificate_002dstatus"></a>Scheme Procedure: <strong>peer-certificate-status</strong> <em>session</em></dt>
22037 <dd><p>Verify the peer certificate for <var>session</var> and return a list of <code>certificate-status</code> values (such as <code>certificate-status/revoked</code>), or the empty list if the certificate is valid.
22038 </p></dd></dl>
22039
22040 <dl>
22041 <dt><a name="index-set_002dcertificate_002dcredentials_002dverify_002dflags_0021"></a>Scheme Procedure: <strong>set-certificate-credentials-verify-flags!</strong> <em>cred [flags...]</em></dt>
22042 <dd><p>Set the certificate verification flags to <var>flags</var>, a series of <code>certificate-verify</code> values.
22043 </p></dd></dl>
22044
22045 <dl>
22046 <dt><a name="index-set_002dcertificate_002dcredentials_002dverify_002dlimits_0021"></a>Scheme Procedure: <strong>set-certificate-credentials-verify-limits!</strong> <em>cred max-bits max-depth</em></dt>
22047 <dd><p>Set the verification limits of <code>peer-certificate-status</code> for certificate credentials <var>cred</var> to <var>max_bits</var> bits for an acceptable certificate and <var>max_depth</var> as the maximum depth of a certificate chain.
22048 </p></dd></dl>
22049
22050 <dl>
22051 <dt><a name="index-set_002dcertificate_002dcredentials_002dx509_002dkeys_0021"></a>Scheme Procedure: <strong>set-certificate-credentials-x509-keys!</strong> <em>cred certs privkey</em></dt>
22052 <dd><p>Have certificate credentials <var>cred</var> use the X.509 certificates listed in <var>certs</var> and X.509 private key <var>privkey</var>.
22053 </p></dd></dl>
22054
22055 <dl>
22056 <dt><a name="index-set_002dcertificate_002dcredentials_002dx509_002dkey_002ddata_0021"></a>Scheme Procedure: <strong>set-certificate-credentials-x509-key-data!</strong> <em>cred cert key format</em></dt>
22057 <dd><p>Use X.509 certificate <var>cert</var> and private key <var>key</var>, both uniform arrays containing the X.509 certificate and key in format <var>format</var>, for certificate credentials <var>cred</var>.
22058 </p></dd></dl>
22059
22060 <dl>
22061 <dt><a name="index-set_002dcertificate_002dcredentials_002dx509_002dcrl_002ddata_0021"></a>Scheme Procedure: <strong>set-certificate-credentials-x509-crl-data!</strong> <em>cred data format</em></dt>
22062 <dd><p>Use <var>data</var> (a uniform array) as the X.509 CRL (certificate revocation list) database for <var>cred</var>.  On success, return the number of CRLs processed.
22063 </p></dd></dl>
22064
22065 <dl>
22066 <dt><a name="index-set_002dcertificate_002dcredentials_002dx509_002dtrust_002ddata_0021"></a>Scheme Procedure: <strong>set-certificate-credentials-x509-trust-data!</strong> <em>cred data format</em></dt>
22067 <dd><p>Use <var>data</var> (a uniform array) as the X.509 trust database for <var>cred</var>.  On success, return the number of certificates processed.
22068 </p></dd></dl>
22069
22070 <dl>
22071 <dt><a name="index-set_002dcertificate_002dcredentials_002dx509_002dcrl_002dfile_0021"></a>Scheme Procedure: <strong>set-certificate-credentials-x509-crl-file!</strong> <em>cred file format</em></dt>
22072 <dd><p>Use <var>file</var> as the X.509 CRL (certificate revocation list) file for certificate credentials <var>cred</var>.  On success, return the number of CRLs processed.
22073 </p></dd></dl>
22074
22075 <dl>
22076 <dt><a name="index-set_002dcertificate_002dcredentials_002dx509_002dtrust_002dfile_0021"></a>Scheme Procedure: <strong>set-certificate-credentials-x509-trust-file!</strong> <em>cred file format</em></dt>
22077 <dd><p>Use <var>file</var> as the X.509 trust file for certificate credentials <var>cred</var>.  On success, return the number of certificates processed.
22078 </p></dd></dl>
22079
22080 <dl>
22081 <dt><a name="index-set_002dcertificate_002dcredentials_002dx509_002dkey_002dfiles_0021"></a>Scheme Procedure: <strong>set-certificate-credentials-x509-key-files!</strong> <em>cred cert-file key-file format</em></dt>
22082 <dd><p>Use <var>file</var> as the password file for PSK server credentials <var>cred</var>.
22083 </p></dd></dl>
22084
22085 <dl>
22086 <dt><a name="index-set_002dcertificate_002dcredentials_002drsa_002dexport_002dparameters_0021"></a>Scheme Procedure: <strong>set-certificate-credentials-rsa-export-parameters!</strong> <em>cred rsa-params</em></dt>
22087 <dd><p>Use RSA parameters <var>rsa_params</var> for certificate credentials <var>cred</var>.
22088 </p></dd></dl>
22089
22090 <dl>
22091 <dt><a name="index-set_002dcertificate_002dcredentials_002ddh_002dparameters_0021"></a>Scheme Procedure: <strong>set-certificate-credentials-dh-parameters!</strong> <em>cred dh-params</em></dt>
22092 <dd><p>Use Diffie-Hellman parameters <var>dh_params</var> for certificate credentials <var>cred</var>.
22093 </p></dd></dl>
22094
22095 <dl>
22096 <dt><a name="index-make_002dcertificate_002dcredentials"></a>Scheme Procedure: <strong>make-certificate-credentials</strong></dt>
22097 <dd><p>Return new certificate credentials (i.e., for use with either X.509 or OpenPGP certificates.
22098 </p></dd></dl>
22099
22100 <dl>
22101 <dt><a name="index-pkcs1_002dexport_002drsa_002dparameters-1"></a>Scheme Procedure: <strong>pkcs1-export-rsa-parameters</strong> <em>rsa-params format</em></dt>
22102 <dd><p>Export Diffie-Hellman parameters <var>rsa_params</var> in PKCS1 format according for <var>format</var> (an <code>x509-certificate-format</code> value).  Return a <code>u8vector</code> containing the result.
22103 </p></dd></dl>
22104
22105 <dl>
22106 <dt><a name="index-pkcs1_002dimport_002drsa_002dparameters"></a>Scheme Procedure: <strong>pkcs1-import-rsa-parameters</strong> <em>array format</em></dt>
22107 <dd><p>Import Diffie-Hellman parameters in PKCS1 format (further specified by <var>format</var>, an <code>x509-certificate-format</code> value) from <var>array</var> (a homogeneous array) and return a new <code>rsa-params</code> object.
22108 </p></dd></dl>
22109
22110 <dl>
22111 <dt><a name="index-make_002drsa_002dparameters-1"></a>Scheme Procedure: <strong>make-rsa-parameters</strong> <em>bits</em></dt>
22112 <dd><p>Return new RSA parameters.
22113 </p></dd></dl>
22114
22115 <dl>
22116 <dt><a name="index-set_002danonymous_002dserver_002ddh_002dparameters_0021"></a>Scheme Procedure: <strong>set-anonymous-server-dh-parameters!</strong> <em>cred dh-params</em></dt>
22117 <dd><p>Set the Diffie-Hellman parameters of anonymous server credentials <var>cred</var>.
22118 </p></dd></dl>
22119
22120 <dl>
22121 <dt><a name="index-make_002danonymous_002dclient_002dcredentials"></a>Scheme Procedure: <strong>make-anonymous-client-credentials</strong></dt>
22122 <dd><p>Return anonymous client credentials.
22123 </p></dd></dl>
22124
22125 <dl>
22126 <dt><a name="index-make_002danonymous_002dserver_002dcredentials"></a>Scheme Procedure: <strong>make-anonymous-server-credentials</strong></dt>
22127 <dd><p>Return anonymous server credentials.
22128 </p></dd></dl>
22129
22130 <dl>
22131 <dt><a name="index-set_002dsession_002ddh_002dprime_002dbits_0021"></a>Scheme Procedure: <strong>set-session-dh-prime-bits!</strong> <em>session bits</em></dt>
22132 <dd><p>Use <var>bits</var> DH prime bits for <var>session</var>.
22133 </p></dd></dl>
22134
22135 <dl>
22136 <dt><a name="index-pkcs3_002dexport_002ddh_002dparameters"></a>Scheme Procedure: <strong>pkcs3-export-dh-parameters</strong> <em>dh-params format</em></dt>
22137 <dd><p>Export Diffie-Hellman parameters <var>dh_params</var> in PKCS3 format according for <var>format</var> (an <code>x509-certificate-format</code> value).  Return a <code>u8vector</code> containing the result.
22138 </p></dd></dl>
22139
22140 <dl>
22141 <dt><a name="index-pkcs3_002dimport_002ddh_002dparameters"></a>Scheme Procedure: <strong>pkcs3-import-dh-parameters</strong> <em>array format</em></dt>
22142 <dd><p>Import Diffie-Hellman parameters in PKCS3 format (further specified by <var>format</var>, an <code>x509-certificate-format</code> value) from <var>array</var> (a homogeneous array) and return a new <code>dh-params</code> object.
22143 </p></dd></dl>
22144
22145 <dl>
22146 <dt><a name="index-make_002ddh_002dparameters"></a>Scheme Procedure: <strong>make-dh-parameters</strong> <em>bits</em></dt>
22147 <dd><p>Return new Diffie-Hellman parameters.
22148 </p></dd></dl>
22149
22150 <dl>
22151 <dt><a name="index-set_002dsession_002dtransport_002dport_0021-1"></a>Scheme Procedure: <strong>set-session-transport-port!</strong> <em>session port</em></dt>
22152 <dd><p>Use <var>port</var> as the input/output port for <var>session</var>.
22153 </p></dd></dl>
22154
22155 <dl>
22156 <dt><a name="index-set_002dsession_002dtransport_002dfd_0021-1"></a>Scheme Procedure: <strong>set-session-transport-fd!</strong> <em>session fd</em></dt>
22157 <dd><p>Use file descriptor <var>fd</var> as the underlying transport for <var>session</var>.
22158 </p></dd></dl>
22159
22160 <dl>
22161 <dt><a name="index-session_002drecord_002dport-1"></a>Scheme Procedure: <strong>session-record-port</strong> <em>session</em></dt>
22162 <dd><p>Return a read-write port that may be used to communicate over <var>session</var>.  All invocations of <code>session-port</code> on a given session return the same object (in the sense of <code>eq?</code>).
22163 </p></dd></dl>
22164
22165 <dl>
22166 <dt><a name="index-record_002dreceive_0021-1"></a>Scheme Procedure: <strong>record-receive!</strong> <em>session array</em></dt>
22167 <dd><p>Receive data from <var>session</var> into <var>array</var>, a uniform homogeneous array.  Return the number of bytes actually received.
22168 </p></dd></dl>
22169
22170 <dl>
22171 <dt><a name="index-record_002dsend-1"></a>Scheme Procedure: <strong>record-send</strong> <em>session array</em></dt>
22172 <dd><p>Send the record constituted by <var>array</var> through <var>session</var>.
22173 </p></dd></dl>
22174
22175 <dl>
22176 <dt><a name="index-set_002dsession_002dcredentials_0021"></a>Scheme Procedure: <strong>set-session-credentials!</strong> <em>session cred</em></dt>
22177 <dd><p>Use <var>cred</var> as <var>session</var>&rsquo;s credentials.
22178 </p></dd></dl>
22179
22180 <dl>
22181 <dt><a name="index-cipher_002dsuite_002d_003estring"></a>Scheme Procedure: <strong>cipher-suite-&gt;string</strong> <em>kx cipher mac</em></dt>
22182 <dd><p>Return the name of the given cipher suite.
22183 </p></dd></dl>
22184
22185 <dl>
22186 <dt><a name="index-set_002dsession_002ddefault_002dexport_002dpriority_0021"></a>Scheme Procedure: <strong>set-session-default-export-priority!</strong> <em>session</em></dt>
22187 <dd><p>Have <var>session</var> use the default export priorities.
22188 </p></dd></dl>
22189
22190 <dl>
22191 <dt><a name="index-set_002dsession_002ddefault_002dpriority_0021"></a>Scheme Procedure: <strong>set-session-default-priority!</strong> <em>session</em></dt>
22192 <dd><p>Have <var>session</var> use the default priorities.
22193 </p></dd></dl>
22194
22195 <dl>
22196 <dt><a name="index-set_002dsession_002dcertificate_002dtype_002dpriority_0021"></a>Scheme Procedure: <strong>set-session-certificate-type-priority!</strong> <em>session items</em></dt>
22197 <dd><p>Use <var>items</var> (a list) as the list of preferred certificate-type for <var>session</var>.
22198 </p></dd></dl>
22199
22200 <dl>
22201 <dt><a name="index-set_002dsession_002dprotocol_002dpriority_0021"></a>Scheme Procedure: <strong>set-session-protocol-priority!</strong> <em>session items</em></dt>
22202 <dd><p>Use <var>items</var> (a list) as the list of preferred protocol for <var>session</var>.
22203 </p></dd></dl>
22204
22205 <dl>
22206 <dt><a name="index-set_002dsession_002dkx_002dpriority_0021"></a>Scheme Procedure: <strong>set-session-kx-priority!</strong> <em>session items</em></dt>
22207 <dd><p>Use <var>items</var> (a list) as the list of preferred kx for <var>session</var>.
22208 </p></dd></dl>
22209
22210 <dl>
22211 <dt><a name="index-set_002dsession_002dcompression_002dmethod_002dpriority_0021"></a>Scheme Procedure: <strong>set-session-compression-method-priority!</strong> <em>session items</em></dt>
22212 <dd><p>Use <var>items</var> (a list) as the list of preferred compression-method for <var>session</var>.
22213 </p></dd></dl>
22214
22215 <dl>
22216 <dt><a name="index-set_002dsession_002dmac_002dpriority_0021"></a>Scheme Procedure: <strong>set-session-mac-priority!</strong> <em>session items</em></dt>
22217 <dd><p>Use <var>items</var> (a list) as the list of preferred mac for <var>session</var>.
22218 </p></dd></dl>
22219
22220 <dl>
22221 <dt><a name="index-set_002dsession_002dcipher_002dpriority_0021"></a>Scheme Procedure: <strong>set-session-cipher-priority!</strong> <em>session items</em></dt>
22222 <dd><p>Use <var>items</var> (a list) as the list of preferred cipher for <var>session</var>.
22223 </p></dd></dl>
22224
22225 <dl>
22226 <dt><a name="index-set_002dserver_002dsession_002dcertificate_002drequest_0021"></a>Scheme Procedure: <strong>set-server-session-certificate-request!</strong> <em>session request</em></dt>
22227 <dd><p>Tell how <var>session</var>, a server-side session, should deal with certificate requests.  <var>request</var> should be either <code>certificate-request/request</code> or <code>certificate-request/require</code>.
22228 </p></dd></dl>
22229
22230 <dl>
22231 <dt><a name="index-session_002dour_002dcertificate_002dchain"></a>Scheme Procedure: <strong>session-our-certificate-chain</strong> <em>session</em></dt>
22232 <dd><p>Return our certificate chain for <var>session</var> (as sent to the peer) in raw format (a u8vector).  In the case of OpenPGP there is exactly one certificate.  Return the empty list if no certificate was used.
22233 </p></dd></dl>
22234
22235 <dl>
22236 <dt><a name="index-session_002dpeer_002dcertificate_002dchain"></a>Scheme Procedure: <strong>session-peer-certificate-chain</strong> <em>session</em></dt>
22237 <dd><p>Return the a list of certificates in raw format (u8vectors) where the first one is the peer&rsquo;s certificate.  In the case of OpenPGP, there is always exactly one certificate.  In the case of X.509, subsequent certificates indicate form a certificate chain.  Return the empty list if no certificate was sent.
22238 </p></dd></dl>
22239
22240 <dl>
22241 <dt><a name="index-session_002dclient_002dauthentication_002dtype"></a>Scheme Procedure: <strong>session-client-authentication-type</strong> <em>session</em></dt>
22242 <dd><p>Return the client authentication type (a <code>credential-type</code> value) used in <var>session</var>.
22243 </p></dd></dl>
22244
22245 <dl>
22246 <dt><a name="index-session_002dserver_002dauthentication_002dtype"></a>Scheme Procedure: <strong>session-server-authentication-type</strong> <em>session</em></dt>
22247 <dd><p>Return the server authentication type (a <code>credential-type</code> value) used in <var>session</var>.
22248 </p></dd></dl>
22249
22250 <dl>
22251 <dt><a name="index-session_002dauthentication_002dtype"></a>Scheme Procedure: <strong>session-authentication-type</strong> <em>session</em></dt>
22252 <dd><p>Return the authentication type (a <code>credential-type</code> value) used by <var>session</var>.
22253 </p></dd></dl>
22254
22255 <dl>
22256 <dt><a name="index-session_002dprotocol"></a>Scheme Procedure: <strong>session-protocol</strong> <em>session</em></dt>
22257 <dd><p>Return the protocol used by <var>session</var>.
22258 </p></dd></dl>
22259
22260 <dl>
22261 <dt><a name="index-session_002dcertificate_002dtype"></a>Scheme Procedure: <strong>session-certificate-type</strong> <em>session</em></dt>
22262 <dd><p>Return <var>session</var>&rsquo;s certificate type.
22263 </p></dd></dl>
22264
22265 <dl>
22266 <dt><a name="index-session_002dcompression_002dmethod"></a>Scheme Procedure: <strong>session-compression-method</strong> <em>session</em></dt>
22267 <dd><p>Return <var>session</var>&rsquo;s compression method.
22268 </p></dd></dl>
22269
22270 <dl>
22271 <dt><a name="index-session_002dmac"></a>Scheme Procedure: <strong>session-mac</strong> <em>session</em></dt>
22272 <dd><p>Return <var>session</var>&rsquo;s MAC.
22273 </p></dd></dl>
22274
22275 <dl>
22276 <dt><a name="index-session_002dkx"></a>Scheme Procedure: <strong>session-kx</strong> <em>session</em></dt>
22277 <dd><p>Return <var>session</var>&rsquo;s kx.
22278 </p></dd></dl>
22279
22280 <dl>
22281 <dt><a name="index-session_002dcipher-1"></a>Scheme Procedure: <strong>session-cipher</strong> <em>session</em></dt>
22282 <dd><p>Return <var>session</var>&rsquo;s cipher.
22283 </p></dd></dl>
22284
22285 <dl>
22286 <dt><a name="index-alert_002dsend"></a>Scheme Procedure: <strong>alert-send</strong> <em>session level alert</em></dt>
22287 <dd><p>Send <var>alert</var> via <var>session</var>.
22288 </p></dd></dl>
22289
22290 <dl>
22291 <dt><a name="index-alert_002dget"></a>Scheme Procedure: <strong>alert-get</strong> <em>session</em></dt>
22292 <dd><p>Get an aleter from <var>session</var>.
22293 </p></dd></dl>
22294
22295 <dl>
22296 <dt><a name="index-rehandshake"></a>Scheme Procedure: <strong>rehandshake</strong> <em>session</em></dt>
22297 <dd><p>Perform a re-handshaking for <var>session</var>.
22298 </p></dd></dl>
22299
22300 <dl>
22301 <dt><a name="index-handshake"></a>Scheme Procedure: <strong>handshake</strong> <em>session</em></dt>
22302 <dd><p>Perform a handshake for <var>session</var>.
22303 </p></dd></dl>
22304
22305 <dl>
22306 <dt><a name="index-bye"></a>Scheme Procedure: <strong>bye</strong> <em>session how</em></dt>
22307 <dd><p>Close <var>session</var> according to <var>how</var>.
22308 </p></dd></dl>
22309
22310 <dl>
22311 <dt><a name="index-make_002dsession"></a>Scheme Procedure: <strong>make-session</strong> <em>end</em></dt>
22312 <dd><p>Return a new session for connection end <var>end</var>, either <code>connection-end/server</code> or <code>connection-end/client</code>.
22313 </p></dd></dl>
22314
22315 <dl>
22316 <dt><a name="index-gnutls_002dversion"></a>Scheme Procedure: <strong>gnutls-version</strong></dt>
22317 <dd><p>Return a string denoting the version number of the underlying GnuTLS library, e.g., <code>&quot;1.7.2&quot;</code>.
22318 </p></dd></dl>
22319
22320 <dl>
22321 <dt><a name="index-x509_002dprivate_002dkey_003f"></a>Scheme Procedure: <strong>x509-private-key?</strong> <em>obj</em></dt>
22322 <dd><p>Return true if <var>obj</var> is of type <code>x509-private-key</code>.
22323 </p></dd></dl>
22324
22325 <dl>
22326 <dt><a name="index-x509_002dcertificate_003f"></a>Scheme Procedure: <strong>x509-certificate?</strong> <em>obj</em></dt>
22327 <dd><p>Return true if <var>obj</var> is of type <code>x509-certificate</code>.
22328 </p></dd></dl>
22329
22330 <dl>
22331 <dt><a name="index-psk_002dclient_002dcredentials_003f"></a>Scheme Procedure: <strong>psk-client-credentials?</strong> <em>obj</em></dt>
22332 <dd><p>Return true if <var>obj</var> is of type <code>psk-client-credentials</code>.
22333 </p></dd></dl>
22334
22335 <dl>
22336 <dt><a name="index-psk_002dserver_002dcredentials_003f"></a>Scheme Procedure: <strong>psk-server-credentials?</strong> <em>obj</em></dt>
22337 <dd><p>Return true if <var>obj</var> is of type <code>psk-server-credentials</code>.
22338 </p></dd></dl>
22339
22340 <dl>
22341 <dt><a name="index-srp_002dclient_002dcredentials_003f"></a>Scheme Procedure: <strong>srp-client-credentials?</strong> <em>obj</em></dt>
22342 <dd><p>Return true if <var>obj</var> is of type <code>srp-client-credentials</code>.
22343 </p></dd></dl>
22344
22345 <dl>
22346 <dt><a name="index-srp_002dserver_002dcredentials_003f"></a>Scheme Procedure: <strong>srp-server-credentials?</strong> <em>obj</em></dt>
22347 <dd><p>Return true if <var>obj</var> is of type <code>srp-server-credentials</code>.
22348 </p></dd></dl>
22349
22350 <dl>
22351 <dt><a name="index-certificate_002dcredentials_003f"></a>Scheme Procedure: <strong>certificate-credentials?</strong> <em>obj</em></dt>
22352 <dd><p>Return true if <var>obj</var> is of type <code>certificate-credentials</code>.
22353 </p></dd></dl>
22354
22355 <dl>
22356 <dt><a name="index-rsa_002dparameters_003f"></a>Scheme Procedure: <strong>rsa-parameters?</strong> <em>obj</em></dt>
22357 <dd><p>Return true if <var>obj</var> is of type <code>rsa-parameters</code>.
22358 </p></dd></dl>
22359
22360 <dl>
22361 <dt><a name="index-dh_002dparameters_003f"></a>Scheme Procedure: <strong>dh-parameters?</strong> <em>obj</em></dt>
22362 <dd><p>Return true if <var>obj</var> is of type <code>dh-parameters</code>.
22363 </p></dd></dl>
22364
22365 <dl>
22366 <dt><a name="index-anonymous_002dserver_002dcredentials_003f"></a>Scheme Procedure: <strong>anonymous-server-credentials?</strong> <em>obj</em></dt>
22367 <dd><p>Return true if <var>obj</var> is of type <code>anonymous-server-credentials</code>.
22368 </p></dd></dl>
22369
22370 <dl>
22371 <dt><a name="index-anonymous_002dclient_002dcredentials_003f"></a>Scheme Procedure: <strong>anonymous-client-credentials?</strong> <em>obj</em></dt>
22372 <dd><p>Return true if <var>obj</var> is of type <code>anonymous-client-credentials</code>.
22373 </p></dd></dl>
22374
22375 <dl>
22376 <dt><a name="index-session_003f"></a>Scheme Procedure: <strong>session?</strong> <em>obj</em></dt>
22377 <dd><p>Return true if <var>obj</var> is of type <code>session</code>.
22378 </p></dd></dl>
22379
22380 <dl>
22381 <dt><a name="index-error_002d_003estring-1"></a>Scheme Procedure: <strong>error-&gt;string</strong> <em>enumval</em></dt>
22382 <dd><p>Return a string describing <var>enumval</var>, a <code>error</code> value.
22383 </p></dd></dl>
22384
22385 <dl>
22386 <dt><a name="index-certificate_002dverify_002d_003estring"></a>Scheme Procedure: <strong>certificate-verify-&gt;string</strong> <em>enumval</em></dt>
22387 <dd><p>Return a string describing <var>enumval</var>, a <code>certificate-verify</code> value.
22388 </p></dd></dl>
22389
22390 <dl>
22391 <dt><a name="index-key_002dusage_002d_003estring"></a>Scheme Procedure: <strong>key-usage-&gt;string</strong> <em>enumval</em></dt>
22392 <dd><p>Return a string describing <var>enumval</var>, a <code>key-usage</code> value.
22393 </p></dd></dl>
22394
22395 <dl>
22396 <dt><a name="index-psk_002dkey_002dformat_002d_003estring"></a>Scheme Procedure: <strong>psk-key-format-&gt;string</strong> <em>enumval</em></dt>
22397 <dd><p>Return a string describing <var>enumval</var>, a <code>psk-key-format</code> value.
22398 </p></dd></dl>
22399
22400 <dl>
22401 <dt><a name="index-sign_002dalgorithm_002d_003estring"></a>Scheme Procedure: <strong>sign-algorithm-&gt;string</strong> <em>enumval</em></dt>
22402 <dd><p>Return a string describing <var>enumval</var>, a <code>sign-algorithm</code> value.
22403 </p></dd></dl>
22404
22405 <dl>
22406 <dt><a name="index-pk_002dalgorithm_002d_003estring"></a>Scheme Procedure: <strong>pk-algorithm-&gt;string</strong> <em>enumval</em></dt>
22407 <dd><p>Return a string describing <var>enumval</var>, a <code>pk-algorithm</code> value.
22408 </p></dd></dl>
22409
22410 <dl>
22411 <dt><a name="index-x509_002dsubject_002dalternative_002dname_002d_003estring"></a>Scheme Procedure: <strong>x509-subject-alternative-name-&gt;string</strong> <em>enumval</em></dt>
22412 <dd><p>Return a string describing <var>enumval</var>, a <code>x509-subject-alternative-name</code> value.
22413 </p></dd></dl>
22414
22415 <dl>
22416 <dt><a name="index-x509_002dcertificate_002dformat_002d_003estring"></a>Scheme Procedure: <strong>x509-certificate-format-&gt;string</strong> <em>enumval</em></dt>
22417 <dd><p>Return a string describing <var>enumval</var>, a <code>x509-certificate-format</code> value.
22418 </p></dd></dl>
22419
22420 <dl>
22421 <dt><a name="index-certificate_002dtype_002d_003estring"></a>Scheme Procedure: <strong>certificate-type-&gt;string</strong> <em>enumval</em></dt>
22422 <dd><p>Return a string describing <var>enumval</var>, a <code>certificate-type</code> value.
22423 </p></dd></dl>
22424
22425 <dl>
22426 <dt><a name="index-protocol_002d_003estring"></a>Scheme Procedure: <strong>protocol-&gt;string</strong> <em>enumval</em></dt>
22427 <dd><p>Return a string describing <var>enumval</var>, a <code>protocol</code> value.
22428 </p></dd></dl>
22429
22430 <dl>
22431 <dt><a name="index-close_002drequest_002d_003estring"></a>Scheme Procedure: <strong>close-request-&gt;string</strong> <em>enumval</em></dt>
22432 <dd><p>Return a string describing <var>enumval</var>, a <code>close-request</code> value.
22433 </p></dd></dl>
22434
22435 <dl>
22436 <dt><a name="index-certificate_002drequest_002d_003estring"></a>Scheme Procedure: <strong>certificate-request-&gt;string</strong> <em>enumval</em></dt>
22437 <dd><p>Return a string describing <var>enumval</var>, a <code>certificate-request</code> value.
22438 </p></dd></dl>
22439
22440 <dl>
22441 <dt><a name="index-certificate_002dstatus_002d_003estring"></a>Scheme Procedure: <strong>certificate-status-&gt;string</strong> <em>enumval</em></dt>
22442 <dd><p>Return a string describing <var>enumval</var>, a <code>certificate-status</code> value.
22443 </p></dd></dl>
22444
22445 <dl>
22446 <dt><a name="index-handshake_002ddescription_002d_003estring"></a>Scheme Procedure: <strong>handshake-description-&gt;string</strong> <em>enumval</em></dt>
22447 <dd><p>Return a string describing <var>enumval</var>, a <code>handshake-description</code> value.
22448 </p></dd></dl>
22449
22450 <dl>
22451 <dt><a name="index-alert_002ddescription_002d_003estring"></a>Scheme Procedure: <strong>alert-description-&gt;string</strong> <em>enumval</em></dt>
22452 <dd><p>Return a string describing <var>enumval</var>, a <code>alert-description</code> value.
22453 </p></dd></dl>
22454
22455 <dl>
22456 <dt><a name="index-alert_002dlevel_002d_003estring"></a>Scheme Procedure: <strong>alert-level-&gt;string</strong> <em>enumval</em></dt>
22457 <dd><p>Return a string describing <var>enumval</var>, a <code>alert-level</code> value.
22458 </p></dd></dl>
22459
22460 <dl>
22461 <dt><a name="index-connection_002dend_002d_003estring"></a>Scheme Procedure: <strong>connection-end-&gt;string</strong> <em>enumval</em></dt>
22462 <dd><p>Return a string describing <var>enumval</var>, a <code>connection-end</code> value.
22463 </p></dd></dl>
22464
22465 <dl>
22466 <dt><a name="index-compression_002dmethod_002d_003estring"></a>Scheme Procedure: <strong>compression-method-&gt;string</strong> <em>enumval</em></dt>
22467 <dd><p>Return a string describing <var>enumval</var>, a <code>compression-method</code> value.
22468 </p></dd></dl>
22469
22470 <dl>
22471 <dt><a name="index-digest_002d_003estring"></a>Scheme Procedure: <strong>digest-&gt;string</strong> <em>enumval</em></dt>
22472 <dd><p>Return a string describing <var>enumval</var>, a <code>digest</code> value.
22473 </p></dd></dl>
22474
22475 <dl>
22476 <dt><a name="index-mac_002d_003estring"></a>Scheme Procedure: <strong>mac-&gt;string</strong> <em>enumval</em></dt>
22477 <dd><p>Return a string describing <var>enumval</var>, a <code>mac</code> value.
22478 </p></dd></dl>
22479
22480 <dl>
22481 <dt><a name="index-credentials_002d_003estring"></a>Scheme Procedure: <strong>credentials-&gt;string</strong> <em>enumval</em></dt>
22482 <dd><p>Return a string describing <var>enumval</var>, a <code>credentials</code> value.
22483 </p></dd></dl>
22484
22485 <dl>
22486 <dt><a name="index-params_002d_003estring"></a>Scheme Procedure: <strong>params-&gt;string</strong> <em>enumval</em></dt>
22487 <dd><p>Return a string describing <var>enumval</var>, a <code>params</code> value.
22488 </p></dd></dl>
22489
22490 <dl>
22491 <dt><a name="index-kx_002d_003estring"></a>Scheme Procedure: <strong>kx-&gt;string</strong> <em>enumval</em></dt>
22492 <dd><p>Return a string describing <var>enumval</var>, a <code>kx</code> value.
22493 </p></dd></dl>
22494
22495 <dl>
22496 <dt><a name="index-cipher_002d_003estring"></a>Scheme Procedure: <strong>cipher-&gt;string</strong> <em>enumval</em></dt>
22497 <dd><p>Return a string describing <var>enumval</var>, a <code>cipher</code> value.
22498 </p></dd></dl>
22499
22500 <hr>
22501 <a name="Extra-Interface"></a>
22502 <div class="header">
22503 <p>
22504 Previous: <a href="#Core-Interface" accesskey="p" rel="previous">Core Interface</a>, Up: <a href="#Guile-Reference" accesskey="u" rel="up">Guile 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>
22505 </div>
22506 <a name="Extra-Interface-1"></a>
22507 <h4 class="subsection">11.4.2 Extra Interface</h4>
22508
22509 <p>This section lists the Scheme procedures exported by the <code>(gnutls
22510 extra)</code> module.  This module is licenced under the GNU General Public
22511 Licence, version 3 or later.
22512 </p>
22513
22514 <dl>
22515 <dt><a name="index-set_002dcertificate_002dcredentials_002dopenpgp_002dkeys_0021"></a>Scheme Procedure: <strong>set-certificate-credentials-openpgp-keys!</strong> <em>cred pub sec</em></dt>
22516 <dd><p>Use certificate <var>pub</var> and secret key <var>sec</var> in certificate credentials <var>cred</var>.
22517 </p></dd></dl>
22518
22519 <dl>
22520 <dt><a name="index-openpgp_002dkeyring_002dcontains_002dkey_002did_003f"></a>Scheme Procedure: <strong>openpgp-keyring-contains-key-id?</strong> <em>keyring id</em></dt>
22521 <dd><p>Return <code>#f</code> if key ID <var>id</var> is in <var>keyring</var>, <code>#f</code> otherwise.
22522 </p></dd></dl>
22523
22524 <dl>
22525 <dt><a name="index-import_002dopenpgp_002dkeyring"></a>Scheme Procedure: <strong>import-openpgp-keyring</strong> <em>data format</em></dt>
22526 <dd><p>Import <var>data</var> (a u8vector) according to <var>format</var> and return the imported keyring.
22527 </p></dd></dl>
22528
22529 <dl>
22530 <dt><a name="index-openpgp_002dcertificate_002dusage"></a>Scheme Procedure: <strong>openpgp-certificate-usage</strong> <em>key</em></dt>
22531 <dd><p>Return a list of values denoting the key usage of <var>key</var>.
22532 </p></dd></dl>
22533
22534 <dl>
22535 <dt><a name="index-openpgp_002dcertificate_002dversion"></a>Scheme Procedure: <strong>openpgp-certificate-version</strong> <em>key</em></dt>
22536 <dd><p>Return the version of the OpenPGP message format (RFC2440) honored by <var>key</var>.
22537 </p></dd></dl>
22538
22539 <dl>
22540 <dt><a name="index-openpgp_002dcertificate_002dalgorithm"></a>Scheme Procedure: <strong>openpgp-certificate-algorithm</strong> <em>key</em></dt>
22541 <dd><p>Return two values: the certificate algorithm used by <var>key</var> and the number of bits used.
22542 </p></dd></dl>
22543
22544 <dl>
22545 <dt><a name="index-openpgp_002dcertificate_002dnames"></a>Scheme Procedure: <strong>openpgp-certificate-names</strong> <em>key</em></dt>
22546 <dd><p>Return the list of names for <var>key</var>.
22547 </p></dd></dl>
22548
22549 <dl>
22550 <dt><a name="index-openpgp_002dcertificate_002dname"></a>Scheme Procedure: <strong>openpgp-certificate-name</strong> <em>key index</em></dt>
22551 <dd><p>Return the <var>index</var>th name of <var>key</var>.
22552 </p></dd></dl>
22553
22554 <dl>
22555 <dt><a name="index-openpgp_002dcertificate_002dfingerprint"></a>Scheme Procedure: <strong>openpgp-certificate-fingerprint</strong> <em>key</em></dt>
22556 <dd><p>Return a new u8vector denoting the fingerprint of <var>key</var>.
22557 </p></dd></dl>
22558
22559 <dl>
22560 <dt><a name="index-openpgp_002dcertificate_002dfingerprint_0021"></a>Scheme Procedure: <strong>openpgp-certificate-fingerprint!</strong> <em>key fpr</em></dt>
22561 <dd><p>Store in <var>fpr</var> (a u8vector) the fingerprint of <var>key</var>.  Return the number of bytes stored in <var>fpr</var>.
22562 </p></dd></dl>
22563
22564 <dl>
22565 <dt><a name="index-openpgp_002dcertificate_002did_0021"></a>Scheme Procedure: <strong>openpgp-certificate-id!</strong> <em>key id</em></dt>
22566 <dd><p>Store the ID (an 8 byte sequence) of certificate <var>key</var> in <var>id</var> (a u8vector).
22567 </p></dd></dl>
22568
22569 <dl>
22570 <dt><a name="index-openpgp_002dcertificate_002did"></a>Scheme Procedure: <strong>openpgp-certificate-id</strong> <em>key</em></dt>
22571 <dd><p>Return the ID (an 8-element u8vector) of certificate <var>key</var>.
22572 </p></dd></dl>
22573
22574 <dl>
22575 <dt><a name="index-import_002dopenpgp_002dprivate_002dkey"></a>Scheme Procedure: <strong>import-openpgp-private-key</strong> <em>data format [pass]</em></dt>
22576 <dd><p>Return a new OpenPGP private key object resulting from the import of <var>data</var> (a uniform array) according to <var>format</var>.  Optionally, a passphrase may be provided.
22577 </p></dd></dl>
22578
22579 <dl>
22580 <dt><a name="index-import_002dopenpgp_002dcertificate"></a>Scheme Procedure: <strong>import-openpgp-certificate</strong> <em>data format</em></dt>
22581 <dd><p>Return a new OpenPGP certificate object resulting from the import of <var>data</var> (a uniform array) according to <var>format</var>.
22582 </p></dd></dl>
22583
22584 <dl>
22585 <dt><a name="index-openpgp_002dcertificate_002dformat_002d_003estring"></a>Scheme Procedure: <strong>openpgp-certificate-format-&gt;string</strong> <em>enumval</em></dt>
22586 <dd><p>Return a string describing <var>enumval</var>, a <code>openpgp-certificate-format</code> value.
22587 </p></dd></dl>
22588
22589 <dl>
22590 <dt><a name="index-openpgp_002dkeyring_003f"></a>Scheme Procedure: <strong>openpgp-keyring?</strong> <em>obj</em></dt>
22591 <dd><p>Return true if <var>obj</var> is of type <code>openpgp-keyring</code>.
22592 </p></dd></dl>
22593
22594 <dl>
22595 <dt><a name="index-openpgp_002dprivate_002dkey_003f"></a>Scheme Procedure: <strong>openpgp-private-key?</strong> <em>obj</em></dt>
22596 <dd><p>Return true if <var>obj</var> is of type <code>openpgp-private-key</code>.
22597 </p></dd></dl>
22598
22599 <dl>
22600 <dt><a name="index-openpgp_002dcertificate_003f"></a>Scheme Procedure: <strong>openpgp-certificate?</strong> <em>obj</em></dt>
22601 <dd><p>Return true if <var>obj</var> is of type <code>openpgp-certificate</code>.
22602 </p></dd></dl>
22603
22604
22605
22606
22607
22608 <hr>
22609 <a name="Internal-architecture-of-GnuTLS"></a>
22610 <div class="header">
22611 <p>
22612 Next: <a href="#Copying-Information" accesskey="n" rel="next">Copying Information</a>, Previous: <a href="#Guile-Bindings" accesskey="p" rel="previous">Guile Bindings</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>
22613 </div>
22614 <a name="Internal-Architecture-of-GnuTLS"></a>
22615 <h2 class="chapter">12 Internal Architecture of GnuTLS</h2>
22616 <a name="index-Internal-architecture"></a>
22617
22618 <p>This chapter is to give a brief description of the
22619 way <acronym>GnuTLS</acronym> works. The focus is to give an idea
22620 to potential developers and those who want to know what
22621 happens inside the black box.
22622 </p>
22623 <table class="menu" border="0" cellspacing="0">
22624 <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">
22625 </td></tr>
22626 <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">
22627 </td></tr>
22628 <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">
22629 </td></tr>
22630 <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">
22631 </td></tr>
22632 <tr><td align="left" valign="top">&bull; <a href="#Certificate-Handling" accesskey="5">Certificate Handling</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
22633 </td></tr>
22634 <tr><td align="left" valign="top">&bull; <a href="#Cryptographic-Backend" accesskey="6">Cryptographic Backend</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
22635 </td></tr>
22636 </table>
22637
22638 <hr>
22639 <a name="The-TLS-Protocol"></a>
22640 <div class="header">
22641 <p>
22642 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>
22643 </div>
22644 <a name="The-TLS-Protocol-1"></a>
22645 <h3 class="section">12.1 The TLS Protocol</h3>
22646 <p>The main needs for the TLS protocol to be used are
22647 shown in the image below.
22648 </p>
22649 <img src="gnutls-client-server-use-case.png" alt="gnutls-client-server-use-case">
22650
22651 <p>This is being accomplished by the following object diagram.
22652 Note that since <acronym>GnuTLS</acronym> is being developed in C
22653 object are just structures with attributes. The operations listed
22654 are functions that require the first parameter to be that object.
22655 <img src="gnutls-objects.png" alt="gnutls-objects">
22656 </p>
22657 <hr>
22658 <a name="TLS-Handshake-Protocol"></a>
22659 <div class="header">
22660 <p>
22661 Next: <a href="#TLS-Authentication-Methods" accesskey="n" rel="next">TLS Authentication Methods</a>, Previous: <a href="#The-TLS-Protocol" accesskey="p" rel="previous">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>
22662 </div>
22663 <a name="TLS-Handshake-Protocol-1"></a>
22664 <h3 class="section">12.2 TLS Handshake Protocol</h3>
22665 <p>The <acronym>GnuTLS</acronym> handshake protocol is implemented as a state
22666 machine that waits for input or returns immediately when the non-blocking
22667 transport layer functions are used. The main idea is shown in the following
22668 figure.
22669 </p>
22670 <img src="gnutls-handshake-state.png" alt="gnutls-handshake-state">
22671
22672 <p>Also the way the input is processed varies per ciphersuite. Several
22673 implementations of the internal handlers are available and
22674 <a href="#gnutls_005fhandshake">gnutls_handshake</a> only multiplexes the input to the appropriate
22675 handler. For example a <acronym>PSK</acronym> ciphersuite has a different
22676 implementation of the <code>process_client_key_exchange</code> than a
22677 certificate ciphersuite.
22678 </p>
22679 <img src="gnutls-handshake-sequence.png" alt="gnutls-handshake-sequence">
22680
22681 <hr>
22682 <a name="TLS-Authentication-Methods"></a>
22683 <div class="header">
22684 <p>
22685 Next: <a href="#TLS-Extension-Handling" accesskey="n" rel="next">TLS Extension Handling</a>, Previous: <a href="#TLS-Handshake-Protocol" accesskey="p" rel="previous">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>
22686 </div>
22687 <a name="TLS-Authentication-Methods-1"></a>
22688 <h3 class="section">12.3 TLS Authentication Methods</h3>
22689 <p>In <acronym>GnuTLS</acronym> authentication methods can be implemented quite
22690 easily.  Since the required changes to add a new authentication method
22691 affect only the handshake protocol, a simple interface is used. An
22692 authentication method needs only to implement the functions as seen in
22693 the figure below.
22694 </p>
22695 <img src="gnutls-mod_auth_st.png" alt="gnutls-mod_auth_st">
22696
22697 <p>The functions that need to be implemented are the ones responsible for
22698 interpreting the handshake protocol messages. It is common for such
22699 functions to read data from one or more <code>credentials_t</code>
22700 structures<a name="DOCF20" href="#FOOT20">(20)</a> and write data,
22701 such as certificates, usernames etc. to <code>auth_info_t</code> structures.
22702 </p>
22703 <p>Simple examples of existing authentication methods can be seen in
22704 <code>auth_psk.c</code> for PSK ciphersuites and <code>auth_srp.c</code> for SRP
22705 ciphersuites. After implementing these functions the structure holding
22706 its pointers has to be registered in <code>gnutls_algorithms.c</code> in the
22707 <code>_gnutls_kx_algorithms</code> structure.
22708 </p>
22709 <hr>
22710 <a name="TLS-Extension-Handling"></a>
22711 <div class="header">
22712 <p>
22713 Next: <a href="#Certificate-Handling" accesskey="n" rel="next">Certificate Handling</a>, Previous: <a href="#TLS-Authentication-Methods" accesskey="p" rel="previous">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>
22714 </div>
22715 <a name="TLS-Extension-Handling-1"></a>
22716 <h3 class="section">12.4 TLS Extension Handling</h3>
22717 <p>As with authentication methods, the TLS extensions handlers can be
22718 implemented using the following interface.
22719 </p>
22720 <img src="gnutls-extensions_st.png" alt="gnutls-extensions_st">
22721
22722 <p>Here there are two functions, one for receiving the extension data
22723 and one for sending. These functions have to check internally whether
22724 they operate in client or server side.
22725 </p>
22726 <p>A simple example of an extension handler can be seen in
22727 <code>ext_srp.c</code> After implementing these functions, together with the
22728 extension number they handle, they have to be registered in
22729 <code>gnutls_extensions.c</code> in the <code>_gnutls_extensions</code> structure.
22730 </p>
22731 <a name="Adding-a-New-TLS-Extension"></a>
22732 <h4 class="subsection">12.4.1 Adding a New TLS Extension</h4>
22733
22734 <p>Adding support for a new TLS extension is done from time to time, and
22735 the process to do so is not difficult.  Here are the steps you need to
22736 follow if you wish to do this yourself.  For sake of discussion, let&rsquo;s
22737 consider adding support for the hypothetical TLS extension
22738 <code>foobar</code>.
22739 </p>
22740 <ol>
22741 <li> Add <code>configure</code> option like <code>--enable-foobar</code> or <code>--disable-foobar</code>.
22742
22743 <p>This step is useful when the extension code is large and it might be desirable
22744 to disable the extension under some circumstances. Otherwise it can be safely
22745 skipped.
22746 </p>
22747 <p>Whether to chose enable or disable depends on whether you intend to make the extension be
22748 enabled by default.  Look at existing checks (i.e., SRP, authz) for
22749 how to model the code.  For example:
22750 </p>
22751 <div class="example">
22752 <pre class="example">AC_MSG_CHECKING([whether to disable foobar support])
22753 AC_ARG_ENABLE(foobar,
22754         AS_HELP_STRING([--disable-foobar],
22755                 [disable foobar support]),
22756         ac_enable_foobar=no)
22757 if test x$ac_enable_foobar != xno; then
22758  AC_MSG_RESULT(no)
22759  AC_DEFINE(ENABLE_FOOBAR, 1, [enable foobar])
22760 else
22761  ac_full=0
22762  AC_MSG_RESULT(yes)
22763 fi
22764 AM_CONDITIONAL(ENABLE_FOOBAR, test &quot;$ac_enable_foobar&quot; != &quot;no&quot;)
22765 </pre></div>
22766
22767 <p>These lines should go in <code>lib/m4/hooks.m4</code>.
22768 </p>
22769 </li><li> Add IANA extension value to <code>extensions_t</code> in <code>gnutls_int.h</code>.
22770
22771 <p>A good name for the value would be GNUTLS_EXTENSION_FOOBAR.  Check
22772 with <a href="http://www.iana.org/assignments/tls-extensiontype-values">http://www.iana.org/assignments/tls-extensiontype-values</a>
22773 for allocated values.  For experiments, you could pick a number but
22774 remember that some consider it a bad idea to deploy such modified
22775 version since it will lead to interoperability problems in the future
22776 when the IANA allocates that number to someone else, or when the
22777 foobar protocol is allocated another number.
22778 </p>
22779 </li><li> Add an entry to <code>_gnutls_extensions</code> in <code>gnutls_extensions.c</code>.
22780
22781 <p>A typical entry would be:
22782 </p>
22783 <div class="example">
22784 <pre class="example">  int ret;
22785
22786   /* ...
22787    */
22788
22789 #if ENABLE_FOOBAR
22790
22791   ret = _gnutls_ext_register (&amp;foobar_ext);
22792   if (ret != GNUTLS_E_SUCCESS)
22793     return ret;
22794 #endif
22795 </pre></div>
22796
22797 <p>Most likely you&rsquo;ll need to add an <code>#include &quot;ext_foobar.h&quot;</code>, that
22798 will contain something like
22799 like:
22800 </p><div class="example">
22801 <pre class="example">  extension_entry_st foobar_ext = {
22802     .name = &quot;FOOBAR&quot;,
22803     .type = GNUTLS_EXTENSION_FOOBAR,
22804     .parse_type = GNUTLS_EXT_TLS,
22805     .recv_func = _foobar_recv_params,
22806     .send_func = _foobar_send_params,
22807     .pack_func = _foobar_pack,
22808     .unpack_func = _foobar_unpack,
22809     .deinit_func = NULL
22810   }
22811 </pre></div>
22812
22813 <p>The GNUTLS_EXTENSION_FOOBAR is the integer value you added to
22814 <code>gnutls_int.h</code> earlier.  In this structure you specify the
22815 functions to read the extension from the hello message, the function
22816 to send the reply to, and two more functions to pack and unpack from
22817 stored session data (e.g. when resumming a session). The <code>deinit</code> function
22818 will be called to deinitialize the extension&rsquo;s private parameters, if any.
22819 </p>
22820 <p>Note that the conditional <code>ENABLE_FOOBAR</code> definition should only be
22821 used if step 1 with the <code>configure</code> options has taken place.
22822 </p>
22823 </li><li> Add new files <code>ext_foobar.c</code> and <code>ext_foobar.h</code> that implement the extension.
22824
22825 <p>The functions you are responsible to add are those mentioned in the
22826 previous step.  As a starter, you could add this:
22827 </p>
22828 <div class="example">
22829 <pre class="example">int
22830 _foobar_recv_params (gnutls_session_t session,
22831                             const opaque * data,
22832                             size_t data_size)
22833 {
22834   return 0;
22835 }
22836
22837 int
22838 _foobar_send_params (gnutls_session_t session,
22839                             opaque * data,
22840                             size_t _data_size)
22841 {
22842   return 0;
22843 }
22844
22845 int
22846 _foobar_pack (extension_priv_data_t epriv, gnutls_buffer_st * ps)
22847 {
22848    /* Append the extension's internal state to buffer */
22849    return 0;
22850 }
22851
22852 int
22853 _foobar_unpack (gnutls_buffer_st * ps, extension_priv_data_t * epriv)
22854 {
22855    /* Read the internal state from buffer */
22856    return 0;
22857 }
22858 </pre></div>
22859
22860 <p>The <code>_foobar_recv_params</code> function is responsible for
22861 parsing incoming extension data (both in the client and server).
22862 </p>
22863 <p>The <code>_foobar_send_params</code> function is responsible for
22864 sending extension data (both in the client and server).
22865 </p>
22866 <p>The <code>_foobar_pack</code> function is responsible for packing
22867 internal extension data to save them in the session storage.
22868 </p>
22869 <p>The <code>_foobar_unpack</code> function is responsible for
22870 restoring session data from the session storage.
22871 </p>
22872 <p>If you receive length fields that doesn&rsquo;t match, return
22873 <code>GNUTLS_E_UNEXPECTED_PACKET_LENGTH</code>.  If you receive invalid
22874 data, return <code>GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER</code>.  You can use
22875 other error codes too.  Return 0 on success.
22876 </p>
22877 <p>The function could store some information in the <code>session</code>
22878 variable for later usage. That can be done using the functions
22879 <code>_gnutls_ext_set_session_data</code> and
22880 <code>_gnutls_ext_get_session_data</code>. You can check simple examples
22881 at <code>ext_max_record.c</code> and <code>ext_server_name.c</code> extensions.
22882 </p>
22883 <p>Recall that both the client and server both send and receives
22884 parameters, and your code most likely will need to do different things
22885 depending on which mode it is in.  It may be useful to make this
22886 distinction explicit in the code.  Thus, for example, a better
22887 template than above would be:
22888 </p>
22889 <div class="example">
22890 <pre class="example">int
22891 _gnutls_foobar_recv_params (gnutls_session_t session,
22892                             const opaque * data,
22893                             size_t data_size)
22894 {
22895   if (session-&gt;security_parameters.entity == GNUTLS_CLIENT)
22896     return foobar_recv_client (session, data, data_size);
22897   else
22898     return foobar_recv_server (session, data, data_size);
22899 }
22900
22901 int
22902 _gnutls_foobar_send_params (gnutls_session_t session,
22903                             opaque * data,
22904                             size_t data_size)
22905 {
22906   if (session-&gt;security_parameters.entity == GNUTLS_CLIENT)
22907     return foobar_send_client (session, data, data_size);
22908   else
22909     return foobar_send_server (session, data, data_size);
22910 }
22911 </pre></div>
22912
22913 <p>The functions used would be declared as <code>static</code> functions, of
22914 the appropriate prototype, in the same file.
22915 </p>
22916 <p>When adding the files, you&rsquo;ll need to add them to <code>Makefile.am</code>
22917 as well, for example:
22918 </p>
22919 <div class="example">
22920 <pre class="example">if ENABLE_FOOBAR
22921 COBJECTS += ext_foobar.c
22922 HFILES += ext_foobar.h
22923 endif
22924 </pre></div>
22925
22926 </li><li> Add API functions to enable/disable the extension.
22927
22928 <p>Normally the client will have one API to request use of the extension,
22929 and setting some extension specific data.  The server will have one
22930 API to let the library know that it is willing to accept the
22931 extension, often this is implemented through a callback but it doesn&rsquo;t
22932 have to.
22933 </p>
22934 <p>The APIs need to be added to <code>includes/gnutls/gnutls.h</code> or
22935 <code>includes/gnutls/extra.h</code> as appropriate.  It is recommended that
22936 if you don&rsquo;t have a requirement to use the LGPLv2.1+ license for your
22937 extension, that you place your work under the GPLv3+ license and thus
22938 in the libgnutls-extra library.
22939 </p>
22940 <p>You can implement the API function in the <code>ext_foobar.c</code> file, or
22941 if that file ends up becoming rather larger, add a
22942 <code>gnutls_foobar.c</code> file.
22943 </p>
22944 <p>To make the API available in the shared library you need to add the
22945 symbol in <code>lib/libgnutls.map</code> or
22946 <code>libextra/libgnutls-extra.map</code> as appropriate, so that the symbol
22947 is exported properly.
22948 </p>
22949 <p>When writing GTK-DOC style documentation for your new APIs, don&rsquo;t
22950 forget to add <code>Since:</code> tags to indicate the GnuTLS version the
22951 API was introduced in.
22952 </p>
22953 </li></ol>
22954
22955 <hr>
22956 <a name="Certificate-Handling"></a>
22957 <div class="header">
22958 <p>
22959 Next: <a href="#Cryptographic-Backend" accesskey="n" rel="next">Cryptographic Backend</a>, Previous: <a href="#TLS-Extension-Handling" accesskey="p" rel="previous">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>
22960 </div>
22961 <a name="Certificate-Handling-1"></a>
22962 <h3 class="section">12.5 Certificate Handling</h3>
22963 <p>What is provided by the certificate handling functions
22964 is summarized in the following diagram.
22965 </p>
22966 <img src="gnutls-certificate-user-use-case.png" alt="gnutls-certificate-user-use-case">
22967
22968 <hr>
22969 <a name="Cryptographic-Backend"></a>
22970 <div class="header">
22971 <p>
22972 Previous: <a href="#Certificate-Handling" accesskey="p" rel="previous">Certificate 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>
22973 </div>
22974 <a name="Cryptographic-Backend-1"></a>
22975 <h3 class="section">12.6 Cryptographic Backend</h3>
22976 <p>Today most new processors, either for embedded or desktop systems
22977 include either instructions  intended to speed up cryptographic operations,
22978 or a co-processor with cryptographic capabilities. Taking advantage of
22979 those is a challenging task for every cryptographic  application or
22980 library. Unfortunately the cryptographic libraries that GnuTLS is based
22981 on take no advantage of these properties. For this reason GnuTLS handles
22982 this internally by following a layered approach to accessing
22983 cryptographic operations as in the following figure.
22984 </p>
22985 <img src="gnutls-crypto-layers.png" alt="gnutls-crypto-layers">
22986
22987 <p>The TLS layer uses a cryptographic provider layer, that will in turn either
22988 use the default crypto provider - a crypto library, or use an external
22989 crypto provider, if available.
22990 </p>
22991 <a name="Cryptographic-Library-layer"></a>
22992 <h4 class="subsection">12.6.1 Cryptographic Library layer</h4>
22993 <p>The Cryptographic Library layer, can  currently be used either with
22994 libgcrypt or libnettle, each of one has its advantages and some
22995 disadvantages. Libgcrypt is a self-contained library, pretty broad
22996 in scope that supports many algorithms. In some processors like VIA,
22997 it will also use the available crypto instruction set hence providing
22998 performance benefit comparing to plain software implementation.
22999 Libnettle provides only software implementation
23000 of the basic algorithms required in TLS, and is on average 30% faster
23001 that libgcrypt on almost all algorithms. For
23002 this reason libnettle is library used by default in GnuTLS.
23003 </p>
23004 <a name="External-cryptography-provider"></a>
23005 <h4 class="subsection">12.6.2 External cryptography provider</h4>
23006 <p>Systems that include a cryptographic co-processor, typically come with
23007 kernel drivers to utilize the operations from software. For this reason
23008 GnuTLS provides a layer where each individual algorithm used can be replaced
23009 by another implementation, i.e. the one provided by the driver. The
23010 FreeBSD, OpenBSD and Linux kernels<a name="DOCF21" href="#FOOT21">(21)</a> include already
23011 a number of hardware assisted implementations, and also provide an interface
23012 to access them, called <code>/dev/crypto</code>.
23013 GnuTLS will take advantage of this interface if compiled with special
23014 options. That is because in most systems where hardware-assisted
23015 cryptographic operations are not available, using this interface might
23016 actually reduce performance.
23017 </p>
23018 <p>It is possible to override parts of crypto backend both at runtime and compile
23019 time. Here we discuss the runtime possibility. The API
23020 available for this functionality is in <code>gnutls/crypto.h</code> header
23021 file.
23022 </p>
23023 <a name="Override-specific-algorithms"></a>
23024 <h4 class="subsubsection">12.6.2.1 Override specific algorithms</h4>
23025 <p>When an optimized implementation of a single algorithm is available,
23026 say a hardware assisted version of <acronym>AES-CBC</acronym> then the
23027 following functions can be used to register those algorithms.
23028 </p>
23029 <ul>
23030 <li> <a href="#gnutls_005fcrypto_005fsingle_005fcipher_005fregister2">gnutls_crypto_single_cipher_register2</a>
23031 To register a cipher algorithm.
23032
23033 <p><a href="#gnutls_005fcrypto_005fsingle_005fdigest_005fregister2">gnutls_crypto_single_digest_register2</a>
23034 To register a hash (digest) or MAC algorithm.
23035 </p>
23036 </li></ul>
23037
23038 <p>Those registration functions will only replace the specified algorithm
23039 and leave the rest of subsystem intact.
23040 </p>
23041 <a name="Override-parts-of-the-backend"></a>
23042 <h4 class="subsubsection">12.6.2.2 Override parts of the backend</h4>
23043 <p>In some systems, such as embedded ones, it might be desirable to
23044 override big parts of the cryptographic backend, or even all of
23045 them. For this reason the following functions are provided.
23046 </p>
23047 <ul>
23048 <li> <a href="#gnutls_005fcrypto_005fcipher_005fregister2">gnutls_crypto_cipher_register2</a>
23049 To override the cryptographic algorithms backend.
23050
23051 </li><li> <a href="#gnutls_005fcrypto_005fdigest_005fregister2">gnutls_crypto_digest_register2</a>
23052 To override the digest algorithms backend.
23053
23054 </li><li> <a href="#gnutls_005fcrypto_005frnd_005fregister2">gnutls_crypto_rnd_register2</a>
23055 To override the random number generator backend.
23056
23057 </li><li> <a href="#gnutls_005fcrypto_005fbigint_005fregister2">gnutls_crypto_bigint_register2</a>
23058 To override the big number number operations backend.
23059
23060 </li><li> <a href="#gnutls_005fcrypto_005fpk_005fregister2">gnutls_crypto_pk_register2</a>
23061 To override the public key encryption backend. This is tight to the
23062 big number operations so either both of them should be updated or care
23063 must be taken to use the same format.
23064
23065 </li></ul>
23066
23067 <p>If all of them are used then GnuTLS will no longer use libgcrypt.
23068 </p>
23069 <hr>
23070 <a name="Copying-Information"></a>
23071 <div class="header">
23072 <p>
23073 Next: <a href="#Bibliography" accesskey="n" rel="next">Bibliography</a>, Previous: <a href="#Internal-architecture-of-GnuTLS" accesskey="p" rel="previous">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>
23074 </div>
23075 <a name="Copying-Information-1"></a>
23076 <h2 class="appendix">Appendix A Copying Information</h2>
23077
23078 <table class="menu" border="0" cellspacing="0">
23079 <tr><td align="left" valign="top">&bull; <a href="#GNU-Free-Documentation-License" accesskey="1">GNU Free Documentation License</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">License for copying this manual.
23080 </td></tr>
23081 <tr><td align="left" valign="top">&bull; <a href="#GNU-LGPL" accesskey="2">GNU LGPL</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">License for copying the core GnuTLS library.
23082 </td></tr>
23083 <tr><td align="left" valign="top">&bull; <a href="#GNU-GPL" accesskey="3">GNU GPL</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">License for copying GnuTLS-extra and tools.
23084 </td></tr>
23085 </table>
23086
23087 <hr>
23088 <a name="GNU-Free-Documentation-License"></a>
23089 <div class="header">
23090 <p>
23091 Next: <a href="#GNU-LGPL" accesskey="n" rel="next">GNU LGPL</a>, Up: <a href="#Copying-Information" accesskey="u" rel="up">Copying Information</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>
23092 </div>
23093 <a name="GNU-Free-Documentation-License-1"></a>
23094 <h3 class="appendixsec">A.1 GNU Free Documentation License</h3>
23095
23096 <a name="index-FDL_002c-GNU-Free-Documentation-License"></a>
23097
23098 <div align="center">Version 1.3, 3 November 2008
23099 </div>
23100
23101 <div class="display">
23102 <pre class="display">Copyright &copy; 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
23103 <a href="http://fsf.org/">http://fsf.org/</a>
23104
23105 Everyone is permitted to copy and distribute verbatim copies
23106 of this license document, but changing it is not allowed.
23107 </pre></div>
23108
23109 <ol>
23110 <li> PREAMBLE
23111
23112 <p>The purpose of this License is to make a manual, textbook, or other
23113 functional and useful document <em>free</em> in the sense of freedom: to
23114 assure everyone the effective freedom to copy and redistribute it,
23115 with or without modifying it, either commercially or noncommercially.
23116 Secondarily, this License preserves for the author and publisher a way
23117 to get credit for their work, while not being considered responsible
23118 for modifications made by others.
23119 </p>
23120 <p>This License is a kind of &ldquo;copyleft&rdquo;, which means that derivative
23121 works of the document must themselves be free in the same sense.  It
23122 complements the GNU General Public License, which is a copyleft
23123 license designed for free software.
23124 </p>
23125 <p>We have designed this License in order to use it for manuals for free
23126 software, because free software needs free documentation: a free
23127 program should come with manuals providing the same freedoms that the
23128 software does.  But this License is not limited to software manuals;
23129 it can be used for any textual work, regardless of subject matter or
23130 whether it is published as a printed book.  We recommend this License
23131 principally for works whose purpose is instruction or reference.
23132 </p>
23133 </li><li> APPLICABILITY AND DEFINITIONS
23134
23135 <p>This License applies to any manual or other work, in any medium, that
23136 contains a notice placed by the copyright holder saying it can be
23137 distributed under the terms of this License.  Such a notice grants a
23138 world-wide, royalty-free license, unlimited in duration, to use that
23139 work under the conditions stated herein.  The &ldquo;Document&rdquo;, below,
23140 refers to any such manual or work.  Any member of the public is a
23141 licensee, and is addressed as &ldquo;you&rdquo;.  You accept the license if you
23142 copy, modify or distribute the work in a way requiring permission
23143 under copyright law.
23144 </p>
23145 <p>A &ldquo;Modified Version&rdquo; of the Document means any work containing the
23146 Document or a portion of it, either copied verbatim, or with
23147 modifications and/or translated into another language.
23148 </p>
23149 <p>A &ldquo;Secondary Section&rdquo; is a named appendix or a front-matter section
23150 of the Document that deals exclusively with the relationship of the
23151 publishers or authors of the Document to the Document&rsquo;s overall
23152 subject (or to related matters) and contains nothing that could fall
23153 directly within that overall subject.  (Thus, if the Document is in
23154 part a textbook of mathematics, a Secondary Section may not explain
23155 any mathematics.)  The relationship could be a matter of historical
23156 connection with the subject or with related matters, or of legal,
23157 commercial, philosophical, ethical or political position regarding
23158 them.
23159 </p>
23160 <p>The &ldquo;Invariant Sections&rdquo; are certain Secondary Sections whose titles
23161 are designated, as being those of Invariant Sections, in the notice
23162 that says that the Document is released under this License.  If a
23163 section does not fit the above definition of Secondary then it is not
23164 allowed to be designated as Invariant.  The Document may contain zero
23165 Invariant Sections.  If the Document does not identify any Invariant
23166 Sections then there are none.
23167 </p>
23168 <p>The &ldquo;Cover Texts&rdquo; are certain short passages of text that are listed,
23169 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
23170 the Document is released under this License.  A Front-Cover Text may
23171 be at most 5 words, and a Back-Cover Text may be at most 25 words.
23172 </p>
23173 <p>A &ldquo;Transparent&rdquo; copy of the Document means a machine-readable copy,
23174 represented in a format whose specification is available to the
23175 general public, that is suitable for revising the document
23176 straightforwardly with generic text editors or (for images composed of
23177 pixels) generic paint programs or (for drawings) some widely available
23178 drawing editor, and that is suitable for input to text formatters or
23179 for automatic translation to a variety of formats suitable for input
23180 to text formatters.  A copy made in an otherwise Transparent file
23181 format whose markup, or absence of markup, has been arranged to thwart
23182 or discourage subsequent modification by readers is not Transparent.
23183 An image format is not Transparent if used for any substantial amount
23184 of text.  A copy that is not &ldquo;Transparent&rdquo; is called &ldquo;Opaque&rdquo;.
23185 </p>
23186 <p>Examples of suitable formats for Transparent copies include plain
23187 ASCII without markup, Texinfo input format, LaTeX input
23188 format, SGML or XML using a publicly available
23189 DTD, and standard-conforming simple HTML,
23190 PostScript or PDF designed for human modification.  Examples
23191 of transparent image formats include PNG, XCF and
23192 JPG.  Opaque formats include proprietary formats that can be
23193 read and edited only by proprietary word processors, SGML or
23194 XML for which the DTD and/or processing tools are
23195 not generally available, and the machine-generated HTML,
23196 PostScript or PDF produced by some word processors for
23197 output purposes only.
23198 </p>
23199 <p>The &ldquo;Title Page&rdquo; means, for a printed book, the title page itself,
23200 plus such following pages as are needed to hold, legibly, the material
23201 this License requires to appear in the title page.  For works in
23202 formats which do not have any title page as such, &ldquo;Title Page&rdquo; means
23203 the text near the most prominent appearance of the work&rsquo;s title,
23204 preceding the beginning of the body of the text.
23205 </p>
23206 <p>The &ldquo;publisher&rdquo; means any person or entity that distributes copies
23207 of the Document to the public.
23208 </p>
23209 <p>A section &ldquo;Entitled XYZ&rdquo; means a named subunit of the Document whose
23210 title either is precisely XYZ or contains XYZ in parentheses following
23211 text that translates XYZ in another language.  (Here XYZ stands for a
23212 specific section name mentioned below, such as &ldquo;Acknowledgements&rdquo;,
23213 &ldquo;Dedications&rdquo;, &ldquo;Endorsements&rdquo;, or &ldquo;History&rdquo;.)  To &ldquo;Preserve the Title&rdquo;
23214 of such a section when you modify the Document means that it remains a
23215 section &ldquo;Entitled XYZ&rdquo; according to this definition.
23216 </p>
23217 <p>The Document may include Warranty Disclaimers next to the notice which
23218 states that this License applies to the Document.  These Warranty
23219 Disclaimers are considered to be included by reference in this
23220 License, but only as regards disclaiming warranties: any other
23221 implication that these Warranty Disclaimers may have is void and has
23222 no effect on the meaning of this License.
23223 </p>
23224 </li><li> VERBATIM COPYING
23225
23226 <p>You may copy and distribute the Document in any medium, either
23227 commercially or noncommercially, provided that this License, the
23228 copyright notices, and the license notice saying this License applies
23229 to the Document are reproduced in all copies, and that you add no other
23230 conditions whatsoever to those of this License.  You may not use
23231 technical measures to obstruct or control the reading or further
23232 copying of the copies you make or distribute.  However, you may accept
23233 compensation in exchange for copies.  If you distribute a large enough
23234 number of copies you must also follow the conditions in section 3.
23235 </p>
23236 <p>You may also lend copies, under the same conditions stated above, and
23237 you may publicly display copies.
23238 </p>
23239 </li><li> COPYING IN QUANTITY
23240
23241 <p>If you publish printed copies (or copies in media that commonly have
23242 printed covers) of the Document, numbering more than 100, and the
23243 Document&rsquo;s license notice requires Cover Texts, you must enclose the
23244 copies in covers that carry, clearly and legibly, all these Cover
23245 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
23246 the back cover.  Both covers must also clearly and legibly identify
23247 you as the publisher of these copies.  The front cover must present
23248 the full title with all words of the title equally prominent and
23249 visible.  You may add other material on the covers in addition.
23250 Copying with changes limited to the covers, as long as they preserve
23251 the title of the Document and satisfy these conditions, can be treated
23252 as verbatim copying in other respects.
23253 </p>
23254 <p>If the required texts for either cover are too voluminous to fit
23255 legibly, you should put the first ones listed (as many as fit
23256 reasonably) on the actual cover, and continue the rest onto adjacent
23257 pages.
23258 </p>
23259 <p>If you publish or distribute Opaque copies of the Document numbering
23260 more than 100, you must either include a machine-readable Transparent
23261 copy along with each Opaque copy, or state in or with each Opaque copy
23262 a computer-network location from which the general network-using
23263 public has access to download using public-standard network protocols
23264 a complete Transparent copy of the Document, free of added material.
23265 If you use the latter option, you must take reasonably prudent steps,
23266 when you begin distribution of Opaque copies in quantity, to ensure
23267 that this Transparent copy will remain thus accessible at the stated
23268 location until at least one year after the last time you distribute an
23269 Opaque copy (directly or through your agents or retailers) of that
23270 edition to the public.
23271 </p>
23272 <p>It is requested, but not required, that you contact the authors of the
23273 Document well before redistributing any large number of copies, to give
23274 them a chance to provide you with an updated version of the Document.
23275 </p>
23276 </li><li> MODIFICATIONS
23277
23278 <p>You may copy and distribute a Modified Version of the Document under
23279 the conditions of sections 2 and 3 above, provided that you release
23280 the Modified Version under precisely this License, with the Modified
23281 Version filling the role of the Document, thus licensing distribution
23282 and modification of the Modified Version to whoever possesses a copy
23283 of it.  In addition, you must do these things in the Modified Version:
23284 </p>
23285 <ol>
23286 <li> Use in the Title Page (and on the covers, if any) a title distinct
23287 from that of the Document, and from those of previous versions
23288 (which should, if there were any, be listed in the History section
23289 of the Document).  You may use the same title as a previous version
23290 if the original publisher of that version gives permission.
23291
23292 </li><li> List on the Title Page, as authors, one or more persons or entities
23293 responsible for authorship of the modifications in the Modified
23294 Version, together with at least five of the principal authors of the
23295 Document (all of its principal authors, if it has fewer than five),
23296 unless they release you from this requirement.
23297
23298 </li><li> State on the Title page the name of the publisher of the
23299 Modified Version, as the publisher.
23300
23301 </li><li> Preserve all the copyright notices of the Document.
23302
23303 </li><li> Add an appropriate copyright notice for your modifications
23304 adjacent to the other copyright notices.
23305
23306 </li><li> Include, immediately after the copyright notices, a license notice
23307 giving the public permission to use the Modified Version under the
23308 terms of this License, in the form shown in the Addendum below.
23309
23310 </li><li> Preserve in that license notice the full lists of Invariant Sections
23311 and required Cover Texts given in the Document&rsquo;s license notice.
23312
23313 </li><li> Include an unaltered copy of this License.
23314
23315 </li><li> Preserve the section Entitled &ldquo;History&rdquo;, Preserve its Title, and add
23316 to it an item stating at least the title, year, new authors, and
23317 publisher of the Modified Version as given on the Title Page.  If
23318 there is no section Entitled &ldquo;History&rdquo; in the Document, create one
23319 stating the title, year, authors, and publisher of the Document as
23320 given on its Title Page, then add an item describing the Modified
23321 Version as stated in the previous sentence.
23322
23323 </li><li> Preserve the network location, if any, given in the Document for
23324 public access to a Transparent copy of the Document, and likewise
23325 the network locations given in the Document for previous versions
23326 it was based on.  These may be placed in the &ldquo;History&rdquo; section.
23327 You may omit a network location for a work that was published at
23328 least four years before the Document itself, or if the original
23329 publisher of the version it refers to gives permission.
23330
23331 </li><li> For any section Entitled &ldquo;Acknowledgements&rdquo; or &ldquo;Dedications&rdquo;, Preserve
23332 the Title of the section, and preserve in the section all the
23333 substance and tone of each of the contributor acknowledgements and/or
23334 dedications given therein.
23335
23336 </li><li> Preserve all the Invariant Sections of the Document,
23337 unaltered in their text and in their titles.  Section numbers
23338 or the equivalent are not considered part of the section titles.
23339
23340 </li><li> Delete any section Entitled &ldquo;Endorsements&rdquo;.  Such a section
23341 may not be included in the Modified Version.
23342
23343 </li><li> Do not retitle any existing section to be Entitled &ldquo;Endorsements&rdquo; or
23344 to conflict in title with any Invariant Section.
23345
23346 </li><li> Preserve any Warranty Disclaimers.
23347 </li></ol>
23348
23349 <p>If the Modified Version includes new front-matter sections or
23350 appendices that qualify as Secondary Sections and contain no material
23351 copied from the Document, you may at your option designate some or all
23352 of these sections as invariant.  To do this, add their titles to the
23353 list of Invariant Sections in the Modified Version&rsquo;s license notice.
23354 These titles must be distinct from any other section titles.
23355 </p>
23356 <p>You may add a section Entitled &ldquo;Endorsements&rdquo;, provided it contains
23357 nothing but endorsements of your Modified Version by various
23358 parties&mdash;for example, statements of peer review or that the text has
23359 been approved by an organization as the authoritative definition of a
23360 standard.
23361 </p>
23362 <p>You may add a passage of up to five words as a Front-Cover Text, and a
23363 passage of up to 25 words as a Back-Cover Text, to the end of the list
23364 of Cover Texts in the Modified Version.  Only one passage of
23365 Front-Cover Text and one of Back-Cover Text may be added by (or
23366 through arrangements made by) any one entity.  If the Document already
23367 includes a cover text for the same cover, previously added by you or
23368 by arrangement made by the same entity you are acting on behalf of,
23369 you may not add another; but you may replace the old one, on explicit
23370 permission from the previous publisher that added the old one.
23371 </p>
23372 <p>The author(s) and publisher(s) of the Document do not by this License
23373 give permission to use their names for publicity for or to assert or
23374 imply endorsement of any Modified Version.
23375 </p>
23376 </li><li> COMBINING DOCUMENTS
23377
23378 <p>You may combine the Document with other documents released under this
23379 License, under the terms defined in section 4 above for modified
23380 versions, provided that you include in the combination all of the
23381 Invariant Sections of all of the original documents, unmodified, and
23382 list them all as Invariant Sections of your combined work in its
23383 license notice, and that you preserve all their Warranty Disclaimers.
23384 </p>
23385 <p>The combined work need only contain one copy of this License, and
23386 multiple identical Invariant Sections may be replaced with a single
23387 copy.  If there are multiple Invariant Sections with the same name but
23388 different contents, make the title of each such section unique by
23389 adding at the end of it, in parentheses, the name of the original
23390 author or publisher of that section if known, or else a unique number.
23391 Make the same adjustment to the section titles in the list of
23392 Invariant Sections in the license notice of the combined work.
23393 </p>
23394 <p>In the combination, you must combine any sections Entitled &ldquo;History&rdquo;
23395 in the various original documents, forming one section Entitled
23396 &ldquo;History&rdquo;; likewise combine any sections Entitled &ldquo;Acknowledgements&rdquo;,
23397 and any sections Entitled &ldquo;Dedications&rdquo;.  You must delete all
23398 sections Entitled &ldquo;Endorsements.&rdquo;
23399 </p>
23400 </li><li> COLLECTIONS OF DOCUMENTS
23401
23402 <p>You may make a collection consisting of the Document and other documents
23403 released under this License, and replace the individual copies of this
23404 License in the various documents with a single copy that is included in
23405 the collection, provided that you follow the rules of this License for
23406 verbatim copying of each of the documents in all other respects.
23407 </p>
23408 <p>You may extract a single document from such a collection, and distribute
23409 it individually under this License, provided you insert a copy of this
23410 License into the extracted document, and follow this License in all
23411 other respects regarding verbatim copying of that document.
23412 </p>
23413 </li><li> AGGREGATION WITH INDEPENDENT WORKS
23414
23415 <p>A compilation of the Document or its derivatives with other separate
23416 and independent documents or works, in or on a volume of a storage or
23417 distribution medium, is called an &ldquo;aggregate&rdquo; if the copyright
23418 resulting from the compilation is not used to limit the legal rights
23419 of the compilation&rsquo;s users beyond what the individual works permit.
23420 When the Document is included in an aggregate, this License does not
23421 apply to the other works in the aggregate which are not themselves
23422 derivative works of the Document.
23423 </p>
23424 <p>If the Cover Text requirement of section 3 is applicable to these
23425 copies of the Document, then if the Document is less than one half of
23426 the entire aggregate, the Document&rsquo;s Cover Texts may be placed on
23427 covers that bracket the Document within the aggregate, or the
23428 electronic equivalent of covers if the Document is in electronic form.
23429 Otherwise they must appear on printed covers that bracket the whole
23430 aggregate.
23431 </p>
23432 </li><li> TRANSLATION
23433
23434 <p>Translation is considered a kind of modification, so you may
23435 distribute translations of the Document under the terms of section 4.
23436 Replacing Invariant Sections with translations requires special
23437 permission from their copyright holders, but you may include
23438 translations of some or all Invariant Sections in addition to the
23439 original versions of these Invariant Sections.  You may include a
23440 translation of this License, and all the license notices in the
23441 Document, and any Warranty Disclaimers, provided that you also include
23442 the original English version of this License and the original versions
23443 of those notices and disclaimers.  In case of a disagreement between
23444 the translation and the original version of this License or a notice
23445 or disclaimer, the original version will prevail.
23446 </p>
23447 <p>If a section in the Document is Entitled &ldquo;Acknowledgements&rdquo;,
23448 &ldquo;Dedications&rdquo;, or &ldquo;History&rdquo;, the requirement (section 4) to Preserve
23449 its Title (section 1) will typically require changing the actual
23450 title.
23451 </p>
23452 </li><li> TERMINATION
23453
23454 <p>You may not copy, modify, sublicense, or distribute the Document
23455 except as expressly provided under this License.  Any attempt
23456 otherwise to copy, modify, sublicense, or distribute it is void, and
23457 will automatically terminate your rights under this License.
23458 </p>
23459 <p>However, if you cease all violation of this License, then your license
23460 from a particular copyright holder is reinstated (a) provisionally,
23461 unless and until the copyright holder explicitly and finally
23462 terminates your license, and (b) permanently, if the copyright holder
23463 fails to notify you of the violation by some reasonable means prior to
23464 60 days after the cessation.
23465 </p>
23466 <p>Moreover, your license from a particular copyright holder is
23467 reinstated permanently if the copyright holder notifies you of the
23468 violation by some reasonable means, this is the first time you have
23469 received notice of violation of this License (for any work) from that
23470 copyright holder, and you cure the violation prior to 30 days after
23471 your receipt of the notice.
23472 </p>
23473 <p>Termination of your rights under this section does not terminate the
23474 licenses of parties who have received copies or rights from you under
23475 this License.  If your rights have been terminated and not permanently
23476 reinstated, receipt of a copy of some or all of the same material does
23477 not give you any rights to use it.
23478 </p>
23479 </li><li> FUTURE REVISIONS OF THIS LICENSE
23480
23481 <p>The Free Software Foundation may publish new, revised versions
23482 of the GNU Free Documentation License from time to time.  Such new
23483 versions will be similar in spirit to the present version, but may
23484 differ in detail to address new problems or concerns.  See
23485 <a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>.
23486 </p>
23487 <p>Each version of the License is given a distinguishing version number.
23488 If the Document specifies that a particular numbered version of this
23489 License &ldquo;or any later version&rdquo; applies to it, you have the option of
23490 following the terms and conditions either of that specified version or
23491 of any later version that has been published (not as a draft) by the
23492 Free Software Foundation.  If the Document does not specify a version
23493 number of this License, you may choose any version ever published (not
23494 as a draft) by the Free Software Foundation.  If the Document
23495 specifies that a proxy can decide which future versions of this
23496 License can be used, that proxy&rsquo;s public statement of acceptance of a
23497 version permanently authorizes you to choose that version for the
23498 Document.
23499 </p>
23500 </li><li> RELICENSING
23501
23502 <p>&ldquo;Massive Multiauthor Collaboration Site&rdquo; (or &ldquo;MMC Site&rdquo;) means any
23503 World Wide Web server that publishes copyrightable works and also
23504 provides prominent facilities for anybody to edit those works.  A
23505 public wiki that anybody can edit is an example of such a server.  A
23506 &ldquo;Massive Multiauthor Collaboration&rdquo; (or &ldquo;MMC&rdquo;) contained in the
23507 site means any set of copyrightable works thus published on the MMC
23508 site.
23509 </p>
23510 <p>&ldquo;CC-BY-SA&rdquo; means the Creative Commons Attribution-Share Alike 3.0
23511 license published by Creative Commons Corporation, a not-for-profit
23512 corporation with a principal place of business in San Francisco,
23513 California, as well as future copyleft versions of that license
23514 published by that same organization.
23515 </p>
23516 <p>&ldquo;Incorporate&rdquo; means to publish or republish a Document, in whole or
23517 in part, as part of another Document.
23518 </p>
23519 <p>An MMC is &ldquo;eligible for relicensing&rdquo; if it is licensed under this
23520 License, and if all works that were first published under this License
23521 somewhere other than this MMC, and subsequently incorporated in whole
23522 or in part into the MMC, (1) had no cover texts or invariant sections,
23523 and (2) were thus incorporated prior to November 1, 2008.
23524 </p>
23525 <p>The operator of an MMC Site may republish an MMC contained in the site
23526 under CC-BY-SA on the same site at any time before August 1, 2009,
23527 provided the MMC is eligible for relicensing.
23528 </p>
23529 </li></ol>
23530
23531 <a name="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></a>
23532 <h3 class="heading">ADDENDUM: How to use this License for your documents</h3>
23533
23534 <p>To use this License in a document you have written, include a copy of
23535 the License in the document and put the following copyright and
23536 license notices just after the title page:
23537 </p>
23538 <div class="smallexample">
23539 <pre class="smallexample">  Copyright (C)  <var>year</var>  <var>your name</var>.
23540   Permission is granted to copy, distribute and/or modify this document
23541   under the terms of the GNU Free Documentation License, Version 1.3
23542   or any later version published by the Free Software Foundation;
23543   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
23544   Texts.  A copy of the license is included in the section entitled ``GNU
23545   Free Documentation License''.
23546 </pre></div>
23547
23548 <p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
23549 replace the &ldquo;with&hellip;Texts.&rdquo; line with this:
23550 </p>
23551 <div class="smallexample">
23552 <pre class="smallexample">    with the Invariant Sections being <var>list their titles</var>, with
23553     the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts
23554     being <var>list</var>.
23555 </pre></div>
23556
23557 <p>If you have Invariant Sections without Cover Texts, or some other
23558 combination of the three, merge those two alternatives to suit the
23559 situation.
23560 </p>
23561 <p>If your document contains nontrivial examples of program code, we
23562 recommend releasing these examples in parallel under your choice of
23563 free software license, such as the GNU General Public License,
23564 to permit their use in free software.
23565 </p>
23566
23567 <hr>
23568 <a name="GNU-LGPL"></a>
23569 <div class="header">
23570 <p>
23571 Next: <a href="#GNU-GPL" accesskey="n" rel="next">GNU GPL</a>, Previous: <a href="#GNU-Free-Documentation-License" accesskey="p" rel="previous">GNU Free Documentation License</a>, Up: <a href="#Copying-Information" accesskey="u" rel="up">Copying Information</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>
23572 </div>
23573 <a name="GNU-Lesser-General-Public-License"></a>
23574 <h3 class="appendixsec">A.2 GNU Lesser General Public License</h3>
23575 <a name="index-LGPL_002c-GNU-Lesser-General-Public-License"></a>
23576 <a name="index-License_002c-GNU-LGPL"></a>
23577
23578 <div align="center">Version 2.1, February 1999
23579 </div>
23580
23581 <div class="display">
23582 <pre class="display">Copyright &copy; 1991, 1999 Free Software Foundation, Inc.
23583 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
23584
23585 Everyone is permitted to copy and distribute verbatim copies
23586 of this license document, but changing it is not allowed.
23587
23588 [This is the first released version of the Lesser GPL.  It also counts
23589 as the successor of the GNU Library Public License, version 2, hence the
23590 version number 2.1.]
23591 </pre></div>
23592
23593 <a name="Preamble"></a>
23594 <h4 class="subheading">Preamble</h4>
23595
23596 <p>The licenses for most software are designed to take away your
23597 freedom to share and change it.  By contrast, the GNU General Public
23598 Licenses are intended to guarantee your freedom to share and change
23599 free software&mdash;to make sure the software is free for all its users.
23600 </p>
23601 <p>This license, the Lesser General Public License, applies to some
23602 specially designated software&mdash;typically libraries&mdash;of the Free
23603 Software Foundation and other authors who decide to use it.  You can use
23604 it too, but we suggest you first think carefully about whether this
23605 license or the ordinary General Public License is the better strategy to
23606 use in any particular case, based on the explanations below.
23607 </p>
23608 <p>When we speak of free software, we are referring to freedom of use,
23609 not price.  Our General Public Licenses are designed to make sure that
23610 you have the freedom to distribute copies of free software (and charge
23611 for this service if you wish); that you receive source code or can get
23612 it if you want it; that you can change the software and use pieces of it
23613 in new free programs; and that you are informed that you can do these
23614 things.
23615 </p>
23616 <p>To protect your rights, we need to make restrictions that forbid
23617 distributors to deny you these rights or to ask you to surrender these
23618 rights.  These restrictions translate to certain responsibilities for
23619 you if you distribute copies of the library or if you modify it.
23620 </p>
23621 <p>For example, if you distribute copies of the library, whether gratis
23622 or for a fee, you must give the recipients all the rights that we gave
23623 you.  You must make sure that they, too, receive or can get the source
23624 code.  If you link other code with the library, you must provide
23625 complete object files to the recipients, so that they can relink them
23626 with the library after making changes to the library and recompiling
23627 it.  And you must show them these terms so they know their rights.
23628 </p>
23629 <p>We protect your rights with a two-step method: (1) we copyright the
23630 library, and (2) we offer you this license, which gives you legal
23631 permission to copy, distribute and/or modify the library.
23632 </p>
23633 <p>To protect each distributor, we want to make it very clear that
23634 there is no warranty for the free library.  Also, if the library is
23635 modified by someone else and passed on, the recipients should know
23636 that what they have is not the original version, so that the original
23637 author&rsquo;s reputation will not be affected by problems that might be
23638 introduced by others.
23639 </p>
23640 <p>Finally, software patents pose a constant threat to the existence of
23641 any free program.  We wish to make sure that a company cannot
23642 effectively restrict the users of a free program by obtaining a
23643 restrictive license from a patent holder.  Therefore, we insist that
23644 any patent license obtained for a version of the library must be
23645 consistent with the full freedom of use specified in this license.
23646 </p>
23647 <p>Most GNU software, including some libraries, is covered by the
23648 ordinary GNU General Public License.  This license, the GNU Lesser
23649 General Public License, applies to certain designated libraries, and
23650 is quite different from the ordinary General Public License.  We use
23651 this license for certain libraries in order to permit linking those
23652 libraries into non-free programs.
23653 </p>
23654 <p>When a program is linked with a library, whether statically or using
23655 a shared library, the combination of the two is legally speaking a
23656 combined work, a derivative of the original library.  The ordinary
23657 General Public License therefore permits such linking only if the
23658 entire combination fits its criteria of freedom.  The Lesser General
23659 Public License permits more lax criteria for linking other code with
23660 the library.
23661 </p>
23662 <p>We call this license the <em>Lesser</em> General Public License because it
23663 does <em>Less</em> to protect the user&rsquo;s freedom than the ordinary General
23664 Public License.  It also provides other free software developers Less
23665 of an advantage over competing non-free programs.  These disadvantages
23666 are the reason we use the ordinary General Public License for many
23667 libraries.  However, the Lesser license provides advantages in certain
23668 special circumstances.
23669 </p>
23670 <p>For example, on rare occasions, there may be a special need to
23671 encourage the widest possible use of a certain library, so that it becomes
23672 a de-facto standard.  To achieve this, non-free programs must be
23673 allowed to use the library.  A more frequent case is that a free
23674 library does the same job as widely used non-free libraries.  In this
23675 case, there is little to gain by limiting the free library to free
23676 software only, so we use the Lesser General Public License.
23677 </p>
23678 <p>In other cases, permission to use a particular library in non-free
23679 programs enables a greater number of people to use a large body of
23680 free software.  For example, permission to use the GNU C Library in
23681 non-free programs enables many more people to use the whole GNU
23682 operating system, as well as its variant, the GNU/Linux operating
23683 system.
23684 </p>
23685 <p>Although the Lesser General Public License is Less protective of the
23686 users&rsquo; freedom, it does ensure that the user of a program that is
23687 linked with the Library has the freedom and the wherewithal to run
23688 that program using a modified version of the Library.
23689 </p>
23690 <p>The precise terms and conditions for copying, distribution and
23691 modification follow.  Pay close attention to the difference between a
23692 &ldquo;work based on the library&rdquo; and a &ldquo;work that uses the library&rdquo;.  The
23693 former contains code derived from the library, whereas the latter must
23694 be combined with the library in order to run.
23695 </p>
23696 <a name="TERMS-AND-CONDITIONS-FOR-COPYING_002c-DISTRIBUTION-AND-MODIFICATION"></a>
23697 <h4 class="subheading">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</h4>
23698
23699 <ol>
23700 <li> This License Agreement applies to any software library or other program
23701 which contains a notice placed by the copyright holder or other
23702 authorized party saying it may be distributed under the terms of this
23703 Lesser General Public License (also called &ldquo;this License&rdquo;).  Each
23704 licensee is addressed as &ldquo;you&rdquo;.
23705
23706 <p>A &ldquo;library&rdquo; means a collection of software functions and/or data
23707 prepared so as to be conveniently linked with application programs
23708 (which use some of those functions and data) to form executables.
23709 </p>
23710 <p>The &ldquo;Library&rdquo;, below, refers to any such software library or work
23711 which has been distributed under these terms.  A &ldquo;work based on the
23712 Library&rdquo; means either the Library or any derivative work under
23713 copyright law: that is to say, a work containing the Library or a
23714 portion of it, either verbatim or with modifications and/or translated
23715 straightforwardly into another language.  (Hereinafter, translation is
23716 included without limitation in the term &ldquo;modification&rdquo;.)
23717 </p>
23718 <p>&ldquo;Source code&rdquo; for a work means the preferred form of the work for
23719 making modifications to it.  For a library, complete source code means
23720 all the source code for all modules it contains, plus any associated
23721 interface definition files, plus the scripts used to control compilation
23722 and installation of the library.
23723 </p>
23724 <p>Activities other than copying, distribution and modification are not
23725 covered by this License; they are outside its scope.  The act of
23726 running a program using the Library is not restricted, and output from
23727 such a program is covered only if its contents constitute a work based
23728 on the Library (independent of the use of the Library in a tool for
23729 writing it).  Whether that is true depends on what the Library does
23730 and what the program that uses the Library does.
23731 </p>
23732 </li><li> You may copy and distribute verbatim copies of the Library&rsquo;s
23733 complete source code as you receive it, in any medium, provided that
23734 you conspicuously and appropriately publish on each copy an
23735 appropriate copyright notice and disclaimer of warranty; keep intact
23736 all the notices that refer to this License and to the absence of any
23737 warranty; and distribute a copy of this License along with the
23738 Library.
23739
23740 <p>You may charge a fee for the physical act of transferring a copy,
23741 and you may at your option offer warranty protection in exchange for a
23742 fee.
23743 </p>
23744 </li><li> You may modify your copy or copies of the Library or any portion
23745 of it, thus forming a work based on the Library, and copy and
23746 distribute such modifications or work under the terms of Section 1
23747 above, provided that you also meet all of these conditions:
23748
23749 <ol>
23750 <li> The modified work must itself be a software library.
23751
23752 </li><li> You must cause the files modified to carry prominent notices
23753 stating that you changed the files and the date of any change.
23754
23755 </li><li> You must cause the whole of the work to be licensed at no
23756 charge to all third parties under the terms of this License.
23757
23758 </li><li> If a facility in the modified Library refers to a function or a
23759 table of data to be supplied by an application program that uses
23760 the facility, other than as an argument passed when the facility
23761 is invoked, then you must make a good faith effort to ensure that,
23762 in the event an application does not supply such function or
23763 table, the facility still operates, and performs whatever part of
23764 its purpose remains meaningful.
23765
23766 <p>(For example, a function in a library to compute square roots has
23767 a purpose that is entirely well-defined independent of the
23768 application.  Therefore, Subsection 2d requires that any
23769 application-supplied function or table used by this function must
23770 be optional: if the application does not supply it, the square
23771 root function must still compute square roots.)
23772 </p></li></ol>
23773
23774 <p>These requirements apply to the modified work as a whole.  If
23775 identifiable sections of that work are not derived from the Library,
23776 and can be reasonably considered independent and separate works in
23777 themselves, then this License, and its terms, do not apply to those
23778 sections when you distribute them as separate works.  But when you
23779 distribute the same sections as part of a whole which is a work based
23780 on the Library, the distribution of the whole must be on the terms of
23781 this License, whose permissions for other licensees extend to the
23782 entire whole, and thus to each and every part regardless of who wrote
23783 it.
23784 </p>
23785 <p>Thus, it is not the intent of this section to claim rights or contest
23786 your rights to work written entirely by you; rather, the intent is to
23787 exercise the right to control the distribution of derivative or
23788 collective works based on the Library.
23789 </p>
23790 <p>In addition, mere aggregation of another work not based on the Library
23791 with the Library (or with a work based on the Library) on a volume of
23792 a storage or distribution medium does not bring the other work under
23793 the scope of this License.
23794 </p>
23795 </li><li> You may opt to apply the terms of the ordinary GNU General Public
23796 License instead of this License to a given copy of the Library.  To do
23797 this, you must alter all the notices that refer to this License, so
23798 that they refer to the ordinary GNU General Public License, version 2,
23799 instead of to this License.  (If a newer version than version 2 of the
23800 ordinary GNU General Public License has appeared, then you can specify
23801 that version instead if you wish.)  Do not make any other change in
23802 these notices.
23803
23804 <p>Once this change is made in a given copy, it is irreversible for
23805 that copy, so the ordinary GNU General Public License applies to all
23806 subsequent copies and derivative works made from that copy.
23807 </p>
23808 <p>This option is useful when you wish to copy part of the code of
23809 the Library into a program that is not a library.
23810 </p>
23811 </li><li> You may copy and distribute the Library (or a portion or
23812 derivative of it, under Section 2) in object code or executable form
23813 under the terms of Sections 1 and 2 above provided that you accompany
23814 it with the complete corresponding machine-readable source code, which
23815 must be distributed under the terms of Sections 1 and 2 above on a
23816 medium customarily used for software interchange.
23817
23818 <p>If distribution of object code is made by offering access to copy
23819 from a designated place, then offering equivalent access to copy the
23820 source code from the same place satisfies the requirement to
23821 distribute the source code, even though third parties are not
23822 compelled to copy the source along with the object code.
23823 </p>
23824 </li><li> A program that contains no derivative of any portion of the
23825 Library, but is designed to work with the Library by being compiled or
23826 linked with it, is called a &ldquo;work that uses the Library&rdquo;.  Such a
23827 work, in isolation, is not a derivative work of the Library, and
23828 therefore falls outside the scope of this License.
23829
23830 <p>However, linking a &ldquo;work that uses the Library&rdquo; with the Library
23831 creates an executable that is a derivative of the Library (because it
23832 contains portions of the Library), rather than a &ldquo;work that uses the
23833 library&rdquo;.  The executable is therefore covered by this License.
23834 Section 6 states terms for distribution of such executables.
23835 </p>
23836 <p>When a &ldquo;work that uses the Library&rdquo; uses material from a header file
23837 that is part of the Library, the object code for the work may be a
23838 derivative work of the Library even though the source code is not.
23839 Whether this is true is especially significant if the work can be
23840 linked without the Library, or if the work is itself a library.  The
23841 threshold for this to be true is not precisely defined by law.
23842 </p>
23843 <p>If such an object file uses only numerical parameters, data
23844 structure layouts and accessors, and small macros and small inline
23845 functions (ten lines or less in length), then the use of the object
23846 file is unrestricted, regardless of whether it is legally a derivative
23847 work.  (Executables containing this object code plus portions of the
23848 Library will still fall under Section 6.)
23849 </p>
23850 <p>Otherwise, if the work is a derivative of the Library, you may
23851 distribute the object code for the work under the terms of Section 6.
23852 Any executables containing that work also fall under Section 6,
23853 whether or not they are linked directly with the Library itself.
23854 </p>
23855 </li><li> As an exception to the Sections above, you may also combine or
23856 link a &ldquo;work that uses the Library&rdquo; with the Library to produce a
23857 work containing portions of the Library, and distribute that work
23858 under terms of your choice, provided that the terms permit
23859 modification of the work for the customer&rsquo;s own use and reverse
23860 engineering for debugging such modifications.
23861
23862 <p>You must give prominent notice with each copy of the work that the
23863 Library is used in it and that the Library and its use are covered by
23864 this License.  You must supply a copy of this License.  If the work
23865 during execution displays copyright notices, you must include the
23866 copyright notice for the Library among them, as well as a reference
23867 directing the user to the copy of this License.  Also, you must do one
23868 of these things:
23869 </p>
23870 <ol>
23871 <li> Accompany the work with the complete corresponding
23872 machine-readable source code for the Library including whatever
23873 changes were used in the work (which must be distributed under
23874 Sections 1 and 2 above); and, if the work is an executable linked
23875 with the Library, with the complete machine-readable &ldquo;work that
23876 uses the Library&rdquo;, as object code and/or source code, so that the
23877 user can modify the Library and then relink to produce a modified
23878 executable containing the modified Library.  (It is understood
23879 that the user who changes the contents of definitions files in the
23880 Library will not necessarily be able to recompile the application
23881 to use the modified definitions.)
23882
23883 </li><li> Use a suitable shared library mechanism for linking with the Library.  A
23884 suitable mechanism is one that (1) uses at run time a copy of the
23885 library already present on the user&rsquo;s computer system, rather than
23886 copying library functions into the executable, and (2) will operate
23887 properly with a modified version of the library, if the user installs
23888 one, as long as the modified version is interface-compatible with the
23889 version that the work was made with.
23890
23891 </li><li> Accompany the work with a written offer, valid for at
23892 least three years, to give the same user the materials
23893 specified in Subsection 6a, above, for a charge no more
23894 than the cost of performing this distribution.
23895
23896 </li><li> If distribution of the work is made by offering access to copy
23897 from a designated place, offer equivalent access to copy the above
23898 specified materials from the same place.
23899
23900 </li><li> Verify that the user has already received a copy of these
23901 materials or that you have already sent this user a copy.
23902 </li></ol>
23903
23904 <p>For an executable, the required form of the &ldquo;work that uses the
23905 Library&rdquo; must include any data and utility programs needed for
23906 reproducing the executable from it.  However, as a special exception,
23907 the materials to be distributed need not include anything that is
23908 normally distributed (in either source or binary form) with the major
23909 components (compiler, kernel, and so on) of the operating system on
23910 which the executable runs, unless that component itself accompanies the
23911 executable.
23912 </p>
23913 <p>It may happen that this requirement contradicts the license
23914 restrictions of other proprietary libraries that do not normally
23915 accompany the operating system.  Such a contradiction means you cannot
23916 use both them and the Library together in an executable that you
23917 distribute.
23918 </p>
23919 </li><li> You may place library facilities that are a work based on the
23920 Library side-by-side in a single library together with other library
23921 facilities not covered by this License, and distribute such a combined
23922 library, provided that the separate distribution of the work based on
23923 the Library and of the other library facilities is otherwise
23924 permitted, and provided that you do these two things:
23925
23926 <ol>
23927 <li> Accompany the combined library with a copy of the same work
23928 based on the Library, uncombined with any other library
23929 facilities.  This must be distributed under the terms of the
23930 Sections above.
23931
23932 </li><li> Give prominent notice with the combined library of the fact
23933 that part of it is a work based on the Library, and explaining
23934 where to find the accompanying uncombined form of the same work.
23935 </li></ol>
23936
23937 </li><li> You may not copy, modify, sublicense, link with, or distribute
23938 the Library except as expressly provided under this License.  Any
23939 attempt otherwise to copy, modify, sublicense, link with, or
23940 distribute the Library is void, and will automatically terminate your
23941 rights under this License.  However, parties who have received copies,
23942 or rights, from you under this License will not have their licenses
23943 terminated so long as such parties remain in full compliance.
23944
23945 </li><li> You are not required to accept this License, since you have not
23946 signed it.  However, nothing else grants you permission to modify or
23947 distribute the Library or its derivative works.  These actions are
23948 prohibited by law if you do not accept this License.  Therefore, by
23949 modifying or distributing the Library (or any work based on the
23950 Library), you indicate your acceptance of this License to do so, and
23951 all its terms and conditions for copying, distributing or modifying
23952 the Library or works based on it.
23953
23954 </li><li> Each time you redistribute the Library (or any work based on the
23955 Library), the recipient automatically receives a license from the
23956 original licensor to copy, distribute, link with or modify the Library
23957 subject to these terms and conditions.  You may not impose any further
23958 restrictions on the recipients&rsquo; exercise of the rights granted herein.
23959 You are not responsible for enforcing compliance by third parties with
23960 this License.
23961
23962 </li><li> If, as a consequence of a court judgment or allegation of patent
23963 infringement or for any other reason (not limited to patent issues),
23964 conditions are imposed on you (whether by court order, agreement or
23965 otherwise) that contradict the conditions of this License, they do not
23966 excuse you from the conditions of this License.  If you cannot
23967 distribute so as to satisfy simultaneously your obligations under this
23968 License and any other pertinent obligations, then as a consequence you
23969 may not distribute the Library at all.  For example, if a patent
23970 license would not permit royalty-free redistribution of the Library by
23971 all those who receive copies directly or indirectly through you, then
23972 the only way you could satisfy both it and this License would be to
23973 refrain entirely from distribution of the Library.
23974
23975 <p>If any portion of this section is held invalid or unenforceable under any
23976 particular circumstance, the balance of the section is intended to apply,
23977 and the section as a whole is intended to apply in other circumstances.
23978 </p>
23979 <p>It is not the purpose of this section to induce you to infringe any
23980 patents or other property right claims or to contest validity of any
23981 such claims; this section has the sole purpose of protecting the
23982 integrity of the free software distribution system which is
23983 implemented by public license practices.  Many people have made
23984 generous contributions to the wide range of software distributed
23985 through that system in reliance on consistent application of that
23986 system; it is up to the author/donor to decide if he or she is willing
23987 to distribute software through any other system and a licensee cannot
23988 impose that choice.
23989 </p>
23990 <p>This section is intended to make thoroughly clear what is believed to
23991 be a consequence of the rest of this License.
23992 </p>
23993 </li><li> If the distribution and/or use of the Library is restricted in
23994 certain countries either by patents or by copyrighted interfaces, the
23995 original copyright holder who places the Library under this License may add
23996 an explicit geographical distribution limitation excluding those countries,
23997 so that distribution is permitted only in or among countries not thus
23998 excluded.  In such case, this License incorporates the limitation as if
23999 written in the body of this License.
24000
24001 </li><li> The Free Software Foundation may publish revised and/or new
24002 versions of the Lesser General Public License from time to time.
24003 Such new versions will be similar in spirit to the present version,
24004 but may differ in detail to address new problems or concerns.
24005
24006 <p>Each version is given a distinguishing version number.  If the Library
24007 specifies a version number of this License which applies to it and
24008 &ldquo;any later version&rdquo;, you have the option of following the terms and
24009 conditions either of that version or of any later version published by
24010 the Free Software Foundation.  If the Library does not specify a
24011 license version number, you may choose any version ever published by
24012 the Free Software Foundation.
24013 </p>
24014 </li><li> If you wish to incorporate parts of the Library into other free
24015 programs whose distribution conditions are incompatible with these,
24016 write to the author to ask for permission.  For software which is
24017 copyrighted by the Free Software Foundation, write to the Free
24018 Software Foundation; we sometimes make exceptions for this.  Our
24019 decision will be guided by the two goals of preserving the free status
24020 of all derivatives of our free software and of promoting the sharing
24021 and reuse of software generally.
24022
24023 <div align="center"><b>NO WARRANTY</b>
24024 </div>
24025 </li><li> BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
24026 WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
24027 EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
24028 OTHER PARTIES PROVIDE THE LIBRARY &ldquo;AS IS&rdquo; WITHOUT WARRANTY OF ANY
24029 KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
24030 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
24031 PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
24032 LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
24033 THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
24034
24035 </li><li> IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
24036 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
24037 AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
24038 FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
24039 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
24040 LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
24041 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
24042 FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
24043 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
24044 DAMAGES.
24045 </li></ol>
24046
24047 <a name="END-OF-TERMS-AND-CONDITIONS"></a>
24048 <h4 class="subheading">END OF TERMS AND CONDITIONS</h4>
24049
24050 <a name="How-to-Apply-These-Terms-to-Your-New-Libraries"></a>
24051 <h4 class="subheading">How to Apply These Terms to Your New Libraries</h4>
24052
24053 <p>If you develop a new library, and you want it to be of the greatest
24054 possible use to the public, we recommend making it free software that
24055 everyone can redistribute and change.  You can do so by permitting
24056 redistribution under these terms (or, alternatively, under the terms of the
24057 ordinary General Public License).
24058 </p>
24059 <p>To apply these terms, attach the following notices to the library.  It is
24060 safest to attach them to the start of each source file to most effectively
24061 convey the exclusion of warranty; and each file should have at least the
24062 &ldquo;copyright&rdquo; line and a pointer to where the full notice is found.
24063 </p>
24064 <div class="smallexample">
24065 <pre class="smallexample"><var>one line to give the library's name and an idea of what it does.</var>
24066 Copyright (C) <var>year</var>  <var>name of author</var>
24067
24068 This library is free software; you can redistribute it and/or modify it
24069 under the terms of the GNU Lesser General Public License as published by
24070 the Free Software Foundation; either version 2.1 of the License, or (at
24071 your option) any later version.
24072
24073 This library is distributed in the hope that it will be useful, but
24074 WITHOUT ANY WARRANTY; without even the implied warranty of
24075 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
24076 Lesser General Public License for more details.
24077
24078 You should have received a copy of the GNU Lesser General Public
24079 License along with this library; if not, write to the Free Software
24080 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
24081 USA.
24082 </pre></div>
24083
24084 <p>Also add information on how to contact you by electronic and paper mail.
24085 </p>
24086 <p>You should also get your employer (if you work as a programmer) or your
24087 school, if any, to sign a &ldquo;copyright disclaimer&rdquo; for the library, if
24088 necessary.  Here is a sample; alter the names:
24089 </p>
24090 <div class="smallexample">
24091 <pre class="smallexample">Yoyodyne, Inc., hereby disclaims all copyright interest in the library
24092 `Frob' (a library for tweaking knobs) written by James Random Hacker.
24093
24094 <var>signature of Ty Coon</var>, 1 April 1990
24095 Ty Coon, President of Vice
24096 </pre></div>
24097
24098 <p>That&rsquo;s all there is to it!
24099 </p>
24100 <hr>
24101 <a name="GNU-GPL"></a>
24102 <div class="header">
24103 <p>
24104 Previous: <a href="#GNU-LGPL" accesskey="p" rel="previous">GNU LGPL</a>, Up: <a href="#Copying-Information" accesskey="u" rel="up">Copying Information</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>
24105 </div>
24106 <a name="GNU-General-Public-License"></a>
24107 <h3 class="appendixsec">A.3 GNU General Public License</h3>
24108 <a name="index-GPL_002c-GNU-General-Public-License"></a>
24109 <a name="index-License_002c-GNU-GPL"></a>
24110
24111 <div align="center">Version 3, 29 June 2007
24112 </div>
24113
24114 <div class="display">
24115 <pre class="display">Copyright &copy; 2007 Free Software Foundation, Inc. <a href="http://fsf.org/">http://fsf.org/</a>
24116
24117 Everyone is permitted to copy and distribute verbatim copies of this
24118 license document, but changing it is not allowed.
24119 </pre></div>
24120
24121 <a name="Preamble-1"></a>
24122 <h3 class="heading">Preamble</h3>
24123
24124 <p>The GNU General Public License is a free, copyleft license for
24125 software and other kinds of works.
24126 </p>
24127 <p>The licenses for most software and other practical works are designed
24128 to take away your freedom to share and change the works.  By contrast,
24129 the GNU General Public License is intended to guarantee your freedom
24130 to share and change all versions of a program&mdash;to make sure it remains
24131 free software for all its users.  We, the Free Software Foundation,
24132 use the GNU General Public License for most of our software; it
24133 applies also to any other work released this way by its authors.  You
24134 can apply it to your programs, too.
24135 </p>
24136 <p>When we speak of free software, we are referring to freedom, not
24137 price.  Our General Public Licenses are designed to make sure that you
24138 have the freedom to distribute copies of free software (and charge for
24139 them if you wish), that you receive source code or can get it if you
24140 want it, that you can change the software or use pieces of it in new
24141 free programs, and that you know you can do these things.
24142 </p>
24143 <p>To protect your rights, we need to prevent others from denying you
24144 these rights or asking you to surrender the rights.  Therefore, you
24145 have certain responsibilities if you distribute copies of the
24146 software, or if you modify it: responsibilities to respect the freedom
24147 of others.
24148 </p>
24149 <p>For example, if you distribute copies of such a program, whether
24150 gratis or for a fee, you must pass on to the recipients the same
24151 freedoms that you received.  You must make sure that they, too,
24152 receive or can get the source code.  And you must show them these
24153 terms so they know their rights.
24154 </p>
24155 <p>Developers that use the GNU GPL protect your rights with two steps:
24156 (1) assert copyright on the software, and (2) offer you this License
24157 giving you legal permission to copy, distribute and/or modify it.
24158 </p>
24159 <p>For the developers&rsquo; and authors&rsquo; protection, the GPL clearly explains
24160 that there is no warranty for this free software.  For both users&rsquo; and
24161 authors&rsquo; sake, the GPL requires that modified versions be marked as
24162 changed, so that their problems will not be attributed erroneously to
24163 authors of previous versions.
24164 </p>
24165 <p>Some devices are designed to deny users access to install or run
24166 modified versions of the software inside them, although the
24167 manufacturer can do so.  This is fundamentally incompatible with the
24168 aim of protecting users&rsquo; freedom to change the software.  The
24169 systematic pattern of such abuse occurs in the area of products for
24170 individuals to use, which is precisely where it is most unacceptable.
24171 Therefore, we have designed this version of the GPL to prohibit the
24172 practice for those products.  If such problems arise substantially in
24173 other domains, we stand ready to extend this provision to those
24174 domains in future versions of the GPL, as needed to protect the
24175 freedom of users.
24176 </p>
24177 <p>Finally, every program is threatened constantly by software patents.
24178 States should not allow patents to restrict development and use of
24179 software on general-purpose computers, but in those that do, we wish
24180 to avoid the special danger that patents applied to a free program
24181 could make it effectively proprietary.  To prevent this, the GPL
24182 assures that patents cannot be used to render the program non-free.
24183 </p>
24184 <p>The precise terms and conditions for copying, distribution and
24185 modification follow.
24186 </p>
24187 <a name="TERMS-AND-CONDITIONS"></a>
24188 <h3 class="heading">TERMS AND CONDITIONS</h3>
24189
24190 <ol>
24191 <li> Definitions.
24192
24193 <p>&ldquo;This License&rdquo; refers to version 3 of the GNU General Public License.
24194 </p>
24195 <p>&ldquo;Copyright&rdquo; also means copyright-like laws that apply to other kinds
24196 of works, such as semiconductor masks.
24197 </p>
24198 <p>&ldquo;The Program&rdquo; refers to any copyrightable work licensed under this
24199 License.  Each licensee is addressed as &ldquo;you&rdquo;.  &ldquo;Licensees&rdquo; and
24200 &ldquo;recipients&rdquo; may be individuals or organizations.
24201 </p>
24202 <p>To &ldquo;modify&rdquo; a work means to copy from or adapt all or part of the work
24203 in a fashion requiring copyright permission, other than the making of
24204 an exact copy.  The resulting work is called a &ldquo;modified version&rdquo; of
24205 the earlier work or a work &ldquo;based on&rdquo; the earlier work.
24206 </p>
24207 <p>A &ldquo;covered work&rdquo; means either the unmodified Program or a work based
24208 on the Program.
24209 </p>
24210 <p>To &ldquo;propagate&rdquo; a work means to do anything with it that, without
24211 permission, would make you directly or secondarily liable for
24212 infringement under applicable copyright law, except executing it on a
24213 computer or modifying a private copy.  Propagation includes copying,
24214 distribution (with or without modification), making available to the
24215 public, and in some countries other activities as well.
24216 </p>
24217 <p>To &ldquo;convey&rdquo; a work means any kind of propagation that enables other
24218 parties to make or receive copies.  Mere interaction with a user
24219 through a computer network, with no transfer of a copy, is not
24220 conveying.
24221 </p>
24222 <p>An interactive user interface displays &ldquo;Appropriate Legal Notices&rdquo; to
24223 the extent that it includes a convenient and prominently visible
24224 feature that (1) displays an appropriate copyright notice, and (2)
24225 tells the user that there is no warranty for the work (except to the
24226 extent that warranties are provided), that licensees may convey the
24227 work under this License, and how to view a copy of this License.  If
24228 the interface presents a list of user commands or options, such as a
24229 menu, a prominent item in the list meets this criterion.
24230 </p>
24231 </li><li> Source Code.
24232
24233 <p>The &ldquo;source code&rdquo; for a work means the preferred form of the work for
24234 making modifications to it.  &ldquo;Object code&rdquo; means any non-source form
24235 of a work.
24236 </p>
24237 <p>A &ldquo;Standard Interface&rdquo; means an interface that either is an official
24238 standard defined by a recognized standards body, or, in the case of
24239 interfaces specified for a particular programming language, one that
24240 is widely used among developers working in that language.
24241 </p>
24242 <p>The &ldquo;System Libraries&rdquo; of an executable work include anything, other
24243 than the work as a whole, that (a) is included in the normal form of
24244 packaging a Major Component, but which is not part of that Major
24245 Component, and (b) serves only to enable use of the work with that
24246 Major Component, or to implement a Standard Interface for which an
24247 implementation is available to the public in source code form.  A
24248 &ldquo;Major Component&rdquo;, in this context, means a major essential component
24249 (kernel, window system, and so on) of the specific operating system
24250 (if any) on which the executable work runs, or a compiler used to
24251 produce the work, or an object code interpreter used to run it.
24252 </p>
24253 <p>The &ldquo;Corresponding Source&rdquo; for a work in object code form means all
24254 the source code needed to generate, install, and (for an executable
24255 work) run the object code and to modify the work, including scripts to
24256 control those activities.  However, it does not include the work&rsquo;s
24257 System Libraries, or general-purpose tools or generally available free
24258 programs which are used unmodified in performing those activities but
24259 which are not part of the work.  For example, Corresponding Source
24260 includes interface definition files associated with source files for
24261 the work, and the source code for shared libraries and dynamically
24262 linked subprograms that the work is specifically designed to require,
24263 such as by intimate data communication or control flow between those
24264 subprograms and other parts of the work.
24265 </p>
24266 <p>The Corresponding Source need not include anything that users can
24267 regenerate automatically from other parts of the Corresponding Source.
24268 </p>
24269 <p>The Corresponding Source for a work in source code form is that same
24270 work.
24271 </p>
24272 </li><li> Basic Permissions.
24273
24274 <p>All rights granted under this License are granted for the term of
24275 copyright on the Program, and are irrevocable provided the stated
24276 conditions are met.  This License explicitly affirms your unlimited
24277 permission to run the unmodified Program.  The output from running a
24278 covered work is covered by this License only if the output, given its
24279 content, constitutes a covered work.  This License acknowledges your
24280 rights of fair use or other equivalent, as provided by copyright law.
24281 </p>
24282 <p>You may make, run and propagate covered works that you do not convey,
24283 without conditions so long as your license otherwise remains in force.
24284 You may convey covered works to others for the sole purpose of having
24285 them make modifications exclusively for you, or provide you with
24286 facilities for running those works, provided that you comply with the
24287 terms of this License in conveying all material for which you do not
24288 control copyright.  Those thus making or running the covered works for
24289 you must do so exclusively on your behalf, under your direction and
24290 control, on terms that prohibit them from making any copies of your
24291 copyrighted material outside their relationship with you.
24292 </p>
24293 <p>Conveying under any other circumstances is permitted solely under the
24294 conditions stated below.  Sublicensing is not allowed; section 10
24295 makes it unnecessary.
24296 </p>
24297 </li><li> Protecting Users&rsquo; Legal Rights From Anti-Circumvention Law.
24298
24299 <p>No covered work shall be deemed part of an effective technological
24300 measure under any applicable law fulfilling obligations under article
24301 11 of the WIPO copyright treaty adopted on 20 December 1996, or
24302 similar laws prohibiting or restricting circumvention of such
24303 measures.
24304 </p>
24305 <p>When you convey a covered work, you waive any legal power to forbid
24306 circumvention of technological measures to the extent such
24307 circumvention is effected by exercising rights under this License with
24308 respect to the covered work, and you disclaim any intention to limit
24309 operation or modification of the work as a means of enforcing, against
24310 the work&rsquo;s users, your or third parties&rsquo; legal rights to forbid
24311 circumvention of technological measures.
24312 </p>
24313 </li><li> Conveying Verbatim Copies.
24314
24315 <p>You may convey verbatim copies of the Program&rsquo;s source code as you
24316 receive it, in any medium, provided that you conspicuously and
24317 appropriately publish on each copy an appropriate copyright notice;
24318 keep intact all notices stating that this License and any
24319 non-permissive terms added in accord with section 7 apply to the code;
24320 keep intact all notices of the absence of any warranty; and give all
24321 recipients a copy of this License along with the Program.
24322 </p>
24323 <p>You may charge any price or no price for each copy that you convey,
24324 and you may offer support or warranty protection for a fee.
24325 </p>
24326 </li><li> Conveying Modified Source Versions.
24327
24328 <p>You may convey a work based on the Program, or the modifications to
24329 produce it from the Program, in the form of source code under the
24330 terms of section 4, provided that you also meet all of these
24331 conditions:
24332 </p>
24333 <ol>
24334 <li> The work must carry prominent notices stating that you modified it,
24335 and giving a relevant date.
24336
24337 </li><li> The work must carry prominent notices stating that it is released
24338 under this License and any conditions added under section 7.  This
24339 requirement modifies the requirement in section 4 to &ldquo;keep intact all
24340 notices&rdquo;.
24341
24342 </li><li> You must license the entire work, as a whole, under this License to
24343 anyone who comes into possession of a copy.  This License will
24344 therefore apply, along with any applicable section 7 additional terms,
24345 to the whole of the work, and all its parts, regardless of how they
24346 are packaged.  This License gives no permission to license the work in
24347 any other way, but it does not invalidate such permission if you have
24348 separately received it.
24349
24350 </li><li> If the work has interactive user interfaces, each must display
24351 Appropriate Legal Notices; however, if the Program has interactive
24352 interfaces that do not display Appropriate Legal Notices, your work
24353 need not make them do so.
24354 </li></ol>
24355
24356 <p>A compilation of a covered work with other separate and independent
24357 works, which are not by their nature extensions of the covered work,
24358 and which are not combined with it such as to form a larger program,
24359 in or on a volume of a storage or distribution medium, is called an
24360 &ldquo;aggregate&rdquo; if the compilation and its resulting copyright are not
24361 used to limit the access or legal rights of the compilation&rsquo;s users
24362 beyond what the individual works permit.  Inclusion of a covered work
24363 in an aggregate does not cause this License to apply to the other
24364 parts of the aggregate.
24365 </p>
24366 </li><li> Conveying Non-Source Forms.
24367
24368 <p>You may convey a covered work in object code form under the terms of
24369 sections 4 and 5, provided that you also convey the machine-readable
24370 Corresponding Source under the terms of this License, in one of these
24371 ways:
24372 </p>
24373 <ol>
24374 <li> Convey the object code in, or embodied in, a physical product
24375 (including a physical distribution medium), accompanied by the
24376 Corresponding Source fixed on a durable physical medium customarily
24377 used for software interchange.
24378
24379 </li><li> Convey the object code in, or embodied in, a physical product
24380 (including a physical distribution medium), accompanied by a written
24381 offer, valid for at least three years and valid for as long as you
24382 offer spare parts or customer support for that product model, to give
24383 anyone who possesses the object code either (1) a copy of the
24384 Corresponding Source for all the software in the product that is
24385 covered by this License, on a durable physical medium customarily used
24386 for software interchange, for a price no more than your reasonable
24387 cost of physically performing this conveying of source, or (2) access
24388 to copy the Corresponding Source from a network server at no charge.
24389
24390 </li><li> Convey individual copies of the object code with a copy of the written
24391 offer to provide the Corresponding Source.  This alternative is
24392 allowed only occasionally and noncommercially, and only if you
24393 received the object code with such an offer, in accord with subsection
24394 6b.
24395
24396 </li><li> Convey the object code by offering access from a designated place
24397 (gratis or for a charge), and offer equivalent access to the
24398 Corresponding Source in the same way through the same place at no
24399 further charge.  You need not require recipients to copy the
24400 Corresponding Source along with the object code.  If the place to copy
24401 the object code is a network server, the Corresponding Source may be
24402 on a different server (operated by you or a third party) that supports
24403 equivalent copying facilities, provided you maintain clear directions
24404 next to the object code saying where to find the Corresponding Source.
24405 Regardless of what server hosts the Corresponding Source, you remain
24406 obligated to ensure that it is available for as long as needed to
24407 satisfy these requirements.
24408
24409 </li><li> Convey the object code using peer-to-peer transmission, provided you
24410 inform other peers where the object code and Corresponding Source of
24411 the work are being offered to the general public at no charge under
24412 subsection 6d.
24413
24414 </li></ol>
24415
24416 <p>A separable portion of the object code, whose source code is excluded
24417 from the Corresponding Source as a System Library, need not be
24418 included in conveying the object code work.
24419 </p>
24420 <p>A &ldquo;User Product&rdquo; is either (1) a &ldquo;consumer product&rdquo;, which means any
24421 tangible personal property which is normally used for personal,
24422 family, or household purposes, or (2) anything designed or sold for
24423 incorporation into a dwelling.  In determining whether a product is a
24424 consumer product, doubtful cases shall be resolved in favor of
24425 coverage.  For a particular product received by a particular user,
24426 &ldquo;normally used&rdquo; refers to a typical or common use of that class of
24427 product, regardless of the status of the particular user or of the way
24428 in which the particular user actually uses, or expects or is expected
24429 to use, the product.  A product is a consumer product regardless of
24430 whether the product has substantial commercial, industrial or
24431 non-consumer uses, unless such uses represent the only significant
24432 mode of use of the product.
24433 </p>
24434 <p>&ldquo;Installation Information&rdquo; for a User Product means any methods,
24435 procedures, authorization keys, or other information required to
24436 install and execute modified versions of a covered work in that User
24437 Product from a modified version of its Corresponding Source.  The
24438 information must suffice to ensure that the continued functioning of
24439 the modified object code is in no case prevented or interfered with
24440 solely because modification has been made.
24441 </p>
24442 <p>If you convey an object code work under this section in, or with, or
24443 specifically for use in, a User Product, and the conveying occurs as
24444 part of a transaction in which the right of possession and use of the
24445 User Product is transferred to the recipient in perpetuity or for a
24446 fixed term (regardless of how the transaction is characterized), the
24447 Corresponding Source conveyed under this section must be accompanied
24448 by the Installation Information.  But this requirement does not apply
24449 if neither you nor any third party retains the ability to install
24450 modified object code on the User Product (for example, the work has
24451 been installed in ROM).
24452 </p>
24453 <p>The requirement to provide Installation Information does not include a
24454 requirement to continue to provide support service, warranty, or
24455 updates for a work that has been modified or installed by the
24456 recipient, or for the User Product in which it has been modified or
24457 installed.  Access to a network may be denied when the modification
24458 itself materially and adversely affects the operation of the network
24459 or violates the rules and protocols for communication across the
24460 network.
24461 </p>
24462 <p>Corresponding Source conveyed, and Installation Information provided,
24463 in accord with this section must be in a format that is publicly
24464 documented (and with an implementation available to the public in
24465 source code form), and must require no special password or key for
24466 unpacking, reading or copying.
24467 </p>
24468 </li><li> Additional Terms.
24469
24470 <p>&ldquo;Additional permissions&rdquo; are terms that supplement the terms of this
24471 License by making exceptions from one or more of its conditions.
24472 Additional permissions that are applicable to the entire Program shall
24473 be treated as though they were included in this License, to the extent
24474 that they are valid under applicable law.  If additional permissions
24475 apply only to part of the Program, that part may be used separately
24476 under those permissions, but the entire Program remains governed by
24477 this License without regard to the additional permissions.
24478 </p>
24479 <p>When you convey a copy of a covered work, you may at your option
24480 remove any additional permissions from that copy, or from any part of
24481 it.  (Additional permissions may be written to require their own
24482 removal in certain cases when you modify the work.)  You may place
24483 additional permissions on material, added by you to a covered work,
24484 for which you have or can give appropriate copyright permission.
24485 </p>
24486 <p>Notwithstanding any other provision of this License, for material you
24487 add to a covered work, you may (if authorized by the copyright holders
24488 of that material) supplement the terms of this License with terms:
24489 </p>
24490 <ol>
24491 <li> Disclaiming warranty or limiting liability differently from the terms
24492 of sections 15 and 16 of this License; or
24493
24494 </li><li> Requiring preservation of specified reasonable legal notices or author
24495 attributions in that material or in the Appropriate Legal Notices
24496 displayed by works containing it; or
24497
24498 </li><li> Prohibiting misrepresentation of the origin of that material, or
24499 requiring that modified versions of such material be marked in
24500 reasonable ways as different from the original version; or
24501
24502 </li><li> Limiting the use for publicity purposes of names of licensors or
24503 authors of the material; or
24504
24505 </li><li> Declining to grant rights under trademark law for use of some trade
24506 names, trademarks, or service marks; or
24507
24508 </li><li> Requiring indemnification of licensors and authors of that material by
24509 anyone who conveys the material (or modified versions of it) with
24510 contractual assumptions of liability to the recipient, for any
24511 liability that these contractual assumptions directly impose on those
24512 licensors and authors.
24513 </li></ol>
24514
24515 <p>All other non-permissive additional terms are considered &ldquo;further
24516 restrictions&rdquo; within the meaning of section 10.  If the Program as you
24517 received it, or any part of it, contains a notice stating that it is
24518 governed by this License along with a term that is a further
24519 restriction, you may remove that term.  If a license document contains
24520 a further restriction but permits relicensing or conveying under this
24521 License, you may add to a covered work material governed by the terms
24522 of that license document, provided that the further restriction does
24523 not survive such relicensing or conveying.
24524 </p>
24525 <p>If you add terms to a covered work in accord with this section, you
24526 must place, in the relevant source files, a statement of the
24527 additional terms that apply to those files, or a notice indicating
24528 where to find the applicable terms.
24529 </p>
24530 <p>Additional terms, permissive or non-permissive, may be stated in the
24531 form of a separately written license, or stated as exceptions; the
24532 above requirements apply either way.
24533 </p>
24534 </li><li> Termination.
24535
24536 <p>You may not propagate or modify a covered work except as expressly
24537 provided under this License.  Any attempt otherwise to propagate or
24538 modify it is void, and will automatically terminate your rights under
24539 this License (including any patent licenses granted under the third
24540 paragraph of section 11).
24541 </p>
24542 <p>However, if you cease all violation of this License, then your license
24543 from a particular copyright holder is reinstated (a) provisionally,
24544 unless and until the copyright holder explicitly and finally
24545 terminates your license, and (b) permanently, if the copyright holder
24546 fails to notify you of the violation by some reasonable means prior to
24547 60 days after the cessation.
24548 </p>
24549 <p>Moreover, your license from a particular copyright holder is
24550 reinstated permanently if the copyright holder notifies you of the
24551 violation by some reasonable means, this is the first time you have
24552 received notice of violation of this License (for any work) from that
24553 copyright holder, and you cure the violation prior to 30 days after
24554 your receipt of the notice.
24555 </p>
24556 <p>Termination of your rights under this section does not terminate the
24557 licenses of parties who have received copies or rights from you under
24558 this License.  If your rights have been terminated and not permanently
24559 reinstated, you do not qualify to receive new licenses for the same
24560 material under section 10.
24561 </p>
24562 </li><li> Acceptance Not Required for Having Copies.
24563
24564 <p>You are not required to accept this License in order to receive or run
24565 a copy of the Program.  Ancillary propagation of a covered work
24566 occurring solely as a consequence of using peer-to-peer transmission
24567 to receive a copy likewise does not require acceptance.  However,
24568 nothing other than this License grants you permission to propagate or
24569 modify any covered work.  These actions infringe copyright if you do
24570 not accept this License.  Therefore, by modifying or propagating a
24571 covered work, you indicate your acceptance of this License to do so.
24572 </p>
24573 </li><li> Automatic Licensing of Downstream Recipients.
24574
24575 <p>Each time you convey a covered work, the recipient automatically
24576 receives a license from the original licensors, to run, modify and
24577 propagate that work, subject to this License.  You are not responsible
24578 for enforcing compliance by third parties with this License.
24579 </p>
24580 <p>An &ldquo;entity transaction&rdquo; is a transaction transferring control of an
24581 organization, or substantially all assets of one, or subdividing an
24582 organization, or merging organizations.  If propagation of a covered
24583 work results from an entity transaction, each party to that
24584 transaction who receives a copy of the work also receives whatever
24585 licenses to the work the party&rsquo;s predecessor in interest had or could
24586 give under the previous paragraph, plus a right to possession of the
24587 Corresponding Source of the work from the predecessor in interest, if
24588 the predecessor has it or can get it with reasonable efforts.
24589 </p>
24590 <p>You may not impose any further restrictions on the exercise of the
24591 rights granted or affirmed under this License.  For example, you may
24592 not impose a license fee, royalty, or other charge for exercise of
24593 rights granted under this License, and you may not initiate litigation
24594 (including a cross-claim or counterclaim in a lawsuit) alleging that
24595 any patent claim is infringed by making, using, selling, offering for
24596 sale, or importing the Program or any portion of it.
24597 </p>
24598 </li><li> Patents.
24599
24600 <p>A &ldquo;contributor&rdquo; is a copyright holder who authorizes use under this
24601 License of the Program or a work on which the Program is based.  The
24602 work thus licensed is called the contributor&rsquo;s &ldquo;contributor version&rdquo;.
24603 </p>
24604 <p>A contributor&rsquo;s &ldquo;essential patent claims&rdquo; are all patent claims owned
24605 or controlled by the contributor, whether already acquired or
24606 hereafter acquired, that would be infringed by some manner, permitted
24607 by this License, of making, using, or selling its contributor version,
24608 but do not include claims that would be infringed only as a
24609 consequence of further modification of the contributor version.  For
24610 purposes of this definition, &ldquo;control&rdquo; includes the right to grant
24611 patent sublicenses in a manner consistent with the requirements of
24612 this License.
24613 </p>
24614 <p>Each contributor grants you a non-exclusive, worldwide, royalty-free
24615 patent license under the contributor&rsquo;s essential patent claims, to
24616 make, use, sell, offer for sale, import and otherwise run, modify and
24617 propagate the contents of its contributor version.
24618 </p>
24619 <p>In the following three paragraphs, a &ldquo;patent license&rdquo; is any express
24620 agreement or commitment, however denominated, not to enforce a patent
24621 (such as an express permission to practice a patent or covenant not to
24622 sue for patent infringement).  To &ldquo;grant&rdquo; such a patent license to a
24623 party means to make such an agreement or commitment not to enforce a
24624 patent against the party.
24625 </p>
24626 <p>If you convey a covered work, knowingly relying on a patent license,
24627 and the Corresponding Source of the work is not available for anyone
24628 to copy, free of charge and under the terms of this License, through a
24629 publicly available network server or other readily accessible means,
24630 then you must either (1) cause the Corresponding Source to be so
24631 available, or (2) arrange to deprive yourself of the benefit of the
24632 patent license for this particular work, or (3) arrange, in a manner
24633 consistent with the requirements of this License, to extend the patent
24634 license to downstream recipients.  &ldquo;Knowingly relying&rdquo; means you have
24635 actual knowledge that, but for the patent license, your conveying the
24636 covered work in a country, or your recipient&rsquo;s use of the covered work
24637 in a country, would infringe one or more identifiable patents in that
24638 country that you have reason to believe are valid.
24639 </p>
24640 <p>If, pursuant to or in connection with a single transaction or
24641 arrangement, you convey, or propagate by procuring conveyance of, a
24642 covered work, and grant a patent license to some of the parties
24643 receiving the covered work authorizing them to use, propagate, modify
24644 or convey a specific copy of the covered work, then the patent license
24645 you grant is automatically extended to all recipients of the covered
24646 work and works based on it.
24647 </p>
24648 <p>A patent license is &ldquo;discriminatory&rdquo; if it does not include within the
24649 scope of its coverage, prohibits the exercise of, or is conditioned on
24650 the non-exercise of one or more of the rights that are specifically
24651 granted under this License.  You may not convey a covered work if you
24652 are a party to an arrangement with a third party that is in the
24653 business of distributing software, under which you make payment to the
24654 third party based on the extent of your activity of conveying the
24655 work, and under which the third party grants, to any of the parties
24656 who would receive the covered work from you, a discriminatory patent
24657 license (a) in connection with copies of the covered work conveyed by
24658 you (or copies made from those copies), or (b) primarily for and in
24659 connection with specific products or compilations that contain the
24660 covered work, unless you entered into that arrangement, or that patent
24661 license was granted, prior to 28 March 2007.
24662 </p>
24663 <p>Nothing in this License shall be construed as excluding or limiting
24664 any implied license or other defenses to infringement that may
24665 otherwise be available to you under applicable patent law.
24666 </p>
24667 </li><li> No Surrender of Others&rsquo; Freedom.
24668
24669 <p>If conditions are imposed on you (whether by court order, agreement or
24670 otherwise) that contradict the conditions of this License, they do not
24671 excuse you from the conditions of this License.  If you cannot convey
24672 a covered work so as to satisfy simultaneously your obligations under
24673 this License and any other pertinent obligations, then as a
24674 consequence you may not convey it at all.  For example, if you agree
24675 to terms that obligate you to collect a royalty for further conveying
24676 from those to whom you convey the Program, the only way you could
24677 satisfy both those terms and this License would be to refrain entirely
24678 from conveying the Program.
24679 </p>
24680 </li><li> Use with the GNU Affero General Public License.
24681
24682 <p>Notwithstanding any other provision of this License, you have
24683 permission to link or combine any covered work with a work licensed
24684 under version 3 of the GNU Affero General Public License into a single
24685 combined work, and to convey the resulting work.  The terms of this
24686 License will continue to apply to the part which is the covered work,
24687 but the special requirements of the GNU Affero General Public License,
24688 section 13, concerning interaction through a network will apply to the
24689 combination as such.
24690 </p>
24691 </li><li> Revised Versions of this License.
24692
24693 <p>The Free Software Foundation may publish revised and/or new versions
24694 of the GNU General Public License from time to time.  Such new
24695 versions will be similar in spirit to the present version, but may
24696 differ in detail to address new problems or concerns.
24697 </p>
24698 <p>Each version is given a distinguishing version number.  If the Program
24699 specifies that a certain numbered version of the GNU General Public
24700 License &ldquo;or any later version&rdquo; applies to it, you have the option of
24701 following the terms and conditions either of that numbered version or
24702 of any later version published by the Free Software Foundation.  If
24703 the Program does not specify a version number of the GNU General
24704 Public License, you may choose any version ever published by the Free
24705 Software Foundation.
24706 </p>
24707 <p>If the Program specifies that a proxy can decide which future versions
24708 of the GNU General Public License can be used, that proxy&rsquo;s public
24709 statement of acceptance of a version permanently authorizes you to
24710 choose that version for the Program.
24711 </p>
24712 <p>Later license versions may give you additional or different
24713 permissions.  However, no additional obligations are imposed on any
24714 author or copyright holder as a result of your choosing to follow a
24715 later version.
24716 </p>
24717 </li><li> Disclaimer of Warranty.
24718
24719 <p>THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
24720 APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
24721 HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM &ldquo;AS IS&rdquo; WITHOUT
24722 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
24723 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24724 A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND
24725 PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE
24726 DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
24727 CORRECTION.
24728 </p>
24729 </li><li> Limitation of Liability.
24730
24731 <p>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
24732 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
24733 CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
24734 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
24735 ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
24736 NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
24737 LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
24738 TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
24739 PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
24740 </p>
24741 </li><li> Interpretation of Sections 15 and 16.
24742
24743 <p>If the disclaimer of warranty and limitation of liability provided
24744 above cannot be given local legal effect according to their terms,
24745 reviewing courts shall apply local law that most closely approximates
24746 an absolute waiver of all civil liability in connection with the
24747 Program, unless a warranty or assumption of liability accompanies a
24748 copy of the Program in return for a fee.
24749 </p>
24750 </li></ol>
24751
24752 <a name="END-OF-TERMS-AND-CONDITIONS-1"></a>
24753 <h3 class="heading">END OF TERMS AND CONDITIONS</h3>
24754
24755 <a name="How-to-Apply-These-Terms-to-Your-New-Programs"></a>
24756 <h3 class="heading">How to Apply These Terms to Your New Programs</h3>
24757
24758 <p>If you develop a new program, and you want it to be of the greatest
24759 possible use to the public, the best way to achieve this is to make it
24760 free software which everyone can redistribute and change under these
24761 terms.
24762 </p>
24763 <p>To do so, attach the following notices to the program.  It is safest
24764 to attach them to the start of each source file to most effectively
24765 state the exclusion of warranty; and each file should have at least
24766 the &ldquo;copyright&rdquo; line and a pointer to where the full notice is found.
24767 </p>
24768 <div class="smallexample">
24769 <pre class="smallexample"><var>one line to give the program's name and a brief idea of what it does.</var>
24770 Copyright (C) <var>year</var> <var>name of author</var>
24771
24772 This program is free software: you can redistribute it and/or modify
24773 it under the terms of the GNU General Public License as published by
24774 the Free Software Foundation, either version 3 of the License, or (at
24775 your option) any later version.
24776
24777 This program is distributed in the hope that it will be useful, but
24778 WITHOUT ANY WARRANTY; without even the implied warranty of
24779 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
24780 General Public License for more details.
24781
24782 You should have received a copy of the GNU General Public License
24783 along with this program.  If not, see <a href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>.
24784 </pre></div>
24785
24786 <p>Also add information on how to contact you by electronic and paper mail.
24787 </p>
24788 <p>If the program does terminal interaction, make it output a short
24789 notice like this when it starts in an interactive mode:
24790 </p>
24791 <div class="smallexample">
24792 <pre class="smallexample"><var>program</var> Copyright (C) <var>year</var> <var>name of author</var>
24793 This program comes with ABSOLUTELY NO WARRANTY; for details type &lsquo;<samp>show w</samp>&rsquo;.
24794 This is free software, and you are welcome to redistribute it
24795 under certain conditions; type &lsquo;<samp>show c</samp>&rsquo; for details.
24796 </pre></div>
24797
24798 <p>The hypothetical commands &lsquo;<samp>show w</samp>&rsquo; and &lsquo;<samp>show c</samp>&rsquo; should show
24799 the appropriate parts of the General Public License.  Of course, your
24800 program&rsquo;s commands might be different; for a GUI interface, you would
24801 use an &ldquo;about box&rdquo;.
24802 </p>
24803 <p>You should also get your employer (if you work as a programmer) or school,
24804 if any, to sign a &ldquo;copyright disclaimer&rdquo; for the program, if necessary.
24805 For more information on this, and how to apply and follow the GNU GPL, see
24806 <a href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>.
24807 </p>
24808 <p>The GNU General Public License does not permit incorporating your
24809 program into proprietary programs.  If your program is a subroutine
24810 library, you may consider it more useful to permit linking proprietary
24811 applications with the library.  If this is what you want to do, use
24812 the GNU Lesser General Public License instead of this License.  But
24813 first, please read <a href="http://www.gnu.org/philosophy/why-not-lgpl.html">http://www.gnu.org/philosophy/why-not-lgpl.html</a>.
24814 </p>
24815 <hr>
24816 <a name="Bibliography"></a>
24817 <div class="header">
24818 <p>
24819 Next: <a href="#Function-and-Data-Index" accesskey="n" rel="next">Function and Data Index</a>, Previous: <a href="#Copying-Information" accesskey="p" rel="previous">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>
24820 </div>
24821 <a name="Bibliography-1"></a>
24822 <h2 class="unnumbered">Bibliography</h2>
24823
24824 <dl compact="compact">
24825 <dt><a name="CBCATT"></a>[CBCATT]</dt>
24826 <dd><p>Bodo Moeller, &quot;Security of CBC Ciphersuites in SSL/TLS: Problems and
24827 Countermeasures&quot;, 2002, available from
24828 <a href="http://www.openssl.org/~bodo/tls-cbc.txt">http://www.openssl.org/~bodo/tls-cbc.txt</a>.
24829 </p>
24830 </dd>
24831 <dt><a name="GPGH"></a>[GPGH]</dt>
24832 <dd><p>Mike Ashley, &quot;The GNU Privacy Handbook&quot;, 2002, available from
24833 <a href="http://www.gnupg.org/gph/en/manual.pdf">http://www.gnupg.org/gph/en/manual.pdf</a>.
24834 </p>
24835 </dd>
24836 <dt><a name="GUTPKI"></a>[GUTPKI]</dt>
24837 <dd><p>Peter Gutmann, &quot;Everything you never wanted to know about PKI but were
24838 forced to find out&quot;, Available from
24839 <a href="http://www.cs.auckland.ac.nz/~pgut001/">http://www.cs.auckland.ac.nz/~pgut001/</a>.
24840 </p>
24841 </dd>
24842 <dt><a name="NISTSP80057"></a>[NISTSP80057]</dt>
24843 <dd><p>NIST Special Publication 800-57, &quot;Recommendation for Key Management -
24844 Part 1: General (Revised)&quot;, March 2007, available from
24845 <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>.
24846 </p>
24847 </dd>
24848 <dt><a name="RFC2246"></a>[RFC2246]</dt>
24849 <dd><p>Tim Dierks and Christopher Allen, &quot;The TLS Protocol Version 1.0&quot;,
24850 January 1999, Available from
24851 <a href="http://www.ietf.org/rfc/rfc2246.txt">http://www.ietf.org/rfc/rfc2246.txt</a>.
24852 </p>
24853 </dd>
24854 <dt><a name="RFC4346"></a>[RFC4346]</dt>
24855 <dd><p>Tim Dierks and Eric Rescorla, &quot;The TLS Protocol Version 1.1&quot;, Match
24856 2006, Available from <a href="http://www.ietf.org/rfc/rfc4346.txt">http://www.ietf.org/rfc/rfc4346.txt</a>.
24857 </p>
24858 </dd>
24859 <dt><a name="RFC2440"></a>[RFC2440]</dt>
24860 <dd><p>Jon Callas, Lutz Donnerhacke, Hal Finney and Rodney Thayer, &quot;OpenPGP
24861 Message Format&quot;, November 1998, Available from
24862 <a href="http://www.ietf.org/rfc/rfc2440.txt">http://www.ietf.org/rfc/rfc2440.txt</a>.
24863 </p>
24864 </dd>
24865 <dt><a name="RFC4880"></a>[RFC4880]</dt>
24866 <dd><p>Jon Callas, Lutz Donnerhacke, Hal Finney, David Shaw and Rodney
24867 Thayer, &quot;OpenPGP Message Format&quot;, November 2007, Available from
24868 <a href="http://www.ietf.org/rfc/rfc4880.txt">http://www.ietf.org/rfc/rfc4880.txt</a>.
24869 </p>
24870 </dd>
24871 <dt><a name="RFC4211"></a>[RFC4211]</dt>
24872 <dd><p>J. Schaad, &quot;Internet X.509 Public Key Infrastructure Certificate
24873 Request Message Format (CRMF)&quot;, September 2005, Available from
24874 <a href="http://www.ietf.org/rfc/rfc4211.txt">http://www.ietf.org/rfc/rfc4211.txt</a>.
24875 </p>
24876 </dd>
24877 <dt><a name="RFC2817"></a>[RFC2817]</dt>
24878 <dd><p>Rohit Khare and Scott Lawrence, &quot;Upgrading to TLS Within HTTP/1.1&quot;,
24879 May 2000, Available from <a href="http://www.ietf.org/rfc/rfc2817.txt">http://www.ietf.org/rfc/rfc2817.txt</a>
24880 </p>
24881 </dd>
24882 <dt><a name="RFC2818"></a>[RFC2818]</dt>
24883 <dd><p>Eric Rescorla, &quot;HTTP Over TLS&quot;, May 2000, Available from
24884 <a href="http://www.ietf/rfc/rfc2818.txt">http://www.ietf/rfc/rfc2818.txt</a>.
24885 </p>
24886 </dd>
24887 <dt><a name="RFC2945"></a>[RFC2945]</dt>
24888 <dd><p>Tom Wu, &quot;The SRP Authentication and Key Exchange System&quot;, September
24889 2000, Available from <a href="http://www.ietf.org/rfc/rfc2945.txt">http://www.ietf.org/rfc/rfc2945.txt</a>.
24890 </p>
24891 </dd>
24892 <dt><a name="RFC2986"></a>[RFC2986]</dt>
24893 <dd><p>Magnus Nystrom and Burt Kaliski, &quot;PKCS 10 v1.7: Certification Request
24894 Syntax Specification&quot;, November 2000, Available from
24895 <a href="http://www.ietf.org/rfc/rfc2986.txt">http://www.ietf.org/rfc/rfc2986.txt</a>.
24896 </p>
24897 </dd>
24898 <dt><a name="PKIX"></a>[PKIX]</dt>
24899 <dd><p>D. Cooper, S. Santesson, S. Farrel, S. Boeyen, R. Housley, W. Polk,
24900 &quot;Internet X.509 Public Key Infrastructure Certificate and Certificate
24901 Revocation List (CRL) Profile&quot;, May 2008, available from
24902 <a href="http://www.ietf.org/rfc/rfc5280.txt">http://www.ietf.org/rfc/rfc5280.txt</a>.
24903 </p>
24904 </dd>
24905 <dt><a name="RFC3749"></a>[RFC3749]</dt>
24906 <dd><p>Scott Hollenbeck, &quot;Transport Layer Security Protocol Compression
24907 Methods&quot;, May 2004, available from
24908 <a href="http://www.ietf.org/rfc/rfc3749.txt">http://www.ietf.org/rfc/rfc3749.txt</a>.
24909 </p>
24910 </dd>
24911 <dt><a name="RFC3820"></a>[RFC3820]</dt>
24912 <dd><p>Steven Tuecke, Von Welch, Doug Engert, Laura Pearlman, and Mary
24913 Thompson, &quot;Internet X.509 Public Key Infrastructure (PKI) Proxy
24914 Certificate Profile&quot;, June 2004, available from
24915 <a href="http://www.ietf.org/rfc/rfc3820">http://www.ietf.org/rfc/rfc3820</a>.
24916 </p>
24917 </dd>
24918 <dt><a name="RFC5746"></a>[RFC5746]</dt>
24919 <dd><p>E. Rescorla, M. Ray, S. Dispensa, and N. Oskov, &quot;Transport Layer
24920 Security (TLS) Renegotiation Indication Extension&quot;, February 2010,
24921 available from <a href="http://www.ietf.org/rfc/rfc5746">http://www.ietf.org/rfc/rfc5746</a>.
24922 </p>
24923 </dd>
24924 <dt><a name="TLSTKT"></a>[TLSTKT]</dt>
24925 <dd><p>Joseph Salowey, Hao Zhou, Pasi Eronen, Hannes Tschofenig, &quot;Transport
24926 Layer Security (TLS) Session Resumption without Server-Side State&quot;,
24927 January 2008, available from <a href="http://www.ietf.org/rfc/rfc5077">http://www.ietf.org/rfc/rfc5077</a>.
24928 </p>
24929 </dd>
24930 <dt><a name="PKCS12"></a>[PKCS12]</dt>
24931 <dd><p>RSA Laboratories, &quot;PKCS 12 v1.0: Personal Information Exchange
24932 Syntax&quot;, June 1999, Available from <a href="http://www.rsa.com">http://www.rsa.com</a>.
24933 </p>
24934 </dd>
24935 <dt><a name="PKCS11"></a>[PKCS11]</dt>
24936 <dd><p>RSA Laboratories, &quot;PKCS #11 Base Functionality v2.30: Cryptoki â\80\93 Draft 4&quot;,
24937 July 2009, Available from <a href="http://www.rsa.com">http://www.rsa.com</a>.
24938 </p>
24939 </dd>
24940 <dt><a name="RESCORLA"></a>[RESCORLA]</dt>
24941 <dd><p>Eric Rescorla, &quot;SSL and TLS: Designing and Building Secure Systems&quot;,
24942 2001
24943 </p>
24944 </dd>
24945 <dt><a name="SELKEY"></a>[SELKEY]</dt>
24946 <dd><p>Arjen Lenstra and Eric Verheul, &quot;Selecting Cryptographic Key Sizes&quot;,
24947 2003, available from <a href="http://www.win.tue.nl/~klenstra/key.pdf">http://www.win.tue.nl/~klenstra/key.pdf</a>.
24948 </p>
24949 </dd>
24950 <dt><a name="SSL3"></a>[SSL3]</dt>
24951 <dd><p>Alan Freier, Philip Karlton and Paul Kocher, &quot;The SSL Protocol Version
24952 3.0&quot;, November 1996, Available from
24953 <a href="http://wp.netscape.com/eng/ssl3/draft302.txt">http://wp.netscape.com/eng/ssl3/draft302.txt</a>.
24954 </p>
24955 </dd>
24956 <dt><a name="STEVENS"></a>[STEVENS]</dt>
24957 <dd><p>Richard Stevens, &quot;UNIX Network Programming, Volume 1&quot;, Prentice Hall
24958 PTR, January 1998
24959 </p>
24960 </dd>
24961 <dt><a name="TLSEXT"></a>[TLSEXT]</dt>
24962 <dd><p>Simon Blake-Wilson, Magnus Nystrom, David Hopwood, Jan Mikkelsen and
24963 Tim Wright, &quot;Transport Layer Security (TLS) Extensions&quot;, June 2003,
24964 Available from <a href="http://www.ietf.org/rfc/rfc3546.txt">http://www.ietf.org/rfc/rfc3546.txt</a>.
24965 </p>
24966 </dd>
24967 <dt><a name="TLSPGP"></a>[TLSPGP]</dt>
24968 <dd><p>Nikos Mavrogiannopoulos, &quot;Using OpenPGP keys for TLS authentication&quot;,
24969 January 2011. Available from
24970 <a href="http://www.ietf.org/rfc/rfc6091.txt">http://www.ietf.org/rfc/rfc6091.txt</a>.
24971 </p>
24972 </dd>
24973 <dt><a name="TLSSRP"></a>[TLSSRP]</dt>
24974 <dd><p>David Taylor, Trevor Perrin, Tom Wu and Nikos Mavrogiannopoulos,
24975 &quot;Using SRP for TLS Authentication&quot;, November 2007. Available from
24976 <a href="http://www.ietf.org/rfc/rfc5054.txt">http://www.ietf.org/rfc/rfc5054.txt</a>.
24977 </p>
24978 </dd>
24979 <dt><a name="TLSPSK"></a>[TLSPSK]</dt>
24980 <dd><p>Pasi Eronen and Hannes Tschofenig, &quot;Pre-shared key Ciphersuites for
24981 TLS&quot;, December 2005, Available from
24982 <a href="http://www.ietf.org/rfc/rfc4279.txt">http://www.ietf.org/rfc/rfc4279.txt</a>.
24983 </p>
24984 </dd>
24985 <dt><a name="TOMSRP"></a>[TOMSRP]</dt>
24986 <dd><p>Tom Wu, &quot;The Stanford SRP Authentication Project&quot;, Available at
24987 <a href="http://srp.stanford.edu/">http://srp.stanford.edu/</a>.
24988 </p>
24989 </dd>
24990 <dt><a name="WEGER"></a>[WEGER]</dt>
24991 <dd><p>Arjen Lenstra and Xiaoyun Wang and Benne de Weger, &quot;Colliding X.509
24992 Certificates&quot;, Cryptology ePrint Archive, Report 2005/067, Available
24993 at <a href="http://eprint.iacr.org/">http://eprint.iacr.org/</a>.
24994 </p>
24995 </dd>
24996 <dt><a name="ECRYPT"></a>[ECRYPT]</dt>
24997 <dd><p>European Network of Excellence in Cryptology II, &quot;ECRYPT II Yearly
24998 Report on Algorithms and Keysizes (2009-2010)&quot;, Available
24999 at <a href="http://www.ecrypt.eu.org/documents/D.SPA.13.pdf">http://www.ecrypt.eu.org/documents/D.SPA.13.pdf</a>.
25000 </p>
25001 </dd>
25002 <dt><a name="RFC5056"></a>[RFC5056]</dt>
25003 <dd><p>N. Williams, &quot;On the Use of Channel Bindings to Secure Channels&quot;,
25004 November 2007, available from <a href="http://www.ietf.org/rfc/rfc5056">http://www.ietf.org/rfc/rfc5056</a>.
25005 </p>
25006 </dd>
25007 <dt><a name="RFC5929"></a>[RFC5929]</dt>
25008 <dd><p>J. Altman, N. Williams, L. Zhu, &quot;Channel Bindings for TLS&quot;, July 2010,
25009 available from <a href="http://www.ietf.org/rfc/rfc5929">http://www.ietf.org/rfc/rfc5929</a>.
25010 </p>
25011 </dd>
25012 </dl>
25013
25014 <hr>
25015 <a name="Function-and-Data-Index"></a>
25016 <div class="header">
25017 <p>
25018 Next: <a href="#Concept-Index" accesskey="n" rel="next">Concept Index</a>, Previous: <a href="#Bibliography" accesskey="p" rel="previous">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>
25019 </div>
25020 <a name="Function-and-Data-Index-1"></a>
25021 <h2 class="unnumbered">Function and Data Index</h2>
25022
25023 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Function-and-Data-Index_fn_letter-A"><b>A</b></a>
25024  &nbsp;
25025 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-B"><b>B</b></a>
25026  &nbsp;
25027 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-C"><b>C</b></a>
25028  &nbsp;
25029 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-D"><b>D</b></a>
25030  &nbsp;
25031 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-E"><b>E</b></a>
25032  &nbsp;
25033 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-G"><b>G</b></a>
25034  &nbsp;
25035 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-H"><b>H</b></a>
25036  &nbsp;
25037 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-I"><b>I</b></a>
25038  &nbsp;
25039 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-K"><b>K</b></a>
25040  &nbsp;
25041 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-M"><b>M</b></a>
25042  &nbsp;
25043 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-O"><b>O</b></a>
25044  &nbsp;
25045 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-P"><b>P</b></a>
25046  &nbsp;
25047 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-R"><b>R</b></a>
25048  &nbsp;
25049 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-S"><b>S</b></a>
25050  &nbsp;
25051 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-X"><b>X</b></a>
25052  &nbsp;
25053 </td></tr></table>
25054 <table class="index-fn" border="0">
25055 <tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
25056 <tr><td colspan="4"> <hr></td></tr>
25057 <tr><th><a name="Function-and-Data-Index_fn_letter-A">A</a></th><td></td><td></td></tr>
25058 <tr><td></td><td valign="top"><a href="#index-alert_002ddescription_002d_003estring"><code>alert-description-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25059 <tr><td></td><td valign="top"><a href="#index-alert_002dget"><code>alert-get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25060 <tr><td></td><td valign="top"><a href="#index-alert_002dlevel_002d_003estring"><code>alert-level-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25061 <tr><td></td><td valign="top"><a href="#index-alert_002dsend"><code>alert-send</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25062 <tr><td></td><td valign="top"><a href="#index-anonymous_002dclient_002dcredentials_003f"><code>anonymous-client-credentials?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25063 <tr><td></td><td valign="top"><a href="#index-anonymous_002dserver_002dcredentials_003f"><code>anonymous-server-credentials?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25064 <tr><td colspan="4"> <hr></td></tr>
25065 <tr><th><a name="Function-and-Data-Index_fn_letter-B">B</a></th><td></td><td></td></tr>
25066 <tr><td></td><td valign="top"><a href="#index-bye"><code>bye</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25067 <tr><td colspan="4"> <hr></td></tr>
25068 <tr><th><a name="Function-and-Data-Index_fn_letter-C">C</a></th><td></td><td></td></tr>
25069 <tr><td></td><td valign="top"><a href="#index-certificate_002dcredentials_003f"><code>certificate-credentials?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25070 <tr><td></td><td valign="top"><a href="#index-certificate_002drequest_002d_003estring"><code>certificate-request-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25071 <tr><td></td><td valign="top"><a href="#index-certificate_002dstatus_002d_003estring"><code>certificate-status-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25072 <tr><td></td><td valign="top"><a href="#index-certificate_002dtype_002d_003estring"><code>certificate-type-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25073 <tr><td></td><td valign="top"><a href="#index-certificate_002dverify_002d_003estring"><code>certificate-verify-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25074 <tr><td></td><td valign="top"><a href="#index-cipher_002d_003estring"><code>cipher-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25075 <tr><td></td><td valign="top"><a href="#index-cipher_002dsuite_002d_003estring"><code>cipher-suite-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25076 <tr><td></td><td valign="top"><a href="#index-close_002drequest_002d_003estring"><code>close-request-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25077 <tr><td></td><td valign="top"><a href="#index-compression_002dmethod_002d_003estring"><code>compression-method-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25078 <tr><td></td><td valign="top"><a href="#index-connection_002dend_002d_003estring"><code>connection-end-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25079 <tr><td></td><td valign="top"><a href="#index-credentials_002d_003estring"><code>credentials-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25080 <tr><td colspan="4"> <hr></td></tr>
25081 <tr><th><a name="Function-and-Data-Index_fn_letter-D">D</a></th><td></td><td></td></tr>
25082 <tr><td></td><td valign="top"><a href="#index-dh_002dparameters_003f"><code>dh-parameters?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25083 <tr><td></td><td valign="top"><a href="#index-digest_002d_003estring"><code>digest-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25084 <tr><td colspan="4"> <hr></td></tr>
25085 <tr><th><a name="Function-and-Data-Index_fn_letter-E">E</a></th><td></td><td></td></tr>
25086 <tr><td></td><td valign="top"><a href="#index-error_002d_003estring"><code>error-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Exception-Handling">Exception Handling</a></td></tr>
25087 <tr><td></td><td valign="top"><a href="#index-error_002d_003estring-1"><code>error-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25088 <tr><td colspan="4"> <hr></td></tr>
25089 <tr><th><a name="Function-and-Data-Index_fn_letter-G">G</a></th><td></td><td></td></tr>
25090 <tr><td></td><td valign="top"><a href="#index-gnutls_002dversion"><code>gnutls-version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25091 <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="#Core-functions">Core functions</a></td></tr>
25092 <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="#Core-functions">Core functions</a></td></tr>
25093 <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="#Core-functions">Core functions</a></td></tr>
25094 <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-functions">Core functions</a></td></tr>
25095 <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-functions">Core functions</a></td></tr>
25096 <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-functions">Core functions</a></td></tr>
25097 <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-functions">Core functions</a></td></tr>
25098 <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-functions">Core functions</a></td></tr>
25099 <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-functions">Core functions</a></td></tr>
25100 <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-functions">Core functions</a></td></tr>
25101 <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-functions">Core functions</a></td></tr>
25102 <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-functions">Core functions</a></td></tr>
25103 <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-functions">Core functions</a></td></tr>
25104 <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-functions">Core functions</a></td></tr>
25105 <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="#Core-functions">Core functions</a></td></tr>
25106 <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-functions">Core functions</a></td></tr>
25107 <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-functions">Core functions</a></td></tr>
25108 <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-functions">Core functions</a></td></tr>
25109 <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="#Core-functions">Core functions</a></td></tr>
25110 <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-functions">Core functions</a></td></tr>
25111 <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-functions">Core functions</a></td></tr>
25112 <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-functions">Core functions</a></td></tr>
25113 <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-functions">Core functions</a></td></tr>
25114 <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-functions">Core functions</a></td></tr>
25115 <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-functions">Core functions</a></td></tr>
25116 <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-functions">Core functions</a></td></tr>
25117 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fget_005fopenpgp_005fkeyring"><code>gnutls_certificate_get_openpgp_keyring</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25118 <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-functions">Core functions</a></td></tr>
25119 <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-functions">Core functions</a></td></tr>
25120 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fget_005fx509_005fcas"><code>gnutls_certificate_get_x509_cas</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25121 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcertificate_005fget_005fx509_005fcrls"><code>gnutls_certificate_get_x509_crls</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25122 <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="#Core-functions">Core functions</a></td></tr>
25123 <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="#Core-functions">Core functions</a></td></tr>
25124 <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="#Core-functions">Core functions</a></td></tr>
25125 <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-functions">Core functions</a></td></tr>
25126 <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-functions">OpenPGP functions</a></td></tr>
25127 <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-functions">OpenPGP functions</a></td></tr>
25128 <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-functions">OpenPGP functions</a></td></tr>
25129 <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-functions">OpenPGP functions</a></td></tr>
25130 <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-functions">OpenPGP functions</a></td></tr>
25131 <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-functions">OpenPGP functions</a></td></tr>
25132 <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-functions">OpenPGP functions</a></td></tr>
25133 <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="#Core-functions">Core functions</a></td></tr>
25134 <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-functions">Core functions</a></td></tr>
25135 <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="#Core-functions">Core functions</a></td></tr>
25136 <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-functions">Core functions</a></td></tr>
25137 <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="#Core-functions">Core functions</a></td></tr>
25138 <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-functions">Core functions</a></td></tr>
25139 <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-functions">Core functions</a></td></tr>
25140 <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-functions">Core functions</a></td></tr>
25141 <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-functions">Core functions</a></td></tr>
25142 <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-functions">Core functions</a></td></tr>
25143 <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-functions">Core functions</a></td></tr>
25144 <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-functions">Core functions</a></td></tr>
25145 <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-functions">Core functions</a></td></tr>
25146 <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-functions">Core functions</a></td></tr>
25147 <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-functions">Core functions</a></td></tr>
25148 <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-functions">Core functions</a></td></tr>
25149 <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-functions">Core functions</a></td></tr>
25150 <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-functions">Core functions</a></td></tr>
25151 <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-functions">Core functions</a></td></tr>
25152 <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-functions">Core functions</a></td></tr>
25153 <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-functions">Core functions</a></td></tr>
25154 <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="#Core-functions">Core functions</a></td></tr>
25155 <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-X_002e509-certificate-paths">Verifying X.509 certificate paths</a></td></tr>
25156 <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-functions">Core functions</a></td></tr>
25157 <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-functions">Core functions</a></td></tr>
25158 <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-functions">Core functions</a></td></tr>
25159 <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="#Core-functions">Core functions</a></td></tr>
25160 <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="#Core-functions">Core functions</a></td></tr>
25161 <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="#Core-functions">Core functions</a></td></tr>
25162 <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="#Core-functions">Core functions</a></td></tr>
25163 <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="#Core-functions">Core functions</a></td></tr>
25164 <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-functions">Core functions</a></td></tr>
25165 <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="#Core-functions">Core functions</a></td></tr>
25166 <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-functions">Core functions</a></td></tr>
25167 <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-functions">Core functions</a></td></tr>
25168 <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-functions">Core functions</a></td></tr>
25169 <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="#Core-functions">Core functions</a></td></tr>
25170 <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-functions">Core functions</a></td></tr>
25171 <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="#Core-functions">Core functions</a></td></tr>
25172 <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-functions">Core functions</a></td></tr>
25173 <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-functions">Core functions</a></td></tr>
25174 <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-functions">Core functions</a></td></tr>
25175 <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-functions">Core functions</a></td></tr>
25176 <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-functions">Core functions</a></td></tr>
25177 <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-functions">Core functions</a></td></tr>
25178 <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="#Core-functions">Core functions</a></td></tr>
25179 <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-functions">Core functions</a></td></tr>
25180 <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="#Core-functions">Core functions</a></td></tr>
25181 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcrypto_005fbigint_005fregister2"><code>gnutls_crypto_bigint_register2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25182 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcrypto_005fcipher_005fregister2"><code>gnutls_crypto_cipher_register2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25183 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcrypto_005fdigest_005fregister2"><code>gnutls_crypto_digest_register2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25184 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcrypto_005fmac_005fregister2"><code>gnutls_crypto_mac_register2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25185 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcrypto_005fpk_005fregister2"><code>gnutls_crypto_pk_register2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25186 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcrypto_005frnd_005fregister2"><code>gnutls_crypto_rnd_register2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25187 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcrypto_005fsingle_005fcipher_005fregister2"><code>gnutls_crypto_single_cipher_register2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25188 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcrypto_005fsingle_005fdigest_005fregister2"><code>gnutls_crypto_single_digest_register2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25189 <tr><td></td><td valign="top"><a href="#index-gnutls_005fcrypto_005fsingle_005fmac_005fregister2"><code>gnutls_crypto_single_mac_register2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25190 <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-functions">Core functions</a></td></tr>
25191 <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-functions">Core functions</a></td></tr>
25192 <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-functions">Core functions</a></td></tr>
25193 <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-functions">Core functions</a></td></tr>
25194 <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-functions">Core functions</a></td></tr>
25195 <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-functions">Core functions</a></td></tr>
25196 <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-functions">Core functions</a></td></tr>
25197 <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-functions">Core functions</a></td></tr>
25198 <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="#Core-functions">Core functions</a></td></tr>
25199 <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-functions">Core functions</a></td></tr>
25200 <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-functions">Core functions</a></td></tr>
25201 <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-functions">Core functions</a></td></tr>
25202 <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-functions">Core functions</a></td></tr>
25203 <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-functions">Core functions</a></td></tr>
25204 <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-functions">Core functions</a></td></tr>
25205 <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-functions">Core functions</a></td></tr>
25206 <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-functions">Core functions</a></td></tr>
25207 <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-functions">Core functions</a></td></tr>
25208 <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-functions">Core functions</a></td></tr>
25209 <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-functions">Core functions</a></td></tr>
25210 <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-functions">Core functions</a></td></tr>
25211 <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-functions">Core functions</a></td></tr>
25212 <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-functions">Core functions</a></td></tr>
25213 <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="#Core-functions">Core functions</a></td></tr>
25214 <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="#Core-functions">Core functions</a></td></tr>
25215 <tr><td></td><td valign="top"><a href="#index-gnutls_005fextra_005fcheck_005fversion"><code>gnutls_extra_check_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GnuTLS_002dextra-functions">GnuTLS-extra functions</a></td></tr>
25216 <tr><td></td><td valign="top"><a href="#index-gnutls_005fext_005fregister"><code>gnutls_ext_register</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25217 <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-functions">Core functions</a></td></tr>
25218 <tr><td></td><td valign="top"><a href="#index-gnutls_005ffree"><code>gnutls_free</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25219 <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-functions">Core functions</a></td></tr>
25220 <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-functions">Core functions</a></td></tr>
25221 <tr><td></td><td valign="top"><a href="#index-gnutls_005fglobal_005finit_005fextra"><code>gnutls_global_init_extra</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GnuTLS_002dextra-functions">GnuTLS-extra functions</a></td></tr>
25222 <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-functions">Core functions</a></td></tr>
25223 <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-functions">Core functions</a></td></tr>
25224 <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="#Core-functions">Core functions</a></td></tr>
25225 <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="#Core-functions">Core functions</a></td></tr>
25226 <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-functions">Core functions</a></td></tr>
25227 <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="#Core-functions">Core functions</a></td></tr>
25228 <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-functions">Core functions</a></td></tr>
25229 <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-functions">Core functions</a></td></tr>
25230 <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-functions">Core functions</a></td></tr>
25231 <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-functions">Core functions</a></td></tr>
25232 <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-functions">Core functions</a></td></tr>
25233 <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="#Core-functions">Core functions</a></td></tr>
25234 <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="#Core-functions">Core functions</a></td></tr>
25235 <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="#Core-functions">Core functions</a></td></tr>
25236 <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="#Core-functions">Core functions</a></td></tr>
25237 <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="#Core-functions">Core functions</a></td></tr>
25238 <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="#Core-functions">Core functions</a></td></tr>
25239 <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-functions">Core functions</a></td></tr>
25240 <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-functions">Core functions</a></td></tr>
25241 <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-functions">Core functions</a></td></tr>
25242 <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="#Core-functions">Core functions</a></td></tr>
25243 <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="#Core-functions">Core functions</a></td></tr>
25244 <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="#Core-functions">Core functions</a></td></tr>
25245 <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="#Core-functions">Core functions</a></td></tr>
25246 <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="#Core-functions">Core functions</a></td></tr>
25247 <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="#Core-functions">Core functions</a></td></tr>
25248 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fallocate_005fclient_005fcredentials"><code>gnutls_ia_allocate_client_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25249 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fallocate_005fserver_005fcredentials"><code>gnutls_ia_allocate_server_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25250 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fenable"><code>gnutls_ia_enable</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25251 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fendphase_005fsend"><code>gnutls_ia_endphase_send</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25252 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fextract_005finner_005fsecret"><code>gnutls_ia_extract_inner_secret</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25253 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005ffree_005fclient_005fcredentials"><code>gnutls_ia_free_client_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25254 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005ffree_005fserver_005fcredentials"><code>gnutls_ia_free_server_credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25255 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fgenerate_005fchallenge"><code>gnutls_ia_generate_challenge</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25256 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fget_005fclient_005favp_005fptr"><code>gnutls_ia_get_client_avp_ptr</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25257 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fget_005fserver_005favp_005fptr"><code>gnutls_ia_get_server_avp_ptr</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25258 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fhandshake"><code>gnutls_ia_handshake</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25259 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fhandshake_005fp"><code>gnutls_ia_handshake_p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25260 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fpermute_005finner_005fsecret"><code>gnutls_ia_permute_inner_secret</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25261 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005frecv"><code>gnutls_ia_recv</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25262 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fsend"><code>gnutls_ia_send</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25263 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fset_005fclient_005favp_005ffunction"><code>gnutls_ia_set_client_avp_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25264 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fset_005fclient_005favp_005fptr"><code>gnutls_ia_set_client_avp_ptr</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25265 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fset_005fserver_005favp_005ffunction"><code>gnutls_ia_set_server_avp_function</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25266 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fset_005fserver_005favp_005fptr"><code>gnutls_ia_set_server_avp_ptr</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25267 <tr><td></td><td valign="top"><a href="#index-gnutls_005fia_005fverify_005fendphase"><code>gnutls_ia_verify_endphase</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
25268 <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="#Core-functions">Core functions</a></td></tr>
25269 <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-functions">Core functions</a></td></tr>
25270 <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-functions">Core functions</a></td></tr>
25271 <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-functions">Core functions</a></td></tr>
25272 <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-functions">Core functions</a></td></tr>
25273 <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="#Core-functions">Core functions</a></td></tr>
25274 <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-functions">Core functions</a></td></tr>
25275 <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-functions">Core functions</a></td></tr>
25276 <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-functions">Core functions</a></td></tr>
25277 <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-functions">Core functions</a></td></tr>
25278 <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-functions">Core functions</a></td></tr>
25279 <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="#Core-functions">Core functions</a></td></tr>
25280 <tr><td></td><td valign="top"><a href="#index-gnutls_005fmalloc"><code>gnutls_malloc</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25281 <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-functions">OpenPGP functions</a></td></tr>
25282 <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-functions">OpenPGP functions</a></td></tr>
25283 <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-functions">OpenPGP functions</a></td></tr>
25284 <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-functions">OpenPGP functions</a></td></tr>
25285 <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-functions">OpenPGP functions</a></td></tr>
25286 <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-functions">OpenPGP functions</a></td></tr>
25287 <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-functions">OpenPGP functions</a></td></tr>
25288 <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-functions">OpenPGP functions</a></td></tr>
25289 <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-functions">OpenPGP functions</a></td></tr>
25290 <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-functions">OpenPGP functions</a></td></tr>
25291 <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-functions">OpenPGP functions</a></td></tr>
25292 <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-functions">OpenPGP functions</a></td></tr>
25293 <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-functions">OpenPGP functions</a></td></tr>
25294 <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-functions">OpenPGP functions</a></td></tr>
25295 <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-functions">OpenPGP functions</a></td></tr>
25296 <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-functions">OpenPGP functions</a></td></tr>
25297 <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-functions">OpenPGP functions</a></td></tr>
25298 <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-functions">OpenPGP functions</a></td></tr>
25299 <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-functions">OpenPGP functions</a></td></tr>
25300 <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-functions">OpenPGP functions</a></td></tr>
25301 <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-functions">OpenPGP functions</a></td></tr>
25302 <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-functions">OpenPGP functions</a></td></tr>
25303 <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-functions">OpenPGP functions</a></td></tr>
25304 <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-functions">OpenPGP functions</a></td></tr>
25305 <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-functions">OpenPGP functions</a></td></tr>
25306 <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-functions">OpenPGP functions</a></td></tr>
25307 <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-functions">OpenPGP functions</a></td></tr>
25308 <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-functions">OpenPGP functions</a></td></tr>
25309 <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-functions">OpenPGP functions</a></td></tr>
25310 <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-functions">OpenPGP functions</a></td></tr>
25311 <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-functions">OpenPGP functions</a></td></tr>
25312 <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-functions">OpenPGP functions</a></td></tr>
25313 <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-functions">OpenPGP functions</a></td></tr>
25314 <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-functions">OpenPGP functions</a></td></tr>
25315 <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-functions">OpenPGP functions</a></td></tr>
25316 <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-functions">OpenPGP functions</a></td></tr>
25317 <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-functions">OpenPGP functions</a></td></tr>
25318 <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-functions">OpenPGP functions</a></td></tr>
25319 <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-functions">OpenPGP functions</a></td></tr>
25320 <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-functions">OpenPGP functions</a></td></tr>
25321 <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-functions">OpenPGP functions</a></td></tr>
25322 <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-functions">OpenPGP functions</a></td></tr>
25323 <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-functions">OpenPGP functions</a></td></tr>
25324 <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-functions">OpenPGP functions</a></td></tr>
25325 <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-functions">OpenPGP functions</a></td></tr>
25326 <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-functions">OpenPGP functions</a></td></tr>
25327 <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-functions">OpenPGP functions</a></td></tr>
25328 <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-functions">OpenPGP functions</a></td></tr>
25329 <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-functions">OpenPGP functions</a></td></tr>
25330 <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-functions">OpenPGP functions</a></td></tr>
25331 <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-functions">OpenPGP functions</a></td></tr>
25332 <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-functions">OpenPGP functions</a></td></tr>
25333 <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-functions">OpenPGP functions</a></td></tr>
25334 <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-functions">OpenPGP functions</a></td></tr>
25335 <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-functions">OpenPGP functions</a></td></tr>
25336 <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-functions">OpenPGP functions</a></td></tr>
25337 <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-functions">OpenPGP functions</a></td></tr>
25338 <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-functions">OpenPGP functions</a></td></tr>
25339 <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-functions">OpenPGP functions</a></td></tr>
25340 <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-functions">OpenPGP functions</a></td></tr>
25341 <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-functions">OpenPGP functions</a></td></tr>
25342 <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-functions">OpenPGP functions</a></td></tr>
25343 <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="#OpenPGP-functions">OpenPGP functions</a></td></tr>
25344 <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-functions">Core functions</a></td></tr>
25345 <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-functions">OpenPGP functions</a></td></tr>
25346 <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-functions">Core functions</a></td></tr>
25347 <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-functions">Core functions</a></td></tr>
25348 <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-functions">Core functions</a></td></tr>
25349 <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-functions">Core functions</a></td></tr>
25350 <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-functions">Core functions</a></td></tr>
25351 <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="#Core-functions">Core functions</a></td></tr>
25352 <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="#Core-functions">Core functions</a></td></tr>
25353 <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="#Core-functions">Core functions</a></td></tr>
25354 <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="#Core-functions">Core functions</a></td></tr>
25355 <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="#Core-functions">Core functions</a></td></tr>
25356 <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="#Core-functions">Core functions</a></td></tr>
25357 <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="#Core-functions">Core functions</a></td></tr>
25358 <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="#Core-functions">Core functions</a></td></tr>
25359 <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="#Core-functions">Core functions</a></td></tr>
25360 <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="#Core-functions">Core functions</a></td></tr>
25361 <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="#Core-functions">Core functions</a></td></tr>
25362 <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="#Core-functions">Core functions</a></td></tr>
25363 <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="#Core-functions">Core functions</a></td></tr>
25364 <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="#Core-functions">Core functions</a></td></tr>
25365 <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="#Core-functions">Core functions</a></td></tr>
25366 <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="#Core-functions">Core functions</a></td></tr>
25367 <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="#Core-functions">Core functions</a></td></tr>
25368 <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="#Core-functions">Core functions</a></td></tr>
25369 <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="#Core-functions">Core functions</a></td></tr>
25370 <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="#Core-functions">Core functions</a></td></tr>
25371 <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="#Core-functions">Core functions</a></td></tr>
25372 <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="#Core-functions">Core functions</a></td></tr>
25373 <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="#Core-functions">Core functions</a></td></tr>
25374 <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="#Core-functions">Core functions</a></td></tr>
25375 <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="#Core-functions">Core functions</a></td></tr>
25376 <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="#Core-functions">Core functions</a></td></tr>
25377 <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="#Core-functions">Core functions</a></td></tr>
25378 <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="#Core-functions">Core functions</a></td></tr>
25379 <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="#Core-functions">Core functions</a></td></tr>
25380 <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="#Core-functions">Core functions</a></td></tr>
25381 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25382 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25383 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25384 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25385 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25386 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25387 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25388 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25389 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25390 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25391 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25392 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25393 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25394 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25395 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25396 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25397 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25398 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25399 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25400 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25401 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25402 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25403 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25404 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25405 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25406 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25407 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25408 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25409 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25410 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25411 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25412 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25413 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25414 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25415 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25416 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25417 <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-functions">Core functions</a></td></tr>
25418 <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="#Core-functions">Core functions</a></td></tr>
25419 <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-functions">Core functions</a></td></tr>
25420 <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-functions">Core functions</a></td></tr>
25421 <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-functions">Core functions</a></td></tr>
25422 <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-functions">Core functions</a></td></tr>
25423 <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-functions">Core functions</a></td></tr>
25424 <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-functions">Core functions</a></td></tr>
25425 <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-functions">Core functions</a></td></tr>
25426 <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-functions">Core functions</a></td></tr>
25427 <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-functions">Core functions</a></td></tr>
25428 <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="#Core-functions">Core functions</a></td></tr>
25429 <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="#Core-functions">Core functions</a></td></tr>
25430 <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="#Core-functions">Core functions</a></td></tr>
25431 <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="#Core-functions">Core functions</a></td></tr>
25432 <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="#Core-functions">Core functions</a></td></tr>
25433 <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="#Core-functions">Core functions</a></td></tr>
25434 <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="#Core-functions">Core functions</a></td></tr>
25435 <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="#Core-functions">Core functions</a></td></tr>
25436 <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="#Core-functions">Core functions</a></td></tr>
25437 <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="#Core-functions">Core functions</a></td></tr>
25438 <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-functions">Core functions</a></td></tr>
25439 <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-functions">Core functions</a></td></tr>
25440 <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-functions">Core functions</a></td></tr>
25441 <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-functions">Core functions</a></td></tr>
25442 <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="#Core-functions">Core functions</a></td></tr>
25443 <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-functions">Core functions</a></td></tr>
25444 <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-functions">Core functions</a></td></tr>
25445 <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-functions">Core functions</a></td></tr>
25446 <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-functions">Core functions</a></td></tr>
25447 <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-functions">Core functions</a></td></tr>
25448 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpsk_005fnetconf_005fderive_005fkey"><code>gnutls_psk_netconf_derive_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25449 <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-functions">Core functions</a></td></tr>
25450 <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-functions">Core functions</a></td></tr>
25451 <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="#Core-functions">Core functions</a></td></tr>
25452 <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-functions">Core functions</a></td></tr>
25453 <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="#Core-functions">Core functions</a></td></tr>
25454 <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-functions">Core functions</a></td></tr>
25455 <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-functions">Core functions</a></td></tr>
25456 <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-functions">Core functions</a></td></tr>
25457 <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-functions">Core functions</a></td></tr>
25458 <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="#Core-functions">Core functions</a></td></tr>
25459 <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="#Core-functions">Core functions</a></td></tr>
25460 <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="#Core-functions">Core functions</a></td></tr>
25461 <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="#Core-functions">Core functions</a></td></tr>
25462 <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="#Core-functions">Core functions</a></td></tr>
25463 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fget_005fpk_005fdsa_005fraw"><code>gnutls_pubkey_get_pk_dsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25464 <tr><td></td><td valign="top"><a href="#index-gnutls_005fpubkey_005fget_005fpk_005frsa_005fraw"><code>gnutls_pubkey_get_pk_rsa_raw</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25465 <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="#Core-functions">Core functions</a></td></tr>
25466 <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="#Core-functions">Core functions</a></td></tr>
25467 <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="#Core-functions">Core functions</a></td></tr>
25468 <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="#Core-functions">Core functions</a></td></tr>
25469 <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="#Core-functions">Core functions</a></td></tr>
25470 <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="#Core-functions">Core functions</a></td></tr>
25471 <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="#Core-functions">Core functions</a></td></tr>
25472 <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="#Core-functions">Core functions</a></td></tr>
25473 <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="#Core-functions">Core functions</a></td></tr>
25474 <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="#Core-functions">Core functions</a></td></tr>
25475 <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="#Core-functions">Core functions</a></td></tr>
25476 <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="#Core-functions">Core functions</a></td></tr>
25477 <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="#Core-functions">Core functions</a></td></tr>
25478 <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="#Core-functions">Core functions</a></td></tr>
25479 <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="#Core-functions">Core functions</a></td></tr>
25480 <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-functions">Core functions</a></td></tr>
25481 <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="#Core-functions">Core functions</a></td></tr>
25482 <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-functions">Core functions</a></td></tr>
25483 <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="#Core-functions">Core functions</a></td></tr>
25484 <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="#Core-functions">Core functions</a></td></tr>
25485 <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-functions">Core functions</a></td></tr>
25486 <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-functions">Core functions</a></td></tr>
25487 <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="#Core-functions">Core functions</a></td></tr>
25488 <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="#Core-functions">Core functions</a></td></tr>
25489 <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="#Core-functions">Core functions</a></td></tr>
25490 <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="#Core-functions">Core functions</a></td></tr>
25491 <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="#Core-functions">Core functions</a></td></tr>
25492 <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="#Core-functions">Core functions</a></td></tr>
25493 <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="#Core-functions">Core functions</a></td></tr>
25494 <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="#Core-functions">Core functions</a></td></tr>
25495 <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="#Core-functions">Core functions</a></td></tr>
25496 <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="#Core-functions">Core functions</a></td></tr>
25497 <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="#Core-functions">Core functions</a></td></tr>
25498 <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-functions">Core functions</a></td></tr>
25499 <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-functions">Core functions</a></td></tr>
25500 <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="#Core-functions">Core functions</a></td></tr>
25501 <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-functions">Core functions</a></td></tr>
25502 <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-functions">Core functions</a></td></tr>
25503 <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-functions">Core functions</a></td></tr>
25504 <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-functions">Core functions</a></td></tr>
25505 <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-functions">Core functions</a></td></tr>
25506 <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-functions">Core functions</a></td></tr>
25507 <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-functions">Core functions</a></td></tr>
25508 <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-functions">Core functions</a></td></tr>
25509 <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="#Core-functions">Core functions</a></td></tr>
25510 <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-functions">Core functions</a></td></tr>
25511 <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-functions">Core functions</a></td></tr>
25512 <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-functions">Core functions</a></td></tr>
25513 <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="#Core-functions">Core functions</a></td></tr>
25514 <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="#Core-functions">Core functions</a></td></tr>
25515 <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="#Core-functions">Core functions</a></td></tr>
25516 <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-functions">Core functions</a></td></tr>
25517 <tr><td></td><td valign="top"><a href="#index-gnutls_005fsign_005falgorithm_005fget_005fname"><code>gnutls_sign_algorithm_get_name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25518 <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-functions">Core functions</a></td></tr>
25519 <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="#Core-functions">Core functions</a></td></tr>
25520 <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="#Core-functions">Core functions</a></td></tr>
25521 <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-functions">Core functions</a></td></tr>
25522 <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-functions">Core functions</a></td></tr>
25523 <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-functions">Core functions</a></td></tr>
25524 <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-functions">Core functions</a></td></tr>
25525 <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-functions">Core functions</a></td></tr>
25526 <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-functions">Core functions</a></td></tr>
25527 <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-functions">Core functions</a></td></tr>
25528 <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-functions">Core functions</a></td></tr>
25529 <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-functions">Core functions</a></td></tr>
25530 <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-functions">Core functions</a></td></tr>
25531 <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-functions">Core functions</a></td></tr>
25532 <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-functions">Core functions</a></td></tr>
25533 <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-functions">Core functions</a></td></tr>
25534 <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="#Core-functions">Core functions</a></td></tr>
25535 <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-functions">Core functions</a></td></tr>
25536 <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="#Core-functions">Core functions</a></td></tr>
25537 <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="#Core-functions">Core functions</a></td></tr>
25538 <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="#Core-functions">Core functions</a></td></tr>
25539 <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-functions">Core functions</a></td></tr>
25540 <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-functions">Core functions</a></td></tr>
25541 <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-functions">Core functions</a></td></tr>
25542 <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-functions">Core functions</a></td></tr>
25543 <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-functions">Core functions</a></td></tr>
25544 <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="#Core-functions">Core functions</a></td></tr>
25545 <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-functions">Core functions</a></td></tr>
25546 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005fglobal_005ferrno"><code>gnutls_transport_set_global_errno</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25547 <tr><td></td><td valign="top"><a href="#index-gnutls_005ftransport_005fset_005flowat"><code>gnutls_transport_set_lowat</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-functions">Core functions</a></td></tr>
25548 <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-functions">Core functions</a></td></tr>
25549 <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-functions">Core functions</a></td></tr>
25550 <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="#Core-functions">Core functions</a></td></tr>
25551 <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="#Core-functions">Core functions</a></td></tr>
25552 <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="#Core-functions">Core functions</a></td></tr>
25553 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25554 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25555 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25556 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25557 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25558 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25559 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25560 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25561 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25562 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25563 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25564 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25565 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25566 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25567 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25568 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25569 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25570 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25571 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25572 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25573 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25574 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25575 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25576 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25577 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25578 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25579 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25580 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25581 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25582 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25583 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25584 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25585 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25586 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25587 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25588 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25589 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25590 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25591 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25592 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25593 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25594 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25595 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25596 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25597 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25598 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25599 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25600 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25601 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25602 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25603 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25604 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25605 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25606 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25607 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25608 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25609 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25610 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25611 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25612 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25613 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25614 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25615 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25616 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25617 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25618 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25619 <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="#Core-functions">Core functions</a></td></tr>
25620 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25621 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25622 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25623 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25624 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25625 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25626 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25627 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25628 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25629 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25630 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25631 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25632 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25633 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25634 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25635 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25636 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25637 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25638 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25639 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25640 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25641 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25642 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25643 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25644 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25645 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25646 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25647 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25648 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25649 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25650 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25651 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25652 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25653 <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-certificate-functions">X.509 certificate functions</a></td></tr>
25654 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25655 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25656 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25657 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25658 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25659 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25660 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25661 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25662 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25663 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25664 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25665 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25666 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25667 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25668 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25669 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25670 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25671 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25672 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25673 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25674 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25675 <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="#Core-functions">Core functions</a></td></tr>
25676 <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="#Core-functions">Core functions</a></td></tr>
25677 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25678 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25679 <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="#Core-functions">Core functions</a></td></tr>
25680 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25681 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25682 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25683 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25684 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25685 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25686 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25687 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25688 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25689 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25690 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25691 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25692 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25693 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25694 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25695 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25696 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25697 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25698 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25699 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25700 <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="#Core-functions">Core functions</a></td></tr>
25701 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25702 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25703 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25704 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25705 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25706 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25707 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25708 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25709 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25710 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25711 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25712 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25713 <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-certificate-functions">X.509 certificate functions</a></td></tr>
25714 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25715 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25716 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25717 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25718 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25719 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25720 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25721 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25722 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25723 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25724 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25725 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25726 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25727 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25728 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25729 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25730 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25731 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25732 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25733 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25734 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25735 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25736 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25737 <tr><td></td><td valign="top"><a href="#index-gnutls_005fx509_005fprivkey_005fverify_005fdata"><code>gnutls_x509_privkey_verify_data</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25738 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25739 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25740 <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="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
25741 <tr><td colspan="4"> <hr></td></tr>
25742 <tr><th><a name="Function-and-Data-Index_fn_letter-H">H</a></th><td></td><td></td></tr>
25743 <tr><td></td><td valign="top"><a href="#index-handshake"><code>handshake</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25744 <tr><td></td><td valign="top"><a href="#index-handshake_002ddescription_002d_003estring"><code>handshake-description-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25745 <tr><td colspan="4"> <hr></td></tr>
25746 <tr><th><a name="Function-and-Data-Index_fn_letter-I">I</a></th><td></td><td></td></tr>
25747 <tr><td></td><td valign="top"><a href="#index-import_002dopenpgp_002dcertificate"><code>import-openpgp-certificate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25748 <tr><td></td><td valign="top"><a href="#index-import_002dopenpgp_002dkeyring"><code>import-openpgp-keyring</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25749 <tr><td></td><td valign="top"><a href="#index-import_002dopenpgp_002dprivate_002dkey"><code>import-openpgp-private-key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25750 <tr><td></td><td valign="top"><a href="#index-import_002dx509_002dcertificate"><code>import-x509-certificate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25751 <tr><td></td><td valign="top"><a href="#index-import_002dx509_002dprivate_002dkey"><code>import-x509-private-key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25752 <tr><td colspan="4"> <hr></td></tr>
25753 <tr><th><a name="Function-and-Data-Index_fn_letter-K">K</a></th><td></td><td></td></tr>
25754 <tr><td></td><td valign="top"><a href="#index-key_002dusage_002d_003estring"><code>key-usage-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25755 <tr><td></td><td valign="top"><a href="#index-kx_002d_003estring"><code>kx-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25756 <tr><td colspan="4"> <hr></td></tr>
25757 <tr><th><a name="Function-and-Data-Index_fn_letter-M">M</a></th><td></td><td></td></tr>
25758 <tr><td></td><td valign="top"><a href="#index-mac_002d_003estring"><code>mac-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25759 <tr><td></td><td valign="top"><a href="#index-make_002danonymous_002dclient_002dcredentials"><code>make-anonymous-client-credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25760 <tr><td></td><td valign="top"><a href="#index-make_002danonymous_002dserver_002dcredentials"><code>make-anonymous-server-credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25761 <tr><td></td><td valign="top"><a href="#index-make_002dcertificate_002dcredentials"><code>make-certificate-credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25762 <tr><td></td><td valign="top"><a href="#index-make_002ddh_002dparameters"><code>make-dh-parameters</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25763 <tr><td></td><td valign="top"><a href="#index-make_002dpsk_002dclient_002dcredentials"><code>make-psk-client-credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25764 <tr><td></td><td valign="top"><a href="#index-make_002dpsk_002dserver_002dcredentials"><code>make-psk-server-credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25765 <tr><td></td><td valign="top"><a href="#index-make_002drsa_002dparameters"><code>make-rsa-parameters</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Representation-of-Binary-Data">Representation of Binary Data</a></td></tr>
25766 <tr><td></td><td valign="top"><a href="#index-make_002drsa_002dparameters-1"><code>make-rsa-parameters</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25767 <tr><td></td><td valign="top"><a href="#index-make_002dsession"><code>make-session</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25768 <tr><td colspan="4"> <hr></td></tr>
25769 <tr><th><a name="Function-and-Data-Index_fn_letter-O">O</a></th><td></td><td></td></tr>
25770 <tr><td></td><td valign="top"><a href="#index-openpgp_002dcertificate_002dalgorithm"><code>openpgp-certificate-algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25771 <tr><td></td><td valign="top"><a href="#index-openpgp_002dcertificate_002dfingerprint"><code>openpgp-certificate-fingerprint</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25772 <tr><td></td><td valign="top"><a href="#index-openpgp_002dcertificate_002dfingerprint_0021"><code>openpgp-certificate-fingerprint!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25773 <tr><td></td><td valign="top"><a href="#index-openpgp_002dcertificate_002dformat_002d_003estring"><code>openpgp-certificate-format-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25774 <tr><td></td><td valign="top"><a href="#index-openpgp_002dcertificate_002did"><code>openpgp-certificate-id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25775 <tr><td></td><td valign="top"><a href="#index-openpgp_002dcertificate_002did_0021"><code>openpgp-certificate-id!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25776 <tr><td></td><td valign="top"><a href="#index-openpgp_002dcertificate_002dname"><code>openpgp-certificate-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25777 <tr><td></td><td valign="top"><a href="#index-openpgp_002dcertificate_002dnames"><code>openpgp-certificate-names</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25778 <tr><td></td><td valign="top"><a href="#index-openpgp_002dcertificate_002dusage"><code>openpgp-certificate-usage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25779 <tr><td></td><td valign="top"><a href="#index-openpgp_002dcertificate_002dversion"><code>openpgp-certificate-version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25780 <tr><td></td><td valign="top"><a href="#index-openpgp_002dcertificate_003f"><code>openpgp-certificate?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25781 <tr><td></td><td valign="top"><a href="#index-openpgp_002dkeyring_002dcontains_002dkey_002did_003f"><code>openpgp-keyring-contains-key-id?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25782 <tr><td></td><td valign="top"><a href="#index-openpgp_002dkeyring_003f"><code>openpgp-keyring?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25783 <tr><td></td><td valign="top"><a href="#index-openpgp_002dprivate_002dkey_003f"><code>openpgp-private-key?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25784 <tr><td colspan="4"> <hr></td></tr>
25785 <tr><th><a name="Function-and-Data-Index_fn_letter-P">P</a></th><td></td><td></td></tr>
25786 <tr><td></td><td valign="top"><a href="#index-params_002d_003estring"><code>params-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25787 <tr><td></td><td valign="top"><a href="#index-peer_002dcertificate_002dstatus"><code>peer-certificate-status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25788 <tr><td></td><td valign="top"><a href="#index-pk_002dalgorithm_002d_003estring"><code>pk-algorithm-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25789 <tr><td></td><td valign="top"><a href="#index-pkcs1_002dexport_002drsa_002dparameters"><code>pkcs1-export-rsa-parameters</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Representation-of-Binary-Data">Representation of Binary Data</a></td></tr>
25790 <tr><td></td><td valign="top"><a href="#index-pkcs1_002dexport_002drsa_002dparameters-1"><code>pkcs1-export-rsa-parameters</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25791 <tr><td></td><td valign="top"><a href="#index-pkcs1_002dimport_002drsa_002dparameters"><code>pkcs1-import-rsa-parameters</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25792 <tr><td></td><td valign="top"><a href="#index-pkcs3_002dexport_002ddh_002dparameters"><code>pkcs3-export-dh-parameters</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25793 <tr><td></td><td valign="top"><a href="#index-pkcs3_002dimport_002ddh_002dparameters"><code>pkcs3-import-dh-parameters</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25794 <tr><td></td><td valign="top"><a href="#index-pkcs8_002dimport_002dx509_002dprivate_002dkey"><code>pkcs8-import-x509-private-key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25795 <tr><td></td><td valign="top"><a href="#index-protocol_002d_003estring"><code>protocol-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25796 <tr><td></td><td valign="top"><a href="#index-psk_002dclient_002dcredentials_003f"><code>psk-client-credentials?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25797 <tr><td></td><td valign="top"><a href="#index-psk_002dkey_002dformat_002d_003estring"><code>psk-key-format-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25798 <tr><td></td><td valign="top"><a href="#index-psk_002dserver_002dcredentials_003f"><code>psk-server-credentials?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25799 <tr><td colspan="4"> <hr></td></tr>
25800 <tr><th><a name="Function-and-Data-Index_fn_letter-R">R</a></th><td></td><td></td></tr>
25801 <tr><td></td><td valign="top"><a href="#index-record_002dreceive_0021"><code>record-receive!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Input-and-Output">Input and Output</a></td></tr>
25802 <tr><td></td><td valign="top"><a href="#index-record_002dreceive_0021-1"><code>record-receive!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25803 <tr><td></td><td valign="top"><a href="#index-record_002dsend"><code>record-send</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Input-and-Output">Input and Output</a></td></tr>
25804 <tr><td></td><td valign="top"><a href="#index-record_002dsend-1"><code>record-send</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25805 <tr><td></td><td valign="top"><a href="#index-rehandshake"><code>rehandshake</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25806 <tr><td></td><td valign="top"><a href="#index-rsa_002dparameters_003f"><code>rsa-parameters?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25807 <tr><td colspan="4"> <hr></td></tr>
25808 <tr><th><a name="Function-and-Data-Index_fn_letter-S">S</a></th><td></td><td></td></tr>
25809 <tr><td></td><td valign="top"><a href="#index-server_002dsession_002dpsk_002dusername"><code>server-session-psk-username</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25810 <tr><td></td><td valign="top"><a href="#index-session_002dauthentication_002dtype"><code>session-authentication-type</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25811 <tr><td></td><td valign="top"><a href="#index-session_002dcertificate_002dtype"><code>session-certificate-type</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25812 <tr><td></td><td valign="top"><a href="#index-session_002dcipher"><code>session-cipher</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Enumerates-and-Constants">Enumerates and Constants</a></td></tr>
25813 <tr><td></td><td valign="top"><a href="#index-session_002dcipher-1"><code>session-cipher</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25814 <tr><td></td><td valign="top"><a href="#index-session_002dclient_002dauthentication_002dtype"><code>session-client-authentication-type</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25815 <tr><td></td><td valign="top"><a href="#index-session_002dcompression_002dmethod"><code>session-compression-method</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25816 <tr><td></td><td valign="top"><a href="#index-session_002dkx"><code>session-kx</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25817 <tr><td></td><td valign="top"><a href="#index-session_002dmac"><code>session-mac</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25818 <tr><td></td><td valign="top"><a href="#index-session_002dour_002dcertificate_002dchain"><code>session-our-certificate-chain</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25819 <tr><td></td><td valign="top"><a href="#index-session_002dpeer_002dcertificate_002dchain"><code>session-peer-certificate-chain</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25820 <tr><td></td><td valign="top"><a href="#index-session_002dprotocol"><code>session-protocol</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25821 <tr><td></td><td valign="top"><a href="#index-session_002drecord_002dport"><code>session-record-port</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Input-and-Output">Input and Output</a></td></tr>
25822 <tr><td></td><td valign="top"><a href="#index-session_002drecord_002dport-1"><code>session-record-port</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25823 <tr><td></td><td valign="top"><a href="#index-session_002dserver_002dauthentication_002dtype"><code>session-server-authentication-type</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25824 <tr><td></td><td valign="top"><a href="#index-session_003f"><code>session?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25825 <tr><td></td><td valign="top"><a href="#index-set_002danonymous_002dserver_002ddh_002dparameters_0021"><code>set-anonymous-server-dh-parameters!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25826 <tr><td></td><td valign="top"><a href="#index-set_002dcertificate_002dcredentials_002ddh_002dparameters_0021"><code>set-certificate-credentials-dh-parameters!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25827 <tr><td></td><td valign="top"><a href="#index-set_002dcertificate_002dcredentials_002dopenpgp_002dkeys_0021"><code>set-certificate-credentials-openpgp-keys!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extra-Interface">Extra Interface</a></td></tr>
25828 <tr><td></td><td valign="top"><a href="#index-set_002dcertificate_002dcredentials_002drsa_002dexport_002dparameters_0021"><code>set-certificate-credentials-rsa-export-parameters!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25829 <tr><td></td><td valign="top"><a href="#index-set_002dcertificate_002dcredentials_002dverify_002dflags_0021"><code>set-certificate-credentials-verify-flags!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25830 <tr><td></td><td valign="top"><a href="#index-set_002dcertificate_002dcredentials_002dverify_002dlimits_0021"><code>set-certificate-credentials-verify-limits!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25831 <tr><td></td><td valign="top"><a href="#index-set_002dcertificate_002dcredentials_002dx509_002dcrl_002ddata_0021"><code>set-certificate-credentials-x509-crl-data!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25832 <tr><td></td><td valign="top"><a href="#index-set_002dcertificate_002dcredentials_002dx509_002dcrl_002dfile_0021"><code>set-certificate-credentials-x509-crl-file!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25833 <tr><td></td><td valign="top"><a href="#index-set_002dcertificate_002dcredentials_002dx509_002dkey_002ddata_0021"><code>set-certificate-credentials-x509-key-data!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25834 <tr><td></td><td valign="top"><a href="#index-set_002dcertificate_002dcredentials_002dx509_002dkey_002dfiles_0021"><code>set-certificate-credentials-x509-key-files!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25835 <tr><td></td><td valign="top"><a href="#index-set_002dcertificate_002dcredentials_002dx509_002dkeys_0021"><code>set-certificate-credentials-x509-keys!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25836 <tr><td></td><td valign="top"><a href="#index-set_002dcertificate_002dcredentials_002dx509_002dtrust_002ddata_0021"><code>set-certificate-credentials-x509-trust-data!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25837 <tr><td></td><td valign="top"><a href="#index-set_002dcertificate_002dcredentials_002dx509_002dtrust_002dfile_0021"><code>set-certificate-credentials-x509-trust-file!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25838 <tr><td></td><td valign="top"><a href="#index-set_002dlog_002dlevel_0021"><code>set-log-level!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25839 <tr><td></td><td valign="top"><a href="#index-set_002dlog_002dprocedure_0021"><code>set-log-procedure!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25840 <tr><td></td><td valign="top"><a href="#index-set_002dpsk_002dclient_002dcredentials_0021"><code>set-psk-client-credentials!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25841 <tr><td></td><td valign="top"><a href="#index-set_002dpsk_002dserver_002dcredentials_002dfile_0021"><code>set-psk-server-credentials-file!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25842 <tr><td></td><td valign="top"><a href="#index-set_002dserver_002dsession_002dcertificate_002drequest_0021"><code>set-server-session-certificate-request!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25843 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002dcertificate_002dtype_002dpriority_0021"><code>set-session-certificate-type-priority!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25844 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002dcipher_002dpriority_0021"><code>set-session-cipher-priority!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25845 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002dcompression_002dmethod_002dpriority_0021"><code>set-session-compression-method-priority!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25846 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002dcredentials_0021"><code>set-session-credentials!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25847 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002ddefault_002dexport_002dpriority_0021"><code>set-session-default-export-priority!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25848 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002ddefault_002dpriority_0021"><code>set-session-default-priority!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25849 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002ddh_002dprime_002dbits_0021"><code>set-session-dh-prime-bits!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25850 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002dkx_002dpriority_0021"><code>set-session-kx-priority!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25851 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002dmac_002dpriority_0021"><code>set-session-mac-priority!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25852 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002dprotocol_002dpriority_0021"><code>set-session-protocol-priority!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25853 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002dtransport_002dfd_0021"><code>set-session-transport-fd!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Input-and-Output">Input and Output</a></td></tr>
25854 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002dtransport_002dfd_0021-1"><code>set-session-transport-fd!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25855 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002dtransport_002dport_0021"><code>set-session-transport-port!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Input-and-Output">Input and Output</a></td></tr>
25856 <tr><td></td><td valign="top"><a href="#index-set_002dsession_002dtransport_002dport_0021-1"><code>set-session-transport-port!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25857 <tr><td></td><td valign="top"><a href="#index-sign_002dalgorithm_002d_003estring"><code>sign-algorithm-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25858 <tr><td></td><td valign="top"><a href="#index-srp_002dclient_002dcredentials_003f"><code>srp-client-credentials?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25859 <tr><td></td><td valign="top"><a href="#index-srp_002dserver_002dcredentials_003f"><code>srp-server-credentials?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25860 <tr><td colspan="4"> <hr></td></tr>
25861 <tr><th><a name="Function-and-Data-Index_fn_letter-X">X</a></th><td></td><td></td></tr>
25862 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002dauthority_002dkey_002did"><code>x509-certificate-authority-key-id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25863 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002ddn"><code>x509-certificate-dn</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25864 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002ddn_002doid"><code>x509-certificate-dn-oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25865 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002dformat_002d_003estring"><code>x509-certificate-format-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25866 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002dissuer_002ddn"><code>x509-certificate-issuer-dn</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25867 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002dissuer_002ddn_002doid"><code>x509-certificate-issuer-dn-oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25868 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002dkey_002did"><code>x509-certificate-key-id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25869 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002dkey_002dusage"><code>x509-certificate-key-usage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25870 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002dmatches_002dhostname_003f"><code>x509-certificate-matches-hostname?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25871 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002dpublic_002dkey_002dalgorithm"><code>x509-certificate-public-key-algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25872 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002dsignature_002dalgorithm"><code>x509-certificate-signature-algorithm</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25873 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002dsubject_002dalternative_002dname"><code>x509-certificate-subject-alternative-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25874 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002dsubject_002dkey_002did"><code>x509-certificate-subject-key-id</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25875 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_002dversion"><code>x509-certificate-version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25876 <tr><td></td><td valign="top"><a href="#index-x509_002dcertificate_003f"><code>x509-certificate?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25877 <tr><td></td><td valign="top"><a href="#index-x509_002dprivate_002dkey_003f"><code>x509-private-key?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25878 <tr><td></td><td valign="top"><a href="#index-x509_002dsubject_002dalternative_002dname_002d_003estring"><code>x509-subject-alternative-name-&gt;string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Core-Interface">Core Interface</a></td></tr>
25879 <tr><td colspan="4"> <hr></td></tr>
25880 </table>
25881 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Function-and-Data-Index_fn_letter-A"><b>A</b></a>
25882  &nbsp;
25883 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-B"><b>B</b></a>
25884  &nbsp;
25885 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-C"><b>C</b></a>
25886  &nbsp;
25887 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-D"><b>D</b></a>
25888  &nbsp;
25889 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-E"><b>E</b></a>
25890  &nbsp;
25891 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-G"><b>G</b></a>
25892  &nbsp;
25893 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-H"><b>H</b></a>
25894  &nbsp;
25895 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-I"><b>I</b></a>
25896  &nbsp;
25897 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-K"><b>K</b></a>
25898  &nbsp;
25899 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-M"><b>M</b></a>
25900  &nbsp;
25901 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-O"><b>O</b></a>
25902  &nbsp;
25903 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-P"><b>P</b></a>
25904  &nbsp;
25905 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-R"><b>R</b></a>
25906  &nbsp;
25907 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-S"><b>S</b></a>
25908  &nbsp;
25909 <a class="summary-letter" href="#Function-and-Data-Index_fn_letter-X"><b>X</b></a>
25910  &nbsp;
25911 </td></tr></table>
25912
25913 <hr>
25914 <a name="Concept-Index"></a>
25915 <div class="header">
25916 <p>
25917 Next: <a href="#Function-and-Data-Index" accesskey="n" rel="next">Function and Data Index</a>, Previous: <a href="#Function-and-Data-Index" accesskey="p" rel="previous">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>
25918 </div>
25919 <a name="Concept-Index-1"></a>
25920 <h2 class="unnumbered">Concept Index</h2>
25921
25922 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a>
25923  &nbsp;
25924 <a class="summary-letter" href="#Concept-Index_cp_letter-B"><b>B</b></a>
25925  &nbsp;
25926 <a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a>
25927  &nbsp;
25928 <a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a>
25929  &nbsp;
25930 <a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a>
25931  &nbsp;
25932 <a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a>
25933  &nbsp;
25934 <a class="summary-letter" href="#Concept-Index_cp_letter-G"><b>G</b></a>
25935  &nbsp;
25936 <a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a>
25937  &nbsp;
25938 <a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a>
25939  &nbsp;
25940 <a class="summary-letter" href="#Concept-Index_cp_letter-K"><b>K</b></a>
25941  &nbsp;
25942 <a class="summary-letter" href="#Concept-Index_cp_letter-L"><b>L</b></a>
25943  &nbsp;
25944 <a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a>
25945  &nbsp;
25946 <a class="summary-letter" href="#Concept-Index_cp_letter-N"><b>N</b></a>
25947  &nbsp;
25948 <a class="summary-letter" href="#Concept-Index_cp_letter-O"><b>O</b></a>
25949  &nbsp;
25950 <a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a>
25951  &nbsp;
25952 <a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a>
25953  &nbsp;
25954 <a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a>
25955  &nbsp;
25956 <a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a>
25957  &nbsp;
25958 <a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a>
25959  &nbsp;
25960 <a class="summary-letter" href="#Concept-Index_cp_letter-X"><b>X</b></a>
25961  &nbsp;
25962 </td></tr></table>
25963 <table class="index-cp" border="0">
25964 <tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
25965 <tr><td colspan="4"> <hr></td></tr>
25966 <tr><th><a name="Concept-Index_cp_letter-A">A</a></th><td></td><td></td></tr>
25967 <tr><td></td><td valign="top"><a href="#index-Abstract-types">Abstract types</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Abstract-data-types">Abstract data types</a></td></tr>
25968 <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>
25969 <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>
25970 <tr><td colspan="4"> <hr></td></tr>
25971 <tr><th><a name="Concept-Index_cp_letter-B">B</a></th><td></td><td></td></tr>
25972 <tr><td></td><td valign="top"><a href="#index-Bad-record-MAC">Bad record MAC</a>:</td><td>&nbsp;</td><td valign="top"><a href="#On-Record-Padding">On Record Padding</a></td></tr>
25973 <tr><td colspan="4"> <hr></td></tr>
25974 <tr><th><a name="Concept-Index_cp_letter-C">C</a></th><td></td><td></td></tr>
25975 <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>
25976 <tr><td></td><td valign="top"><a href="#index-Certificate-authentication">Certificate authentication</a>:</td><td>&nbsp;</td><td valign="top"><a href="#More-on-certificate-authentication">More on certificate authentication</a></td></tr>
25977 <tr><td></td><td valign="top"><a href="#index-Certificate-requests">Certificate requests</a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-_002310-certificate-requests">PKCS #10 certificate requests</a></td></tr>
25978 <tr><td></td><td valign="top"><a href="#index-certtool">certtool</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-certtool">Invoking certtool</a></td></tr>
25979 <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>
25980 <tr><td></td><td valign="top"><a href="#index-Ciphersuites">Ciphersuites</a>:</td><td>&nbsp;</td><td valign="top"><a href="#All-the-supported-ciphersuites-in-GnuTLS">All the supported ciphersuites in GnuTLS</a></td></tr>
25981 <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>
25982 <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>
25983 <tr><td></td><td valign="top"><a href="#index-constant">constant</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Enumerates-and-Constants">Enumerates and Constants</a></td></tr>
25984 <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>
25985 <tr><td colspan="4"> <hr></td></tr>
25986 <tr><th><a name="Concept-Index_cp_letter-D">D</a></th><td></td><td></td></tr>
25987 <tr><td></td><td valign="top"><a href="#index-debug-server">debug server</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-gnutls_002dserv">Invoking gnutls-serv</a></td></tr>
25988 <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>
25989 <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>
25990 <tr><td colspan="4"> <hr></td></tr>
25991 <tr><th><a name="Concept-Index_cp_letter-E">E</a></th><td></td><td></td></tr>
25992 <tr><td></td><td valign="top"><a href="#index-enumerate">enumerate</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Enumerates-and-Constants">Enumerates and Constants</a></td></tr>
25993 <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-and-descriptions">Error codes and descriptions</a></td></tr>
25994 <tr><td></td><td valign="top"><a href="#index-errors">errors</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Exception-Handling">Exception Handling</a></td></tr>
25995 <tr><td></td><td valign="top"><a href="#index-Example-programs">Example programs</a>:</td><td>&nbsp;</td><td valign="top"><a href="#How-to-use-GnuTLS-in-applications">How to use GnuTLS in applications</a></td></tr>
25996 <tr><td></td><td valign="top"><a href="#index-exceptions">exceptions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Exception-Handling">Exception Handling</a></td></tr>
25997 <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="#Keying-Material-Exporters">Keying Material Exporters</a></td></tr>
25998 <tr><td colspan="4"> <hr></td></tr>
25999 <tr><th><a name="Concept-Index_cp_letter-F">F</a></th><td></td><td></td></tr>
26000 <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="#GNU-Free-Documentation-License">GNU Free Documentation License</a></td></tr>
26001 <tr><td></td><td valign="top"><a href="#index-Function-reference">Function reference</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Function-reference">Function reference</a></td></tr>
26002 <tr><td colspan="4"> <hr></td></tr>
26003 <tr><th><a name="Concept-Index_cp_letter-G">G</a></th><td></td><td></td></tr>
26004 <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>
26005 <tr><td></td><td valign="top"><a href="#index-gnutls_002dcli">gnutls-cli</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-gnutls_002dcli">Invoking gnutls-cli</a></td></tr>
26006 <tr><td></td><td valign="top"><a href="#index-gnutls_002dcli_002ddebug">gnutls-cli-debug</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-gnutls_002dcli_002ddebug">Invoking gnutls-cli-debug</a></td></tr>
26007 <tr><td></td><td valign="top"><a href="#index-gnutls_002derror"><code>gnutls-error</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Exception-Handling">Exception Handling</a></td></tr>
26008 <tr><td></td><td valign="top"><a href="#index-GnuTLS_002dextra-functions"><acronym>GnuTLS-extra</acronym> functions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GnuTLS_002dextra-functions">GnuTLS-extra functions</a></td></tr>
26009 <tr><td></td><td valign="top"><a href="#index-gnutls_002dserv">gnutls-serv</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-gnutls_002dserv">Invoking gnutls-serv</a></td></tr>
26010 <tr><td></td><td valign="top"><a href="#index-GPL_002c-GNU-General-Public-License">GPL, GNU General Public License</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GNU-GPL">GNU GPL</a></td></tr>
26011 <tr><td colspan="4"> <hr></td></tr>
26012 <tr><th><a name="Concept-Index_cp_letter-H">H</a></th><td></td><td></td></tr>
26013 <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>
26014 <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>
26015 <tr><td></td><td valign="top"><a href="#index-homogeneous-vector">homogeneous vector</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Representation-of-Binary-Data">Representation of Binary Data</a></td></tr>
26016 <tr><td></td><td valign="top"><a href="#index-HTTPS-server">HTTPS server</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-gnutls_002dserv">Invoking gnutls-serv</a></td></tr>
26017 <tr><td colspan="4"> <hr></td></tr>
26018 <tr><th><a name="Concept-Index_cp_letter-I">I</a></th><td></td><td></td></tr>
26019 <tr><td></td><td valign="top"><a href="#index-Inner-Application-_0028TLS_002fIA_0029-functions">Inner Application (<acronym>TLS/IA</acronym>) functions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
26020 <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>
26021 <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>
26022 <tr><td colspan="4"> <hr></td></tr>
26023 <tr><th><a name="Concept-Index_cp_letter-K">K</a></th><td></td><td></td></tr>
26024 <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>
26025 <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="#Keying-Material-Exporters">Keying Material Exporters</a></td></tr>
26026 <tr><td colspan="4"> <hr></td></tr>
26027 <tr><th><a name="Concept-Index_cp_letter-L">L</a></th><td></td><td></td></tr>
26028 <tr><td></td><td valign="top"><a href="#index-LGPL_002c-GNU-Lesser-General-Public-License">LGPL, GNU Lesser General Public License</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GNU-LGPL">GNU LGPL</a></td></tr>
26029 <tr><td></td><td valign="top"><a href="#index-License_002c-GNU-GPL">License, GNU GPL</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GNU-GPL">GNU GPL</a></td></tr>
26030 <tr><td></td><td valign="top"><a href="#index-License_002c-GNU-LGPL">License, GNU LGPL</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GNU-LGPL">GNU LGPL</a></td></tr>
26031 <tr><td colspan="4"> <hr></td></tr>
26032 <tr><th><a name="Concept-Index_cp_letter-M">M</a></th><td></td><td></td></tr>
26033 <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="#TLS-Extensions">TLS Extensions</a></td></tr>
26034 <tr><td colspan="4"> <hr></td></tr>
26035 <tr><th><a name="Concept-Index_cp_letter-N">N</a></th><td></td><td></td></tr>
26036 <tr><td></td><td valign="top"><a href="#index-Netconf">Netconf</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Example-client-PSK-connection">Example client PSK connection</a></td></tr>
26037 <tr><td colspan="4"> <hr></td></tr>
26038 <tr><th><a name="Concept-Index_cp_letter-O">O</a></th><td></td><td></td></tr>
26039 <tr><td></td><td valign="top"><a href="#index-OpenPGP-functions"><acronym>OpenPGP</acronym> functions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#OpenPGP-functions">OpenPGP functions</a></td></tr>
26040 <tr><td></td><td valign="top"><a href="#index-OpenPGP-Keys"><acronym>OpenPGP</acronym> Keys</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-authentication">Certificate authentication</a></td></tr>
26041 <tr><td></td><td valign="top"><a href="#index-OpenPGP-Keys-1"><acronym>OpenPGP</acronym> Keys</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-OpenPGP-trust-model">The OpenPGP trust model</a></td></tr>
26042 <tr><td></td><td valign="top"><a href="#index-OpenPGP-Server"><acronym>OpenPGP</acronym> Server</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Echo-Server-with-OpenPGP-authentication">Echo Server with OpenPGP authentication</a></td></tr>
26043 <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>
26044 <tr><td colspan="4"> <hr></td></tr>
26045 <tr><th><a name="Concept-Index_cp_letter-P">P</a></th><td></td><td></td></tr>
26046 <tr><td></td><td valign="top"><a href="#index-p11tool">p11tool</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-p11tool">Invoking p11tool</a></td></tr>
26047 <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>
26048 <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>
26049 <tr><td></td><td valign="top"><a href="#index-PKCS-_002310"><acronym>PKCS</acronym> #10</a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-_002310-certificate-requests">PKCS #10 certificate requests</a></td></tr>
26050 <tr><td></td><td valign="top"><a href="#index-PKCS-_002311-tokens"><acronym>PKCS #11</acronym> tokens</a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-_002311-tokens">PKCS #11 tokens</a></td></tr>
26051 <tr><td></td><td valign="top"><a href="#index-PKCS-_002312"><acronym>PKCS</acronym> #12</a>:</td><td>&nbsp;</td><td valign="top"><a href="#PKCS-_002312-structures">PKCS #12 structures</a></td></tr>
26052 <tr><td></td><td valign="top"><a href="#index-PSK-authentication"><acronym>PSK</acronym> authentication</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Authentication-using-PSK">Authentication using PSK</a></td></tr>
26053 <tr><td></td><td valign="top"><a href="#index-PSK-client">PSK client</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Example-client-PSK-connection">Example client PSK connection</a></td></tr>
26054 <tr><td></td><td valign="top"><a href="#index-PSK-server">PSK server</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Example-server-PSK-connection">Example server PSK connection</a></td></tr>
26055 <tr><td></td><td valign="top"><a href="#index-psktool">psktool</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-psktool">Invoking psktool</a></td></tr>
26056 <tr><td colspan="4"> <hr></td></tr>
26057 <tr><th><a name="Concept-Index_cp_letter-R">R</a></th><td></td><td></td></tr>
26058 <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>
26059 <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>
26060 <tr><td></td><td valign="top"><a href="#index-renegotiation">renegotiation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Extensions">TLS Extensions</a></td></tr>
26061 <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>
26062 <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>
26063 <tr><td colspan="4"> <hr></td></tr>
26064 <tr><th><a name="Concept-Index_cp_letter-S">S</a></th><td></td><td></td></tr>
26065 <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="#TLS-Extensions">TLS Extensions</a></td></tr>
26066 <tr><td></td><td valign="top"><a href="#index-Session-Tickets">Session Tickets</a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Extensions">TLS Extensions</a></td></tr>
26067 <tr><td></td><td valign="top"><a href="#index-SRFI_002d4">SRFI-4</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Representation-of-Binary-Data">Representation of Binary Data</a></td></tr>
26068 <tr><td></td><td valign="top"><a href="#index-SRP-authentication"><acronym>SRP</acronym> authentication</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Authentication-using-SRP">Authentication using SRP</a></td></tr>
26069 <tr><td></td><td valign="top"><a href="#index-srptool">srptool</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-srptool">Invoking srptool</a></td></tr>
26070 <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>
26071 <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>
26072 <tr><td colspan="4"> <hr></td></tr>
26073 <tr><th><a name="Concept-Index_cp_letter-T">T</a></th><td></td><td></td></tr>
26074 <tr><td></td><td valign="top"><a href="#index-Ticket">Ticket</a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Extensions">TLS Extensions</a></td></tr>
26075 <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>
26076 <tr><td></td><td valign="top"><a href="#index-TLS-Extensions-1">TLS Extensions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Extensions">TLS Extensions</a></td></tr>
26077 <tr><td></td><td valign="top"><a href="#index-TLS-Extensions-2">TLS Extensions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Extensions">TLS Extensions</a></td></tr>
26078 <tr><td></td><td valign="top"><a href="#index-TLS-Extensions-3">TLS Extensions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Extensions">TLS Extensions</a></td></tr>
26079 <tr><td></td><td valign="top"><a href="#index-TLS-Inner-Application-_0028TLS_002fIA_0029-functions"><acronym>TLS</acronym> Inner Application (<acronym>TLS/IA</acronym>) functions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#TLS-Inner-Application-_0028TLS_002fIA_0029-functions">TLS Inner Application (TLS/IA) functions</a></td></tr>
26080 <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>
26081 <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>
26082 <tr><td colspan="4"> <hr></td></tr>
26083 <tr><th><a name="Concept-Index_cp_letter-V">V</a></th><td></td><td></td></tr>
26084 <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>
26085 <tr><td colspan="4"> <hr></td></tr>
26086 <tr><th><a name="Concept-Index_cp_letter-X">X</a></th><td></td><td></td></tr>
26087 <tr><td></td><td valign="top"><a href="#index-X_002e509-certificates"><acronym>X.509</acronym> certificates</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Certificate-authentication">Certificate authentication</a></td></tr>
26088 <tr><td></td><td valign="top"><a href="#index-X_002e509-certificates-1"><acronym>X.509</acronym> certificates</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-X_002e509-trust-model">The X.509 trust model</a></td></tr>
26089 <tr><td></td><td valign="top"><a href="#index-X_002e509-Functions"><acronym>X.509</acronym> Functions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#X_002e509-certificate-functions">X.509 certificate functions</a></td></tr>
26090 <tr><td colspan="4"> <hr></td></tr>
26091 </table>
26092 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a>
26093  &nbsp;
26094 <a class="summary-letter" href="#Concept-Index_cp_letter-B"><b>B</b></a>
26095  &nbsp;
26096 <a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a>
26097  &nbsp;
26098 <a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a>
26099  &nbsp;
26100 <a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a>
26101  &nbsp;
26102 <a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a>
26103  &nbsp;
26104 <a class="summary-letter" href="#Concept-Index_cp_letter-G"><b>G</b></a>
26105  &nbsp;
26106 <a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a>
26107  &nbsp;
26108 <a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a>
26109  &nbsp;
26110 <a class="summary-letter" href="#Concept-Index_cp_letter-K"><b>K</b></a>
26111  &nbsp;
26112 <a class="summary-letter" href="#Concept-Index_cp_letter-L"><b>L</b></a>
26113  &nbsp;
26114 <a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a>
26115  &nbsp;
26116 <a class="summary-letter" href="#Concept-Index_cp_letter-N"><b>N</b></a>
26117  &nbsp;
26118 <a class="summary-letter" href="#Concept-Index_cp_letter-O"><b>O</b></a>
26119  &nbsp;
26120 <a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a>
26121  &nbsp;
26122 <a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a>
26123  &nbsp;
26124 <a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a>
26125  &nbsp;
26126 <a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a>
26127  &nbsp;
26128 <a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a>
26129  &nbsp;
26130 <a class="summary-letter" href="#Concept-Index_cp_letter-X"><b>X</b></a>
26131  &nbsp;
26132 </td></tr></table>
26133
26134 <div class="footnote">
26135 <hr>
26136 <h4 class="footnotes-heading">Footnotes</h4>
26137
26138 <h3><a name="FOOT1" href="#DOCF1">(1)</a></h3>
26139 <p><a href="http://www.openssl.org/">http://www.openssl.org/</a></p>
26140 <h3><a name="FOOT2" href="#DOCF2">(2)</a></h3>
26141 <p><a href="ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/libtasn1/">ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/libtasn1/</a></p>
26142 <h3><a name="FOOT3" href="#DOCF3">(3)</a></h3>
26143 <p><a href="ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/opencdk/">ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/opencdk/</a></p>
26144 <h3><a name="FOOT4" href="#DOCF4">(4)</a></h3>
26145 <p><a href="ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/">ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/</a></p>
26146 <h3><a name="FOOT5" href="#DOCF5">(5)</a></h3>
26147 <p>On current versions of GnuTLS it is possible to
26148 override the default crypto backend. Check see <a href="#Cryptographic-Backend">Cryptographic
26149 Backend</a> for details</p>
26150 <h3><a name="FOOT6" href="#DOCF6">(6)</a></h3>
26151 <p>The first message in a <acronym>TLS</acronym> handshake</p>
26152 <h3><a name="FOOT7" href="#DOCF7">(7)</a></h3>
26153 <p>IETF, or Internet Engineering Task Force,
26154 is a large open international community of network designers,
26155 operators, vendors, and researchers concerned with the evolution of
26156 the Internet architecture and the smooth operation of the Internet.
26157 It is open to any interested individual.</p>
26158 <h3><a name="FOOT8" href="#DOCF8">(8)</a></h3>
26159 <p>AES,
26160 or Advanced Encryption Standard, is actually the RIJNDAEL algorithm.
26161 This is the algorithm that replaced DES.</p>
26162 <h3><a name="FOOT9" href="#DOCF9">(9)</a></h3>
26163 <p><code>ARCFOUR_128</code> is a compatible
26164 algorithm with RSA&rsquo;s RC4 algorithm, which is considered to be a trade
26165 secret.</p>
26166 <h3><a name="FOOT10" href="#DOCF10">(10)</a></h3>
26167 <p>You should use
26168 <a href="#gnutls_005fhandshake_005fset_005fprivate_005fextensions">gnutls_handshake_set_private_extensions</a> to enable private
26169 extensions.</p>
26170 <h3><a name="FOOT11" href="#DOCF11">(11)</a></h3>
26171 <p>MAC stands for Message Authentication Code. It can be described as a keyed hash algorithm. See RFC2104.</p>
26172 <h3><a name="FOOT12" href="#DOCF12">(12)</a></h3>
26173 <p>To avoid collisions in order to specify a compression algorithm in
26174 this string you have to prefix it with &quot;COMP-&quot;, protocol versions
26175 with &quot;VERS-&quot;, signature algorithms with &quot;SIGN-&quot; and certificate types with &quot;CTYPE-&quot;. All other
26176 algorithms don&rsquo;t need a prefix.</p>
26177 <h3><a name="FOOT13" href="#DOCF13">(13)</a></h3>
26178 <p>It really depends on the group used.  Primes with
26179 lesser bits are always faster, but also easier to break.  Values less
26180 than 768 should not be used today</p>
26181 <h3><a name="FOOT14" href="#DOCF14">(14)</a></h3>
26182 <p><acronym>SRP</acronym> is described in [RFC2945] (see <a href="#Bibliography">Bibliography</a>)</p>
26183 <h3><a name="FOOT15" href="#DOCF15">(15)</a></h3>
26184 <p>GnuTLS used to provide
26185 <code>gnutls_psk_netconf_derive_key</code> which follows the algorithm
26186 specified in &lsquo;<tt>draft-ietf-netconf-tls-02.txt</tt>&rsquo;. This method
26187 is deprecated and might be removed in later versions of GnuTLS.</p>
26188 <h3><a name="FOOT16" href="#DOCF16">(16)</a></h3>
26189 <p>http://p11-glue.freedesktop.org/</p>
26190 <h3><a name="FOOT17" href="#DOCF17">(17)</a></h3>
26191 <p>See also the Server Name Indication extension on
26192 <a href="#serverind">serverind</a>.</p>
26193 <h3><a name="FOOT18" href="#DOCF18">(18)</a></h3>
26194 <p>See LDAP, IMAP etc.</p>
26195 <h3><a name="FOOT19" href="#DOCF19">(19)</a></h3>
26196 <p>in <acronym>SRP</acronym> authentication</p>
26197 <h3><a name="FOOT20" href="#DOCF20">(20)</a></h3>
26198 <p>such as the
26199 <code>gnutls_certificate_credentials_t</code> structures</p>
26200 <h3><a name="FOOT21" href="#DOCF21">(21)</a></h3>
26201 <p>Check <a href="http://home.gna.org/cryptodev-linux/">http://home.gna.org/cryptodev-linux/</a>
26202 for the Linux kernel implementation of <code>/dev/crypto</code>.</p>
26203 </div>
26204 <hr>
26205
26206
26207
26208 </body>
26209 </html>