1 This is gnutls.info, produced by makeinfo version 6.0 from gnutls.texi.
3 This manual is last updated 4 March 2015 for version 3.4.11 of GnuTLS.
5 Copyright (C) 2001-2015 Free Software Foundation, Inc.\\ Copyright (C)
6 2001-2015 Nikos Mavrogiannopoulos
8 Permission is granted to copy, distribute and/or modify this
9 document under the terms of the GNU Free Documentation License,
10 Version 1.3 or any later version published by the Free Software
11 Foundation; with no Invariant Sections, no Front-Cover Texts, and
12 no Back-Cover Texts. A copy of the license is included in the
13 section entitled "GNU Free Documentation License".
14 INFO-DIR-SECTION Software libraries
16 * GnuTLS: (gnutls). GNU Transport Layer Security Library.
19 INFO-DIR-SECTION System Administration
21 * certtool: (gnutls)Invoking certtool. Manipulate certificates and keys.
22 * gnutls-serv: (gnutls)Invoking gnutls-serv. GnuTLS test server.
23 * gnutls-cli: (gnutls)Invoking gnutls-cli. GnuTLS test client.
24 * gnutls-cli-debug: (gnutls)Invoking gnutls-cli-debug. GnuTLS debug client.
25 * psktool: (gnutls)Invoking psktool. Simple TLS-Pre-Shared-Keys manager.
26 * srptool: (gnutls)Invoking srptool. Simple SRP password tool.
30 File: gnutls.info, Node: Top, Next: Preface, Up: (dir)
35 This manual is last updated 4 March 2015 for version 3.4.11 of GnuTLS.
37 Copyright (C) 2001-2015 Free Software Foundation, Inc.\\ Copyright (C)
38 2001-2015 Nikos Mavrogiannopoulos
40 Permission is granted to copy, distribute and/or modify this
41 document under the terms of the GNU Free Documentation License,
42 Version 1.3 or any later version published by the Free Software
43 Foundation; with no Invariant Sections, no Front-Cover Texts, and
44 no Back-Cover Texts. A copy of the license is included in the
45 section entitled "GNU Free Documentation License".
50 * Introduction to GnuTLS::
51 * Introduction to TLS::
52 * Authentication methods::
53 * Hardware security modules and abstract key types::
54 * How to use GnuTLS in applications::
55 * GnuTLS application examples::
56 * Using GnuTLS as a cryptographic library::
57 * Other included programs::
58 * Internal architecture of GnuTLS::
59 * Upgrading from previous versions::
62 * Supported ciphersuites::
64 * Copying Information::
66 * Function and Data Index::
70 File: gnutls.info, Node: Preface, Next: Introduction to GnuTLS, Prev: Top, Up: Top
75 This document demonstrates and explains the GnuTLS library API. A brief
76 introduction to the protocols and the technology involved is also
77 included so that an application programmer can better understand the
78 GnuTLS purpose and actual offerings. Even if GnuTLS is a typical
79 library software, it operates over several security and cryptographic
80 protocols which require the programmer to make careful and correct usage
81 of them. Otherwise it is likely to only obtain a false sense of
82 security. The term of security is very broad even if restricted to
83 computer software, and cannot be confined to a single cryptographic
84 library. For that reason, do not consider any program secure just
85 because it uses GnuTLS; there are several ways to compromise a program
86 or a communication line and GnuTLS only helps with some of them.
88 Although this document tries to be self contained, basic network
89 programming and public key infrastructure (PKI) knowledge is assumed in
90 most of it. A good introduction to networking can be found in
91 [_STEVENS_], to public key infrastructure in [_GUTPKI_] and to security
92 engineering in [_ANDERSON_].
94 Updated versions of the GnuTLS software and this document will be
95 available from <http://www.gnutls.org/>.
98 File: gnutls.info, Node: Introduction to GnuTLS, Next: Introduction to TLS, Prev: Preface, Up: Top
100 2 Introduction to GnuTLS
101 ************************
103 In brief GnuTLS can be described as a library which offers an API to
104 access secure communication protocols. These protocols provide privacy
105 over insecure lines, and were designed to prevent eavesdropping,
106 tampering, or message forgery.
108 Technically GnuTLS is a portable ANSI C based library which implements
109 the protocols ranging from SSL 3.0 to TLS 1.2 (see *note Introduction to
110 TLS::, for a detailed description of the protocols), accompanied with
111 the required framework for authentication and public key infrastructure.
112 Important features of the GnuTLS library include:
114 * Support for TLS 1.2, TLS 1.1, TLS 1.0 and SSL 3.0 protocols.
116 * Support for Datagram TLS 1.0 and 1.2.
118 * Support for handling and verification of X.509 and OpenPGP
121 * Support for password authentication using TLS-SRP.
123 * Support for keyed authentication using TLS-PSK.
125 * Support for TPM, PKCS #11 tokens and smart-cards.
127 The GnuTLS library consists of three independent parts, namely the "TLS
128 protocol part", the "Certificate part", and the "Cryptographic back-end"
129 part. The "TLS protocol part" is the actual protocol implementation,
130 and is entirely implemented within the GnuTLS library. The "Certificate
131 part" consists of the certificate parsing, and verification functions
132 and it uses functionality from the libtasn1 library. The "Cryptographic
133 back-end" is provided by the nettle and gmplib libraries.
137 * Downloading and installing::
138 * Installing for a software distribution::
139 * Document overview::
142 File: gnutls.info, Node: Downloading and installing, Next: Installing for a software distribution, Up: Introduction to GnuTLS
144 2.1 Downloading and installing
145 ==============================
147 GnuTLS is available for download at:
148 <http://www.gnutls.org/download.html>
150 GnuTLS uses a development cycle where even minor version numbers
151 indicate a stable release and a odd minor version number indicate a
152 development release. For example, GnuTLS 1.6.3 denote a stable release
153 since 6 is even, and GnuTLS 1.7.11 denote a development release since 7
156 GnuTLS depends on 'nettle' and 'gmplib', and you will need to install it
157 before installing GnuTLS. The 'nettle' library is available from
158 <http://www.lysator.liu.se/~nisse/nettle/>, while 'gmplib' is available
159 from <http://www.gmplib.org/>. Don't forget to verify the cryptographic
160 signature after downloading source code packages.
162 The package is then extracted, configured and built like many other
163 packages that use Autoconf. For detailed information on configuring and
164 building it, refer to the 'INSTALL' file that is part of the
165 distribution archive. Typically you invoke './configure' and then 'make
166 check install'. There are a number of compile-time parameters, as
169 Several parts of GnuTLS require ASN.1 functionality, which is provided
170 by a library called libtasn1. A copy of libtasn1 is included in GnuTLS.
171 If you want to install it separately (e.g., to make it possibly to use
172 libtasn1 in other programs), you can get it from
173 <http://www.gnu.org/software/libtasn1/>.
175 The compression library, 'libz', the PKCS #11 helper library 'p11-kit',
176 the TPM library 'trousers', as well as the IDN library 'libidn'(1) are
177 optional dependencies. Check the README file in the distribution on how
178 to obtain these libraries.
180 A few 'configure' options may be relevant, summarized below. They
181 disable or enable particular features, to create a smaller library with
182 only the required features. Note however, that although a smaller
183 library is generated, the included programs are not guaranteed to
184 compile if some of these options are given.
186 --disable-srp-authentication
187 --disable-psk-authentication
188 --disable-anon-authentication
189 --disable-openpgp-authentication
192 --disable-openssl-compatibility
193 --disable-dtls-srtp-support
194 --disable-alpn-support
195 --disable-heartbeat-support
202 For the complete list, refer to the output from 'configure --help'.
204 ---------- Footnotes ----------
206 (1) Needed to use RFC6125 name comparison in internationalized
210 File: gnutls.info, Node: Installing for a software distribution, Next: Document overview, Prev: Downloading and installing, Up: Introduction to GnuTLS
212 2.2 Installing for a software distribution
213 ==========================================
215 When installing for a software distribution, it is often desirable to
216 preconfigure GnuTLS with the system-wide paths and files. There two
217 important configuration options, one sets the trust store in system,
218 which are the CA certificates to be used by programs by default (if they
219 don't override it), and the other sets to DNSSEC root key file used by
220 unbound for DNSSEC verification.
222 For the latter the following configuration option is available, and if
223 not specified GnuTLS will try to auto-detect the location of that file.
224 --with-unbound-root-key-file
227 To set the trust store the following options are available.
228 --with-default-trust-store-file
229 --with-default-trust-store-dir
230 --with-default-trust-store-pkcs11
232 The first option is used to set a PEM file which contains a list of
233 trusted certificates, while the second will read all certificates in the
234 given path. The recommended option is the last, which allows to use a
235 PKCS #11 trust policy module. That module not only provides the trusted
236 certificates, but allows the categorization of them using purpose, e.g.,
237 CAs can be restricted for e-mail usage only, or administrative
238 restrictions of CAs, for examples by restricting a CA to only issue
239 certificates for a given DNS domain using NameConstraints. A publicly
240 available PKCS #11 trust module is p11-kit's trust module(1).
242 ---------- Footnotes ----------
244 (1) <http://p11-glue.freedesktop.org/doc/p11-kit/trust-module.html>
247 File: gnutls.info, Node: Document overview, Prev: Installing for a software distribution, Up: Introduction to GnuTLS
252 In this document we present an overview of the supported security
253 protocols in *note Introduction to TLS::, and continue by providing more
254 information on the certificate authentication in *note Certificate
255 authentication::, and shared-key as well anonymous authentication in
256 *note Shared-key and anonymous authentication::. We elaborate on
257 certificate authentication by demonstrating advanced usage of the API in
258 *note More on certificate authentication::. The core of the TLS library
259 is presented in *note How to use GnuTLS in applications:: and example
260 applications are listed in *note GnuTLS application examples::. In
261 *note Other included programs:: the usage of few included programs that
262 may assist debugging is presented. The last chapter is *note Internal
263 architecture of GnuTLS:: that provides a short introduction to GnuTLS'
264 internal architecture.
267 File: gnutls.info, Node: Introduction to TLS, Next: Authentication methods, Prev: Introduction to GnuTLS, Up: Top
269 3 Introduction to TLS and DTLS
270 ******************************
272 TLS stands for "Transport Layer Security" and is the successor of SSL,
273 the Secure Sockets Layer protocol [_SSL3_] designed by Netscape. TLS is
274 an Internet protocol, defined by IETF(1), described in [_RFC5246_]. The
275 protocol provides confidentiality, and authentication layers over any
276 reliable transport layer. The description, above, refers to TLS 1.0 but
277 applies to all other TLS versions as the differences between the
278 protocols are not major.
280 The DTLS protocol, or "Datagram TLS" [_RFC4347_] is a protocol with
281 identical goals as TLS, but can operate under unreliable transport
282 layers such as UDP. The discussions below apply to this protocol as
283 well, except when noted otherwise.
288 * The transport layer::
289 * The TLS record protocol::
290 * The TLS Alert Protocol::
291 * The TLS Handshake Protocol::
293 * How to use TLS in application protocols::
294 * On SSL 2 and older protocols::
296 ---------- Footnotes ----------
298 (1) IETF, or Internet Engineering Task Force, is a large open
299 international community of network designers, operators, vendors, and
300 researchers concerned with the evolution of the Internet architecture
301 and the smooth operation of the Internet. It is open to any interested
305 File: gnutls.info, Node: TLS layers, Next: The transport layer, Up: Introduction to TLS
310 TLS is a layered protocol, and consists of the record protocol, the
311 handshake protocol and the alert protocol. The record protocol is to
312 serve all other protocols and is above the transport layer. The record
313 protocol offers symmetric encryption, data authenticity, and optionally
314 compression. The alert protocol offers some signaling to the other
315 protocols. It can help informing the peer for the cause of failures and
316 other error conditions. *Note The Alert Protocol::, for more
317 information. The alert protocol is above the record protocol.
319 The handshake protocol is responsible for the security parameters'
320 negotiation, the initial key exchange and authentication. *Note The
321 Handshake Protocol::, for more information about the handshake protocol.
322 The protocol layering in TLS is shown in *note Figure 3.1:
325 \0\b[image src="gnutls-layers.png"
\0\b]
327 Figure 3.1: The TLS protocol layers.
330 File: gnutls.info, Node: The transport layer, Next: The TLS record protocol, Prev: TLS layers, Up: Introduction to TLS
332 3.2 The Transport Layer
333 =======================
335 TLS is not limited to any transport layer and can be used above any
336 transport layer, as long as it is a reliable one. DTLS can be used over
337 reliable and unreliable transport layers. GnuTLS supports TCP and UDP
338 layers transparently using the Berkeley sockets API. However, any
339 transport layer can be used by providing callbacks for GnuTLS to access
340 the transport layer (for details see *note Setting up the transport
344 File: gnutls.info, Node: The TLS record protocol, Next: The TLS Alert Protocol, Prev: The transport layer, Up: Introduction to TLS
346 3.3 The TLS record protocol
347 ===========================
349 The record protocol is the secure communications provider. Its purpose
350 is to encrypt, authenticate and --optionally-- compress packets. The
351 record layer functions can be called at any time after the handshake
352 process is finished, when there is need to receive or send data. In
353 DTLS however, due to re-transmission timers used in the handshake
354 out-of-order handshake data might be received for some time (maximum 60
355 seconds) after the handshake process is finished.
357 The functions to access the record protocol are limited to send and
358 receive functions, which might, given the importance of this protocol in
359 TLS, seem awkward. This is because the record protocol's parameters are
360 all set by the handshake protocol. The record protocol initially starts
361 with NULL parameters, which means no encryption, and no MAC is used.
362 Encryption and authentication begin just after the handshake protocol
367 * Encryption algorithms used in the record layer::
368 * Compression algorithms used in the record layer::
369 * Weaknesses and countermeasures::
370 * On Record Padding::
373 File: gnutls.info, Node: Encryption algorithms used in the record layer, Next: Compression algorithms used in the record layer, Up: The TLS record protocol
375 3.3.1 Encryption algorithms used in the record layer
376 ----------------------------------------------------
378 Confidentiality in the record layer is achieved by using symmetric block
379 encryption algorithms like '3DES', 'AES' or stream algorithms like
380 'ARCFOUR_128'. Ciphers are encryption algorithms that use a single,
381 secret, key to encrypt and decrypt data. Block algorithms in CBC mode
382 also provide protection against statistical analysis of the data. Thus,
383 if you're using the TLS protocol, a random number of blocks will be
384 appended to data, to prevent eavesdroppers from guessing the actual data
387 The supported in GnuTLS ciphers and MAC algorithms are shown in *note
388 Table 3.1: tab:ciphers. and *note Table 3.2: tab:macs.
390 Algorithm Description
391 ------------------------------------------------------------------
392 AES_CBC AES or RIJNDAEL is the block cipher algorithm
393 that replaces the old DES algorithm. Has 128
394 bits block size and is used in CBC mode.
396 AES_GCM This is the AES algorithm in the authenticated
397 encryption GCM mode. This mode combines message
398 authentication and encryption and can be
399 extremely fast on CPUs that support hardware
402 AES_CCM This is the AES algorithm in the authenticated
403 encryption CCM mode. This mode combines message
404 authentication and encryption and is often used
405 by systems without AES or GCM acceleration
408 AES_CCM_8 This is the AES algorithm in the authenticated
409 encryption CCM mode with a truncated to 64-bit
410 authentication tag. This mode is for
411 communication with restricted systems.
413 CAMELLIA_CBC This is an 128-bit block cipher developed by
414 Mitsubishi and NTT. It is one of the approved
415 ciphers of the European NESSIE and Japanese
418 CHACHA20_POLY1305CHACHA20-POLY1305 is an authenticated encryption
419 algorithm based on CHACHA20 cipher and POLY1305
420 MAC. CHACHA20 is a refinement of SALSA20
421 algorithm, an approved cipher by the European
422 ESTREAM project. POLY1305 is Wegman-Carter,
423 one-time authenticator. The combination
424 provides a fast stream cipher suitable for
425 systems where a hardware AES accelerator is not
428 3DES_CBC This is the DES block cipher algorithm used with
429 triple encryption (EDE). Has 64 bits block size
430 and is used in CBC mode.
432 ARCFOUR_128 ARCFOUR-128 is a compatible algorithm with RSA's
433 RC4 algorithm, which is considered to be a trade
434 secret. It is a fast cipher but considered weak
435 today, and thus it is not enabled by default.
438 Table 3.1: Supported ciphers in TLS.
440 Algorithm Description
441 ------------------------------------------------------------------
442 MAC_MD5 This is an HMAC based on MD5 a cryptographic
443 hash algorithm designed by Ron Rivest. Outputs
446 MAC_SHA1 An HMAC based on the SHA1 cryptographic hash
447 algorithm designed by NSA. Outputs 160 bits of
450 MAC_SHA256 An HMAC based on SHA2-256. Outputs 256 bits of
453 MAC_SHA384 An HMAC based on SHA2-384. Outputs 384 bits of
456 MAC_AEAD This indicates that an authenticated encryption
457 algorithm, such as GCM, is in use.
460 Table 3.2: Supported MAC algorithms in TLS.
463 File: gnutls.info, Node: Compression algorithms used in the record layer, Next: Weaknesses and countermeasures, Prev: Encryption algorithms used in the record layer, Up: The TLS record protocol
465 3.3.2 Compression algorithms used in the record layer
466 -----------------------------------------------------
468 The TLS record layer also supports compression. The algorithms
469 implemented in GnuTLS can be found in the table below. The included
470 algorithms perform really good when text, or other compressible data are
471 to be transferred, but offer nothing on already compressed data, such as
472 compressed images, zipped archives etc. These compression algorithms,
473 may be useful in high bandwidth TLS tunnels, and in cases where network
474 usage has to be minimized. It should be noted however that compression
477 The record layer compression in GnuTLS is implemented based on
478 [_RFC3749_]. The supported algorithms are shown below.
480 'GNUTLS_COMP_UNKNOWN'
481 Unknown compression method.
483 The NULL compression method (no compression).
484 'GNUTLS_COMP_DEFLATE'
485 The DEFLATE compression method from zlib.
487 Same as 'GNUTLS_COMP_DEFLATE' .
489 Figure 3.2: Supported compression algorithms
491 Note that compression enables attacks such as traffic analysis, or even
492 plaintext recovery under certain circumstances. To avoid some of these
493 attacks GnuTLS allows each record to be compressed independently (i.e.,
494 stateless compression), by using the "%STATELESS_COMPRESSION" priority
495 string, in order to be used in cases where the attacker controlled data
496 are pt in separate records.
499 File: gnutls.info, Node: Weaknesses and countermeasures, Next: On Record Padding, Prev: Compression algorithms used in the record layer, Up: The TLS record protocol
501 3.3.3 Weaknesses and countermeasures
502 ------------------------------------
504 Some weaknesses that may affect the security of the record layer have
505 been found in TLS 1.0 protocol. These weaknesses can be exploited by
506 active attackers, and exploit the facts that
508 1. TLS has separate alerts for "decryption_failed" and
511 2. The decryption failure reason can be detected by timing the
514 3. The IV for CBC encrypted packets is the last block of the previous
517 Those weaknesses were solved in TLS 1.1 [_RFC4346_] which is implemented
518 in GnuTLS. For this reason we suggest to always negotiate the highest
519 supported TLS version with the peer(1). For a detailed discussion of
520 the issues see the archives of the TLS Working Group mailing list and
523 ---------- Footnotes ----------
525 (1) If this is not possible then please consult *note
529 File: gnutls.info, Node: On Record Padding, Prev: Weaknesses and countermeasures, Up: The TLS record protocol
531 3.3.4 On record padding
532 -----------------------
534 The TLS protocol allows for extra padding of records in CBC ciphers, to
535 prevent statistical analysis based on the length of exchanged messages
536 (see [_RFC5246_] section 6.2.3.2). GnuTLS appears to be one of few
537 implementations that take advantage of this feature: the user can
538 provide some plaintext data with a range of lengths she wishes to hide,
539 and GnuTLS adds extra padding to make sure the attacker cannot tell the
540 real plaintext length is in a range smaller than the user-provided one.
541 Use *note gnutls_record_send_range:: to send length-hidden messages and
542 *note gnutls_record_can_use_length_hiding:: to check whether the current
543 session supports length hiding. Using the standard *note
544 gnutls_record_send:: will only add minimal padding.
546 The TLS implementation in the Symbian operating system, frequently used
547 by Nokia and Sony-Ericsson mobile phones, cannot handle non-minimal
548 record padding. What happens when one of these clients handshake with a
549 GnuTLS server is that the client will fail to compute the correct MAC
550 for the record. The client sends a TLS alert ('bad_record_mac') and
551 disconnects. Typically this will result in error messages such as 'A
552 TLS fatal alert has been received', 'Bad record MAC', or both, on the
555 If compatibility with such devices is a concern, not sending
556 length-hidden messages solves the problem by using minimal padding.
558 If you implement an application that has a configuration file, we
559 recommend that you make it possible for users or administrators to
560 specify a GnuTLS protocol priority string, which is used by your
561 application via *note gnutls_priority_set::. To allow the best
562 flexibility, make it possible to have a different priority string for
563 different incoming IP addresses.
566 File: gnutls.info, Node: The TLS Alert Protocol, Next: The TLS Handshake Protocol, Prev: The TLS record protocol, Up: Introduction to TLS
568 3.4 The TLS alert protocol
569 ==========================
571 The alert protocol is there to allow signals to be sent between peers.
572 These signals are mostly used to inform the peer about the cause of a
573 protocol failure. Some of these signals are used internally by the
574 protocol and the application protocol does not have to cope with them
575 (e.g. 'GNUTLS_A_CLOSE_NOTIFY'), and others refer to the application
576 protocol solely (e.g. 'GNUTLS_A_USER_CANCELLED'). An alert signal
577 includes a level indication which may be either fatal or warning. Fatal
578 alerts always terminate the current connection, and prevent future
579 re-negotiations using the current session ID. All alert messages are
580 summarized in the table below.
582 The alert messages are protected by the record protocol, thus the
583 information that is included does not leak. You must take extreme care
584 for the alert information not to leak to a possible attacker, via public
588 ------------------------------------------------------------------------
589 GNUTLS_A_CLOSE_NOTIFY 0 Close notify
590 GNUTLS_A_UNEXPECTED_MESSAGE 10 Unexpected message
591 GNUTLS_A_BAD_RECORD_MAC 20 Bad record MAC
592 GNUTLS_A_DECRYPTION_FAILED 21 Decryption failed
593 GNUTLS_A_RECORD_OVERFLOW 22 Record overflow
594 GNUTLS_A_DECOMPRESSION_FAILURE 30 Decompression failed
595 GNUTLS_A_HANDSHAKE_FAILURE 40 Handshake failed
596 GNUTLS_A_SSL3_NO_CERTIFICATE 41 No certificate (SSL
598 GNUTLS_A_BAD_CERTIFICATE 42 Certificate is bad
599 GNUTLS_A_UNSUPPORTED_CERTIFICATE 43 Certificate is not
601 GNUTLS_A_CERTIFICATE_REVOKED 44 Certificate was
603 GNUTLS_A_CERTIFICATE_EXPIRED 45 Certificate is
605 GNUTLS_A_CERTIFICATE_UNKNOWN 46 Unknown certificate
606 GNUTLS_A_ILLEGAL_PARAMETER 47 Illegal parameter
607 GNUTLS_A_UNKNOWN_CA 48 CA is unknown
608 GNUTLS_A_ACCESS_DENIED 49 Access was denied
609 GNUTLS_A_DECODE_ERROR 50 Decode error
610 GNUTLS_A_DECRYPT_ERROR 51 Decrypt error
611 GNUTLS_A_EXPORT_RESTRICTION 60 Export restriction
612 GNUTLS_A_PROTOCOL_VERSION 70 Error in protocol
614 GNUTLS_A_INSUFFICIENT_SECURITY 71 Insufficient
616 GNUTLS_A_INTERNAL_ERROR 80 Internal error
617 GNUTLS_A_INAPPROPRIATE_FALLBACK 86 Inappropriate
619 GNUTLS_A_USER_CANCELED 90 User canceled
620 GNUTLS_A_NO_RENEGOTIATION 100 No renegotiation is
622 GNUTLS_A_UNSUPPORTED_EXTENSION 110 An unsupported
624 GNUTLS_A_CERTIFICATE_UNOBTAINABLE 111 Could not retrieve
627 GNUTLS_A_UNRECOGNIZED_NAME 112 The server name sent
629 GNUTLS_A_UNKNOWN_PSK_IDENTITY 115 The SRP/PSK username
632 GNUTLS_A_NO_APPLICATION_PROTOCOL 120 No supported
637 File: gnutls.info, Node: The TLS Handshake Protocol, Next: TLS Extensions, Prev: The TLS Alert Protocol, Up: Introduction to TLS
639 3.5 The TLS handshake protocol
640 ==============================
642 The handshake protocol is responsible for the ciphersuite negotiation,
643 the initial key exchange, and the authentication of the two peers. This
644 is fully controlled by the application layer, thus your program has to
645 set up the required parameters. The main handshake function is *note
646 gnutls_handshake::. In the next paragraphs we elaborate on the
647 handshake protocol, i.e., the ciphersuite negotiation.
651 * TLS Cipher Suites:: TLS session parameters.
652 * Authentication:: TLS authentication.
653 * Client Authentication:: Requesting a certificate from the client.
654 * Resuming Sessions:: Reusing previously established keys.
657 File: gnutls.info, Node: TLS Cipher Suites, Next: Authentication, Up: The TLS Handshake Protocol
659 3.5.1 TLS ciphersuites
660 ----------------------
662 The handshake protocol of TLS negotiates cipher suites of a special form
663 illustrated by the 'TLS_DHE_RSA_WITH_3DES_CBC_SHA' cipher suite name. A
664 typical cipher suite contains these parameters:
666 * The key exchange algorithm. 'DHE_RSA' in the example.
668 * The Symmetric encryption algorithm and mode '3DES_CBC' in this
671 * The MAC(1) algorithm used for authentication. 'MAC_SHA' is used in
674 The cipher suite negotiated in the handshake protocol will affect the
675 record protocol, by enabling encryption and data authentication. Note
676 that you should not over rely on TLS to negotiate the strongest
677 available cipher suite. Do not enable ciphers and algorithms that you
680 All the supported ciphersuites are listed in *note ciphersuites::.
682 ---------- Footnotes ----------
684 (1) MAC stands for Message Authentication Code. It can be described
685 as a keyed hash algorithm. See RFC2104.
688 File: gnutls.info, Node: Authentication, Next: Client Authentication, Prev: TLS Cipher Suites, Up: The TLS Handshake Protocol
693 The key exchange algorithms of the TLS protocol offer authentication,
694 which is a prerequisite for a secure connection. The available
695 authentication methods in GnuTLS follow.
697 * Certificate authentication: Authenticated key exchange using public
698 key infrastructure and certificates (X.509 or OpenPGP).
699 * SRP authentication: Authenticated key exchange using a password.
700 * PSK authentication: Authenticated key exchange using a pre-shared
702 * Anonymous authentication: Key exchange without peer authentication.
705 File: gnutls.info, Node: Client Authentication, Next: Resuming Sessions, Prev: Authentication, Up: The TLS Handshake Protocol
707 3.5.3 Client authentication
708 ---------------------------
710 In the case of ciphersuites that use certificate authentication, the
711 authentication of the client is optional in TLS. A server may request a
712 certificate from the client using the *note
713 gnutls_certificate_server_set_request:: function. We elaborate in *note
714 Certificate credentials::.
717 File: gnutls.info, Node: Resuming Sessions, Prev: Client Authentication, Up: The TLS Handshake Protocol
719 3.5.4 Resuming sessions
720 -----------------------
722 The TLS handshake process performs expensive calculations and a busy
723 server might easily be put under load. To reduce the load, session
724 resumption may be used. This is a feature of the TLS protocol which
725 allows a client to connect to a server after a successful handshake,
726 without the expensive calculations. This is achieved by re-using the
727 previously established keys, meaning the server needs to store the state
728 of established connections (unless session tickets are used - *note
731 Session resumption is an integral part of GnuTLS, and *note Session
732 resumption::, *note ex-resume-client:: illustrate typical uses of it.
735 File: gnutls.info, Node: TLS Extensions, Next: How to use TLS in application protocols, Prev: The TLS Handshake Protocol, Up: Introduction to TLS
740 A number of extensions to the TLS protocol have been proposed mainly in
741 [_TLSEXT_]. The extensions supported in GnuTLS are discussed in the
742 subsections that follow.
746 * Maximum fragment length negotiation::
747 * Server name indication::
750 * Safe renegotiation::
751 * OCSP status request::
753 * Application Layer Protocol Negotiation (ALPN)::
754 * Extensions and Supplemental Data::
757 File: gnutls.info, Node: Maximum fragment length negotiation, Next: Server name indication, Up: TLS Extensions
759 3.6.1 Maximum fragment length negotiation
760 -----------------------------------------
762 This extension allows a TLS implementation to negotiate a smaller value
763 for record packet maximum length. This extension may be useful to
764 clients with constrained capabilities. The functions shown below can be
765 used to control this extension.
767 'SIZE_T *note gnutls_record_get_max_size:: (gnutls_session_t SESSION)'
768 'SSIZE_T *note gnutls_record_set_max_size:: (gnutls_session_t SESSION, size_t SIZE)'
771 File: gnutls.info, Node: Server name indication, Next: Session tickets, Prev: Maximum fragment length negotiation, Up: TLS Extensions
773 3.6.2 Server name indication
774 ----------------------------
776 A common problem in HTTPS servers is the fact that the TLS protocol is
777 not aware of the hostname that a client connects to, when the handshake
778 procedure begins. For that reason the TLS server has no way to know
779 which certificate to send.
781 This extension solves that problem within the TLS protocol, and allows a
782 client to send the HTTP hostname before the handshake begins within the
783 first handshake packet. The functions *note gnutls_server_name_set::
784 and *note gnutls_server_name_get:: can be used to enable this extension,
785 or to retrieve the name sent by a client.
787 'INT *note gnutls_server_name_set:: (gnutls_session_t SESSION, gnutls_server_name_type_t TYPE, const void * NAME, size_t NAME_LENGTH)'
788 'INT *note gnutls_server_name_get:: (gnutls_session_t SESSION, void * DATA, size_t * DATA_LENGTH, unsigned int * TYPE, unsigned int INDX)'
791 File: gnutls.info, Node: Session tickets, Next: HeartBeat, Prev: Server name indication, Up: TLS Extensions
793 3.6.3 Session tickets
794 ---------------------
796 To resume a TLS session, the server normally stores session parameters.
797 This complicates deployment, and can be avoided by delegating the
798 storage to the client. Because session parameters are sensitive they
799 are encrypted and authenticated with a key only known to the server and
800 then sent to the client. The Session Tickets extension is described in
803 A disadvantage of session tickets is that they eliminate the effects of
804 forward secrecy when a server uses the same key for long time. That is,
805 the secrecy of all sessions on a server using tickets depends on the
806 ticket key being kept secret. For that reason server keys should be
807 rotated and discarded regularly.
809 Since version 3.1.3 GnuTLS clients transparently support session
810 tickets, unless forward secrecy is explicitly requested (with the PFS
814 File: gnutls.info, Node: HeartBeat, Next: Safe renegotiation, Prev: Session tickets, Up: TLS Extensions
819 This is a TLS extension that allows to ping and receive confirmation
820 from the peer, and is described in [_RFC6520_]. The extension is
821 disabled by default and *note gnutls_heartbeat_enable:: can be used to
822 enable it. A policy may be negotiated to only allow sending heartbeat
823 messages or sending and receiving. The current session policy can be
824 checked with *note gnutls_heartbeat_allowed::. The requests coming from
825 the peer result to 'GNUTLS_E_HEARTBEAT_PING_RECEIVED' being returned
826 from the receive function. Ping requests to peer can be send via *note
827 gnutls_heartbeat_ping::.
829 'INT *note gnutls_heartbeat_allowed:: (gnutls_session_t SESSION, unsigned int TYPE)'
830 'VOID *note gnutls_heartbeat_enable:: (gnutls_session_t SESSION, unsigned int TYPE)'
832 'INT *note gnutls_heartbeat_ping:: (gnutls_session_t SESSION, size_t DATA_SIZE, unsigned int MAX_TRIES, unsigned int FLAGS)'
833 'INT *note gnutls_heartbeat_pong:: (gnutls_session_t SESSION, unsigned int FLAGS)'
834 'VOID *note gnutls_heartbeat_set_timeouts:: (gnutls_session_t SESSION, unsigned int RETRANS_TIMEOUT, unsigned int TOTAL_TIMEOUT)'
835 'UNSIGNED INT *note gnutls_heartbeat_get_timeout:: (gnutls_session_t SESSION)'
838 File: gnutls.info, Node: Safe renegotiation, Next: OCSP status request, Prev: HeartBeat, Up: TLS Extensions
840 3.6.5 Safe renegotiation
841 ------------------------
843 TLS gives the option to two communicating parties to renegotiate and
844 update their security parameters. One useful example of this feature
845 was for a client to initially connect using anonymous negotiation to a
846 server, and the renegotiate using some authenticated ciphersuite. This
847 occurred to avoid having the client sending its credentials in the
850 However this renegotiation, as initially designed would not ensure that
851 the party one is renegotiating is the same as the one in the initial
852 negotiation. For example one server could forward all renegotiation
853 traffic to an other server who will see this traffic as an initial
856 This might be seen as a valid design decision, but it seems it was not
857 widely known or understood, thus today some application protocols use
858 the TLS renegotiation feature in a manner that enables a malicious
859 server to insert content of his choice in the beginning of a TLS
862 The most prominent vulnerability was with HTTPS. There servers request a
863 renegotiation to enforce an anonymous user to use a certificate in order
864 to access certain parts of a web site. The attack works by having the
865 attacker simulate a client and connect to a server, with server-only
866 authentication, and send some data intended to cause harm. The server
867 will then require renegotiation from him in order to perform the
868 request. When the proper client attempts to contact the server, the
869 attacker hijacks that connection and forwards traffic to the initial
870 server that requested renegotiation. The attacker will not be able to
871 read the data exchanged between the client and the server. However, the
872 server will (incorrectly) assume that the initial request sent by the
873 attacker was sent by the now authenticated client. The result is a
874 prefix plain-text injection attack.
876 The above is just one example. Other vulnerabilities exists that do not
877 rely on the TLS renegotiation to change the client's authenticated
878 status (either TLS or application layer).
880 While fixing these application protocols and implementations would be
881 one natural reaction, an extension to TLS has been designed that
882 cryptographically binds together any renegotiated handshakes with the
883 initial negotiation. When the extension is used, the attack is detected
884 and the session can be terminated. The extension is specified in
887 GnuTLS supports the safe renegotiation extension. The default behavior
888 is as follows. Clients will attempt to negotiate the safe renegotiation
889 extension when talking to servers. Servers will accept the extension
890 when presented by clients. Clients and servers will permit an initial
891 handshake to complete even when the other side does not support the safe
892 renegotiation extension. Clients and servers will refuse renegotiation
893 attempts when the extension has not been negotiated.
895 Note that permitting clients to connect to servers when the safe
896 renegotiation extension is not enabled, is open up for attacks.
897 Changing this default behavior would prevent interoperability against
898 the majority of deployed servers out there. We will reconsider this
899 default behavior in the future when more servers have been upgraded.
900 Note that it is easy to configure clients to always require the safe
901 renegotiation extension from servers.
903 To modify the default behavior, we have introduced some new priority
904 strings (see *note Priority Strings::). The '%UNSAFE_RENEGOTIATION'
905 priority string permits (re-)handshakes even when the safe renegotiation
906 extension was not negotiated. The default behavior is
907 '%PARTIAL_RENEGOTIATION' that will prevent renegotiation with clients
908 and servers not supporting the extension. This is secure for servers
909 but leaves clients vulnerable to some attacks, but this is a trade-off
910 between security and compatibility with old servers. The
911 '%SAFE_RENEGOTIATION' priority string makes clients and servers require
912 the extension for every handshake. The latter is the most secure option
913 for clients, at the cost of not being able to connect to legacy servers.
914 Servers will also deny clients that do not support the extension from
917 It is possible to disable use of the extension completely, in both
918 clients and servers, by using the '%DISABLE_SAFE_RENEGOTIATION' priority
919 string however we strongly recommend you to only do this for debugging
922 The default values if the flags above are not specified are:
925 %PARTIAL_RENEGOTIATION
928 %PARTIAL_RENEGOTIATION
930 For applications we have introduced a new API related to safe
931 renegotiation. The *note gnutls_safe_renegotiation_status:: function is
932 used to check if the extension has been negotiated on a session, and can
933 be used both by clients and servers.
936 File: gnutls.info, Node: OCSP status request, Next: SRTP, Prev: Safe renegotiation, Up: TLS Extensions
938 3.6.6 OCSP status request
939 -------------------------
941 The Online Certificate Status Protocol (OCSP) is a protocol that allows
942 the client to verify the server certificate for revocation without
943 messing with certificate revocation lists. Its drawback is that it
944 requires the client to connect to the server's CA OCSP server and
945 request the status of the certificate. This extension however, enables
946 a TLS server to include its CA OCSP server response in the handshake.
947 That is an HTTPS server may periodically run 'ocsptool' (see *note
948 ocsptool Invocation::) to obtain its certificate revocation status and
949 serve it to the clients. That way a client avoids an additional
950 connection to the OCSP server.
952 'VOID *note gnutls_certificate_set_ocsp_status_request_function:: (gnutls_certificate_credentials_t SC, gnutls_status_request_ocsp_func OCSP_FUNC, void * PTR)'
953 'INT *note gnutls_certificate_set_ocsp_status_request_file:: (gnutls_certificate_credentials_t SC, const char * RESPONSE_FILE, unsigned int FLAGS)'
954 'INT *note gnutls_ocsp_status_request_enable_client:: (gnutls_session_t SESSION, gnutls_datum_t * RESPONDER_ID, size_t RESPONDER_ID_SIZE, gnutls_datum_t * EXTENSIONS)'
955 'INT *note gnutls_ocsp_status_request_is_checked:: (gnutls_session_t SESSION, unsigned int FLAGS)'
957 A server is required to provide the OCSP server's response using the
958 *note gnutls_certificate_set_ocsp_status_request_file::. The response
959 may be obtained periodically using the following command.
961 ocsptool --ask --load-cert server_cert.pem --load-issuer the_issuer.pem
962 --load-signer the_issuer.pem --outfile ocsp.response
964 Since version 3.1.3 GnuTLS clients transparently support the certificate
968 File: gnutls.info, Node: SRTP, Next: Application Layer Protocol Negotiation (ALPN), Prev: OCSP status request, Up: TLS Extensions
973 The TLS protocol was extended in [_RFC5764_] to provide keying material
974 to the Secure RTP (SRTP) protocol. The SRTP protocol provides an
975 encapsulation of encrypted data that is optimized for voice data. With
976 the SRTP TLS extension two peers can negotiate keys using TLS or DTLS
977 and obtain keying material for use with SRTP. The available SRTP
978 profiles are listed below.
980 'GNUTLS_SRTP_AES128_CM_HMAC_SHA1_80'
981 128 bit AES with a 80 bit HMAC-SHA1
982 'GNUTLS_SRTP_AES128_CM_HMAC_SHA1_32'
983 128 bit AES with a 32 bit HMAC-SHA1
984 'GNUTLS_SRTP_NULL_HMAC_SHA1_80'
985 NULL cipher with a 80 bit HMAC-SHA1
986 'GNUTLS_SRTP_NULL_HMAC_SHA1_32'
987 NULL cipher with a 32 bit HMAC-SHA1
989 Figure 3.3: Supported SRTP profiles
991 To enable use the following functions.
993 'INT *note gnutls_srtp_set_profile:: (gnutls_session_t SESSION, gnutls_srtp_profile_t PROFILE)'
994 'INT *note gnutls_srtp_set_profile_direct:: (gnutls_session_t SESSION, const char * PROFILES, const char ** ERR_POS)'
996 To obtain the negotiated keys use the function below.
998 -- Function: int gnutls_srtp_get_keys (gnutls_session_t SESSION, void *
999 KEY_MATERIAL, unsigned int KEY_MATERIAL_SIZE, gnutls_datum_t *
1000 CLIENT_KEY, gnutls_datum_t * CLIENT_SALT, gnutls_datum_t *
1001 SERVER_KEY, gnutls_datum_t * SERVER_SALT)
1002 SESSION: is a 'gnutls_session_t' type.
1004 KEY_MATERIAL: Space to hold the generated key material
1006 KEY_MATERIAL_SIZE: The maximum size of the key material
1008 CLIENT_KEY: The master client write key, pointing inside the key
1011 CLIENT_SALT: The master client write salt, pointing inside the key
1014 SERVER_KEY: The master server write key, pointing inside the key
1017 SERVER_SALT: The master server write salt, pointing inside the key
1020 This is a helper function to generate the keying material for SRTP.
1021 It requires the space of the key material to be pre-allocated
1022 (should be at least 2x the maximum key size and salt size). The
1023 'client_key' , 'client_salt' , 'server_key' and 'server_salt' are
1024 convenience datums that point inside the key material. They may be
1027 *Returns:* On success the size of the key material is returned,
1028 otherwise, 'GNUTLS_E_SHORT_MEMORY_BUFFER' if the buffer given is
1029 not sufficient, or a negative error code.
1033 Other helper functions are listed below.
1035 'INT *note gnutls_srtp_get_selected_profile:: (gnutls_session_t SESSION, gnutls_srtp_profile_t * PROFILE)'
1036 'CONST CHAR * *note gnutls_srtp_get_profile_name:: (gnutls_srtp_profile_t PROFILE)'
1037 'INT *note gnutls_srtp_get_profile_id:: (const char * NAME, gnutls_srtp_profile_t * PROFILE)'
1040 File: gnutls.info, Node: Application Layer Protocol Negotiation (ALPN), Next: Extensions and Supplemental Data, Prev: SRTP, Up: TLS Extensions
1042 3.6.8 Application Layer Protocol Negotiation (ALPN)
1043 ---------------------------------------------------
1045 The TLS protocol was extended in 'RFC7301' to provide the application
1046 layer a method of negotiating the application protocol version. This
1047 allows for negotiation of the application protocol during the TLS
1048 handshake, thus reducing round-trips. The application protocol is
1049 described by an opaque string. To enable, use the following functions.
1051 'INT *note gnutls_alpn_set_protocols:: (gnutls_session_t SESSION, const gnutls_datum_t * PROTOCOLS, unsigned PROTOCOLS_SIZE, unsigned int FLAGS)'
1052 'INT *note gnutls_alpn_get_selected_protocol:: (gnutls_session_t SESSION, gnutls_datum_t * PROTOCOL)'
1054 Note that these functions are intended to be used with protocols that
1055 are registered in the Application Layer Protocol Negotiation IANA
1056 registry. While you can use them for other protocols (at the risk of
1057 collisions), it is preferable to register them.
1060 File: gnutls.info, Node: Extensions and Supplemental Data, Prev: Application Layer Protocol Negotiation (ALPN), Up: TLS Extensions
1062 3.6.9 Extensions and Supplemental Data
1063 --------------------------------------
1065 It is possible to transfer supplemental data during the TLS handshake,
1066 following [_RFC4680_]. This is for "custom" protocol modifications for
1067 applications which may want to transfer additional data (e.g.
1068 additional authentication messages). Such an exchange requires a custom
1069 extension to be registered. The provided API for this functionality is
1070 low-level and described in *note TLS Extension Handling::.
1073 File: gnutls.info, Node: How to use TLS in application protocols, Next: On SSL 2 and older protocols, Prev: TLS Extensions, Up: Introduction to TLS
1075 3.7 How to use TLS in application protocols
1076 ===========================================
1078 This chapter is intended to provide some hints on how to use TLS over
1079 simple custom made application protocols. The discussion below mainly
1080 refers to the TCP/IP transport layer but may be extended to other ones
1086 * Upward negotiation::
1089 File: gnutls.info, Node: Separate ports, Next: Upward negotiation, Up: How to use TLS in application protocols
1091 3.7.1 Separate ports
1092 --------------------
1094 Traditionally SSL was used in application protocols by assigning a new
1095 port number for the secure services. By doing this two separate ports
1096 were assigned, one for the non-secure sessions, and one for the secure
1097 sessions. This method ensures that if a user requests a secure session
1098 then the client will attempt to connect to the secure port and fail
1099 otherwise. The only possible attack with this method is to perform a
1100 denial of service attack. The most famous example of this method is
1101 "HTTP over TLS" or HTTPS protocol [_RFC2818_].
1103 Despite its wide use, this method has several issues. This approach
1104 starts the TLS Handshake procedure just after the client connects on the
1105 --so called-- secure port. That way the TLS protocol does not know
1106 anything about the client, and popular methods like the host advertising
1107 in HTTP do not work(1). There is no way for the client to say "I
1108 connected to YYY server" before the Handshake starts, so the server
1109 cannot possibly know which certificate to use.
1111 Other than that it requires two separate ports to run a single service,
1112 which is unnecessary complication. Due to the fact that there is a
1113 limitation on the available privileged ports, this approach was soon
1114 deprecated in favor of upward negotiation.
1116 ---------- Footnotes ----------
1118 (1) See also the Server Name Indication extension on *note
1122 File: gnutls.info, Node: Upward negotiation, Prev: Separate ports, Up: How to use TLS in application protocols
1124 3.7.2 Upward negotiation
1125 ------------------------
1127 Other application protocols(1) use a different approach to enable the
1128 secure layer. They use something often called as the "TLS upgrade"
1129 method. This method is quite tricky but it is more flexible. The idea
1130 is to extend the application protocol to have a "STARTTLS" request,
1131 whose purpose it to start the TLS protocols just after the client
1132 requests it. This approach does not require any extra port to be
1133 reserved. There is even an extension to HTTP protocol to support this
1136 The tricky part, in this method, is that the "STARTTLS" request is sent
1137 in the clear, thus is vulnerable to modifications. A typical attack is
1138 to modify the messages in a way that the client is fooled and thinks
1139 that the server does not have the "STARTTLS" capability. See a typical
1140 conversation of a hypothetical protocol:
1142 (client connects to the server)
1144 CLIENT: HELLO I'M MR. XXX
1146 SERVER: NICE TO MEET YOU XXX
1148 CLIENT: PLEASE START TLS
1154 CLIENT: HERE ARE SOME CONFIDENTIAL DATA
1156 And an example of a conversation where someone is acting in between:
1158 (client connects to the server)
1160 CLIENT: HELLO I'M MR. XXX
1162 SERVER: NICE TO MEET YOU XXX
1164 CLIENT: PLEASE START TLS
1166 (here someone inserts this message)
1168 SERVER: SORRY I DON'T HAVE THIS CAPABILITY
1170 CLIENT: HERE ARE SOME CONFIDENTIAL DATA
1172 As you can see above the client was fooled, and was nai"ve enough to
1173 send the confidential data in the clear, despite the server telling the
1174 client that it does not support "STARTTLS".
1176 How do we avoid the above attack? As you may have already noticed this
1177 situation is easy to avoid. The client has to ask the user before it
1178 connects whether the user requests TLS or not. If the user answered
1179 that he certainly wants the secure layer the last conversation should
1182 (client connects to the server)
1184 CLIENT: HELLO I'M MR. XXX
1186 SERVER: NICE TO MEET YOU XXX
1188 CLIENT: PLEASE START TLS
1190 (here someone inserts this message)
1192 SERVER: SORRY I DON'T HAVE THIS CAPABILITY
1196 (the client notifies the user that the secure connection was not
1199 This method, if implemented properly, is far better than the traditional
1200 method, and the security properties remain the same, since only denial
1201 of service is possible. The benefit is that the server may request
1202 additional data before the TLS Handshake protocol starts, in order to
1203 send the correct certificate, use the correct password file, or anything
1206 ---------- Footnotes ----------
1208 (1) See LDAP, IMAP etc.
1211 File: gnutls.info, Node: On SSL 2 and older protocols, Prev: How to use TLS in application protocols, Up: Introduction to TLS
1213 3.8 On SSL 2 and older protocols
1214 ================================
1216 One of the initial decisions in the GnuTLS development was to implement
1217 the known security protocols for the transport layer. Initially TLS 1.0
1218 was implemented since it was the latest at that time, and was considered
1219 to be the most advanced in security properties. Later the SSL 3.0
1220 protocol was implemented since it is still the only protocol supported
1221 by several servers and there are no serious security vulnerabilities
1224 One question that may arise is why we didn't implement SSL 2.0 in the
1225 library. There are several reasons, most important being that it has
1226 serious security flaws, unacceptable for a modern security library.
1227 Other than that, this protocol is barely used by anyone these days since
1228 it has been deprecated since 1996. The security problems in SSL 2.0
1231 * Message integrity compromised. The SSLv2 message authentication
1232 uses the MD5 function, and is insecure.
1234 * Man-in-the-middle attack. There is no protection of the handshake
1235 in SSLv2, which permits a man-in-the-middle attack.
1237 * Truncation attack. SSLv2 relies on TCP FIN to close the session,
1238 so the attacker can forge a TCP FIN, and the peer cannot tell if it
1239 was a legitimate end of data or not.
1241 * Weak message integrity for export ciphers. The cryptographic keys
1242 in SSLv2 are used for both message authentication and encryption,
1243 so if weak encryption schemes are negotiated (say 40-bit keys) the
1244 message authentication code uses the same weak key, which isn't
1247 Other protocols such as Microsoft's PCT 1 and PCT 2 were not implemented
1248 because they were also abandoned and deprecated by SSL 3.0 and later TLS
1252 File: gnutls.info, Node: Authentication methods, Next: Hardware security modules and abstract key types, Prev: Introduction to TLS, Up: Top
1254 4 Authentication methods
1255 ************************
1257 The initial key exchange of the TLS protocol performs authentication of
1258 the peers. In typical scenarios the server is authenticated to the
1259 client, and optionally the client to the server.
1261 While many associate TLS with X.509 certificates and public key
1262 authentication, the protocol supports various authentication methods,
1263 including pre-shared keys, and passwords. In this chapter a description
1264 of the existing authentication methods is provided, as well as some
1265 guidance on which use-cases each method can be used at.
1269 * Certificate authentication::
1270 * More on certificate authentication::
1271 * Shared-key and anonymous authentication::
1272 * Selecting an appropriate authentication method::
1275 File: gnutls.info, Node: Certificate authentication, Next: More on certificate authentication, Up: Authentication methods
1277 4.1 Certificate authentication
1278 ==============================
1280 The most known authentication method of TLS are certificates. The PKIX
1281 [_PKIX_] public key infrastructure is daily used by anyone using a
1282 browser today. GnuTLS supports both X.509 certificates [_PKIX_] and
1283 OpenPGP certificates using a common API.
1285 The key exchange algorithms supported by certificate authentication are
1286 shown in *note Table 4.1: tab:key-exchange.
1288 Key exchange Description
1290 ------------------------------------------------------------------
1291 RSA The RSA algorithm is used to encrypt a key and
1292 send it to the peer. The certificate must allow
1293 the key to be used for encryption.
1295 DHE_RSA The RSA algorithm is used to sign ephemeral
1296 Diffie-Hellman parameters which are sent to the
1297 peer. The key in the certificate must allow the
1298 key to be used for signing. Note that key
1299 exchange algorithms which use ephemeral
1300 Diffie-Hellman parameters, offer perfect forward
1301 secrecy. That means that even if the private
1302 key used for signing is compromised, it cannot
1303 be used to reveal past session data.
1305 ECDHE_RSA The RSA algorithm is used to sign ephemeral
1306 elliptic curve Diffie-Hellman parameters which
1307 are sent to the peer. The key in the
1308 certificate must allow the key to be used for
1309 signing. It also offers perfect forward
1310 secrecy. That means that even if the private
1311 key used for signing is compromised, it cannot
1312 be used to reveal past session data.
1314 DHE_DSS The DSA algorithm is used to sign ephemeral
1315 Diffie-Hellman parameters which are sent to the
1316 peer. The certificate must contain DSA
1317 parameters to use this key exchange algorithm.
1318 DSA is the algorithm of the Digital Signature
1321 ECDHE_ECDSA The Elliptic curve DSA algorithm is used to sign
1322 ephemeral elliptic curve Diffie-Hellman
1323 parameters which are sent to the peer. The
1324 certificate must contain ECDSA parameters (i.e.,
1325 EC and marked for signing) to use this key
1329 Table 4.1: Supported key exchange algorithms.
1333 * X.509 certificates::
1334 * OpenPGP certificates::
1335 * Advanced certificate verification::
1336 * Digital signatures::
1339 File: gnutls.info, Node: X.509 certificates, Next: OpenPGP certificates, Up: Certificate authentication
1341 4.1.1 X.509 certificates
1342 ------------------------
1344 The X.509 protocols rely on a hierarchical trust model. In this trust
1345 model Certification Authorities (CAs) are used to certify entities.
1346 Usually more than one certification authorities exist, and certification
1347 authorities may certify other authorities to issue certificates as well,
1348 following a hierarchical model.
1350 \0\b[image src="gnutls-x509.png"
\0\b]
1352 Figure 4.1: An example of the X.509 hierarchical trust model.
1354 One needs to trust one or more CAs for his secure communications. In
1355 that case only the certificates issued by the trusted authorities are
1356 acceptable. The framework is illustrated on *note Figure 4.1: fig-x509.
1360 * X.509 certificate structure::
1361 * Importing an X.509 certificate::
1362 * X.509 certificate names::
1363 * X.509 distinguished names::
1364 * X.509 extensions::
1365 * X.509 public and private keys::
1366 * Verifying X.509 certificate paths::
1367 * Verifying a certificate in the context of TLS session::
1368 * Verification using PKCS11::
1371 File: gnutls.info, Node: X.509 certificate structure, Next: Importing an X.509 certificate, Up: X.509 certificates
1373 4.1.1.1 X.509 certificate structure
1374 ...................................
1376 An X.509 certificate usually contains information about the certificate
1377 holder, the signer, a unique serial number, expiration dates and some
1378 other fields [_PKIX_] as shown in *note Table 4.2: tab:x509.
1382 ------------------------------------------------------------------
1383 version The field that indicates the version of the
1386 serialNumber This field holds a unique serial number per
1389 signature The issuing authority's signature.
1391 issuer Holds the issuer's distinguished name.
1393 validity The activation and expiration dates.
1395 subject The subject's distinguished name of the
1398 extensions The extensions are fields only present in
1399 version 3 certificates.
1402 Table 4.2: X.509 certificate fields.
1404 The certificate's _subject or issuer name_ is not just a single string.
1405 It is a Distinguished name and in the ASN.1 notation is a sequence of
1406 several object identifiers with their corresponding values. Some of
1407 available OIDs to be used in an X.509 distinguished name are defined in
1410 The _Version_ field in a certificate has values either 1 or 3 for
1411 version 3 certificates. Version 1 certificates do not support the
1412 extensions field so it is not possible to distinguish a CA from a
1413 person, thus their usage should be avoided.
1415 The _validity_ dates are there to indicate the date that the specific
1416 certificate was activated and the date the certificate's key would be
1419 In GnuTLS the X.509 certificate structures are handled using the
1420 'gnutls_x509_crt_t' type and the corresponding private keys with the
1421 'gnutls_x509_privkey_t' type. All the available functions for X.509
1422 certificate handling have their prototypes in 'gnutls/x509.h'. An
1423 example program to demonstrate the X.509 parsing capabilities can be
1424 found in *note ex-x509-info::.
1427 File: gnutls.info, Node: Importing an X.509 certificate, Next: X.509 certificate names, Prev: X.509 certificate structure, Up: X.509 certificates
1429 4.1.1.2 Importing an X.509 certificate
1430 ......................................
1432 The certificate structure should be initialized using *note
1433 gnutls_x509_crt_init::, and a certificate structure can be imported
1434 using *note gnutls_x509_crt_import::.
1436 'INT *note gnutls_x509_crt_init:: (gnutls_x509_crt_t * CERT)'
1437 'INT *note gnutls_x509_crt_import:: (gnutls_x509_crt_t CERT, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)'
1438 'VOID *note gnutls_x509_crt_deinit:: (gnutls_x509_crt_t CERT)'
1440 In several functions an array of certificates is required. To assist in
1441 initialization and import the following two functions are provided.
1443 'INT *note gnutls_x509_crt_list_import:: (gnutls_x509_crt_t * CERTS, unsigned int * CERT_MAX, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)'
1444 'INT *note gnutls_x509_crt_list_import2:: (gnutls_x509_crt_t ** CERTS, unsigned int * SIZE, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)'
1446 In all cases after use a certificate must be deinitialized using *note
1447 gnutls_x509_crt_deinit::. Note that although the functions above apply
1448 to 'gnutls_x509_crt_t' structure, similar functions exist for the CRL
1449 structure 'gnutls_x509_crl_t'.
1452 File: gnutls.info, Node: X.509 certificate names, Next: X.509 distinguished names, Prev: Importing an X.509 certificate, Up: X.509 certificates
1454 4.1.1.3 X.509 certificate names
1455 ...............................
1457 X.509 certificates allow for multiple names and types of names to be
1458 specified. CA certificates often rely on X.509 distinguished names (see
1459 *note X.509 distinguished names::) for unique identification, while
1460 end-user and server certificates rely on the 'subject alternative
1461 names'. The subject alternative names provide a typed name, e.g., a DNS
1462 name, or an email address, which identifies the owner of the
1463 certificate. The following functions provide access to that names.
1465 'INT *note gnutls_x509_crt_get_subject_alt_name2:: (gnutls_x509_crt_t CERT, unsigned int SEQ, void * SAN, size_t * SAN_SIZE, unsigned int * SAN_TYPE, unsigned int * CRITICAL)'
1466 'INT *note gnutls_x509_crt_set_subject_alt_name:: (gnutls_x509_crt_t CRT, gnutls_x509_subject_alt_name_t TYPE, const void * DATA, unsigned int DATA_SIZE, unsigned int FLAGS)'
1467 'INT *note gnutls_subject_alt_names_init:: (gnutls_subject_alt_names_t * SANS)'
1468 'INT *note gnutls_subject_alt_names_get:: (gnutls_subject_alt_names_t SANS, unsigned int SEQ, unsigned int * SAN_TYPE, gnutls_datum_t * SAN, gnutls_datum_t * OTHERNAME_OID)'
1469 'INT *note gnutls_subject_alt_names_set:: (gnutls_subject_alt_names_t SANS, unsigned int SAN_TYPE, const gnutls_datum_t * SAN, const char * OTHERNAME_OID)'
1471 Note however, that server certificates often used the Common Name (CN),
1472 part of the certificate DistinguishedName to place a single DNS address.
1473 That practice is discouraged (see [_RFC6125_]), because only a single
1474 address can be specified, and the CN field is free-form making matching
1478 File: gnutls.info, Node: X.509 distinguished names, Next: X.509 extensions, Prev: X.509 certificate names, Up: X.509 certificates
1480 4.1.1.4 X.509 distinguished names
1481 .................................
1483 The "subject" of an X.509 certificate is not described by a single name,
1484 but rather with a distinguished name. This in X.509 terminology is a
1485 list of strings each associated an object identifier. To make things
1486 simple GnuTLS provides *note gnutls_x509_crt_get_dn2:: which follows the
1487 rules in [_RFC4514_] and returns a single string. Access to each string
1488 by individual object identifiers can be accessed using *note
1489 gnutls_x509_crt_get_dn_by_oid::.
1491 -- Function: int gnutls_x509_crt_get_dn2 (gnutls_x509_crt_t CERT,
1492 gnutls_datum_t * DN)
1493 CERT: should contain a 'gnutls_x509_crt_t' type
1495 DN: a pointer to a structure to hold the name
1497 This function will allocate buffer and copy the name of the
1498 Certificate. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz"
1499 as described in RFC4514. The output string will be ASCII or UTF-8
1500 encoded, depending on the certificate data.
1502 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1503 otherwise a negative error value.
1506 'INT *note gnutls_x509_crt_get_dn:: (gnutls_x509_crt_t CERT, char * BUF, size_t * BUF_SIZE)'
1507 'INT *note gnutls_x509_crt_get_dn_by_oid:: (gnutls_x509_crt_t CERT, const char * OID, int INDX, unsigned int RAW_FLAG, void * BUF, size_t * BUF_SIZE)'
1508 'INT *note gnutls_x509_crt_get_dn_oid:: (gnutls_x509_crt_t CERT, int INDX, void * OID, size_t * OID_SIZE)'
1510 Similar functions exist to access the distinguished name of the issuer
1513 'INT *note gnutls_x509_crt_get_issuer_dn:: (gnutls_x509_crt_t CERT, char * BUF, size_t * BUF_SIZE)'
1514 'INT *note gnutls_x509_crt_get_issuer_dn2:: (gnutls_x509_crt_t CERT, gnutls_datum_t * DN)'
1515 'INT *note gnutls_x509_crt_get_issuer_dn_by_oid:: (gnutls_x509_crt_t CERT, const char * OID, int INDX, unsigned int RAW_FLAG, void * BUF, size_t * BUF_SIZE)'
1516 'INT *note gnutls_x509_crt_get_issuer_dn_oid:: (gnutls_x509_crt_t CERT, int INDX, void * OID, size_t * OID_SIZE)'
1517 'INT *note gnutls_x509_crt_get_issuer:: (gnutls_x509_crt_t CERT, gnutls_x509_dn_t * DN)'
1519 The more powerful *note gnutls_x509_crt_get_subject:: and *note
1520 gnutls_x509_dn_get_rdn_ava:: provide efficient but low-level access to
1521 the contents of the distinguished name structure.
1523 'INT *note gnutls_x509_crt_get_subject:: (gnutls_x509_crt_t CERT, gnutls_x509_dn_t * DN)'
1524 'INT *note gnutls_x509_crt_get_issuer:: (gnutls_x509_crt_t CERT, gnutls_x509_dn_t * DN)'
1526 -- Function: int gnutls_x509_dn_get_rdn_ava (gnutls_x509_dn_t DN, int
1527 IRDN, int IAVA, gnutls_x509_ava_st * AVA)
1534 AVA: Pointer to structure which will hold output information.
1536 Get pointers to data within the DN. The format of the 'ava'
1537 structure is shown below.
1539 struct gnutls_x509_ava_st { gnutls_datum_t oid; gnutls_datum_t
1540 value; unsigned long value_tag; };
1542 The X.509 distinguished name is a sequence of sequences of strings
1543 and this is what the 'irdn' and 'iava' indexes model.
1545 Note that 'ava' will contain pointers into the 'dn' structure which
1546 in turns points to the original certificate. Thus you should not
1547 modify any data or deallocate any of those.
1549 This is a low-level function that requires the caller to do the
1550 value conversions when necessary (e.g. from UCS-2).
1552 *Returns:* Returns 0 on success, or an error code.
1555 File: gnutls.info, Node: X.509 extensions, Next: X.509 public and private keys, Prev: X.509 distinguished names, Up: X.509 certificates
1557 4.1.1.5 X.509 extensions
1558 ........................
1560 X.509 version 3 certificates include a list of extensions that can be
1561 used to obtain additional information on the subject or the issuer of
1562 the certificate. Those may be e-mail addresses, flags that indicate
1563 whether the belongs to a CA etc. All the supported X.509 version 3
1564 extensions are shown in *note Table 4.3: tab:x509-ext.
1566 The certificate extensions access is split into two parts. The first
1567 requires to retrieve the extension, and the second is the parsing part.
1569 To enumerate and retrieve the DER-encoded extension data available in a
1570 certificate the following two functions are available.
1571 'INT *note gnutls_x509_crt_get_extension_info:: (gnutls_x509_crt_t CERT, int INDX, void * OID, size_t * OID_SIZE, unsigned int * CRITICAL)'
1572 'INT *note gnutls_x509_crt_get_extension_data2:: (gnutls_x509_crt_t CERT, unsigned INDX, gnutls_datum_t * DATA)'
1573 'INT *note gnutls_x509_crt_get_extension_by_oid2:: (gnutls_x509_crt_t CERT, const char * OID, int INDX, gnutls_datum_t * OUTPUT, unsigned int * CRITICAL)'
1575 After a supported DER-encoded extension is retrieved it can be parsed
1576 using the APIs in 'x509-ext.h'. Complex extensions may require
1577 initializing an intermediate structure that holds the parsed extension
1578 data. Examples of simple parsing functions are shown below.
1579 'INT *note gnutls_x509_ext_import_basic_constraints:: (const gnutls_datum_t * EXT, unsigned int * CA, int * PATHLEN)'
1580 'INT *note gnutls_x509_ext_export_basic_constraints:: (unsigned int CA, int PATHLEN, gnutls_datum_t * EXT)'
1581 'INT *note gnutls_x509_ext_import_key_usage:: (const gnutls_datum_t * EXT, unsigned int * KEY_USAGE)'
1582 'INT *note gnutls_x509_ext_export_key_usage:: (unsigned int USAGE, gnutls_datum_t * EXT)'
1584 More complex extensions, such as Name Constraints, require an
1585 intermediate structure, in that case 'gnutls_x509_name_constraints_t' to
1586 be initialized in order to store the parsed extension data.
1587 'INT *note gnutls_x509_ext_import_name_constraints:: (const gnutls_datum_t * EXT, gnutls_x509_name_constraints_t NC, unsigned int FLAGS)'
1588 'INT *note gnutls_x509_ext_export_name_constraints:: (gnutls_x509_name_constraints_t NC, gnutls_datum_t * EXT)'
1590 After the name constraints are extracted in the structure, the following
1591 functions can be used to access them.
1593 'INT *note gnutls_x509_name_constraints_get_permitted:: (gnutls_x509_name_constraints_t NC, unsigned IDX, unsigned * TYPE, gnutls_datum_t * NAME)'
1594 'INT *note gnutls_x509_name_constraints_get_excluded:: (gnutls_x509_name_constraints_t NC, unsigned IDX, unsigned * TYPE, gnutls_datum_t * NAME)'
1595 'INT *note gnutls_x509_name_constraints_add_permitted:: (gnutls_x509_name_constraints_t NC, gnutls_x509_subject_alt_name_t TYPE, const gnutls_datum_t * NAME)'
1596 'INT *note gnutls_x509_name_constraints_add_excluded:: (gnutls_x509_name_constraints_t NC, gnutls_x509_subject_alt_name_t TYPE, const gnutls_datum_t * NAME)'
1597 'UNSIGNED *note gnutls_x509_name_constraints_check:: (gnutls_x509_name_constraints_t NC, gnutls_x509_subject_alt_name_t TYPE, const gnutls_datum_t * NAME)'
1598 'UNSIGNED *note gnutls_x509_name_constraints_check_crt:: (gnutls_x509_name_constraints_t NC, gnutls_x509_subject_alt_name_t TYPE, gnutls_x509_crt_t CERT)'
1600 Other utility functions are listed below.
1601 'INT *note gnutls_x509_name_constraints_init:: (gnutls_x509_name_constraints_t * NC)'
1602 'VOID *note gnutls_x509_name_constraints_deinit:: (gnutls_x509_name_constraints_t NC)'
1604 Similar functions exist for all of the other supported extensions,
1605 listed in *note Table 4.3: tab:x509-ext.
1607 Extension OID Description
1609 --------------------------------------------------------------------
1610 Subject key id 2.5.29.14 An identifier of the key of
1613 Key usage 2.5.29.15 Constraints the key's usage
1616 Private key usage 2.5.29.16 Constraints the validity
1617 period time of the private key.
1619 Subject alternative 2.5.29.17 Alternative names to
1620 name subject's distinguished
1623 Issuer alternative 2.5.29.18 Alternative names to the
1624 name issuer's distinguished
1627 Basic constraints 2.5.29.19 Indicates whether this is a
1628 CA certificate or not, and
1629 specify the maximum path
1630 lengths of certificate
1633 Name constraints 2.5.29.30 A field in CA certificates
1634 that restricts the scope of
1638 CRL distribution 2.5.29.31 This extension is set by
1639 points the CA, in order to inform
1640 about the issued CRLs.
1642 Certificate policy 2.5.29.32 This extension is set to
1643 indicate the certificate
1644 policy as object identifier
1646 descriptive string or URL.
1648 Authority key 2.5.29.35 An identifier of the key of
1649 identifier the issuer of the
1650 certificate. That is used
1651 to distinguish between
1652 different keys of the same
1655 Extended key usage 2.5.29.37 Constraints the purpose of
1658 Authority 1.3.6.1.5.5.7.1.1Information on services by
1659 information access the issuer of the
1662 Proxy Certification 1.3.6.1.5.5.7.1.14Proxy Certificates includes
1663 Information this extension that
1664 contains the OID of the
1665 proxy policy language used,
1666 and can specify limits on
1667 the maximum lengths of
1669 Certificates are specified
1673 Table 4.3: Supported X.509 certificate extensions.
1675 Note, that there are also direct APIs to access extensions that may be
1676 simpler to use for non-complex extensions. They are available in
1677 'x509.h' and some examples are listed below.
1678 'INT *note gnutls_x509_crt_get_basic_constraints:: (gnutls_x509_crt_t CERT, unsigned int * CRITICAL, unsigned int * CA, int * PATHLEN)'
1679 'INT *note gnutls_x509_crt_set_basic_constraints:: (gnutls_x509_crt_t CRT, unsigned int CA, int PATHLENCONSTRAINT)'
1680 'INT *note gnutls_x509_crt_get_key_usage:: (gnutls_x509_crt_t CERT, unsigned int * KEY_USAGE, unsigned int * CRITICAL)'
1681 'INT *note gnutls_x509_crt_set_key_usage:: (gnutls_x509_crt_t CRT, unsigned int USAGE)'
1684 File: gnutls.info, Node: X.509 public and private keys, Next: Verifying X.509 certificate paths, Prev: X.509 extensions, Up: X.509 certificates
1686 4.1.1.6 Accessing public and private keys
1687 .........................................
1689 Each X.509 certificate contains a public key that corresponds to a
1690 private key. To get a unique identifier of the public key the *note
1691 gnutls_x509_crt_get_key_id:: function is provided. To export the public
1692 key or its parameters you may need to convert the X.509 structure to a
1693 'gnutls_pubkey_t'. See *note Abstract public keys:: for more
1696 -- Function: int gnutls_x509_crt_get_key_id (gnutls_x509_crt_t CRT,
1697 unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t *
1699 CRT: Holds the certificate
1701 FLAGS: should be one of the flags from 'gnutls_keyid_flags_t'
1703 OUTPUT_DATA: will contain the key ID
1705 OUTPUT_DATA_SIZE: holds the size of output_data (and will be
1706 replaced by the actual size of parameters)
1708 This function will return a unique ID that depends on the public
1709 key parameters. This ID can be used in checking whether a
1710 certificate corresponds to the given private key.
1712 If the buffer provided is not long enough to hold the output, then
1713 *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
1714 be returned. The output will normally be a SHA-1 hash output,
1717 *Returns:* In case of failure a negative error code will be
1718 returned, and 0 on success.
1720 The private key parameters may be directly accessed by using one of the
1721 following functions.
1723 'INT *note gnutls_x509_privkey_get_pk_algorithm2:: (gnutls_x509_privkey_t KEY, unsigned int * BITS)'
1724 'INT *note gnutls_x509_privkey_export_rsa_raw2:: (gnutls_x509_privkey_t KEY, gnutls_datum_t * M, gnutls_datum_t * E, gnutls_datum_t * D, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * U, gnutls_datum_t * E1, gnutls_datum_t * E2)'
1725 'INT *note gnutls_x509_privkey_export_ecc_raw:: (gnutls_x509_privkey_t KEY, gnutls_ecc_curve_t * CURVE, gnutls_datum_t * X, gnutls_datum_t * Y, gnutls_datum_t * K)'
1726 'INT *note gnutls_x509_privkey_export_dsa_raw:: (gnutls_x509_privkey_t KEY, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y, gnutls_datum_t * X)'
1727 'INT *note gnutls_x509_privkey_get_key_id:: (gnutls_x509_privkey_t KEY, unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE)'
1730 File: gnutls.info, Node: Verifying X.509 certificate paths, Next: Verifying a certificate in the context of TLS session, Prev: X.509 public and private keys, Up: X.509 certificates
1732 4.1.1.7 Verifying X.509 certificate paths
1733 .........................................
1735 Verifying certificate paths is important in X.509 authentication. For
1736 this purpose the following functions are provided.
1738 -- Function: int gnutls_x509_trust_list_add_cas
1739 (gnutls_x509_trust_list_t LIST, const gnutls_x509_crt_t *
1740 CLIST, unsigned CLIST_SIZE, unsigned int FLAGS)
1743 CLIST: A list of CAs
1745 CLIST_SIZE: The length of the CA list
1747 FLAGS: should be 0 or an or'ed sequence of 'GNUTLS_TL' options.
1749 This function will add the given certificate authorities to the
1750 trusted list. The list of CAs must not be deinitialized during
1751 this structure's lifetime.
1753 If the flag 'GNUTLS_TL_NO_DUPLICATES' is specified, then the
1754 provided 'clist' entries that are duplicates will not be added to
1755 the list and will be deinitialized.
1757 *Returns:* The number of added elements is returned.
1761 -- Function: int gnutls_x509_trust_list_add_named_crt
1762 (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t CERT, const
1763 void * NAME, size_t NAME_SIZE, unsigned int FLAGS)
1768 NAME: An identifier for the certificate
1770 NAME_SIZE: The size of the identifier
1774 This function will add the given certificate to the trusted list
1775 and associate it with a name. The certificate will not be be used
1776 for verification with 'gnutls_x509_trust_list_verify_crt()' but
1777 with 'gnutls_x509_trust_list_verify_named_crt()' or
1778 'gnutls_x509_trust_list_verify_crt2()' - the latter only since
1779 GnuTLS 3.4.0 and if a hostname is provided.
1781 In principle this function can be used to set individual "server"
1782 certificates that are trusted by the user for that specific server
1783 but for no other purposes.
1785 The certificate must not be deinitialized during the lifetime of
1788 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1789 otherwise a negative error value.
1793 -- Function: int gnutls_x509_trust_list_add_crls
1794 (gnutls_x509_trust_list_t LIST, const gnutls_x509_crl_t *
1795 CRL_LIST, int CRL_SIZE, unsigned int FLAGS, unsigned int
1799 CRL_LIST: A list of CRLs
1801 CRL_SIZE: The length of the CRL list
1803 FLAGS: if GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified
1806 VERIFICATION_FLAGS: gnutls_certificate_verify_flags if flags
1807 specifies GNUTLS_TL_VERIFY_CRL
1809 This function will add the given certificate revocation lists to
1810 the trusted list. The list of CRLs must not be deinitialized
1811 during this structure's lifetime.
1813 This function must be called after
1814 'gnutls_x509_trust_list_add_cas()' to allow verifying the CRLs for
1815 validity. If the flag 'GNUTLS_TL_NO_DUPLICATES' is given, then any
1816 provided CRLs that are a duplicate, will be deinitialized and not
1817 added to the list (that assumes that
1818 'gnutls_x509_trust_list_deinit()' will be called with all=1).
1820 *Returns:* The number of added elements is returned.
1824 -- Function: int gnutls_x509_trust_list_verify_crt
1825 (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t * CERT_LIST,
1826 unsigned int CERT_LIST_SIZE, unsigned int FLAGS, unsigned int
1827 * VOUTPUT, gnutls_verify_output_function FUNC)
1830 CERT_LIST: is the certificate list to be verified
1832 CERT_LIST_SIZE: is the certificate list size
1834 FLAGS: Flags that may be used to change the verification algorithm.
1835 Use OR of the gnutls_certificate_verify_flags enumerations.
1837 VOUTPUT: will hold the certificate verification output.
1839 FUNC: If non-null will be called on each chain element verification
1842 This function will try to verify the given certificate and return
1843 its status. The 'voutput' parameter will hold an OR'ed sequence of
1844 'gnutls_certificate_status_t' flags.
1846 The details of the verification are the same as in
1847 'gnutls_x509_trust_list_verify_crt2()' .
1849 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1850 otherwise a negative error value.
1854 -- Function: int gnutls_x509_trust_list_verify_crt2
1855 (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t * CERT_LIST,
1856 unsigned int CERT_LIST_SIZE, gnutls_typed_vdata_st * DATA,
1857 unsigned int ELEMENTS, unsigned int FLAGS, unsigned int *
1858 VOUTPUT, gnutls_verify_output_function FUNC)
1861 CERT_LIST: is the certificate list to be verified
1863 CERT_LIST_SIZE: is the certificate list size
1865 DATA: an array of typed data
1867 ELEMENTS: the number of data elements
1869 FLAGS: Flags that may be used to change the verification algorithm.
1870 Use OR of the gnutls_certificate_verify_flags enumerations.
1872 VOUTPUT: will hold the certificate verification output.
1874 FUNC: If non-null will be called on each chain element verification
1877 This function will attempt to verify the given certificate and
1878 return its status. The 'voutput' parameter will hold an OR'ed
1879 sequence of 'gnutls_certificate_status_t' flags. When a chain of
1880 'cert_list_size' with more than one certificates is provided, the
1881 verification status will apply to the first certificate in the
1882 chain that failed verification. The verification process starts
1883 from the end of the chain (from CA to end certificate).
1885 Additionally a certificate verification profile can be specified
1886 from the ones in 'gnutls_certificate_verification_profiles_t' by
1887 ORing the result of 'GNUTLS_PROFILE_TO_VFLAGS()' to the
1890 The acceptable 'data' types are 'GNUTLS_DT_DNS_HOSTNAME' and
1891 'GNUTLS_DT_KEY_PURPOSE_OID' . The former accepts as data a
1892 null-terminated hostname, and the latter a null-terminated object
1893 identifier (e.g., 'GNUTLS_KP_TLS_WWW_SERVER' ). If a DNS hostname
1894 is provided then this function will compare the hostname in the
1895 certificate against the given. If names do not match the
1896 'GNUTLS_CERT_UNEXPECTED_OWNER' status flag will be set. In
1897 addition it will consider certificates provided with
1898 'gnutls_x509_trust_list_add_named_crt()' .
1900 If a key purpose OID is provided and the end-certificate contains
1901 the extended key usage PKIX extension, it will be required to match
1902 the provided OID or be marked for any purpose, otherwise
1903 verification will fail with 'GNUTLS_CERT_PURPOSE_MISMATCH' status.
1905 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1906 otherwise a negative error value. Note that verification failure
1907 will not result to an error code, only 'voutput' will be updated.
1911 -- Function: int gnutls_x509_trust_list_verify_named_crt
1912 (gnutls_x509_trust_list_t LIST, gnutls_x509_crt_t CERT, const
1913 void * NAME, size_t NAME_SIZE, unsigned int FLAGS, unsigned
1914 int * VOUTPUT, gnutls_verify_output_function FUNC)
1917 CERT: is the certificate to be verified
1919 NAME: is the certificate's name
1921 NAME_SIZE: is the certificate's name size
1923 FLAGS: Flags that may be used to change the verification algorithm.
1924 Use OR of the gnutls_certificate_verify_flags enumerations.
1926 VOUTPUT: will hold the certificate verification output.
1928 FUNC: If non-null will be called on each chain element verification
1931 This function will try to find a certificate that is associated
1932 with the provided name -see
1933 'gnutls_x509_trust_list_add_named_crt()' . If a match is found the
1934 certificate is considered valid. In addition to that this function
1935 will also check CRLs. The 'voutput' parameter will hold an OR'ed
1936 sequence of 'gnutls_certificate_status_t' flags.
1938 Additionally a certificate verification profile can be specified
1939 from the ones in 'gnutls_certificate_verification_profiles_t' by
1940 ORing the result of 'GNUTLS_PROFILE_TO_VFLAGS()' to the
1943 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
1944 otherwise a negative error value.
1948 -- Function: int gnutls_x509_trust_list_add_trust_file
1949 (gnutls_x509_trust_list_t LIST, const char * CA_FILE, const
1950 char * CRL_FILE, gnutls_x509_crt_fmt_t TYPE, unsigned int
1951 TL_FLAGS, unsigned int TL_VFLAGS)
1954 CA_FILE: A file containing a list of CAs (optional)
1956 CRL_FILE: A file containing a list of CRLs (optional)
1958 TYPE: The format of the certificates
1960 TL_FLAGS: GNUTLS_TL_*
1962 TL_VFLAGS: gnutls_certificate_verify_flags if flags specifies
1963 GNUTLS_TL_VERIFY_CRL
1965 This function will add the given certificate authorities to the
1966 trusted list. PKCS '11' URLs are also accepted, instead of files,
1967 by this function. A PKCS '11' URL implies a trust database (a
1968 specially marked module in p11-kit); the URL "pkcs11:" implies all
1969 trust databases in the system. Only a single URL specifying trust
1970 databases can be set; they cannot be stacked with multiple calls.
1972 *Returns:* The number of added elements is returned.
1976 -- Function: int gnutls_x509_trust_list_add_trust_mem
1977 (gnutls_x509_trust_list_t LIST, const gnutls_datum_t * CAS,
1978 const gnutls_datum_t * CRLS, gnutls_x509_crt_fmt_t TYPE,
1979 unsigned int TL_FLAGS, unsigned int TL_VFLAGS)
1982 CAS: A buffer containing a list of CAs (optional)
1984 CRLS: A buffer containing a list of CRLs (optional)
1986 TYPE: The format of the certificates
1988 TL_FLAGS: GNUTLS_TL_*
1990 TL_VFLAGS: gnutls_certificate_verify_flags if flags specifies
1991 GNUTLS_TL_VERIFY_CRL
1993 This function will add the given certificate authorities to the
1996 *Returns:* The number of added elements is returned.
2000 -- Function: int gnutls_x509_trust_list_add_system_trust
2001 (gnutls_x509_trust_list_t LIST, unsigned int TL_FLAGS,
2002 unsigned int TL_VFLAGS)
2003 LIST: The structure of the list
2005 TL_FLAGS: GNUTLS_TL_*
2007 TL_VFLAGS: gnutls_certificate_verify_flags if flags specifies
2008 GNUTLS_TL_VERIFY_CRL
2010 This function adds the system's default trusted certificate
2011 authorities to the trusted list. Note that on unsupported systems
2012 this function returns 'GNUTLS_E_UNIMPLEMENTED_FEATURE' .
2014 This function implies the flag 'GNUTLS_TL_NO_DUPLICATES' .
2016 *Returns:* The number of added elements or a negative error code on
2021 The verification function will verify a given certificate chain against
2022 a list of certificate authorities and certificate revocation lists, and
2023 output a bit-wise OR of elements of the 'gnutls_certificate_status_t'
2024 enumeration shown in *note Figure 4.2: gnutls_certificate_status_t. The
2025 'GNUTLS_CERT_INVALID' flag is always set on a verification error and
2026 more detailed flags will also be set when appropriate.
2028 'GNUTLS_CERT_INVALID'
2029 The certificate is not signed by one of the known authorities or
2030 the signature is invalid (deprecated by the flags
2031 'GNUTLS_CERT_SIGNATURE_FAILURE' and 'GNUTLS_CERT_SIGNER_NOT_FOUND'
2033 'GNUTLS_CERT_REVOKED'
2034 Certificate is revoked by its authority. In X.509 this will be set
2035 only if CRLs are checked.
2036 'GNUTLS_CERT_SIGNER_NOT_FOUND'
2037 The certificate's issuer is not known. This is the case if the
2038 issuer is not included in the trusted certificate list.
2039 'GNUTLS_CERT_SIGNER_NOT_CA'
2040 The certificate's signer was not a CA. This may happen if this was
2041 a version 1 certificate, which is common with some CAs, or a
2042 version 3 certificate without the basic constrains extension.
2043 'GNUTLS_CERT_INSECURE_ALGORITHM'
2044 The certificate was signed using an insecure algorithm such as MD2
2045 or MD5. These algorithms have been broken and should not be
2047 'GNUTLS_CERT_NOT_ACTIVATED'
2048 The certificate is not yet activated.
2049 'GNUTLS_CERT_EXPIRED'
2050 The certificate has expired.
2051 'GNUTLS_CERT_SIGNATURE_FAILURE'
2052 The signature verification failed.
2053 'GNUTLS_CERT_REVOCATION_DATA_SUPERSEDED'
2054 The revocation data are old and have been superseded.
2055 'GNUTLS_CERT_UNEXPECTED_OWNER'
2056 The owner is not the expected one.
2057 'GNUTLS_CERT_REVOCATION_DATA_ISSUED_IN_FUTURE'
2058 The revocation data have a future issue date.
2059 'GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE'
2060 The certificate's signer constraints were violated.
2061 'GNUTLS_CERT_MISMATCH'
2062 The certificate presented isn't the expected one (TOFU)
2063 'GNUTLS_CERT_PURPOSE_MISMATCH'
2064 The certificate or an intermediate does not match the intended
2065 purpose (extended key usage).
2067 Figure 4.2: The 'gnutls_certificate_status_t' enumeration.
2069 An example of certificate verification is shown in *note ex-verify2::.
2070 It is also possible to have a set of certificates that are trusted for a
2071 particular server but not to authorize other certificates. This purpose
2072 is served by the functions *note gnutls_x509_trust_list_add_named_crt::
2073 and *note gnutls_x509_trust_list_verify_named_crt::.
2076 File: gnutls.info, Node: Verifying a certificate in the context of TLS session, Next: Verification using PKCS11, Prev: Verifying X.509 certificate paths, Up: X.509 certificates
2078 4.1.1.8 Verifying a certificate in the context of TLS session
2079 .............................................................
2081 When operating in the context of a TLS session, the trusted certificate
2082 authority list may also be set using:
2083 'INT *note gnutls_certificate_set_x509_trust_file:: (gnutls_certificate_credentials_t CRED, const char * CAFILE, gnutls_x509_crt_fmt_t TYPE)'
2084 'INT *note gnutls_certificate_set_x509_trust_dir:: (gnutls_certificate_credentials_t CRED, const char * CA_DIR, gnutls_x509_crt_fmt_t TYPE)'
2085 'INT *note gnutls_certificate_set_x509_crl_file:: (gnutls_certificate_credentials_t RES, const char * CRLFILE, gnutls_x509_crt_fmt_t TYPE)'
2086 'INT *note gnutls_certificate_set_x509_system_trust:: (gnutls_certificate_credentials_t CRED)'
2088 These functions allow the specification of the trusted certificate
2089 authorities, either via a file, a directory or use the system-specified
2090 certificate authorities. Unless the authorities are application
2091 specific, it is generally recommended to use the system trust storage
2092 (see *note gnutls_certificate_set_x509_system_trust::).
2094 Unlike the previous section it is not required to setup a trusted list,
2095 and there are two approaches to verify the peer's certificate and
2096 identity. The recommended in GnuTLS 3.5.0 and later is via the *note
2097 gnutls_session_set_verify_cert::, but for older GnuTLS versions you may
2098 use an explicit callback set via *note
2099 gnutls_certificate_set_verify_function:: and then utilize *note
2100 gnutls_certificate_verify_peers3:: for verification. The reported
2101 verification status is identical to the verification functions described
2102 in the previous section.
2104 Note that in certain cases it is required to check the marked purpose of
2105 the end certificate (e.g. 'GNUTLS_KP_TLS_WWW_SERVER'); in these cases
2106 the more advanced *note gnutls_session_set_verify_cert2:: and *note
2107 gnutls_certificate_verify_peers:: should be used instead.
2109 There is also the possibility to pass some input to the verification
2110 functions in the form of flags. For *note
2111 gnutls_x509_trust_list_verify_crt2:: the flags are passed directly, but
2112 for *note gnutls_certificate_verify_peers3::, the flags are set using
2113 *note gnutls_certificate_set_verify_flags::. All the available flags
2114 are part of the enumeration 'gnutls_certificate_verify_flags' shown in
2115 *note Figure 4.3: gnutls_certificate_verify_flags.
2117 'GNUTLS_VERIFY_DISABLE_CA_SIGN'
2118 If set a signer does not have to be a certificate authority. This
2119 flag should normally be disabled, unless you know what this means.
2120 'GNUTLS_VERIFY_DO_NOT_ALLOW_SAME'
2121 If a certificate is not signed by anyone trusted but exists in the
2122 trusted CA list do not treat it as trusted.
2123 'GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT'
2124 Allow CA certificates that have version 1 (both root and
2125 intermediate). This might be dangerous since those haven't the
2126 basicConstraints extension.
2127 'GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2'
2128 Allow certificates to be signed using the broken MD2 algorithm.
2129 'GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5'
2130 Allow certificates to be signed using the broken MD5 algorithm.
2131 'GNUTLS_VERIFY_DISABLE_TIME_CHECKS'
2132 Disable checking of activation and expiration validity periods of
2133 certificate chains. Don't set this unless you understand the
2134 security implications.
2135 'GNUTLS_VERIFY_DISABLE_TRUSTED_TIME_CHECKS'
2136 If set a signer in the trusted list is never checked for expiration
2138 'GNUTLS_VERIFY_DO_NOT_ALLOW_X509_V1_CA_CRT'
2139 Do not allow trusted CA certificates that have version 1. This
2140 option is to be used to deprecate all certificates of version 1.
2141 'GNUTLS_VERIFY_DISABLE_CRL_CHECKS'
2142 Disable checking for validity using certificate revocation lists or
2143 the available OCSP data.
2144 'GNUTLS_VERIFY_ALLOW_UNSORTED_CHAIN'
2145 A certificate chain is tolerated if unsorted (the case with many
2146 TLS servers out there). This is the default since GnuTLS 3.1.4.
2147 'GNUTLS_VERIFY_DO_NOT_ALLOW_UNSORTED_CHAIN'
2148 Do not tolerate an unsorted certificate chain.
2149 'GNUTLS_VERIFY_DO_NOT_ALLOW_WILDCARDS'
2150 When including a hostname check in the verification, do not
2151 consider any wildcards.
2152 'GNUTLS_VERIFY_USE_TLS1_RSA'
2153 This indicates that a (raw) RSA signature is provided as in the TLS
2154 1.0 protocol. Not all functions accept this flag.
2156 Figure 4.3: The 'gnutls_certificate_verify_flags' enumeration.
2159 File: gnutls.info, Node: Verification using PKCS11, Prev: Verifying a certificate in the context of TLS session, Up: X.509 certificates
2161 4.1.1.9 Verifying a certificate using PKCS #11
2162 ..............................................
2164 Some systems provide a system wide trusted certificate storage
2165 accessible using the PKCS #11 API. That is, the trusted certificates are
2166 queried and accessed using the PKCS #11 API, and trusted certificate
2167 properties, such as purpose, are marked using attached extensions. One
2168 example is the p11-kit trust module(1).
2170 These special PKCS #11 modules can be used for GnuTLS certificate
2171 verification if marked as trust policy modules, i.e., with
2172 'trust-policy: yes' in the p11-kit module file. The way to use them is
2173 by specifying to the file verification function (e.g., *note
2174 gnutls_certificate_set_x509_trust_file::), a pkcs11 URL, or simply
2175 'pkcs11:' to use all the marked with trust policy modules.
2177 The trust modules of p11-kit assign a purpose to trusted authorities
2178 using the extended key usage object identifiers. The common purposes
2179 are shown in *note Table 4.4: tab:purposes. Note that typically
2180 according to [_RFC5280_] the extended key usage object identifiers apply
2181 to end certificates. Their application to CA certificates is an
2182 extension used by the trust modules.
2184 Purpose OID Description
2186 --------------------------------------------------------------------------
2187 GNUTLS_KP_TLS_WWW_SERVER1.3.6.1.5.5.7.3.1The certificate is to be used for TLS WWW
2188 authentication. When in a CA
2189 certificate, it indicates that the CA is
2190 allowed to sign certificates for TLS WWW
2193 GNUTLS_KP_TLS_WWW_CLIENT1.3.6.1.5.5.7.3.2The certificate is to be used for TLS WWW
2194 client authentication. When in a CA
2195 certificate, it indicates that the CA is
2196 allowed to sign certificates for TLS WWW
2197 client authentication.
2199 GNUTLS_KP_CODE_SIGNING1.3.6.1.5.5.7.3.3The certificate is to be used for code
2200 signing. When in a CA certificate, it
2201 indicates that the CA is allowed to sign
2202 certificates for code signing.
2204 GNUTLS_KP_EMAIL_PROTECTION1.3.6.1.5.5.7.3.4The certificate is to be used for email
2205 protection. When in a CA certificate, it
2206 indicates that the CA is allowed to sign
2207 certificates for email users.
2209 GNUTLS_KP_OCSP_SIGNING1.3.6.1.5.5.7.3.9The certificate is to be used for signing
2210 OCSP responses. When in a CA
2211 certificate, it indicates that the CA is
2212 allowed to sign certificates which sign
2215 GNUTLS_KP_ANY 2.5.29.37.0 The certificate is to be used for any
2216 purpose. When in a CA certificate, it
2217 indicates that the CA is allowed to sign
2218 any kind of certificates.
2221 Table 4.4: Key purpose object identifiers.
2223 With such modules, it is recommended to use the verification functions
2224 *note gnutls_x509_trust_list_verify_crt2::, or *note
2225 gnutls_certificate_verify_peers::, which allow to explicitly specify the
2226 key purpose. The other verification functions which do not allow
2227 setting a purpose, would operate as if 'GNUTLS_KP_TLS_WWW_SERVER' was
2228 requested from the trusted authorities.
2230 ---------- Footnotes ----------
2232 (1) see <http://p11-glue.freedesktop.org/trust-module.html>.
2235 File: gnutls.info, Node: OpenPGP certificates, Next: Advanced certificate verification, Prev: X.509 certificates, Up: Certificate authentication
2237 4.1.2 OpenPGP certificates
2238 --------------------------
2240 The OpenPGP key authentication relies on a distributed trust model,
2241 called the "web of trust". The "web of trust" uses a decentralized
2242 system of trusted introducers, which are the same as a CA. OpenPGP
2243 allows anyone to sign anyone else's public key. When Alice signs Bob's
2244 key, she is introducing Bob's key to anyone who trusts Alice. If
2245 someone trusts Alice to introduce keys, then Alice is a trusted
2246 introducer in the mind of that observer. For example in *note Figure
2247 4.4: fig-openpgp, David trusts Alice to be an introducer and Alice
2248 signed Bob's key thus Dave trusts Bob's key to be the real one.
2250 \0\b[image src="gnutls-pgp.png"
\0\b]
2252 Figure 4.4: An example of the OpenPGP trust model.
2254 There are some key points that are important in that model. In the
2255 example Alice has to sign Bob's key, only if she is sure that the key
2256 belongs to Bob. Otherwise she may also make Dave falsely believe that
2257 this is Bob's key. Dave has also the responsibility to know who to
2258 trust. This model is similar to real life relations.
2260 Just see how Charlie behaves in the previous example. Although he has
2261 signed Bob's key - because he knows, somehow, that it belongs to Bob -
2262 he does not trust Bob to be an introducer. Charlie decided to trust
2263 only Kevin, for some reason. A reason could be that Bob is lazy enough,
2264 and signs other people's keys without being sure that they belong to the
2269 ------------------------------------------------------------------
2270 version The field that indicates the version of the
2273 user ID An RFC 2822 string that identifies the owner of
2274 the key. There may be multiple user identifiers
2277 public key The main public key of the certificate.
2279 expiration The expiration time of the main public key.
2281 public An additional public key of the certificate.
2282 subkey There may be multiple subkeys in a certificate.
2284 public The expiration time of the subkey.
2288 Table 4.5: OpenPGP certificate fields.
2290 4.1.2.1 OpenPGP certificate structure
2291 .....................................
2293 In GnuTLS the OpenPGP certificate structures [_RFC2440_] are handled
2294 using the 'gnutls_openpgp_crt_t' type. A typical certificate contains
2295 the user ID, which is an RFC 2822 mail and name address, a public key,
2296 possibly a number of additional public keys (called subkeys), and a
2297 number of signatures. The various fields are shown in *note Table 4.5:
2298 tab:openpgp-certificate.
2300 The additional subkeys may provide key for various different purposes,
2301 e.g. one key to encrypt mail, and another to sign a TLS key exchange.
2302 Each subkey is identified by a unique key ID. The keys that are to be
2303 used in a TLS key exchange that requires signatures are called
2304 authentication keys in the OpenPGP jargon. The mapping of TLS key
2305 exchange methods to public keys is shown in *note Table 4.6:
2306 tab:openpgp-key-exchange.
2308 Key exchange Public key requirements
2310 ------------------------------------------------------------------
2311 RSA An RSA public key that allows encryption.
2313 DHE_RSA An RSA public key that is marked for
2316 ECDHE_RSA An RSA public key that is marked for
2319 DHE_DSS A DSA public key that is marked for
2323 Table 4.6: The types of (sub)keys required for the various TLS key
2326 The corresponding private keys are stored in the
2327 'gnutls_openpgp_privkey_t' type. All the prototypes for the key
2328 handling functions can be found in 'gnutls/openpgp.h'.
2330 4.1.2.2 Verifying an OpenPGP certificate
2331 ........................................
2333 The verification functions of OpenPGP keys, included in GnuTLS, are
2334 simple ones, and do not use the features of the "web of trust". For
2335 that reason, if the verification needs are complex, the assistance of
2336 external tools like GnuPG and GPGME(1) is recommended.
2338 In GnuTLS there is a verification function for OpenPGP certificates, the
2339 *note gnutls_openpgp_crt_verify_ring::. This checks an OpenPGP key
2340 against a given set of public keys (keyring) and returns the key status.
2341 The key verification status is the same as in X.509 certificates,
2342 although the meaning and interpretation are different. For example an
2343 OpenPGP key may be valid, if the self signature is ok, even if no
2344 signers were found. The meaning of verification status flags is the
2345 same as in the X.509 certificates (see *note Figure 4.3:
2346 gnutls_certificate_verify_flags.).
2348 -- Function: int gnutls_openpgp_crt_verify_ring (gnutls_openpgp_crt_t
2349 KEY, gnutls_openpgp_keyring_t KEYRING, unsigned int FLAGS,
2350 unsigned int * VERIFY)
2351 KEY: the structure that holds the key.
2353 KEYRING: holds the keyring to check against
2355 FLAGS: unused (should be 0)
2357 VERIFY: will hold the certificate verification output.
2359 Verify all signatures in the key, using the given set of keys
2362 The key verification output will be put in 'verify' and will be one
2363 or more of the 'gnutls_certificate_status_t' enumerated elements
2366 Note that this function does not verify using any "web of trust".
2367 You may use GnuPG for that purpose, or any other external PGP
2370 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
2372 -- Function: int gnutls_openpgp_crt_verify_self (gnutls_openpgp_crt_t
2373 KEY, unsigned int FLAGS, unsigned int * VERIFY)
2374 KEY: the structure that holds the key.
2376 FLAGS: unused (should be 0)
2378 VERIFY: will hold the key verification output.
2380 Verifies the self signature in the key. The key verification
2381 output will be put in 'verify' and will be one or more of the
2382 gnutls_certificate_status_t enumerated elements bitwise or'd.
2384 *Returns:* 'GNUTLS_E_SUCCESS' on success, or an error code.
2386 4.1.2.3 Verifying a certificate in the context of a TLS session
2387 ...............................................................
2389 Similarly with X.509 certificates, one needs to specify the OpenPGP
2390 keyring file in the credentials structure. The certificates in this
2391 file will be used by *note gnutls_certificate_verify_peers3:: to verify
2392 the signatures in the certificate sent by the peer.
2394 -- Function: int gnutls_certificate_set_openpgp_keyring_file
2395 (gnutls_certificate_credentials_t C, const char * FILE,
2396 gnutls_openpgp_crt_fmt_t FORMAT)
2397 C: A certificate credentials structure
2399 FILE: filename of the keyring.
2401 FORMAT: format of keyring.
2403 The function is used to set keyrings that will be used internally
2404 by various OpenPGP functions. For example to find a key when it is
2405 needed for an operations. The keyring will also be used at the
2406 verification functions.
2408 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2409 otherwise a negative error value.
2411 ---------- Footnotes ----------
2413 (1) <http://www.gnupg.org/related_software/gpgme/>
2416 File: gnutls.info, Node: Advanced certificate verification, Next: Digital signatures, Prev: OpenPGP certificates, Up: Certificate authentication
2418 4.1.3 Advanced certificate verification
2419 ---------------------------------------
2421 The verification of X.509 certificates in the HTTPS and other Internet
2422 protocols is typically done by loading a trusted list of commercial
2423 Certificate Authorities (see *note
2424 gnutls_certificate_set_x509_system_trust::), and using them as trusted
2425 anchors. However, there are several examples (eg. the Diginotar
2426 incident) where one of these authorities was compromised. This risk can
2427 be mitigated by using in addition to CA certificate verification, other
2428 verification methods. In this section we list the available in GnuTLS
2433 * Verifying a certificate using trust on first use authentication::
2434 * Verifying a certificate using DANE::
2437 File: gnutls.info, Node: Verifying a certificate using trust on first use authentication, Next: Verifying a certificate using DANE, Up: Advanced certificate verification
2439 4.1.3.1 Verifying a certificate using trust on first use authentication
2440 .......................................................................
2442 It is possible to use a trust on first use (TOFU) authentication method
2443 in GnuTLS. That is the concept used by the SSH programs, where the
2444 public key of the peer is not verified, or verified in an out-of-bound
2445 way, but subsequent connections to the same peer require the public key
2446 to remain the same. Such a system in combination with the typical CA
2447 verification of a certificate, and OCSP revocation checks, can help to
2448 provide multiple factor verification, where a single point of failure is
2449 not enough to compromise the system. For example a server compromise
2450 may be detected using OCSP, and a CA compromise can be detected using
2451 the trust on first use method. Such a hybrid system with X.509 and
2452 trust on first use authentication is shown in *note Simple client
2453 example with SSH-style certificate verification::.
2455 See *note Certificate verification:: on how to use the available
2459 File: gnutls.info, Node: Verifying a certificate using DANE, Prev: Verifying a certificate using trust on first use authentication, Up: Advanced certificate verification
2461 4.1.3.2 Verifying a certificate using DANE (DNSSEC)
2462 ...................................................
2464 The DANE protocol is a protocol that can be used to verify TLS
2465 certificates using the DNS (or better DNSSEC) protocols. The DNS
2466 security extensions (DNSSEC) provide an alternative public key
2467 infrastructure to the commercial CAs that are typically used to sign TLS
2468 certificates. The DANE protocol takes advantage of the DNSSEC
2469 infrastructure to verify TLS certificates. This can be in addition to
2470 the verification by CA infrastructure or may even replace it where
2471 DNSSEC is fully deployed. Note however, that DNSSEC deployment is
2472 fairly new and it would be better to use it as an additional
2473 verification method rather than the only one.
2475 The DANE functionality is provided by the 'libgnutls-dane' library that
2476 is shipped with GnuTLS and the function prototypes are in
2477 'gnutls/dane.h'. See *note Certificate verification:: for information
2478 on how to use the library.
2480 Note however, that the DANE RFC mandates the verification methods one
2481 should use in addition to the validation via DNSSEC TLSA entries.
2482 GnuTLS doesn't follow that RFC requirement, and the term DANE
2483 verification in this manual refers to the TLSA entry verification. In
2484 GnuTLS any other verification methods can be used (e.g., PKIX or TOFU)
2488 File: gnutls.info, Node: Digital signatures, Prev: Advanced certificate verification, Up: Certificate authentication
2490 4.1.4 Digital signatures
2491 ------------------------
2493 In this section we will provide some information about digital
2494 signatures, how they work, and give the rationale for disabling some of
2495 the algorithms used.
2497 Digital signatures work by using somebody's secret key to sign some
2498 arbitrary data. Then anybody else could use the public key of that
2499 person to verify the signature. Since the data may be arbitrary it is
2500 not suitable input to a cryptographic digital signature algorithm. For
2501 this reason and also for performance cryptographic hash algorithms are
2502 used to preprocess the input to the signature algorithm. This works as
2503 long as it is difficult enough to generate two different messages with
2504 the same hash algorithm output. In that case the same signature could
2505 be used as a proof for both messages. Nobody wants to sign an innocent
2506 message of donating 1 euro to Greenpeace and find out that they donated
2507 1.000.000 euros to Bad Inc.
2509 For a hash algorithm to be called cryptographic the following three
2510 requirements must hold:
2512 1. Preimage resistance. That means the algorithm must be one way and
2513 given the output of the hash function H(x), it is impossible to
2516 2. 2nd preimage resistance. That means that given a pair x,y with
2517 y=H(x) it is impossible to calculate an x' such that y=H(x').
2519 3. Collision resistance. That means that it is impossible to
2520 calculate random x and x' such H(x')=H(x).
2522 The last two requirements in the list are the most important in digital
2523 signatures. These protect against somebody who would like to generate
2524 two messages with the same hash output. When an algorithm is considered
2525 broken usually it means that the Collision resistance of the algorithm
2526 is less than brute force. Using the birthday paradox the brute force
2527 attack takes 2^{((hash size) / 2)} operations. Today colliding
2528 certificates using the MD5 hash algorithm have been generated as shown
2531 There has been cryptographic results for the SHA-1 hash algorithms as
2532 well, although they are not yet critical. Before 2004, MD5 had a
2533 presumed collision strength of 2^{64}, but it has been showed to have a
2534 collision strength well under 2^{50}. As of November 2005, it is
2535 believed that SHA-1's collision strength is around 2^{63}. We consider
2536 this sufficiently hard so that we still support SHA-1. We anticipate
2537 that SHA-256/386/512 will be used in publicly-distributed certificates
2538 in the future. When 2^{63} can be considered too weak compared to the
2539 computer power available sometime in the future, SHA-1 will be disabled
2540 as well. The collision attacks on SHA-1 may also get better, given the
2541 new interest in tools for creating them.
2543 4.1.4.1 Trading security for interoperability
2544 .............................................
2546 If you connect to a server and use GnuTLS' functions to verify the
2547 certificate chain, and get a 'GNUTLS_CERT_INSECURE_ALGORITHM' validation
2548 error (see *note Verifying X.509 certificate paths::), it means that
2549 somewhere in the certificate chain there is a certificate signed using
2550 'RSA-MD2' or 'RSA-MD5'. These two digital signature algorithms are
2551 considered broken, so GnuTLS fails verifying the certificate. In some
2552 situations, it may be useful to be able to verify the certificate chain
2553 anyway, assuming an attacker did not utilize the fact that these
2554 signatures algorithms are broken. This section will give help on how to
2557 It is important to know that you do not have to enable any of the flags
2558 discussed here to be able to use trusted root CA certificates
2559 self-signed using 'RSA-MD2' or 'RSA-MD5'. The certificates in the
2560 trusted list are considered trusted irrespective of the signature.
2562 If you are using *note gnutls_certificate_verify_peers3:: to verify the
2563 certificate chain, you can call *note
2564 gnutls_certificate_set_verify_flags:: with the flags:
2565 * 'GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2'
2566 * 'GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5'
2567 as in the following example:
2569 gnutls_certificate_set_verify_flags (x509cred,
2570 GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5);
2572 This will signal the verifier algorithm to enable 'RSA-MD5' when
2573 verifying the certificates.
2575 If you are using *note gnutls_x509_crt_verify:: or *note
2576 gnutls_x509_crt_list_verify::, you can pass the
2577 'GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5' parameter directly in the 'flags'
2580 If you are using these flags, it may also be a good idea to warn the
2581 user when verification failure occur for this reason. The simplest is
2582 to not use the flags by default, and only fall back to using them after
2583 warning the user. If you wish to inspect the certificate chain
2584 yourself, you can use *note gnutls_certificate_get_peers:: to extract
2585 the raw server's certificate chain, *note gnutls_x509_crt_list_import::
2586 to parse each of the certificates, and then *note
2587 gnutls_x509_crt_get_signature_algorithm:: to find out the signing
2588 algorithm used for each certificate. If any of the intermediary
2589 certificates are using 'GNUTLS_SIGN_RSA_MD2' or 'GNUTLS_SIGN_RSA_MD5',
2590 you could present a warning.
2593 File: gnutls.info, Node: More on certificate authentication, Next: Shared-key and anonymous authentication, Prev: Certificate authentication, Up: Authentication methods
2595 4.2 More on certificate authentication
2596 ======================================
2598 Certificates are not the only structures involved in a public key
2599 infrastructure. Several other structures that are used for certificate
2600 requests, encrypted private keys, revocation lists, GnuTLS abstract key
2601 structures, etc., are discussed in this chapter.
2605 * PKCS 10 certificate requests::
2606 * PKIX certificate revocation lists::
2607 * OCSP certificate status checking::
2608 * Managing encrypted keys::
2609 * certtool Invocation:: Invoking certtool
2610 * ocsptool Invocation:: Invoking ocsptool
2611 * danetool Invocation:: Invoking danetool
2614 File: gnutls.info, Node: PKCS 10 certificate requests, Next: PKIX certificate revocation lists, Up: More on certificate authentication
2616 4.2.1 PKCS #10 certificate requests
2617 -----------------------------------
2619 A certificate request is a structure, which contain information about an
2620 applicant of a certificate service. It usually contains a private key,
2621 a distinguished name and secondary data such as a challenge password.
2622 GnuTLS supports the requests defined in PKCS #10 [_RFC2986_]. Other
2623 formats of certificate requests are not currently supported.
2625 A certificate request can be generated by associating it with a private
2626 key, setting the subject's information and finally self signing it. The
2627 last step ensures that the requester is in possession of the private
2630 'INT *note gnutls_x509_crq_set_version:: (gnutls_x509_crq_t CRQ, unsigned int VERSION)'
2631 'INT *note gnutls_x509_crq_set_dn:: (gnutls_x509_crq_t CRQ, const char * DN, const char ** ERR)'
2632 'INT *note gnutls_x509_crq_set_dn_by_oid:: (gnutls_x509_crq_t CRQ, const char * OID, unsigned int RAW_FLAG, const void * DATA, unsigned int SIZEOF_DATA)'
2633 'INT *note gnutls_x509_crq_set_key_usage:: (gnutls_x509_crq_t CRQ, unsigned int USAGE)'
2634 'INT *note gnutls_x509_crq_set_key_purpose_oid:: (gnutls_x509_crq_t CRQ, const void * OID, unsigned int CRITICAL)'
2635 'INT *note gnutls_x509_crq_set_basic_constraints:: (gnutls_x509_crq_t CRQ, unsigned int CA, int PATHLENCONSTRAINT)'
2637 The *note gnutls_x509_crq_set_key:: and *note gnutls_x509_crq_sign2::
2638 functions associate the request with a private key and sign it. If a
2639 request is to be signed with a key residing in a PKCS #11 token it is
2640 recommended to use the signing functions shown in *note Abstract key
2643 -- Function: int gnutls_x509_crq_set_key (gnutls_x509_crq_t CRQ,
2644 gnutls_x509_privkey_t KEY)
2645 CRQ: should contain a 'gnutls_x509_crq_t' type
2647 KEY: holds a private key
2649 This function will set the public parameters from the given private
2652 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2653 otherwise a negative error value.
2655 -- Function: int gnutls_x509_crq_sign2 (gnutls_x509_crq_t CRQ,
2656 gnutls_x509_privkey_t KEY, gnutls_digest_algorithm_t DIG,
2658 CRQ: should contain a 'gnutls_x509_crq_t' type
2660 KEY: holds a private key
2662 DIG: The message digest to use, i.e., 'GNUTLS_DIG_SHA1'
2666 This function will sign the certificate request with a private key.
2667 This must be the same key as the one used in
2668 'gnutls_x509_crt_set_key()' since a certificate request is self
2671 This must be the last step in a certificate request generation
2672 since all the previously set parameters are now signed.
2674 *Returns:* 'GNUTLS_E_SUCCESS' on success, otherwise a negative
2675 error code. 'GNUTLS_E_ASN1_VALUE_NOT_FOUND' is returned if you
2676 didn't set all information in the certificate request (e.g., the
2677 version using 'gnutls_x509_crq_set_version()' ).
2679 The following example is about generating a certificate request, and a
2680 private key. A certificate request can be later be processed by a CA
2681 which should return a signed certificate.
2683 /* This example code is placed in the public domain. */
2685 #ifdef HAVE_CONFIG_H
2692 #include <gnutls/gnutls.h>
2693 #include <gnutls/x509.h>
2694 #include <gnutls/abstract.h>
2697 /* This example will generate a private key and a certificate
2703 gnutls_x509_crq_t crq;
2704 gnutls_x509_privkey_t key;
2705 unsigned char buffer[10 * 1024];
2706 size_t buffer_size = sizeof(buffer);
2709 gnutls_global_init();
2711 /* Initialize an empty certificate request, and
2712 * an empty private key.
2714 gnutls_x509_crq_init(&crq);
2716 gnutls_x509_privkey_init(&key);
2718 /* Generate an RSA key of moderate security.
2721 gnutls_sec_param_to_pk_bits(GNUTLS_PK_RSA,
2722 GNUTLS_SEC_PARAM_MEDIUM);
2723 gnutls_x509_privkey_generate(key, GNUTLS_PK_RSA, bits, 0);
2725 /* Add stuff to the distinguished name
2727 gnutls_x509_crq_set_dn_by_oid(crq, GNUTLS_OID_X520_COUNTRY_NAME,
2730 gnutls_x509_crq_set_dn_by_oid(crq, GNUTLS_OID_X520_COMMON_NAME,
2731 0, "Nikos", strlen("Nikos"));
2733 /* Set the request version.
2735 gnutls_x509_crq_set_version(crq, 1);
2737 /* Set a challenge password.
2739 gnutls_x509_crq_set_challenge_password(crq,
2740 "something to remember here");
2742 /* Associate the request with the private key
2744 gnutls_x509_crq_set_key(crq, key);
2746 /* Self sign the certificate request.
2748 gnutls_x509_crq_sign2(crq, key, GNUTLS_DIG_SHA1, 0);
2750 /* Export the PEM encoded certificate request, and
2753 gnutls_x509_crq_export(crq, GNUTLS_X509_FMT_PEM, buffer,
2756 printf("Certificate Request: \n%s", buffer);
2759 /* Export the PEM encoded private key, and
2762 buffer_size = sizeof(buffer);
2763 gnutls_x509_privkey_export(key, GNUTLS_X509_FMT_PEM, buffer,
2766 printf("\n\nPrivate key: \n%s", buffer);
2768 gnutls_x509_crq_deinit(crq);
2769 gnutls_x509_privkey_deinit(key);
2776 File: gnutls.info, Node: PKIX certificate revocation lists, Next: OCSP certificate status checking, Prev: PKCS 10 certificate requests, Up: More on certificate authentication
2778 4.2.2 PKIX certificate revocation lists
2779 ---------------------------------------
2781 A certificate revocation list (CRL) is a structure issued by an
2782 authority periodically containing a list of revoked certificates serial
2783 numbers. The CRL structure is signed with the issuing authorities'
2784 keys. A typical CRL contains the fields as shown in *note Table 4.7:
2785 tab:crl. Certificate revocation lists are used to complement the
2786 expiration date of a certificate, in order to account for other reasons
2787 of revocation, such as compromised keys, etc.
2789 Each CRL is valid for limited amount of time and is required to provide,
2790 except for the current issuing time, also the issuing time of the next
2795 ------------------------------------------------------------------
2796 version The field that indicates the version of the CRL
2799 signature A signature by the issuing authority.
2801 issuer Holds the issuer's distinguished name.
2803 thisUpdate The issuing time of the revocation list.
2805 nextUpdate The issuing time of the revocation list that
2806 will update that one.
2808 revokedCertificatesList of revoked certificates serial numbers.
2810 extensions Optional CRL structure extensions.
2813 Table 4.7: Certificate revocation list fields.
2815 The basic CRL structure functions follow.
2817 'INT *note gnutls_x509_crl_init:: (gnutls_x509_crl_t * CRL)'
2818 'INT *note gnutls_x509_crl_import:: (gnutls_x509_crl_t CRL, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)'
2819 'INT *note gnutls_x509_crl_export:: (gnutls_x509_crl_t CRL, gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE)'
2820 'INT *note gnutls_x509_crl_export:: (gnutls_x509_crl_t CRL, gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE)'
2825 The most important function that extracts the certificate revocation
2826 information from a CRL is *note gnutls_x509_crl_get_crt_serial::. Other
2827 functions that return other fields of the CRL structure are also
2830 -- Function: int gnutls_x509_crl_get_crt_serial (gnutls_x509_crl_t CRL,
2831 int INDX, unsigned char * SERIAL, size_t * SERIAL_SIZE, time_t
2833 CRL: should contain a 'gnutls_x509_crl_t' type
2835 INDX: the index of the certificate to extract (starting from 0)
2837 SERIAL: where the serial number will be copied
2839 SERIAL_SIZE: initially holds the size of serial
2841 T: if non null, will hold the time this certificate was revoked
2843 This function will retrieve the serial number of the specified, by
2844 the index, revoked certificate.
2846 Note that this function will have performance issues in large
2847 sequences of revoked certificates. In that case use
2848 'gnutls_x509_crl_iter_crt_serial()' .
2850 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2851 otherwise a negative error value.
2853 'INT *note gnutls_x509_crl_get_version:: (gnutls_x509_crl_t CRL)'
2854 'INT *note gnutls_x509_crl_get_issuer_dn:: (const gnutls_x509_crl_t CRL, char * BUF, size_t * SIZEOF_BUF)'
2855 'INT *note gnutls_x509_crl_get_issuer_dn2:: (gnutls_x509_crl_t CRL, gnutls_datum_t * DN)'
2856 'TIME_T *note gnutls_x509_crl_get_this_update:: (gnutls_x509_crl_t CRL)'
2857 'TIME_T *note gnutls_x509_crl_get_next_update:: (gnutls_x509_crl_t CRL)'
2858 'INT *note gnutls_x509_crl_get_crt_count:: (gnutls_x509_crl_t CRL)'
2863 The following functions can be used to generate a CRL.
2865 'INT *note gnutls_x509_crl_set_version:: (gnutls_x509_crl_t CRL, unsigned int VERSION)'
2866 'INT *note gnutls_x509_crl_set_crt_serial:: (gnutls_x509_crl_t CRL, const void * SERIAL, size_t SERIAL_SIZE, time_t REVOCATION_TIME)'
2867 'INT *note gnutls_x509_crl_set_crt:: (gnutls_x509_crl_t CRL, gnutls_x509_crt_t CRT, time_t REVOCATION_TIME)'
2868 'INT *note gnutls_x509_crl_set_next_update:: (gnutls_x509_crl_t CRL, time_t EXP_TIME)'
2869 'INT *note gnutls_x509_crl_set_this_update:: (gnutls_x509_crl_t CRL, time_t ACT_TIME)'
2871 The *note gnutls_x509_crl_sign2:: and *note
2872 gnutls_x509_crl_privkey_sign:: functions sign the revocation list with a
2873 private key. The latter function can be used to sign with a key
2874 residing in a PKCS #11 token.
2876 -- Function: int gnutls_x509_crl_sign2 (gnutls_x509_crl_t CRL,
2877 gnutls_x509_crt_t ISSUER, gnutls_x509_privkey_t ISSUER_KEY,
2878 gnutls_digest_algorithm_t DIG, unsigned int FLAGS)
2879 CRL: should contain a gnutls_x509_crl_t type
2881 ISSUER: is the certificate of the certificate issuer
2883 ISSUER_KEY: holds the issuer's private key
2885 DIG: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice
2886 unless you know what you're doing.
2890 This function will sign the CRL with the issuer's private key, and
2891 will copy the issuer's information into the CRL.
2893 This must be the last step in a certificate CRL since all the
2894 previously set parameters are now signed.
2896 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2897 otherwise a negative error value.
2899 -- Function: int gnutls_x509_crl_privkey_sign (gnutls_x509_crl_t CRL,
2900 gnutls_x509_crt_t ISSUER, gnutls_privkey_t ISSUER_KEY,
2901 gnutls_digest_algorithm_t DIG, unsigned int FLAGS)
2902 CRL: should contain a gnutls_x509_crl_t type
2904 ISSUER: is the certificate of the certificate issuer
2906 ISSUER_KEY: holds the issuer's private key
2908 DIG: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice
2909 unless you know what you're doing.
2913 This function will sign the CRL with the issuer's private key, and
2914 will copy the issuer's information into the CRL.
2916 This must be the last step in a certificate CRL since all the
2917 previously set parameters are now signed.
2919 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
2920 otherwise a negative error value.
2924 Few extensions on the CRL structure are supported, including the CRL
2925 number extension and the authority key identifier.
2927 'INT *note gnutls_x509_crl_set_number:: (gnutls_x509_crl_t CRL, const void * NR, size_t NR_SIZE)'
2928 'INT *note gnutls_x509_crl_set_authority_key_id:: (gnutls_x509_crl_t CRL, const void * ID, size_t ID_SIZE)'
2931 File: gnutls.info, Node: OCSP certificate status checking, Next: Managing encrypted keys, Prev: PKIX certificate revocation lists, Up: More on certificate authentication
2933 4.2.3 OCSP certificate status checking
2934 --------------------------------------
2936 Certificates may be revoked before their expiration time has been
2937 reached. There are several reasons for revoking certificates, but a
2938 typical situation is when the private key associated with a certificate
2939 has been compromised. Traditionally, Certificate Revocation Lists
2940 (CRLs) have been used by application to implement revocation checking,
2941 however, several problems with CRLs have been identified [_RIVESTCRL_].
2943 The Online Certificate Status Protocol, or OCSP [_RFC2560_], is a widely
2944 implemented protocol which performs certificate revocation status
2945 checking. An application that wish to verify the identity of a peer
2946 will verify the certificate against a set of trusted certificates and
2947 then check whether the certificate is listed in a CRL and/or perform an
2948 OCSP check for the certificate.
2950 Note that in the context of a TLS session the server may provide an OCSP
2951 response that will be used during the TLS certificate verification (see
2952 *note gnutls_certificate_verify_peers2::). You may obtain this response
2953 using *note gnutls_ocsp_status_request_get::.
2955 Before performing the OCSP query, the application will need to figure
2956 out the address of the OCSP server. The OCSP server address can be
2957 provided by the local user in manual configuration or may be stored in
2958 the certificate that is being checked. When stored in a certificate the
2959 OCSP server is in the extension field called the Authority Information
2960 Access (AIA). The following function extracts this information from a
2963 'INT *note gnutls_x509_crt_get_authority_info_access:: (gnutls_x509_crt_t CRT, unsigned int SEQ, int WHAT, gnutls_datum_t * DATA, unsigned int * CRITICAL)'
2965 There are several functions in GnuTLS for creating and manipulating OCSP
2966 requests and responses. The general idea is that a client application
2967 creates an OCSP request object, stores some information about the
2968 certificate to check in the request, and then exports the request in DER
2969 format. The request will then need to be sent to the OCSP responder,
2970 which needs to be done by the application (GnuTLS does not send and
2971 receive OCSP packets). Normally an OCSP response is received that the
2972 application will need to import into an OCSP response object. The
2973 digital signature in the OCSP response needs to be verified against a
2974 set of trust anchors before the information in the response can be
2977 The ASN.1 structure of OCSP requests are briefly as follows. It is
2978 useful to review the structures to get an understanding of which fields
2979 are modified by GnuTLS functions.
2981 OCSPRequest ::= SEQUENCE {
2982 tbsRequest TBSRequest,
2983 optionalSignature [0] EXPLICIT Signature OPTIONAL }
2985 TBSRequest ::= SEQUENCE {
2986 version [0] EXPLICIT Version DEFAULT v1,
2987 requestorName [1] EXPLICIT GeneralName OPTIONAL,
2988 requestList SEQUENCE OF Request,
2989 requestExtensions [2] EXPLICIT Extensions OPTIONAL }
2991 Request ::= SEQUENCE {
2993 singleRequestExtensions [0] EXPLICIT Extensions OPTIONAL }
2995 CertID ::= SEQUENCE {
2996 hashAlgorithm AlgorithmIdentifier,
2997 issuerNameHash OCTET STRING, -- Hash of Issuer's DN
2998 issuerKeyHash OCTET STRING, -- Hash of Issuers public key
2999 serialNumber CertificateSerialNumber }
3001 The basic functions to initialize, import, export and deallocate OCSP
3002 requests are the following.
3004 'INT *note gnutls_ocsp_req_init:: (gnutls_ocsp_req_t * REQ)'
3005 'VOID *note gnutls_ocsp_req_deinit:: (gnutls_ocsp_req_t REQ)'
3006 'INT *note gnutls_ocsp_req_import:: (gnutls_ocsp_req_t REQ, const gnutls_datum_t * DATA)'
3007 'INT *note gnutls_ocsp_req_export:: (gnutls_ocsp_req_t REQ, gnutls_datum_t * DATA)'
3008 'INT *note gnutls_ocsp_req_print:: (gnutls_ocsp_req_t REQ, gnutls_ocsp_print_formats_t FORMAT, gnutls_datum_t * OUT)'
3010 To generate an OCSP request the issuer name hash, issuer key hash, and
3011 the checked certificate's serial number are required. There are two
3012 interfaces available for setting those in an OCSP request. The is a
3013 low-level function when you have the issuer name hash, issuer key hash,
3014 and certificate serial number in binary form. The second is more useful
3015 if you have the certificate (and its issuer) in a 'gnutls_x509_crt_t'
3016 type. There is also a function to extract this information from
3017 existing an OCSP request.
3019 'INT *note gnutls_ocsp_req_add_cert_id:: (gnutls_ocsp_req_t REQ, gnutls_digest_algorithm_t DIGEST, const gnutls_datum_t * ISSUER_NAME_HASH, const gnutls_datum_t * ISSUER_KEY_HASH, const gnutls_datum_t * SERIAL_NUMBER)'
3020 'INT *note gnutls_ocsp_req_add_cert:: (gnutls_ocsp_req_t REQ, gnutls_digest_algorithm_t DIGEST, gnutls_x509_crt_t ISSUER, gnutls_x509_crt_t CERT)'
3021 'INT *note gnutls_ocsp_req_get_cert_id:: (gnutls_ocsp_req_t REQ, unsigned INDX, gnutls_digest_algorithm_t * DIGEST, gnutls_datum_t * ISSUER_NAME_HASH, gnutls_datum_t * ISSUER_KEY_HASH, gnutls_datum_t * SERIAL_NUMBER)'
3023 Each OCSP request may contain a number of extensions. Extensions are
3024 identified by an Object Identifier (OID) and an opaque data buffer whose
3025 syntax and semantics is implied by the OID. You can extract or set those
3026 extensions using the following functions.
3028 'INT *note gnutls_ocsp_req_get_extension:: (gnutls_ocsp_req_t REQ, unsigned INDX, gnutls_datum_t * OID, unsigned int * CRITICAL, gnutls_datum_t * DATA)'
3029 'INT *note gnutls_ocsp_req_set_extension:: (gnutls_ocsp_req_t REQ, const char * OID, unsigned int CRITICAL, const gnutls_datum_t * DATA)'
3031 A common OCSP Request extension is the nonce extension (OID
3032 1.3.6.1.5.5.7.48.1.2), which is used to avoid replay attacks of earlier
3033 recorded OCSP responses. The nonce extension carries a value that is
3034 intended to be sufficiently random and unique so that an attacker will
3035 not be able to give a stale response for the same nonce.
3037 'INT *note gnutls_ocsp_req_get_nonce:: (gnutls_ocsp_req_t REQ, unsigned int * CRITICAL, gnutls_datum_t * NONCE)'
3038 'INT *note gnutls_ocsp_req_set_nonce:: (gnutls_ocsp_req_t REQ, unsigned int CRITICAL, const gnutls_datum_t * NONCE)'
3039 'INT *note gnutls_ocsp_req_randomize_nonce:: (gnutls_ocsp_req_t REQ)'
3041 The OCSP response structures is a complex structure. A simplified
3042 overview of it is in *note Table 4.8: tab:ocsp-response. Note that a
3043 response may contain information on multiple certificates.
3047 ------------------------------------------------------------------
3048 version The OCSP response version number (typically 1).
3050 responder ID An identifier of the responder (DN name or a
3053 issue time The time the response was generated.
3055 thisUpdate The issuing time of the revocation information.
3057 nextUpdate The issuing time of the revocation information
3058 that will update that one.
3060 Revoked certificates
3062 certificate The status of the certificate.
3064 certificate The certificate's serial number.
3066 revocationTime The time the certificate was revoked.
3068 revocationReasonThe reason the certificate was revoked.
3071 Table 4.8: The most important OCSP response fields.
3073 We provide basic functions for initialization, importing, exporting and
3074 deallocating OCSP responses.
3076 'INT *note gnutls_ocsp_resp_init:: (gnutls_ocsp_resp_t * RESP)'
3077 'VOID *note gnutls_ocsp_resp_deinit:: (gnutls_ocsp_resp_t RESP)'
3078 'INT *note gnutls_ocsp_resp_import:: (gnutls_ocsp_resp_t RESP, const gnutls_datum_t * DATA)'
3079 'INT *note gnutls_ocsp_resp_export:: (gnutls_ocsp_resp_t RESP, gnutls_datum_t * DATA)'
3080 'INT *note gnutls_ocsp_resp_print:: (gnutls_ocsp_resp_t RESP, gnutls_ocsp_print_formats_t FORMAT, gnutls_datum_t * OUT)'
3082 The utility function that extracts the revocation as well as other
3083 information from a response is shown below.
3085 -- Function: int gnutls_ocsp_resp_get_single (gnutls_ocsp_resp_t RESP,
3086 unsigned INDX, gnutls_digest_algorithm_t * DIGEST,
3087 gnutls_datum_t * ISSUER_NAME_HASH, gnutls_datum_t *
3088 ISSUER_KEY_HASH, gnutls_datum_t * SERIAL_NUMBER, unsigned int
3089 * CERT_STATUS, time_t * THIS_UPDATE, time_t * NEXT_UPDATE,
3090 time_t * REVOCATION_TIME, unsigned int * REVOCATION_REASON)
3091 RESP: should contain a 'gnutls_ocsp_resp_t' type
3093 INDX: Specifies response number to get. Use (0) to get the first
3096 DIGEST: output variable with 'gnutls_digest_algorithm_t' hash
3099 ISSUER_NAME_HASH: output buffer with hash of issuer's DN
3101 ISSUER_KEY_HASH: output buffer with hash of issuer's public key
3103 SERIAL_NUMBER: output buffer with serial number of certificate to
3106 CERT_STATUS: a certificate status, a 'gnutls_ocsp_cert_status_t'
3109 THIS_UPDATE: time at which the status is known to be correct.
3111 NEXT_UPDATE: when newer information will be available, or
3112 (time_t)-1 if unspecified
3114 REVOCATION_TIME: when 'cert_status' is 'GNUTLS_OCSP_CERT_REVOKED' ,
3115 holds time of revocation.
3117 REVOCATION_REASON: revocation reason, a 'gnutls_x509_crl_reason_t'
3120 This function will return the certificate information of the 'indx'
3121 'ed response in the Basic OCSP Response 'resp' . The information
3122 returned corresponds to the OCSP SingleResponse structure except
3123 the final singleExtensions.
3125 Each of the pointers to output variables may be NULL to indicate
3126 that the caller is not interested in that value.
3128 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3129 otherwise a negative error code is returned. If you have reached
3130 the last CertID available 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE'
3133 The possible revocation reasons available in an OCSP response are shown
3136 'GNUTLS_X509_CRLREASON_UNSPECIFIED'
3138 'GNUTLS_X509_CRLREASON_KEYCOMPROMISE'
3139 Private key compromised.
3140 'GNUTLS_X509_CRLREASON_CACOMPROMISE'
3142 'GNUTLS_X509_CRLREASON_AFFILIATIONCHANGED'
3143 Affiliation has changed.
3144 'GNUTLS_X509_CRLREASON_SUPERSEDED'
3145 Certificate superseded.
3146 'GNUTLS_X509_CRLREASON_CESSATIONOFOPERATION'
3147 Operation has ceased.
3148 'GNUTLS_X509_CRLREASON_CERTIFICATEHOLD'
3149 Certificate is on hold.
3150 'GNUTLS_X509_CRLREASON_REMOVEFROMCRL'
3151 Will be removed from delta CRL.
3152 'GNUTLS_X509_CRLREASON_PRIVILEGEWITHDRAWN'
3153 Privilege withdrawn.
3154 'GNUTLS_X509_CRLREASON_AACOMPROMISE'
3157 Figure 4.5: The revocation reasons
3159 Note, that the OCSP response needs to be verified against some set of
3160 trust anchors before it can be relied upon. It is also important to
3161 check whether the received OCSP response corresponds to the certificate
3164 'INT *note gnutls_ocsp_resp_verify:: (gnutls_ocsp_resp_t RESP, gnutls_x509_trust_list_t TRUSTLIST, unsigned int * VERIFY, unsigned int FLAGS)'
3165 'INT *note gnutls_ocsp_resp_verify_direct:: (gnutls_ocsp_resp_t RESP, gnutls_x509_crt_t ISSUER, unsigned int * VERIFY, unsigned int FLAGS)'
3166 'INT *note gnutls_ocsp_resp_check_crt:: (gnutls_ocsp_resp_t RESP, unsigned int INDX, gnutls_x509_crt_t CRT)'
3169 File: gnutls.info, Node: Managing encrypted keys, Next: certtool Invocation, Prev: OCSP certificate status checking, Up: More on certificate authentication
3171 4.2.4 Managing encrypted keys
3172 -----------------------------
3174 Transferring or storing private keys in plain may not be a good idea,
3175 since any compromise is irreparable. Storing the keys in hardware
3176 security modules (see *note Smart cards and HSMs::) could solve the
3177 storage problem but it is not always practical or efficient enough.
3178 This section describes ways to store and transfer encrypted private
3181 There are methods for key encryption, namely the PKCS #8, PKCS #12 and
3182 OpenSSL's custom encrypted private key formats. The PKCS #8 and the
3183 OpenSSL's method allow encryption of the private key, while the PKCS #12
3184 method allows, in addition, the bundling of accompanying data into the
3185 structure. That is typically the corresponding certificate, as well as
3186 a trusted CA certificate.
3188 High level functionality
3189 ........................
3191 Generic and higher level private key import functions are available,
3192 that import plain or encrypted keys and will auto-detect the encrypted
3195 -- Function: int gnutls_privkey_import_x509_raw (gnutls_privkey_t PKEY,
3196 const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT,
3197 const char * PASSWORD, unsigned int FLAGS)
3198 PKEY: The private key
3200 DATA: The private key data to be imported
3202 FORMAT: The format of the private key
3204 PASSWORD: A password (optional)
3206 FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t
3208 This function will import the given private key to the abstract
3209 'gnutls_privkey_t' type.
3211 The supported formats are basic unencrypted key, PKCS8, PKCS12, and
3214 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3215 otherwise a negative error value.
3219 -- Function: int gnutls_x509_privkey_import2 (gnutls_x509_privkey_t
3220 KEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t
3221 FORMAT, const char * PASSWORD, unsigned int FLAGS)
3222 KEY: The data to store the parsed key
3224 DATA: The DER or PEM encoded key.
3226 FORMAT: One of DER or PEM
3228 PASSWORD: A password (optional)
3230 FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t
3232 This function will import the given DER or PEM encoded key, to the
3233 native 'gnutls_x509_privkey_t' format, irrespective of the input
3234 format. The input format is auto-detected.
3236 The supported formats are basic unencrypted key, PKCS8, PKCS12, and
3239 If the provided key is encrypted but no password was given, then
3240 'GNUTLS_E_DECRYPTION_FAILED' is returned. Since GnuTLS 3.4.0 this
3241 function will utilize the PIN callbacks if any.
3243 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3244 otherwise a negative error value.
3246 Any keys imported using those functions can be imported to a certificate
3247 credentials structure using *note gnutls_certificate_set_key::, or
3248 alternatively they can be directly imported using *note
3249 gnutls_certificate_set_x509_key_file2::.
3254 PKCS #8 keys can be imported and exported as normal private keys using
3255 the functions below. An addition to the normal import functions, are a
3256 password and a flags argument. The flags can be any element of the
3257 'gnutls_pkcs_encrypt_flags_t' enumeration. Note however, that GnuTLS
3258 only supports the PKCS #5 PBES2 encryption scheme. Keys encrypted with
3259 the obsolete PBES1 scheme cannot be decrypted.
3261 'INT *note gnutls_x509_privkey_import_pkcs8:: (gnutls_x509_privkey_t KEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, const char * PASSWORD, unsigned int FLAGS)'
3262 'INT *note gnutls_x509_privkey_export_pkcs8:: (gnutls_x509_privkey_t KEY, gnutls_x509_crt_fmt_t FORMAT, const char * PASSWORD, unsigned int FLAGS, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE)'
3263 'INT *note gnutls_x509_privkey_export2_pkcs8:: (gnutls_x509_privkey_t KEY, gnutls_x509_crt_fmt_t FORMAT, const char * PASSWORD, unsigned int FLAGS, gnutls_datum_t * OUT)'
3266 Unencrypted private key.
3267 'GNUTLS_PKCS_PKCS12_3DES'
3269 'GNUTLS_PKCS_PKCS12_ARCFOUR'
3271 'GNUTLS_PKCS_PKCS12_RC2_40'
3273 'GNUTLS_PKCS_PBES2_3DES'
3275 'GNUTLS_PKCS_PBES2_AES_128'
3277 'GNUTLS_PKCS_PBES2_AES_192'
3279 'GNUTLS_PKCS_PBES2_AES_256'
3281 'GNUTLS_PKCS_NULL_PASSWORD'
3282 Some schemas distinguish between an empty and a NULL password.
3283 'GNUTLS_PKCS_PBES2_DES'
3286 Figure 4.6: Encryption flags
3291 A PKCS #12 structure [_PKCS12_] usually contains a user's private keys
3292 and certificates. It is commonly used in browsers to export and import
3293 the user's identities. A file containing such a key can be directly
3294 imported to a certificate credentials structure by using *note
3295 gnutls_certificate_set_x509_simple_pkcs12_file::.
3297 In GnuTLS the PKCS #12 structures are handled using the
3298 'gnutls_pkcs12_t' type. This is an abstract type that may hold several
3299 'gnutls_pkcs12_bag_t' types. The bag types are the holders of the
3300 actual data, which may be certificates, private keys or encrypted data.
3301 A bag of type encrypted should be decrypted in order for its data to be
3304 To reduce the complexity in parsing the structures the simple helper
3305 function *note gnutls_pkcs12_simple_parse:: is provided. For more
3306 advanced uses, manual parsing of the structure is required using the
3309 'INT *note gnutls_pkcs12_get_bag:: (gnutls_pkcs12_t PKCS12, int INDX, gnutls_pkcs12_bag_t BAG)'
3310 'INT *note gnutls_pkcs12_verify_mac:: (gnutls_pkcs12_t PKCS12, const char * PASS)'
3311 'INT *note gnutls_pkcs12_bag_decrypt:: (gnutls_pkcs12_bag_t BAG, const char * PASS)'
3312 'INT *note gnutls_pkcs12_bag_get_count:: (gnutls_pkcs12_bag_t BAG)'
3314 -- Function: int gnutls_pkcs12_simple_parse (gnutls_pkcs12_t P12, const
3315 char * PASSWORD, gnutls_x509_privkey_t * KEY,
3316 gnutls_x509_crt_t ** CHAIN, unsigned int * CHAIN_LEN,
3317 gnutls_x509_crt_t ** EXTRA_CERTS, unsigned int *
3318 EXTRA_CERTS_LEN, gnutls_x509_crl_t * CRL, unsigned int FLAGS)
3321 PASSWORD: optional password used to decrypt the structure, bags and
3324 KEY: a structure to store the parsed private key.
3326 CHAIN: the corresponding to key certificate chain (may be 'NULL' )
3328 CHAIN_LEN: will be updated with the number of additional (may be
3331 EXTRA_CERTS: optional pointer to receive an array of additional
3332 certificates found in the PKCS12 structure (may be 'NULL' ).
3334 EXTRA_CERTS_LEN: will be updated with the number of additional
3335 certs (may be 'NULL' ).
3337 CRL: an optional structure to store the parsed CRL (may be 'NULL'
3340 FLAGS: should be zero or one of GNUTLS_PKCS12_SP_*
3342 This function parses a PKCS12 structure in 'pkcs12' and extracts
3343 the private key, the corresponding certificate chain, any
3344 additional certificates and a CRL.
3346 The 'extra_certs' and 'extra_certs_len' parameters are optional and
3347 both may be set to 'NULL' . If either is non-'NULL' , then both
3348 must be set. The value for 'extra_certs' is allocated using
3351 Encrypted PKCS12 bags and PKCS8 private keys are supported, but
3352 only with password based security and the same password for all
3355 Note that a PKCS12 structure may contain many keys and/or
3356 certificates, and there is no way to identify which key/certificate
3357 pair you want. For this reason this function is useful for PKCS12
3358 files that contain only one key/certificate pair and/or one CRL.
3360 If the provided structure has encrypted fields but no password is
3361 provided then this function returns 'GNUTLS_E_DECRYPTION_FAILED' .
3363 Note that normally the chain constructed does not include self
3364 signed certificates, to comply with TLS' requirements. If,
3365 however, the flag 'GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED' is
3366 specified then self signed certificates will be included in the
3369 Prior to using this function the PKCS '12' structure integrity must
3370 be verified using 'gnutls_pkcs12_verify_mac()' .
3372 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3373 otherwise a negative error value.
3376 'INT *note gnutls_pkcs12_bag_get_data:: (gnutls_pkcs12_bag_t BAG, int INDX, gnutls_datum_t * DATA)'
3377 'INT *note gnutls_pkcs12_bag_get_key_id:: (gnutls_pkcs12_bag_t BAG, int INDX, gnutls_datum_t * ID)'
3378 'INT *note gnutls_pkcs12_bag_get_friendly_name:: (gnutls_pkcs12_bag_t BAG, int INDX, char ** NAME)'
3380 The functions below are used to generate a PKCS #12 structure. An
3381 example of their usage is shown at *note PKCS12 structure generation
3384 'INT *note gnutls_pkcs12_set_bag:: (gnutls_pkcs12_t PKCS12, gnutls_pkcs12_bag_t BAG)'
3385 'INT *note gnutls_pkcs12_bag_encrypt:: (gnutls_pkcs12_bag_t BAG, const char * PASS, unsigned int FLAGS)'
3386 'INT *note gnutls_pkcs12_generate_mac:: (gnutls_pkcs12_t PKCS12, const char * PASS)'
3387 'INT *note gnutls_pkcs12_bag_set_data:: (gnutls_pkcs12_bag_t BAG, gnutls_pkcs12_bag_type_t TYPE, const gnutls_datum_t * DATA)'
3388 'INT *note gnutls_pkcs12_bag_set_crl:: (gnutls_pkcs12_bag_t BAG, gnutls_x509_crl_t CRL)'
3389 'INT *note gnutls_pkcs12_bag_set_crt:: (gnutls_pkcs12_bag_t BAG, gnutls_x509_crt_t CRT)'
3390 'INT *note gnutls_pkcs12_bag_set_key_id:: (gnutls_pkcs12_bag_t BAG, int INDX, const gnutls_datum_t * ID)'
3391 'INT *note gnutls_pkcs12_bag_set_friendly_name:: (gnutls_pkcs12_bag_t BAG, int INDX, const char * NAME)'
3393 OpenSSL encrypted keys
3394 ......................
3396 Unfortunately the structures discussed in the previous sections are not
3397 the only structures that may hold an encrypted private key. For example
3398 the OpenSSL library offers a custom key encryption method. Those
3399 structures are also supported in GnuTLS with *note
3400 gnutls_x509_privkey_import_openssl::.
3402 -- Function: int gnutls_x509_privkey_import_openssl
3403 (gnutls_x509_privkey_t KEY, const gnutls_datum_t * DATA, const
3405 KEY: The data to store the parsed key
3407 DATA: The DER or PEM encoded key.
3409 PASSWORD: the password to decrypt the key (if it is encrypted).
3411 This function will convert the given PEM encrypted to the native
3412 gnutls_x509_privkey_t format. The output will be stored in 'key' .
3414 The 'password' should be in ASCII. If the password is not provided
3415 or wrong then 'GNUTLS_E_DECRYPTION_FAILED' will be returned.
3417 If the Certificate is PEM encoded it should have a header of
3418 "PRIVATE KEY" and the "DEK-Info" header.
3420 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
3421 otherwise a negative error value.
3424 File: gnutls.info, Node: certtool Invocation, Next: ocsptool Invocation, Prev: Managing encrypted keys, Up: More on certificate authentication
3426 4.2.5 Invoking certtool
3427 -----------------------
3429 Tool to parse and generate X.509 certificates, requests and private
3430 keys. It can be used interactively or non interactively by specifying
3431 the template command line option.
3433 The tool accepts files or URLs supported by GnuTLS. In case PIN is
3434 required for the URL access you can provide it using the environment
3435 variables GNUTLS_PIN and GNUTLS_SO_PIN.
3437 This section was generated by *AutoGen*, using the 'agtexi-cmd' template
3438 and the option descriptions for the 'certtool' program. This software
3439 is released under the GNU General Public License, version 3 or later.
3441 certtool help/usage ('--help')
3442 ..............................
3444 This is the automatically generated usage text for certtool.
3446 The text printed is the same whether selected with the 'help' option
3447 ('--help') or the 'more-help' option ('--more-help'). 'more-help' will
3448 print the usage text by passing it through a pager program. 'more-help'
3449 is disabled on platforms without a working 'fork(2)' function. The
3450 'PAGER' environment variable is used to select the program, defaulting
3451 to 'more'. Both will exit with a status code of 0.
3453 certtool - GnuTLS certificate tool
3454 Usage: certtool [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
3456 -d, --debug=num Enable debugging
3457 - it must be in the range:
3459 -V, --verbose More verbose output
3460 - may appear multiple times
3461 --infile=file Input file
3462 - file must pre-exist
3463 --outfile=str Output file
3464 -s, --generate-self-signed Generate a self-signed certificate
3465 -c, --generate-certificate Generate a signed certificate
3466 --generate-proxy Generates a proxy certificate
3467 --generate-crl Generate a CRL
3468 -u, --update-certificate Update a signed certificate
3469 -p, --generate-privkey Generate a private key
3470 -q, --generate-request Generate a PKCS #10 certificate request
3471 - prohibits the option 'infile'
3472 -e, --verify-chain Verify a PEM encoded certificate chain
3473 --verify Verify a PEM encoded certificate chain using a trusted list
3474 --verify-crl Verify a CRL using a trusted list
3475 - requires the option 'load-ca-certificate'
3476 --verify-hostname=str Specify a hostname to be used for certificate chain verification
3477 --verify-email=str Specify a email to be used for certificate chain verification
3478 - prohibits the option 'verify-hostname'
3479 --verify-purpose=str Specify a purpose OID to be used for certificate chain verification
3480 --generate-dh-params Generate PKCS #3 encoded Diffie-Hellman parameters
3481 --get-dh-params Get the included PKCS #3 encoded Diffie-Hellman parameters
3482 --dh-info Print information PKCS #3 encoded Diffie-Hellman parameters
3483 --load-privkey=str Loads a private key file
3484 --load-pubkey=str Loads a public key file
3485 --load-request=str Loads a certificate request file
3486 --load-certificate=str Loads a certificate file
3487 --load-ca-privkey=str Loads the certificate authority's private key file
3488 --load-ca-certificate=str Loads the certificate authority's certificate file
3489 --load-crl=str Loads the provided CRL
3490 --load-data=str Loads auxilary data
3491 --password=str Password to use
3492 --null-password Enforce a NULL password
3493 --empty-password Enforce an empty password
3494 --hex-numbers Print big number in an easier format to parse
3495 --cprint In certain operations it prints the information in C-friendly format
3496 -i, --certificate-info Print information on the given certificate
3497 --fingerprint Print the fingerprint of the given certificate
3498 --key-id Print the key ID of the given certificate
3499 --certificate-pubkey Print certificate's public key
3500 --pgp-certificate-info Print information on the given OpenPGP certificate
3501 --pgp-ring-info Print information on the given OpenPGP keyring structure
3502 -l, --crl-info Print information on the given CRL structure
3503 --crq-info Print information on the given certificate request
3504 --no-crq-extensions Do not use extensions in certificate requests
3505 -!, --p12-info Print information on a PKCS #12 structure
3506 -", --p12-name=str The PKCS #12 friendly name to use
3507 -#, --p7-generate Generate a PKCS #7 structure
3508 -$, --p7-sign Signs using a PKCS #7 structure
3509 -%, --p7-detached-sign Signs using a detached PKCS #7 structure
3510 -&, --p7-include-cert The signer's certificate will be included in the cert list.
3511 - disabled as '--no-p7-include-cert'
3512 - enabled by default
3513 -', --p7-time Will include a timestamp in the PKCS #7 structure
3514 -(, --p7-show-data Will show the embedded data in the PKCS #7 structure
3515 - disabled as '--no-p7-show-data'
3516 -), --p7-info Print information on a PKCS #7 structure
3517 -*, --p7-verify Verify the provided PKCS #7 structure
3518 -+, --p8-info Print information on a PKCS #8 structure
3519 -,, --smime-to-p7 Convert S/MIME to PKCS #7 structure
3520 -k, --key-info Print information on a private key
3521 --, --pgp-key-info Print information on an OpenPGP private key
3522 -., --pubkey-info Print information on a public key
3523 -/, --v1 Generate an X.509 version 1 certificate (with no extensions)
3524 -0, --to-p12 Generate a PKCS #12 structure
3525 - requires the option 'load-certificate'
3526 -1, --to-p8 Generate a PKCS #8 structure
3527 -8, --pkcs8 Use PKCS #8 format for private keys
3528 -2, --rsa Generate RSA key
3529 -3, --dsa Generate DSA key
3530 -4, --ecc Generate ECC (ECDSA) key
3531 -5, --ecdsa an alias for the 'ecc' option
3532 -6, --hash=str Hash algorithm to use for signing
3533 -7, --inder Use DER format for input certificates, private keys, and DH parameters
3534 - disabled as '--no-inder'
3535 -8, --inraw an alias for the 'inder' option
3536 -9, --outder Use DER format for output certificates, private keys, and DH parameters
3537 - disabled as '--no-outder'
3538 -:, --outraw an alias for the 'outder' option
3539 -;, --bits=num Specify the number of bits for key generate
3540 -<, --curve=str Specify the curve used for EC key generation
3541 -=, --sec-param=str Specify the security level [low, legacy, medium, high, ultra]
3542 ->, --disable-quick-random No effect
3543 -?, --template=str Template file to use for non-interactive operation
3544 -@, --stdout-info Print information to stdout instead of stderr
3545 -A, --ask-pass Enable interaction for entering password when in batch mode.
3546 -B, --pkcs-cipher=str Cipher to use for PKCS #8 and #12 operations
3547 -C, --provider=str Specify the PKCS #11 provider library
3548 -v, --version[=arg] output version information and exit
3549 -h, --help display extended usage information and exit
3550 -!, --more-help extended usage information passed thru pager
3552 Options are specified by doubled hyphens and their name or by a single
3553 hyphen and the flag character.
3555 Tool to parse and generate X.509 certificates, requests and private keys.
3556 It can be used interactively or non interactively by specifying the
3557 template command line option.
3559 The tool accepts files or URLs supported by GnuTLS. In case PIN is
3560 required for the URL access you can provide it using the environment
3561 variables GNUTLS_PIN and GNUTLS_SO_PIN.
3567 This is the "enable debugging" option. This option takes a number
3568 argument. Specifies the debug level.
3573 This is the "generate a crl" option. This option generates a CRL. When
3574 combined with -load-crl it would use the loaded CRL as base for the
3575 generated (i.e., all revoked certificates in the base will be copied to
3578 generate-request option (-q)
3579 ............................
3581 This is the "generate a pkcs #10 certificate request" option.
3583 This option has some usage constraints. It:
3584 * must not appear in combination with any of the following options:
3587 Will generate a PKCS #10 certificate request. To specify a private key
3590 verify-chain option (-e)
3591 ........................
3593 This is the "verify a pem encoded certificate chain" option. The last
3594 certificate in the chain must be a self signed one. It can be combined
3595 with -verify-purpose or -verify-hostname.
3600 This is the "verify a pem encoded certificate chain using a trusted
3601 list" option. The trusted certificate list can be loaded with
3602 -load-ca-certificate. If no certificate list is provided, then the
3603 system's certificate list is used. Note that during verification
3604 multiple paths may be explored. On a successful verification the
3605 successful path will be the last one. It can be combined with
3606 -verify-purpose or -verify-hostname.
3611 This is the "verify a crl using a trusted list" option.
3613 This option has some usage constraints. It:
3614 * must appear in combination with the following options:
3615 load-ca-certificate.
3617 The trusted certificate list must be loaded with -load-ca-certificate.
3619 verify-hostname option
3620 ......................
3622 This is the "specify a hostname to be used for certificate chain
3623 verification" option. This option takes a string argument. This is to
3624 be combined with one of the verify certificate options.
3629 This is the "specify a email to be used for certificate chain
3630 verification" option. This option takes a string argument.
3632 This option has some usage constraints. It:
3633 * must not appear in combination with any of the following options:
3636 This is to be combined with one of the verify certificate options.
3638 verify-purpose option
3639 .....................
3641 This is the "specify a purpose oid to be used for certificate chain
3642 verification" option. This option takes a string argument. This object
3643 identifier restricts the purpose of the certificates to be verified.
3644 Example purposes are 1.3.6.1.5.5.7.3.1 (TLS WWW), 1.3.6.1.5.5.7.3.4
3645 (EMAIL) etc. Note that a CA certificate without a purpose set (extended
3646 key usage) is valid for any purpose.
3648 get-dh-params option
3649 ....................
3651 This is the "get the included pkcs #3 encoded diffie-hellman parameters"
3652 option. Returns stored DH parameters in GnuTLS. Those parameters are
3653 used in the SRP protocol. The parameters returned by fresh generation
3654 are more efficient since GnuTLS 3.0.9.
3659 This is the "loads a private key file" option. This option takes a
3660 string argument. This can be either a file or a PKCS #11 URL
3665 This is the "loads a public key file" option. This option takes a
3666 string argument. This can be either a file or a PKCS #11 URL
3668 load-certificate option
3669 .......................
3671 This is the "loads a certificate file" option. This option takes a
3672 string argument. This can be either a file or a PKCS #11 URL
3674 load-ca-privkey option
3675 ......................
3677 This is the "loads the certificate authority's private key file" option.
3678 This option takes a string argument. This can be either a file or a
3681 load-ca-certificate option
3682 ..........................
3684 This is the "loads the certificate authority's certificate file" option.
3685 This option takes a string argument. This can be either a file or a
3691 This is the "password to use" option. This option takes a string
3692 argument. You can use this option to specify the password in the
3693 command line instead of reading it from the tty. Note, that the command
3694 line arguments are available for view in others in the system.
3695 Specifying password as " is the same as specifying no password.
3697 null-password option
3698 ....................
3700 This is the "enforce a null password" option. This option enforces a
3701 NULL password. This is different than the empty or no password in
3702 schemas like PKCS #8.
3704 empty-password option
3705 .....................
3707 This is the "enforce an empty password" option. This option enforces an
3708 empty password. This is different than the NULL or no password in
3709 schemas like PKCS #8.
3714 This is the "in certain operations it prints the information in
3715 c-friendly format" option. In certain operations it prints the
3716 information in C-friendly format, suitable for including into C
3722 This is the "print the fingerprint of the given certificate" option.
3723 This is a simple hash of the DER encoding of the certificate. It can be
3724 combined with the -hash parameter. However, it is recommended for
3725 identification to use the key-id which depends only on the certificate's
3731 This is the "print the key id of the given certificate" option. This is
3732 a hash of the public key of the given certificate. It identifies the
3733 key uniquely, remains the same on a certificate renewal and depends only
3734 on signed fields of the certificate.
3739 This is the "print information on a pkcs #12 structure" option. This
3740 option will dump the contents and print the metadata of the provided
3746 This is the "the pkcs #12 friendly name to use" option. This option
3747 takes a string argument. The name to be used for the primary
3748 certificate and private key in a PKCS #12 file.
3753 This is the "generate a pkcs #7 structure" option. This option
3754 generates a PKCS #7 certificate container structure. To add
3755 certificates in the structure use -load-certificate and -load-crl.
3760 This is the "signs using a pkcs #7 structure" option. This option
3761 generates a PKCS #7 structure containing a signature for the provided
3762 data. The data are stored within the structure. The signer certificate
3763 has to be specified using -load-certificate and -load-privkey.
3765 p7-detached-sign option
3766 .......................
3768 This is the "signs using a detached pkcs #7 structure" option. This
3769 option generates a PKCS #7 structure containing a signature for the
3770 provided data. The signer certificate has to be specified using
3771 -load-certificate and -load-privkey.
3773 p7-include-cert option
3774 ......................
3776 This is the "the signer's certificate will be included in the cert
3779 This option has some usage constraints. It:
3780 * can be disabled with -no-p7-include-cert.
3781 * It is enabled by default.
3783 This options works with -p7-sign or -p7-detached-sign and will include
3784 or exclude the signer's certificate into the generated signature.
3789 This is the "will include a timestamp in the pkcs #7 structure" option.
3790 This option will include a timestamp in the generated signature
3795 This is the "will show the embedded data in the pkcs #7 structure"
3798 This option has some usage constraints. It:
3799 * can be disabled with -no-p7-show-data.
3801 This option can be combined with -p7-verify and will display the
3802 embedded signed data in the PKCS #7 structure.
3807 This is the "verify the provided pkcs #7 structure" option. This option
3808 verifies the signed PKCS #7 structure. The certificate list to use for
3809 verification can be specified with -load-ca-certificate. When no
3810 certificate list is provided, then the system's certificate list is
3811 used. Alternatively a direct signer can be provided using
3812 -load-certificate. A key purpose can be enforced with the
3813 -verify-purpose option, and the -load-data option will utilize detached
3819 This is the "print information on a pkcs #8 structure" option. This
3820 option will print information about encrypted PKCS #8 structures. That
3821 option does not require the decryption of the structure.
3826 This is the "print information on a public key" option. The option
3827 combined with -load-request, -load-pubkey, -load-privkey and
3828 -load-certificate will extract the public key of the object in question.
3833 This is the "generate a pkcs #12 structure" option.
3835 This option has some usage constraints. It:
3836 * must appear in combination with the following options:
3839 It requires a certificate, a private key and possibly a CA certificate
3845 This is the "generate rsa key" option. When combined with
3846 -generate-privkey generates an RSA private key.
3851 This is the "generate dsa key" option. When combined with
3852 -generate-privkey generates a DSA private key.
3857 This is the "generate ecc (ecdsa) key" option. When combined with
3858 -generate-privkey generates an elliptic curve private key to be used
3864 This is an alias for the 'ecc' option, *note the ecc option
3865 documentation: certtool ecc.
3870 This is the "hash algorithm to use for signing" option. This option
3871 takes a string argument. Available hash functions are SHA1, RMD160,
3872 SHA256, SHA384, SHA512.
3877 This is the "use der format for input certificates, private keys, and dh
3878 parameters " option.
3880 This option has some usage constraints. It:
3881 * can be disabled with -no-inder.
3883 The input files will be assumed to be in DER or RAW format. Unlike
3884 options that in PEM input would allow multiple input data (e.g.
3885 multiple certificates), when reading in DER format a single data
3891 This is an alias for the 'inder' option, *note the inder option
3892 documentation: certtool inder.
3897 This is the "use der format for output certificates, private keys, and
3898 dh parameters" option.
3900 This option has some usage constraints. It:
3901 * can be disabled with -no-outder.
3903 The output will be in DER or RAW format.
3908 This is an alias for the 'outder' option, *note the outder option
3909 documentation: certtool outder.
3914 This is the "specify the curve used for ec key generation" option. This
3915 option takes a string argument. Supported values are secp192r1,
3916 secp224r1, secp256r1, secp384r1 and secp521r1.
3921 This is the "specify the security level [low, legacy, medium, high,
3922 ultra]" option. This option takes a string argument 'Security
3923 parameter'. This is alternative to the bits option.
3928 This is the "enable interaction for entering password when in batch
3929 mode." option. This option will enable interaction to enter password
3930 when in batch mode. That is useful when the template option has been
3936 This is the "cipher to use for pkcs #8 and #12 operations" option. This
3937 option takes a string argument 'Cipher'. Cipher may be one of 3des,
3938 3des-pkcs12, aes-128, aes-192, aes-256, rc2-40, arcfour.
3943 This is the "specify the pkcs #11 provider library" option. This option
3944 takes a string argument. This will override the default options in
3945 /etc/gnutls/pkcs11.conf
3947 certtool exit status
3948 ....................
3950 One of the following exit values will be returned:
3952 Successful program execution.
3954 The operation failed or the command syntax was not valid.
3964 Generating private keys
3965 .......................
3967 To create an RSA private key, run:
3968 $ certtool --generate-privkey --outfile key.pem --rsa
3970 To create a DSA or elliptic curves (ECDSA) private key use the above
3971 command combined with 'dsa' or 'ecc' options.
3973 Generating certificate requests
3974 ...............................
3976 To create a certificate request (needed when the certificate is issued
3977 by another party), run:
3978 certtool --generate-request --load-privkey key.pem \
3979 --outfile request.pem
3981 If the private key is stored in a smart card you can generate a request
3982 by specifying the private key object URL.
3983 $ ./certtool --generate-request --load-privkey "pkcs11:..." \
3984 --load-pubkey "pkcs11:..." --outfile request.pem
3986 Generating a self-signed certificate
3987 ....................................
3989 To create a self signed certificate, use the command:
3990 $ certtool --generate-privkey --outfile ca-key.pem
3991 $ certtool --generate-self-signed --load-privkey ca-key.pem \
3992 --outfile ca-cert.pem
3994 Note that a self-signed certificate usually belongs to a certificate
3995 authority, that signs other certificates.
3997 Generating a certificate
3998 ........................
4000 To generate a certificate using the previous request, use the command:
4001 $ certtool --generate-certificate --load-request request.pem \
4002 --outfile cert.pem --load-ca-certificate ca-cert.pem \
4003 --load-ca-privkey ca-key.pem
4005 To generate a certificate using the private key only, use the command:
4006 $ certtool --generate-certificate --load-privkey key.pem \
4007 --outfile cert.pem --load-ca-certificate ca-cert.pem \
4008 --load-ca-privkey ca-key.pem
4010 Certificate information
4011 .......................
4013 To view the certificate information, use:
4014 $ certtool --certificate-info --infile cert.pem
4016 PKCS #12 structure generation
4017 .............................
4019 To generate a PKCS #12 structure using the previous key and certificate,
4021 $ certtool --load-certificate cert.pem --load-privkey key.pem \
4022 --to-p12 --outder --outfile key.p12
4024 Some tools (reportedly web browsers) have problems with that file
4025 because it does not contain the CA certificate for the certificate. To
4026 work around that problem in the tool, you can use the
4027 -load-ca-certificate parameter as follows:
4029 $ certtool --load-ca-certificate ca.pem \
4030 --load-certificate cert.pem --load-privkey key.pem \
4031 --to-p12 --outder --outfile key.p12
4033 Diffie-Hellman parameter generation
4034 ...................................
4036 To generate parameters for Diffie-Hellman key exchange, use the command:
4037 $ certtool --generate-dh-params --outfile dh.pem --sec-param medium
4039 Proxy certificate generation
4040 ............................
4042 Proxy certificate can be used to delegate your credential to a
4043 temporary, typically short-lived, certificate. To create one from the
4044 previously created certificate, first create a temporary key and then
4045 generate a proxy certificate for it, using the commands:
4047 $ certtool --generate-privkey > proxy-key.pem
4048 $ certtool --generate-proxy --load-ca-privkey key.pem \
4049 --load-privkey proxy-key.pem --load-certificate cert.pem \
4050 --outfile proxy-cert.pem
4052 Certificate revocation list generation
4053 ......................................
4055 To create an empty Certificate Revocation List (CRL) do:
4057 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
4058 --load-ca-certificate x509-ca.pem
4060 To create a CRL that contains some revoked certificates, place the
4061 certificates in a file and use '--load-certificate' as follows:
4063 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
4064 --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
4066 To verify a Certificate Revocation List (CRL) do:
4068 $ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
4073 Certtool's template file format
4074 ...............................
4076 A template file can be used to avoid the interactive questions of
4077 certtool. Initially create a file named 'cert.cfg' that contains the
4078 information about the certificate. The template can be used as below:
4080 $ certtool --generate-certificate --load-privkey key.pem \
4081 --template cert.cfg --outfile cert.pem \
4082 --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
4084 An example certtool template file that can be used to generate a
4085 certificate request or a self signed certificate follows.
4087 # X.509 Certificate options
4091 # The organization of the subject.
4092 organization = "Koko inc."
4094 # The organizational unit of the subject.
4095 unit = "sleeping dept."
4097 # The locality of the subject.
4100 # The state of the certificate owner.
4103 # The country of the subject. Two letter code.
4106 # The common name of the certificate owner.
4109 # A user id of the certificate owner.
4112 # Set domain components
4116 # If the supported DN OIDs are not adequate you can set
4118 # For example set the X.520 Title and the X.520 Pseudonym
4119 # by using OID and string pairs.
4120 #dn_oid = 2.5.4.12 Dr.
4121 #dn_oid = 2.5.4.65 jackal
4123 # This is deprecated and should not be used in new
4125 # pkcs9_email = "none@none.org"
4127 # An alternative way to set the certificate's distinguished name directly
4128 # is with the "dn" option. The attribute names allowed are:
4129 # C (country), street, O (organization), OU (unit), title, CN (common name),
4130 # L (locality), ST (state), placeOfBirth, gender, countryOfCitizenship,
4131 # countryOfResidence, serialNumber, telephoneNumber, surName, initials,
4132 # generationQualifier, givenName, pseudonym, dnQualifier, postalCode, name,
4133 # businessCategory, DC, UID, jurisdictionOfIncorporationLocalityName,
4134 # jurisdictionOfIncorporationStateOrProvinceName,
4135 # jurisdictionOfIncorporationCountryName, XmppAddr, and numeric OIDs.
4137 #dn = "cn = Nikos,st = New\, Something,C=GR,surName=Mavrogiannopoulos,2.5.4.9=Arkadias"
4139 # The serial number of the certificate
4140 # Comment the field for a time-based serial number.
4143 # In how many days, counting from today, this certificate will expire.
4144 # Use -1 if there is no expiration date.
4145 expiration_days = 700
4147 # Alternatively you may set concrete dates and time. The GNU date string
4148 # formats are accepted. See:
4149 # http://www.gnu.org/software/tar/manual/html_node/Date-input-formats.html
4151 #activation_date = "2004-02-29 16:21:42"
4152 #expiration_date = "2025-02-29 16:24:41"
4154 # X.509 v3 extensions
4156 # A dnsname in case of a WWW server.
4157 #dns_name = "www.none.org"
4158 #dns_name = "www.morethanone.org"
4160 # A subject alternative name URI
4161 #uri = "http://www.example.com"
4163 # An IP address in case of a server.
4164 #ip_address = "192.168.1.1"
4166 # An email in case of a person
4167 email = "none@none.org"
4169 # Challenge password used in certificate requests
4170 challenge_password = 123456
4172 # Password when encrypting a private key
4175 # An URL that has CRLs (certificate revocation lists)
4176 # available. Needed in CA certificates.
4177 #crl_dist_points = "http://www.getcrl.crl/getcrl/"
4179 # Whether this is a CA certificate or not
4182 # Subject Unique ID (in hex)
4183 #subject_unique_id = 00153224
4185 # Issuer Unique ID (in hex)
4186 #issuer_unique_id = 00153225
4190 # The following key usage flags are used by CAs and end certificates
4192 # Whether this certificate will be used to sign data (needed
4193 # in TLS DHE ciphersuites). This is the digitalSignature flag
4194 # in RFC5280 terminology.
4197 # Whether this certificate will be used to encrypt data (needed
4198 # in TLS RSA ciphersuites). Note that it is preferred to use different
4199 # keys for encryption and signing. This is the keyEncipherment flag
4200 # in RFC5280 terminology.
4203 # Whether this key will be used to sign other certificates. The
4204 # keyCertSign flag in RFC5280 terminology.
4207 # Whether this key will be used to sign CRLs. The
4208 # cRLSign flag in RFC5280 terminology.
4211 # The keyAgreement flag of RFC5280. It's purpose is loosely
4212 # defined. Not use it unless required by a protocol.
4215 # The dataEncipherment flag of RFC5280. It's purpose is loosely
4216 # defined. Not use it unless required by a protocol.
4219 # The nonRepudiation flag of RFC5280. It's purpose is loosely
4220 # defined. Not use it unless required by a protocol.
4223 #### Extended key usage (key purposes)
4225 # The following extensions are used in an end certificate
4226 # to clarify its purpose. Some CAs also use it to indicate
4227 # the types of certificates they are purposed to sign.
4230 # Whether this certificate will be used for a TLS client;
4231 # this sets the id-kp-serverAuth (1.3.6.1.5.5.7.3.1) of
4232 # extended key usage.
4235 # Whether this certificate will be used for a TLS server;
4236 # This sets the id-kp-clientAuth (1.3.6.1.5.5.7.3.2) of
4237 # extended key usage.
4240 # Whether this key will be used to sign code. This sets the
4241 # id-kp-codeSigning (1.3.6.1.5.5.7.3.3) of extended key usage
4245 # Whether this key will be used to sign OCSP data. This sets the
4246 # id-kp-OCSPSigning (1.3.6.1.5.5.7.3.9) of extended key usage extension.
4249 # Whether this key will be used for time stamping. This sets the
4250 # id-kp-timeStamping (1.3.6.1.5.5.7.3.8) of extended key usage extension.
4253 # Whether this key will be used for email protection. This sets the
4254 # id-kp-emailProtection (1.3.6.1.5.5.7.3.4) of extended key usage extension.
4255 #email_protection_key
4257 # Whether this key will be used for IPsec IKE operations (1.3.6.1.5.5.7.3.17).
4260 ## adding custom key purpose OIDs
4262 # for microsoft smart card logon
4263 # key_purpose_oid = 1.3.6.1.4.1.311.20.2.2
4265 # for email protection
4266 # key_purpose_oid = 1.3.6.1.5.5.7.3.4
4268 # for any purpose (must not be used in intermediate CA certificates)
4269 # key_purpose_oid = 2.5.29.37.0
4271 ### end of key purpose OIDs
4273 # When generating a certificate from a certificate
4274 # request, then honor the extensions stored in the request
4275 # and store them in the real certificate.
4276 #honor_crq_extensions
4278 # Path length contraint. Sets the maximum number of
4279 # certificates that can be used to certify this certificate.
4280 # (i.e. the certificate chain length)
4285 # ocsp_uri = http://my.ocsp.server/ocsp
4288 # ca_issuers_uri = http://my.ca.issuer
4290 # Certificate policies
4291 #policy1 = 1.3.6.1.4.1.5484.1.10.99.1.0
4292 #policy1_txt = "This is a long policy to summarize"
4293 #policy1_url = http://www.example.com/a-policy-to-read
4295 #policy2 = 1.3.6.1.4.1.5484.1.10.99.1.1
4296 #policy2_txt = "This is a short policy"
4297 #policy2_url = http://www.example.com/another-policy-to-read
4302 #nc_permit_dns = example.com
4303 #nc_exclude_dns = test.example.com
4306 #nc_permit_email = "nmav@ex.net"
4308 # Exclude subdomains of example.com
4309 #nc_exclude_email = .example.com
4311 # Exclude all e-mail addresses of example.com
4312 #nc_exclude_email = example.com
4315 # Options for proxy certificates
4316 #proxy_policy_language = 1.3.6.1.5.5.7.21.1
4319 # Options for generating a CRL
4321 # The number of days the next CRL update will be due.
4322 # next CRL update will be in 43 days
4323 #crl_next_update = 43
4325 # this is the 5th CRL by this CA
4326 # Comment the field for a time-based number.
4329 # Specify the update dates more precisely.
4330 #crl_this_update_date = "2004-02-29 16:21:42"
4331 #crl_next_update_date = "2025-02-29 16:24:41"
4333 # The date that the certificates will be made seen as
4335 #crl_revocation_date = "2025-02-29 16:24:41"
4339 File: gnutls.info, Node: ocsptool Invocation, Next: danetool Invocation, Prev: certtool Invocation, Up: More on certificate authentication
4341 4.2.6 Invoking ocsptool
4342 -----------------------
4344 Ocsptool is a program that can parse and print information about OCSP
4345 requests/responses, generate requests and verify responses.
4347 This section was generated by *AutoGen*, using the 'agtexi-cmd' template
4348 and the option descriptions for the 'ocsptool' program. This software
4349 is released under the GNU General Public License, version 3 or later.
4351 ocsptool help/usage ('--help')
4352 ..............................
4354 This is the automatically generated usage text for ocsptool.
4356 The text printed is the same whether selected with the 'help' option
4357 ('--help') or the 'more-help' option ('--more-help'). 'more-help' will
4358 print the usage text by passing it through a pager program. 'more-help'
4359 is disabled on platforms without a working 'fork(2)' function. The
4360 'PAGER' environment variable is used to select the program, defaulting
4361 to 'more'. Both will exit with a status code of 0.
4363 ocsptool - GnuTLS OCSP tool
4364 Usage: ocsptool [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
4366 -d, --debug=num Enable debugging
4367 - it must be in the range:
4369 -V, --verbose More verbose output
4370 - may appear multiple times
4371 --infile=file Input file
4372 - file must pre-exist
4373 --outfile=str Output file
4374 --ask[=arg] Ask an OCSP/HTTP server on a certificate validity
4375 - requires these options:
4378 -e, --verify-response Verify response
4379 -i, --request-info Print information on a OCSP request
4380 -j, --response-info Print information on a OCSP response
4381 -q, --generate-request Generate an OCSP request
4382 --nonce Use (or not) a nonce to OCSP request
4383 - disabled as '--no-nonce'
4384 --load-issuer=file Read issuer certificate from file
4385 - file must pre-exist
4386 --load-cert=file Read certificate to check from file
4387 - file must pre-exist
4388 --load-trust=file Read OCSP trust anchors from file
4389 - prohibits the option 'load-signer'
4390 - file must pre-exist
4391 --load-signer=file Read OCSP response signer from file
4392 - prohibits the option 'load-trust'
4393 - file must pre-exist
4394 --inder Use DER format for input certificates and private keys
4395 - disabled as '--no-inder'
4396 -Q, --load-request=file Read DER encoded OCSP request from file
4397 - file must pre-exist
4398 -S, --load-response=file Read DER encoded OCSP response from file
4399 - file must pre-exist
4400 --ignore-errors Ignore any verification errors
4401 -v, --version[=arg] output version information and exit
4402 -h, --help display extended usage information and exit
4403 -!, --more-help extended usage information passed thru pager
4405 Options are specified by doubled hyphens and their name or by a single
4406 hyphen and the flag character.
4408 Ocsptool is a program that can parse and print information about OCSP
4409 requests/responses, generate requests and verify responses.
4415 This is the "enable debugging" option. This option takes a number
4416 argument. Specifies the debug level.
4421 This is the "ask an ocsp/http server on a certificate validity" option.
4422 This option takes an optional string argument 'server name|url'.
4424 This option has some usage constraints. It:
4425 * must appear in combination with the following options: load-cert,
4428 Connects to the specified HTTP OCSP server and queries on the validity
4429 of the loaded certificate.
4431 ocsptool exit status
4432 ....................
4434 One of the following exit values will be returned:
4436 Successful program execution.
4438 The operation failed or the command syntax was not valid.
4448 Print information about an OCSP request
4449 .......................................
4451 To parse an OCSP request and print information about the content, the
4452 '-i' or '--request-info' parameter may be used as follows. The '-Q'
4453 parameter specify the name of the file containing the OCSP request, and
4454 it should contain the OCSP request in binary DER format.
4456 $ ocsptool -i -Q ocsp-request.der
4458 The input file may also be sent to standard input like this:
4460 $ cat ocsp-request.der | ocsptool --request-info
4462 Print information about an OCSP response
4463 ........................................
4465 Similar to parsing OCSP requests, OCSP responses can be parsed using the
4466 '-j' or '--response-info' as follows.
4468 $ ocsptool -j -Q ocsp-response.der
4469 $ cat ocsp-response.der | ocsptool --response-info
4471 Generate an OCSP request
4472 ........................
4474 The '-q' or '--generate-request' parameters are used to generate an OCSP
4475 request. By default the OCSP request is written to standard output in
4476 binary DER format, but can be stored in a file using '--outfile'. To
4477 generate an OCSP request the issuer of the certificate to check needs to
4478 be specified with '--load-issuer' and the certificate to check with
4479 '--load-cert'. By default PEM format is used for these files, although
4480 '--inder' can be used to specify that the input files are in DER format.
4482 $ ocsptool -q --load-issuer issuer.pem --load-cert client.pem \
4483 --outfile ocsp-request.der
4485 When generating OCSP requests, the tool will add an OCSP extension
4486 containing a nonce. This behaviour can be disabled by specifying
4489 Verify signature in OCSP response
4490 .................................
4492 To verify the signature in an OCSP response the '-e' or
4493 '--verify-response' parameter is used. The tool will read an OCSP
4494 response in DER format from standard input, or from the file specified
4495 by '--load-response'. The OCSP response is verified against a set of
4496 trust anchors, which are specified using '--load-trust'. The trust
4497 anchors are concatenated certificates in PEM format. The certificate
4498 that signed the OCSP response needs to be in the set of trust anchors,
4499 or the issuer of the signer certificate needs to be in the set of trust
4500 anchors and the OCSP Extended Key Usage bit has to be asserted in the
4503 $ ocsptool -e --load-trust issuer.pem \
4504 --load-response ocsp-response.der
4506 The tool will print status of verification.
4508 Verify signature in OCSP response against given certificate
4509 ...........................................................
4511 It is possible to override the normal trust logic if you know that a
4512 certain certificate is supposed to have signed the OCSP response, and
4513 you want to use it to check the signature. This is achieved using
4514 '--load-signer' instead of '--load-trust'. This will load one
4515 certificate and it will be used to verify the signature in the OCSP
4516 response. It will not check the Extended Key Usage bit.
4518 $ ocsptool -e --load-signer ocsp-signer.pem \
4519 --load-response ocsp-response.der
4521 This approach is normally only relevant in two situations. The first is
4522 when the OCSP response does not contain a copy of the signer
4523 certificate, so the '--load-trust' code would fail. The second is if
4524 you want to avoid the indirect mode where the OCSP response signer
4525 certificate is signed by a trust anchor.
4530 Here is an example of how to generate an OCSP request for a certificate
4531 and to verify the response. For illustration we'll use the
4532 'blog.josefsson.org' host, which (as of writing) uses a certificate from
4533 CACert. First we'll use 'gnutls-cli' to get a copy of the server
4534 certificate chain. The server is not required to send this information,
4535 but this particular one is configured to do so.
4537 $ echo | gnutls-cli -p 443 blog.josefsson.org --print-cert > chain.pem
4539 Use a text editor on 'chain.pem' to create three files for each separate
4540 certificates, called 'cert.pem' for the first certificate for the domain
4541 itself, secondly 'issuer.pem' for the intermediate certificate and
4542 'root.pem' for the final root certificate.
4544 The domain certificate normally contains a pointer to where the OCSP
4545 responder is located, in the Authority Information Access Information
4546 extension. For example, from 'certtool -i < cert.pem' there is this
4549 Authority Information Access Information (not critical):
4550 Access Method: 1.3.6.1.5.5.7.48.1 (id-ad-ocsp)
4551 Access Location URI: http://ocsp.CAcert.org/
4553 This means the CA support OCSP queries over HTTP. We are now ready to
4554 create a OCSP request for the certificate.
4556 $ ocsptool --ask ocsp.CAcert.org --load-issuer issuer.pem \
4557 --load-cert cert.pem --outfile ocsp-response.der
4559 The request is sent via HTTP to the OCSP server address specified. If
4560 the address is ommited ocsptool will use the address stored in the
4564 File: gnutls.info, Node: danetool Invocation, Prev: ocsptool Invocation, Up: More on certificate authentication
4566 4.2.7 Invoking danetool
4567 -----------------------
4569 Tool to generate and check DNS resource records for the DANE protocol.
4571 This section was generated by *AutoGen*, using the 'agtexi-cmd' template
4572 and the option descriptions for the 'danetool' program. This software
4573 is released under the GNU General Public License, version 3 or later.
4575 danetool help/usage ('--help')
4576 ..............................
4578 This is the automatically generated usage text for danetool.
4580 The text printed is the same whether selected with the 'help' option
4581 ('--help') or the 'more-help' option ('--more-help'). 'more-help' will
4582 print the usage text by passing it through a pager program. 'more-help'
4583 is disabled on platforms without a working 'fork(2)' function. The
4584 'PAGER' environment variable is used to select the program, defaulting
4585 to 'more'. Both will exit with a status code of 0.
4587 danetool - GnuTLS DANE tool
4588 Usage: danetool [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
4590 -d, --debug=num Enable debugging
4591 - it must be in the range:
4593 -V, --verbose More verbose output
4594 - may appear multiple times
4595 --infile=file Input file
4596 - file must pre-exist
4597 --outfile=str Output file
4598 --load-pubkey=str Loads a public key file
4599 --load-certificate=str Loads a certificate file
4600 --dlv=str Sets a DLV file
4601 --hash=str Hash algorithm to use for signing
4602 --check=str Check a host's DANE TLSA entry
4603 --check-ee Check only the end-entity's certificate
4604 --check-ca Check only the CA's certificate
4605 --tlsa-rr Print the DANE RR data on a certificate or public key
4606 - requires the option 'host'
4607 --host=str Specify the hostname to be used in the DANE RR
4608 --proto=str The protocol set for DANE data (tcp, udp etc.)
4609 --port=num Specify the port number for the DANE data
4610 --app-proto=str an alias for the 'starttls-proto' option
4611 --starttls-proto=str The application protocol to be used to obtain the server's certificate
4612 (https, ftp, smtp, imap, ldap, xmpp)
4613 --ca Whether the provided certificate or public key is a Certificate
4615 --x509 Use the hash of the X.509 certificate, rather than the public key
4616 --local an alias for the 'domain' option
4617 - enabled by default
4618 --domain The provided certificate or public key is issued by the local domain
4619 - disabled as '--no-domain'
4620 - enabled by default
4621 --local-dns Use the local DNS server for DNSSEC resolving
4622 - disabled as '--no-local-dns'
4623 --insecure Do not verify any DNSSEC signature
4624 --inder Use DER format for input certificates and private keys
4625 - disabled as '--no-inder'
4626 --inraw an alias for the 'inder' option
4627 --print-raw Print the received DANE data in raw format
4628 - disabled as '--no-print-raw'
4629 --quiet Suppress several informational messages
4630 -v, --version[=arg] output version information and exit
4631 -h, --help display extended usage information and exit
4632 -!, --more-help extended usage information passed thru pager
4634 Options are specified by doubled hyphens and their name or by a single
4635 hyphen and the flag character.
4637 Tool to generate and check DNS resource records for the DANE protocol.
4643 This is the "enable debugging" option. This option takes a number
4644 argument. Specifies the debug level.
4649 This is the "loads a public key file" option. This option takes a
4650 string argument. This can be either a file or a PKCS #11 URL
4652 load-certificate option
4653 .......................
4655 This is the "loads a certificate file" option. This option takes a
4656 string argument. This can be either a file or a PKCS #11 URL
4661 This is the "sets a dlv file" option. This option takes a string
4662 argument. This sets a DLV file to be used for DNSSEC verification.
4667 This is the "hash algorithm to use for signing" option. This option
4668 takes a string argument. Available hash functions are SHA1, RMD160,
4669 SHA256, SHA384, SHA512.
4674 This is the "check a host's dane tlsa entry" option. This option takes
4675 a string argument. Obtains the DANE TLSA entry from the given hostname
4676 and prints information. Note that the actual certificate of the host
4677 can be provided using -load-certificate, otherwise danetool will connect
4678 to the server to obtain it. The exit code on verification success will
4684 This is the "check only the end-entity's certificate" option. Checks
4685 the end-entity's certificate only. Trust anchors or CAs are not
4691 This is the "check only the ca's certificate" option. Checks the trust
4692 anchor's and CA's certificate only. End-entities are not considered.
4697 This is the "print the dane rr data on a certificate or public key"
4700 This option has some usage constraints. It:
4701 * must appear in combination with the following options: host.
4703 This command prints the DANE RR data needed to enable DANE on a DNS
4709 This is the "specify the hostname to be used in the dane rr" option.
4710 This option takes a string argument 'Hostname'. This command sets the
4711 hostname for the DANE RR.
4716 This is the "the protocol set for dane data (tcp, udp etc.)" option.
4717 This option takes a string argument 'Protocol'. This command specifies
4718 the protocol for the service set in the DANE data.
4723 This is an alias for the 'starttls-proto' option, *note the
4724 starttls-proto option documentation: danetool starttls-proto.
4726 starttls-proto option
4727 .....................
4729 This is the "the application protocol to be used to obtain the server's
4730 certificate (https, ftp, smtp, imap, ldap, xmpp)" option. This option
4731 takes a string argument. When the server's certificate isn't provided
4732 danetool will connect to the server to obtain the certificate. In that
4733 case it is required to known the protocol to talk with the server prior
4734 to initiating the TLS handshake.
4739 This is the "whether the provided certificate or public key is a
4740 certificate authority" option. Marks the DANE RR as a CA certificate if
4746 This is the "use the hash of the x.509 certificate, rather than the
4747 public key" option. This option forces the generated record to contain
4748 the hash of the full X.509 certificate. By default only the hash of the
4754 This is an alias for the 'domain' option, *note the domain option
4755 documentation: danetool domain.
4760 This is the "the provided certificate or public key is issued by the
4761 local domain" option.
4763 This option has some usage constraints. It:
4764 * can be disabled with -no-domain.
4765 * It is enabled by default.
4767 DANE distinguishes certificates and public keys offered via the DNSSEC
4768 to trusted and local entities. This flag indicates that this is a
4769 domain-issued certificate, meaning that there could be no CA involved.
4774 This is the "use the local dns server for dnssec resolving" option.
4776 This option has some usage constraints. It:
4777 * can be disabled with -no-local-dns.
4779 This option will use the local DNS server for DNSSEC. This is disabled
4780 by default due to many servers not allowing DNSSEC.
4785 This is the "do not verify any dnssec signature" option. Ignores any
4786 DNSSEC signature verification results.
4791 This is the "use der format for input certificates and private keys"
4794 This option has some usage constraints. It:
4795 * can be disabled with -no-inder.
4797 The input files will be assumed to be in DER or RAW format. Unlike
4798 options that in PEM input would allow multiple input data (e.g.
4799 multiple certificates), when reading in DER format a single data
4805 This is an alias for the 'inder' option, *note the inder option
4806 documentation: danetool inder.
4811 This is the "print the received dane data in raw format" option.
4813 This option has some usage constraints. It:
4814 * can be disabled with -no-print-raw.
4816 This option will print the received DANE data.
4821 This is the "suppress several informational messages" option. In that
4822 case on the exit code can be used as an indication of verification
4825 danetool exit status
4826 ....................
4828 One of the following exit values will be returned:
4830 Successful program execution.
4832 The operation failed or the command syntax was not valid.
4842 DANE TLSA RR generation
4843 .......................
4845 To create a DANE TLSA resource record for a certificate (or public key)
4846 that was issued localy and may or may not be signed by a CA use the
4848 $ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem
4850 To create a DANE TLSA resource record for a CA signed certificate, which
4851 will be marked as such use the following command.
4852 $ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem \
4855 The former is useful to add in your DNS entry even if your certificate
4856 is signed by a CA. That way even users who do not trust your CA will be
4857 able to verify your certificate using DANE.
4859 In order to create a record for the CA signer of your certificate use
4861 $ danetool --tlsa-rr --host www.example.com --load-certificate cert.pem \
4864 To read a server's DANE TLSA entry, use:
4865 $ danetool --check www.example.com --proto tcp --port 443
4867 To verify a server's DANE TLSA entry, use:
4868 $ danetool --check www.example.com --proto tcp --port 443 --load-certificate chain.pem
4871 File: gnutls.info, Node: Shared-key and anonymous authentication, Next: Selecting an appropriate authentication method, Prev: More on certificate authentication, Up: Authentication methods
4873 4.3 Shared-key and anonymous authentication
4874 ===========================================
4876 In addition to certificate authentication, the TLS protocol may be used
4877 with password, shared-key and anonymous authentication methods. The
4878 rest of this chapter discusses details of these methods.
4882 * SRP authentication::
4883 * PSK authentication::
4884 * Anonymous authentication::
4887 File: gnutls.info, Node: SRP authentication, Next: PSK authentication, Up: Shared-key and anonymous authentication
4889 4.3.1 SRP authentication
4890 ------------------------
4894 * Authentication using SRP::
4895 * srptool Invocation:: Invoking srptool
4898 File: gnutls.info, Node: Authentication using SRP, Next: srptool Invocation, Up: SRP authentication
4900 4.3.1.1 Authentication using SRP
4901 ................................
4903 GnuTLS supports authentication via the Secure Remote Password or SRP
4904 protocol (see [_RFC2945,TOMSRP_] for a description). The SRP key
4905 exchange is an extension to the TLS protocol, and it provides an
4906 authenticated with a password key exchange. The peers can be identified
4907 using a single password, or there can be combinations where the client
4908 is authenticated using SRP and the server using a certificate.
4910 The advantage of SRP authentication, over other proposed secure password
4911 authentication schemes, is that SRP is not susceptible to off-line
4912 dictionary attacks. Moreover, SRP does not require the server to hold
4913 the user's password. This kind of protection is similar to the one used
4914 traditionally in the UNIX '/etc/passwd' file, where the contents of this
4915 file did not cause harm to the system security if they were revealed.
4916 The SRP needs instead of the plain password something called a verifier,
4917 which is calculated using the user's password, and if stolen cannot be
4918 used to impersonate the user.
4920 Typical conventions in SRP are a password file, called 'tpasswd' that
4921 holds the SRP verifiers (encoded passwords) and another file,
4922 'tpasswd.conf', which holds the allowed SRP parameters. The included in
4923 GnuTLS helper follow those conventions. The srptool program, discussed
4924 in the next section is a tool to manipulate the SRP parameters.
4926 The implementation in GnuTLS is based on [_TLSSRP_]. The supported key
4927 exchange methods are shown below.
4930 Authentication using the SRP protocol.
4933 Client authentication using the SRP protocol. Server is
4934 authenticated using a certificate with DSA parameters.
4937 Client authentication using the SRP protocol. Server is
4938 authenticated using a certificate with RSA parameters.
4940 -- Function: int gnutls_srp_verifier (const char * USERNAME, const char
4941 * PASSWORD, const gnutls_datum_t * SALT, const gnutls_datum_t
4942 * GENERATOR, const gnutls_datum_t * PRIME, gnutls_datum_t *
4944 USERNAME: is the user's name
4946 PASSWORD: is the user's password
4948 SALT: should be some randomly generated bytes
4950 GENERATOR: is the generator of the group
4952 PRIME: is the group's prime
4954 RES: where the verifier will be stored.
4956 This function will create an SRP verifier, as specified in RFC2945.
4957 The 'prime' and 'generator' should be one of the static parameters
4958 defined in gnutls/gnutls.h or may be generated.
4960 The verifier will be allocated with 'gnutls_malloc' () and will be
4961 stored in 'res' using binary format.
4963 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned, or an
4966 'INT *note gnutls_srp_base64_encode2:: (const gnutls_datum_t * DATA, gnutls_datum_t * RESULT)'
4967 'INT *note gnutls_srp_base64_decode2:: (const gnutls_datum_t * B64_DATA, gnutls_datum_t * RESULT)'
4970 File: gnutls.info, Node: srptool Invocation, Prev: Authentication using SRP, Up: SRP authentication
4972 4.3.1.2 Invoking srptool
4973 ........................
4975 Simple program that emulates the programs in the Stanford SRP (Secure
4976 Remote Password) libraries using GnuTLS. It is intended for use in
4977 places where you don't expect SRP authentication to be the used for
4980 In brief, to use SRP you need to create two files. These are the
4981 password file that holds the users and the verifiers associated with
4982 them and the configuration file to hold the group parameters (called
4985 This section was generated by *AutoGen*, using the 'agtexi-cmd' template
4986 and the option descriptions for the 'srptool' program. This software is
4987 released under the GNU General Public License, version 3 or later.
4989 srptool help/usage ('--help')
4990 .............................
4992 This is the automatically generated usage text for srptool.
4994 The text printed is the same whether selected with the 'help' option
4995 ('--help') or the 'more-help' option ('--more-help'). 'more-help' will
4996 print the usage text by passing it through a pager program. 'more-help'
4997 is disabled on platforms without a working 'fork(2)' function. The
4998 'PAGER' environment variable is used to select the program, defaulting
4999 to 'more'. Both will exit with a status code of 0.
5001 srptool - GnuTLS SRP tool
5002 Usage: srptool [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
5004 -d, --debug=num Enable debugging
5005 - it must be in the range:
5007 -i, --index=num specify the index of the group parameters in tpasswd.conf to use
5008 -u, --username=str specify a username
5009 -p, --passwd=str specify a password file
5010 -s, --salt=num specify salt size
5011 --verify just verify the password.
5012 -v, --passwd-conf=str specify a password conf file.
5013 --create-conf=str Generate a password configuration file.
5014 -v, --version[=arg] output version information and exit
5015 -h, --help display extended usage information and exit
5016 -!, --more-help extended usage information passed thru pager
5018 Options are specified by doubled hyphens and their name or by a single
5019 hyphen and the flag character.
5021 Simple program that emulates the programs in the Stanford SRP (Secure
5022 Remote Password) libraries using GnuTLS. It is intended for use in places
5023 where you don't expect SRP authentication to be the used for system users.
5025 In brief, to use SRP you need to create two files. These are the password
5026 file that holds the users and the verifiers associated with them and the
5027 configuration file to hold the group parameters (called tpasswd.conf).
5033 This is the "enable debugging" option. This option takes a number
5034 argument. Specifies the debug level.
5039 This is the "just verify the password." option. Verifies the password
5040 provided against the password file.
5042 passwd-conf option (-v)
5043 .......................
5045 This is the "specify a password conf file." option. This option takes
5046 a string argument. Specify a filename or a PKCS #11 URL to read the CAs
5052 This is the "generate a password configuration file." option. This
5053 option takes a string argument. This generates a password configuration
5054 file (tpasswd.conf) containing the required for TLS parameters.
5059 One of the following exit values will be returned:
5061 Successful program execution.
5063 The operation failed or the command syntax was not valid.
5068 gnutls-cli-debug (1), gnutls-serv (1), srptool (1), psktool (1),
5074 To create 'tpasswd.conf' which holds the g and n values for SRP protocol
5075 (generator and a large prime), run:
5076 $ srptool --create-conf /etc/tpasswd.conf
5078 This command will create '/etc/tpasswd' and will add user 'test' (you
5079 will also be prompted for a password). Verifiers are stored by default
5080 in the way libsrp expects.
5081 $ srptool --passwd /etc/tpasswd --passwd-conf /etc/tpasswd.conf -u test
5083 This command will check against a password. If the password matches the
5084 one in '/etc/tpasswd' you will get an ok.
5085 $ srptool --passwd /etc/tpasswd --passwd\-conf /etc/tpasswd.conf --verify -u test
5088 File: gnutls.info, Node: PSK authentication, Next: Anonymous authentication, Prev: SRP authentication, Up: Shared-key and anonymous authentication
5090 4.3.2 PSK authentication
5091 ------------------------
5095 * Authentication using PSK::
5096 * psktool Invocation:: Invoking psktool
5099 File: gnutls.info, Node: Authentication using PSK, Next: psktool Invocation, Up: PSK authentication
5101 4.3.2.1 Authentication using PSK
5102 ................................
5104 Authentication using Pre-shared keys is a method to authenticate using
5105 usernames and binary keys. This protocol avoids making use of public
5106 key infrastructure and expensive calculations, thus it is suitable for
5109 The implementation in GnuTLS is based on [_TLSPSK_]. The supported PSK
5110 key exchange methods are:
5113 Authentication using the PSK protocol.
5116 Authentication using the PSK protocol and Diffie-Hellman key
5117 exchange. This method offers perfect forward secrecy.
5120 Authentication using the PSK protocol and Elliptic curve
5121 Diffie-Hellman key exchange. This method offers perfect forward
5125 Authentication using the PSK protocol for the client and an RSA
5126 certificate for the server.
5128 Helper functions to generate and maintain PSK keys are also included in
5131 'INT *note gnutls_key_generate:: (gnutls_datum_t * KEY, unsigned int KEY_SIZE)'
5132 'INT *note gnutls_hex_encode:: (const gnutls_datum_t * DATA, char * RESULT, size_t * RESULT_SIZE)'
5133 'INT *note gnutls_hex_decode:: (const gnutls_datum_t * HEX_DATA, void * RESULT, size_t * RESULT_SIZE)'
5136 File: gnutls.info, Node: psktool Invocation, Prev: Authentication using PSK, Up: PSK authentication
5138 4.3.2.2 Invoking psktool
5139 ........................
5141 Program that generates random keys for use with TLS-PSK. The keys are
5142 stored in hexadecimal format in a key file.
5144 This section was generated by *AutoGen*, using the 'agtexi-cmd' template
5145 and the option descriptions for the 'psktool' program. This software is
5146 released under the GNU General Public License, version 3 or later.
5148 psktool help/usage ('--help')
5149 .............................
5151 This is the automatically generated usage text for psktool.
5153 The text printed is the same whether selected with the 'help' option
5154 ('--help') or the 'more-help' option ('--more-help'). 'more-help' will
5155 print the usage text by passing it through a pager program. 'more-help'
5156 is disabled on platforms without a working 'fork(2)' function. The
5157 'PAGER' environment variable is used to select the program, defaulting
5158 to 'more'. Both will exit with a status code of 0.
5160 psktool - GnuTLS PSK tool
5161 Usage: psktool [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
5163 -d, --debug=num Enable debugging
5164 - it must be in the range:
5166 -s, --keysize=num specify the key size in bytes
5167 - it must be in the range:
5169 -u, --username=str specify a username
5170 -p, --passwd=str specify a password file
5171 -v, --version[=arg] output version information and exit
5172 -h, --help display extended usage information and exit
5173 -!, --more-help extended usage information passed thru pager
5175 Options are specified by doubled hyphens and their name or by a single
5176 hyphen and the flag character.
5178 Program that generates random keys for use with TLS-PSK. The keys are
5179 stored in hexadecimal format in a key file.
5185 This is the "enable debugging" option. This option takes a number
5186 argument. Specifies the debug level.
5191 One of the following exit values will be returned:
5193 Successful program execution.
5195 The operation failed or the command syntax was not valid.
5200 gnutls-cli-debug (1), gnutls-serv (1), srptool (1), certtool (1)
5205 To add a user 'psk_identity' in 'passwd.psk' for use with GnuTLS run:
5206 $ ./psktool -u psk_identity -p passwd.psk
5207 Generating a random key for user 'psk_identity'
5208 Key stored to passwd.psk
5210 psk_identity:88f3824b3e5659f52d00e959bacab954b6540344
5213 This command will create 'passwd.psk' if it does not exist and will add
5214 user 'psk_identity' (you will also be prompted for a password).
5217 File: gnutls.info, Node: Anonymous authentication, Prev: PSK authentication, Up: Shared-key and anonymous authentication
5219 4.3.3 Anonymous authentication
5220 ------------------------------
5222 The anonymous key exchange offers encryption without any indication of
5223 the peer's identity. This kind of authentication is vulnerable to a man
5224 in the middle attack, but can be used even if there is no prior
5225 communication or shared trusted parties with the peer. It is useful to
5226 establish a session over which certificate authentication will occur in
5227 order to hide the indentities of the participants from passive
5230 Unless in the above case, it is not recommended to use anonymous
5231 authentication. In the cases where there is no prior communication with
5232 the peers, an alternative with better properties, such as key
5233 continuity, is trust on first use (see *note Verifying a certificate
5234 using trust on first use authentication::).
5236 The available key exchange algorithms for anonymous authentication are
5237 shown below, but note that few public servers support them, and they
5238 have to be explicitly enabled.
5241 This algorithm exchanges Diffie-Hellman parameters.
5244 This algorithm exchanges elliptic curve Diffie-Hellman parameters.
5245 It is more efficient than ANON_DH on equivalent security levels.
5248 File: gnutls.info, Node: Selecting an appropriate authentication method, Prev: Shared-key and anonymous authentication, Up: Authentication methods
5250 4.4 Selecting an appropriate authentication method
5251 ==================================================
5253 This section provides some guidance on how to use the available
5254 authentication methods in GnuTLS in various scenarios.
5256 4.4.1 Two peers with an out-of-band channel
5257 -------------------------------------------
5259 Let's consider two peers who need to communicate over an untrusted
5260 channel (the Internet), but have an out-of-band channel available. The
5261 latter channel is considered safe from eavesdropping and message
5262 modification and thus can be used for an initial bootstrapping of the
5263 protocol. The options available are:
5264 * Pre-shared keys (see *note PSK authentication::). The server and a
5265 client communicate a shared randomly generated key over the trusted
5266 channel and use it to negotiate further sessions over the untrusted
5269 * Passwords (see *note SRP authentication::). The client
5270 communicates to the server its username and password of choice and
5271 uses it to negotiate further sessions over the untrusted channel.
5273 * Public keys (see *note Certificate authentication::). The client
5274 and the server exchange their public keys (or fingerprints of them)
5275 over the trusted channel. On future sessions over the untrusted
5276 channel they verify the key being the same (similar to *note
5277 Verifying a certificate using trust on first use authentication::).
5279 Provided that the out-of-band channel is trusted all of the above
5280 provide a similar level of protection. An out-of-band channel may be
5281 the initial bootstrapping of a user's PC in a corporate environment,
5282 in-person communication, communication over an alternative network (e.g.
5283 the phone network), etc.
5285 4.4.2 Two peers without an out-of-band channel
5286 ----------------------------------------------
5288 When an out-of-band channel is not available a peer cannot be reliably
5289 authenticated. What can be done, however, is to allow some form of
5290 registration of users connecting for the first time and ensure that
5291 their keys remain the same after that initial connection. This is
5292 termed key continuity or trust on first use (TOFU).
5294 The available option is to use public key authentication (see *note
5295 Certificate authentication::). The client and the server store each
5296 other's public keys (or fingerprints of them) and associate them with
5297 their identity. On future sessions over the untrusted channel they
5298 verify the keys being the same (see *note Verifying a certificate using
5299 trust on first use authentication::).
5301 To mitigate the uncertainty of the information exchanged in the first
5302 connection other channels over the Internet may be used, e.g., DNSSEC
5303 (see *note Verifying a certificate using DANE::).
5305 4.4.3 Two peers and a trusted third party
5306 -----------------------------------------
5308 When a trusted third party is available (or a certificate authority) the
5309 most suitable option is to use certificate authentication (see *note
5310 Certificate authentication::). The client and the server obtain
5311 certificates that associate their identity and public keys using a
5312 digital signature by the trusted party and use them to on the subsequent
5313 communications with each other. Each party verifies the peer's
5314 certificate using the trusted third party's signature. The parameters
5315 of the third party's signature are present in its certificate which must
5316 be available to all communicating parties.
5318 While the above is the typical authentication method for servers in the
5319 Internet by using the commercial CAs, the users that act as clients in
5320 the protocol rarely possess such certificates. In that case a hybrid
5321 method can be used where the server is authenticated by the client using
5322 the commercial CAs and the client is authenticated based on some
5323 information the client provided over the initial server-authenticated
5324 channel. The available options are:
5325 * Passwords (see *note SRP authentication::). The client
5326 communicates to the server its username and password of choice on
5327 the initial server-authenticated connection and uses it to
5328 negotiate further sessions. This is possible because the SRP
5329 protocol allows for the server to be authenticated using a
5330 certificate and the client using the password.
5332 * Public keys (see *note Certificate authentication::). The client
5333 sends its public key to the server (or a fingerprint of it) over
5334 the initial server-authenticated connection. On future sessions
5335 the client verifies the server using the third party certificate
5336 and the server verifies that the client's public key remained the
5337 same (see *note Verifying a certificate using trust on first use
5341 File: gnutls.info, Node: Hardware security modules and abstract key types, Next: How to use GnuTLS in applications, Prev: Authentication methods, Up: Top
5343 5 Abstract keys types and Hardware security modules
5344 ***************************************************
5346 In several cases storing the long term cryptographic keys in a hard disk
5347 or even in memory poses a significant risk. Once the system they are
5348 stored is compromised the keys must be replaced as the secrecy of future
5349 sessions is no longer guaranteed. Moreover, past sessions that were not
5350 protected by a perfect forward secrecy offering ciphersuite are also to
5351 be assumed compromised.
5353 If such threats need to be addressed, then it may be wise storing the
5354 keys in a security module such as a smart card, an HSM or the TPM chip.
5355 Those modules ensure the protection of the cryptographic keys by only
5356 allowing operations on them and preventing their extraction. The
5357 purpose of the abstract key API is to provide an API that will allow the
5358 handle of keys in memory and files, as well as keys stored in such
5361 In GnuTLS the approach is to handle all keys transparently by the high
5362 level API, e.g., the API that loads a key or certificate from a file.
5363 The high-level API will accept URIs in addition to files that specify
5364 keys on an HSM or in TPM, and a callback function will be used to obtain
5365 any required keys. The URI format is defined in [_TPMURI_] and the
5366 standardized [_PKCS11URI_].
5368 More information on the API is provided in the next sections. Examples
5369 of a URI of a certificate stored in an HSM, as well as a key stored in
5370 the TPM chip are shown below. To discover the URIs of the objects the
5371 'p11tool' (see *note p11tool Invocation::), or 'tpmtool' (see *note
5372 tpmtool Invocation::) may be used.
5374 pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
5375 manufacturer=EnterSafe;object=test1;type=cert
5377 tpmkey:uuid=42309df8-d101-11e1-a89a-97bb33c23ad1;storage=user
5381 * Abstract key types::
5382 * Application-specific keys::
5383 * Smart cards and HSMs::
5384 * Trusted Platform Module::
5387 File: gnutls.info, Node: Abstract key types, Next: Application-specific keys, Up: Hardware security modules and abstract key types
5389 5.1 Abstract key types
5390 ======================
5392 Since there are many forms of a public or private keys supported by
5393 GnuTLS such as X.509, OpenPGP, PKCS #11 or TPM it is desirable to allow
5394 common operations on them. For these reasons the abstract
5395 'gnutls_privkey_t' and 'gnutls_pubkey_t' were introduced in
5396 'gnutls/abstract.h' header. Those types are initialized using a
5397 specific type of key and then can be used to perform operations in an
5398 abstract way. For example in order to sign an X.509 certificate with a
5399 key that resides in a token the following steps can be used.
5401 #inlude <gnutls/abstract.h>
5403 void sign_cert( gnutls_x509_crt_t to_be_signed)
5405 gnutls_x509_crt_t ca_cert;
5406 gnutls_privkey_t abs_key;
5408 /* initialize the abstract key */
5409 gnutls_privkey_init(&abs_key);
5411 /* keys stored in tokens are identified by URLs */
5412 gnutls_privkey_import_url(abs_key, key_url);
5414 gnutls_x509_crt_init(&ca_cert);
5415 gnutls_x509_crt_import_url(&ca_cert, cert_url);
5417 /* sign the certificate to be signed */
5418 gnutls_x509_crt_privkey_sign(to_be_signed, ca_cert, abs_key,
5419 GNUTLS_DIG_SHA256, 0);
5424 * Abstract public keys::
5425 * Abstract private keys::
5429 File: gnutls.info, Node: Abstract public keys, Next: Abstract private keys, Up: Abstract key types
5434 An abstract 'gnutls_pubkey_t' can be initialized using the functions
5435 below. It can be imported through an existing structure like
5436 'gnutls_x509_crt_t', or through an ASN.1 encoding of the X.509
5437 'SubjectPublicKeyInfo' sequence.
5439 'INT *note gnutls_pubkey_import_x509:: (gnutls_pubkey_t KEY, gnutls_x509_crt_t CRT, unsigned int FLAGS)'
5440 'INT *note gnutls_pubkey_import_openpgp:: (gnutls_pubkey_t KEY, gnutls_openpgp_crt_t CRT, unsigned int FLAGS)'
5441 'INT *note gnutls_pubkey_import_pkcs11:: (gnutls_pubkey_t KEY, gnutls_pkcs11_obj_t OBJ, unsigned int FLAGS)'
5443 'INT *note gnutls_pubkey_import_url:: (gnutls_pubkey_t KEY, const char * URL, unsigned int FLAGS)'
5444 'INT *note gnutls_pubkey_import_privkey:: (gnutls_pubkey_t KEY, gnutls_privkey_t PKEY, unsigned int USAGE, unsigned int FLAGS)'
5445 'INT *note gnutls_pubkey_import:: (gnutls_pubkey_t KEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT)'
5446 'INT *note gnutls_pubkey_export:: (gnutls_pubkey_t KEY, gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE)'
5448 -- Function: int gnutls_pubkey_export2 (gnutls_pubkey_t KEY,
5449 gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT)
5450 KEY: Holds the certificate
5452 FORMAT: the format of output params. One of PEM or DER.
5454 OUT: will contain a certificate PEM or DER encoded
5456 This function will export the public key to DER or PEM format. The
5457 contents of the exported data is the SubjectPublicKeyInfo X.509
5460 The output buffer will be allocated using 'gnutls_malloc()' .
5462 If the structure is PEM encoded, it will have a header of "BEGIN
5465 *Returns:* In case of failure a negative error code will be
5466 returned, and 0 on success.
5470 Other helper functions that allow directly importing from raw X.509 or
5471 OpenPGP structures are shown below.
5473 'INT *note gnutls_pubkey_import_x509_raw:: (gnutls_pubkey_t PKEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)'
5474 'INT *note gnutls_pubkey_import_openpgp_raw:: (gnutls_pubkey_t PKEY, const gnutls_datum_t * DATA, gnutls_openpgp_crt_fmt_t FORMAT, const gnutls_openpgp_keyid_t KEYID, unsigned int FLAGS)'
5476 An important function is *note gnutls_pubkey_import_url:: which will
5477 import public keys from URLs that identify objects stored in tokens (see
5478 *note Smart cards and HSMs:: and *note Trusted Platform Module::). A
5479 function to check for a supported by GnuTLS URL is *note
5480 gnutls_url_is_supported::.
5482 -- Function: int gnutls_url_is_supported (const char * URL)
5485 Check whether url is supported. Depending on the system libraries
5486 GnuTLS may support pkcs11 or tpmkey URLs.
5488 *Returns:* return non-zero if the given URL is supported, and zero
5493 Additional functions are available that will return information over a
5494 public key, such as a unique key ID, as well as a function that given a
5495 public key fingerprint would provide a memorable sketch.
5497 Note that *note gnutls_pubkey_get_key_id:: calculates a SHA1 digest of
5498 the public key as a DER-formatted, subjectPublicKeyInfo object. Other
5499 implementations use different approaches, e.g., some use the "common
5500 method" described in section 4.2.1.2 of [_RFC5280_] which calculates a
5501 digest on a part of the subjectPublicKeyInfo object.
5503 'INT *note gnutls_pubkey_get_pk_algorithm:: (gnutls_pubkey_t KEY, unsigned int * BITS)'
5504 'INT *note gnutls_pubkey_get_preferred_hash_algorithm:: (gnutls_pubkey_t KEY, gnutls_digest_algorithm_t * HASH, unsigned int * MAND)'
5505 'INT *note gnutls_pubkey_get_key_id:: (gnutls_pubkey_t KEY, unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE)'
5506 'INT *note gnutls_random_art:: (gnutls_random_art_t TYPE, const char * KEY_TYPE, unsigned int KEY_SIZE, void * FPR, size_t FPR_SIZE, gnutls_datum_t * ART)'
5508 To export the key-specific parameters, or obtain a unique key ID the
5509 following functions are provided.
5511 'INT *note gnutls_pubkey_export_rsa_raw:: (gnutls_pubkey_t KEY, gnutls_datum_t * M, gnutls_datum_t * E)'
5512 'INT *note gnutls_pubkey_export_dsa_raw:: (gnutls_pubkey_t KEY, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y)'
5513 'INT *note gnutls_pubkey_export_ecc_raw:: (gnutls_pubkey_t KEY, gnutls_ecc_curve_t * CURVE, gnutls_datum_t * X, gnutls_datum_t * Y)'
5514 'INT *note gnutls_pubkey_export_ecc_x962:: (gnutls_pubkey_t KEY, gnutls_datum_t * PARAMETERS, gnutls_datum_t * ECPOINT)'
5517 File: gnutls.info, Node: Abstract private keys, Next: Operations, Prev: Abstract public keys, Up: Abstract key types
5522 An abstract 'gnutls_privkey_t' can be initialized using the functions
5523 below. It can be imported through an existing structure like
5524 'gnutls_x509_privkey_t', but unlike public keys it cannot be exported.
5525 That is to allow abstraction over keys stored in hardware that makes
5526 available only operations.
5528 'INT *note gnutls_privkey_import_x509:: (gnutls_privkey_t PKEY, gnutls_x509_privkey_t KEY, unsigned int FLAGS)'
5529 'INT *note gnutls_privkey_import_openpgp:: (gnutls_privkey_t PKEY, gnutls_openpgp_privkey_t KEY, unsigned int FLAGS)'
5530 'INT *note gnutls_privkey_import_pkcs11:: (gnutls_privkey_t PKEY, gnutls_pkcs11_privkey_t KEY, unsigned int FLAGS)'
5532 Other helper functions that allow directly importing from raw X.509 or
5533 OpenPGP structures are shown below. Again, as with public keys, private
5534 keys can be imported from a hardware module using URLs.
5536 'INT *note gnutls_privkey_import_x509_raw:: (gnutls_privkey_t PKEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, const char * PASSWORD, unsigned int FLAGS)'
5537 'INT *note gnutls_privkey_import_openpgp_raw:: (gnutls_privkey_t PKEY, const gnutls_datum_t * DATA, gnutls_openpgp_crt_fmt_t FORMAT, const gnutls_openpgp_keyid_t KEYID, const char * PASSWORD)'
5539 -- Function: int gnutls_privkey_import_url (gnutls_privkey_t KEY, const
5540 char * URL, unsigned int FLAGS)
5541 KEY: A key of type 'gnutls_privkey_t'
5545 FLAGS: should be zero
5547 This function will import a PKCS11 or TPM URL as a private key.
5548 The supported URL types can be checked using
5549 'gnutls_url_is_supported()' .
5551 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5552 otherwise a negative error value.
5556 'INT *note gnutls_privkey_get_pk_algorithm:: (gnutls_privkey_t KEY, unsigned int * BITS)'
5557 'GNUTLS_PRIVKEY_TYPE_T *note gnutls_privkey_get_type:: (gnutls_privkey_t KEY)'
5558 'INT *note gnutls_privkey_status:: (gnutls_privkey_t KEY)'
5560 In order to support cryptographic operations using an external API, the
5561 following function is provided. This allows for a simple extensibility
5562 API without resorting to PKCS #11.
5564 -- Function: int gnutls_privkey_import_ext3 (gnutls_privkey_t PKEY,
5565 void * USERDATA, gnutls_privkey_sign_func SIGN_FN,
5566 gnutls_privkey_decrypt_func DECRYPT_FN,
5567 gnutls_privkey_deinit_func DEINIT_FN, gnutls_privkey_info_func
5568 INFO_FN, unsigned int FLAGS)
5569 PKEY: The private key
5571 USERDATA: private data to be provided to the callbacks
5573 SIGN_FN: callback for signature operations
5575 DECRYPT_FN: callback for decryption operations
5577 DEINIT_FN: a deinitialization function
5579 INFO_FN: returns info about the public key algorithm (should not be
5582 FLAGS: Flags for the import
5584 This function will associate the given callbacks with the
5585 'gnutls_privkey_t' type. At least one of the two callbacks must be
5586 non-null. If a deinitialization function is provided then flags is
5587 assumed to contain 'GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE' .
5589 Note that the signing function is supposed to "raw" sign data,
5590 i.e., without any hashing or preprocessing. In case of RSA the
5591 DigestInfo will be provided, and the signing function is expected
5592 to do the PKCS '1' 1.5 padding and the exponentiation.
5594 The 'info_fn' must provide information on the algorithms supported
5595 by this private key, and should support the flags
5596 'GNUTLS_PRIVKEY_INFO_PK_ALGO' and 'GNUTLS_PRIVKEY_INFO_SIGN_ALGO' .
5597 It must return -1 on unknown flags.
5599 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5600 otherwise a negative error value.
5605 File: gnutls.info, Node: Operations, Prev: Abstract private keys, Up: Abstract key types
5610 The abstract key types can be used to access signing and signature
5611 verification operations with the underlying keys.
5613 -- Function: int gnutls_pubkey_verify_data2 (gnutls_pubkey_t PUBKEY,
5614 gnutls_sign_algorithm_t ALGO, unsigned int FLAGS, const
5615 gnutls_datum_t * DATA, const gnutls_datum_t * SIGNATURE)
5616 PUBKEY: Holds the public key
5618 ALGO: The signature algorithm used
5620 FLAGS: Zero or an OR list of 'gnutls_certificate_verify_flags'
5622 DATA: holds the signed data
5624 SIGNATURE: contains the signature
5626 This function will verify the given signed data, using the
5627 parameters from the certificate.
5629 *Returns:* In case of a verification failure
5630 'GNUTLS_E_PK_SIG_VERIFY_FAILED' is returned, and zero or positive
5631 code on success. For known to be insecure signatures this function
5632 will return 'GNUTLS_E_INSUFFICIENT_SECURITY' unless the flag
5633 'GNUTLS_VERIFY_ALLOW_BROKEN' is specified.
5637 -- Function: int gnutls_pubkey_verify_hash2 (gnutls_pubkey_t KEY,
5638 gnutls_sign_algorithm_t ALGO, unsigned int FLAGS, const
5639 gnutls_datum_t * HASH, const gnutls_datum_t * SIGNATURE)
5640 KEY: Holds the public key
5642 ALGO: The signature algorithm used
5644 FLAGS: Zero or an OR list of 'gnutls_certificate_verify_flags'
5646 HASH: holds the hash digest to be verified
5648 SIGNATURE: contains the signature
5650 This function will verify the given signed digest, using the
5651 parameters from the public key. Note that unlike
5652 'gnutls_privkey_sign_hash()' , this function accepts a signature
5653 algorithm instead of a digest algorithm. You can use
5654 'gnutls_pk_to_sign()' to get the appropriate value.
5656 *Returns:* In case of a verification failure
5657 'GNUTLS_E_PK_SIG_VERIFY_FAILED' is returned, and zero or positive
5662 -- Function: int gnutls_pubkey_encrypt_data (gnutls_pubkey_t KEY,
5663 unsigned int FLAGS, const gnutls_datum_t * PLAINTEXT,
5664 gnutls_datum_t * CIPHERTEXT)
5665 KEY: Holds the public key
5667 FLAGS: should be 0 for now
5669 PLAINTEXT: The data to be encrypted
5671 CIPHERTEXT: contains the encrypted data
5673 This function will encrypt the given data, using the public key.
5674 On success the 'ciphertext' will be allocated using
5677 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5678 otherwise a negative error value.
5682 -- Function: int gnutls_privkey_sign_data (gnutls_privkey_t SIGNER,
5683 gnutls_digest_algorithm_t HASH, unsigned int FLAGS, const
5684 gnutls_datum_t * DATA, gnutls_datum_t * SIGNATURE)
5685 SIGNER: Holds the key
5687 HASH: should be a digest algorithm
5689 FLAGS: Zero or one of 'gnutls_privkey_flags_t'
5691 DATA: holds the data to be signed
5693 SIGNATURE: will contain the signature allocated with
5696 This function will sign the given data using a signature algorithm
5697 supported by the private key. Signature algorithms are always used
5698 together with a hash functions. Different hash functions may be
5699 used for the RSA algorithm, but only the SHA family for the DSA
5702 You may use 'gnutls_pubkey_get_preferred_hash_algorithm()' to
5703 determine the hash algorithm.
5705 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5706 otherwise a negative error value.
5710 -- Function: int gnutls_privkey_sign_hash (gnutls_privkey_t SIGNER,
5711 gnutls_digest_algorithm_t HASH_ALGO, unsigned int FLAGS, const
5712 gnutls_datum_t * HASH_DATA, gnutls_datum_t * SIGNATURE)
5713 SIGNER: Holds the signer's key
5715 HASH_ALGO: The hash algorithm used
5717 FLAGS: Zero or one of 'gnutls_privkey_flags_t'
5719 HASH_DATA: holds the data to be signed
5721 SIGNATURE: will contain newly allocated signature
5723 This function will sign the given hashed data using a signature
5724 algorithm supported by the private key. Signature algorithms are
5725 always used together with a hash functions. Different hash
5726 functions may be used for the RSA algorithm, but only SHA-XXX for
5729 You may use 'gnutls_pubkey_get_preferred_hash_algorithm()' to
5730 determine the hash algorithm.
5732 Note that if 'GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA' flag is specified
5733 this function will ignore 'hash_algo' and perform a raw PKCS1
5736 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5737 otherwise a negative error value.
5741 -- Function: int gnutls_privkey_decrypt_data (gnutls_privkey_t KEY,
5742 unsigned int FLAGS, const gnutls_datum_t * CIPHERTEXT,
5743 gnutls_datum_t * PLAINTEXT)
5748 CIPHERTEXT: holds the data to be decrypted
5750 PLAINTEXT: will contain the decrypted data, allocated with
5753 This function will decrypt the given data using the algorithm
5754 supported by the private key.
5756 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5757 otherwise a negative error value.
5761 Signing existing structures, such as certificates, CRLs, or certificate
5762 requests, as well as associating public keys with structures is also
5763 possible using the key abstractions.
5765 -- Function: int gnutls_x509_crq_set_pubkey (gnutls_x509_crq_t CRQ,
5766 gnutls_pubkey_t KEY)
5767 CRQ: should contain a 'gnutls_x509_crq_t' type
5769 KEY: holds a public key
5771 This function will set the public parameters from the given public
5772 key to the request. The 'key' can be deallocated after that.
5774 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5775 otherwise a negative error value.
5779 -- Function: int gnutls_x509_crt_set_pubkey (gnutls_x509_crt_t CRT,
5780 gnutls_pubkey_t KEY)
5781 CRT: should contain a 'gnutls_x509_crt_t' type
5783 KEY: holds a public key
5785 This function will set the public parameters from the given public
5786 key to the certificate. The 'key' can be deallocated after that.
5788 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5789 otherwise a negative error value.
5792 'INT *note gnutls_x509_crt_privkey_sign:: (gnutls_x509_crt_t CRT, gnutls_x509_crt_t ISSUER, gnutls_privkey_t ISSUER_KEY, gnutls_digest_algorithm_t DIG, unsigned int FLAGS)'
5793 'INT *note gnutls_x509_crl_privkey_sign:: (gnutls_x509_crl_t CRL, gnutls_x509_crt_t ISSUER, gnutls_privkey_t ISSUER_KEY, gnutls_digest_algorithm_t DIG, unsigned int FLAGS)'
5794 'INT *note gnutls_x509_crq_privkey_sign:: (gnutls_x509_crq_t CRQ, gnutls_privkey_t KEY, gnutls_digest_algorithm_t DIG, unsigned int FLAGS)'
5797 File: gnutls.info, Node: Application-specific keys, Next: Smart cards and HSMs, Prev: Abstract key types, Up: Hardware security modules and abstract key types
5799 5.2 System and application-specific keys
5800 ========================================
5802 5.2.1 System-specific keys
5803 --------------------------
5805 In several systems there are keystores which allow to read, store and
5806 use certificates and private keys. For these systems GnuTLS provides
5807 the system-key API in 'gnutls/system-keys.h'. That API provides the
5808 ability to iterate through all stored keys, add and delete keys as well
5809 as use these keys using a URL which starts with "system:". The format
5810 of the URLs is system-specific.
5812 -- Function: int gnutls_system_key_iter_get_info
5813 (gnutls_system_key_iter_t * ITER, unsigned CERT_TYPE, char **
5814 CERT_URL, char ** KEY_URL, char ** LABEL, gnutls_datum_t *
5815 DER, unsigned int FLAGS)
5816 ITER: an iterator of the system keys (must be set to 'NULL'
5819 CERT_TYPE: A value of gnutls_certificate_type_t which indicates the
5820 type of certificate to look for
5822 CERT_URL: The certificate URL of the pair (may be 'NULL' )
5824 KEY_URL: The key URL of the pair (may be 'NULL' )
5826 LABEL: The friendly name (if any) of the pair (may be 'NULL' )
5828 DER: if non-NULL the DER data of the certificate
5830 FLAGS: should be zero
5832 This function will return on each call a certificate and key pair
5833 URLs, as well as a label associated with them, and the DER-encoded
5834 certificate. When the iteration is complete it will return
5835 'GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE' .
5837 Typically 'cert_type' should be 'GNUTLS_CRT_X509' .
5839 All values set are allocated and must be cleared using
5842 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
5843 otherwise a negative error value.
5847 'VOID *note gnutls_system_key_iter_deinit:: (gnutls_system_key_iter_t ITER)'
5848 'INT *note gnutls_system_key_add_x509:: (gnutls_x509_crt_t CRT, gnutls_x509_privkey_t PRIVKEY, const char * LABEL, char ** CERT_URL, char ** KEY_URL)'
5849 'INT *note gnutls_system_key_delete:: (const char * CERT_URL, const char * KEY_URL)'
5851 5.2.2 Application-specific keys
5852 -------------------------------
5854 For systems where GnuTLS doesn't provide a system specific store, it may
5855 often be desirable to define a custom class of keys that are identified
5856 via URLs and available to GnuTLS calls such as *note
5857 gnutls_certificate_set_x509_key_file2::. Such keys can be registered
5858 using the API in 'gnutls/urls.h'. The function which registers such
5859 keys is *note gnutls_register_custom_url::.
5861 -- Function: int gnutls_register_custom_url (const gnutls_custom_url_st
5863 ST: A 'gnutls_custom_url_st' structure
5865 Register a custom URL. This will affect the following functions:
5866 'gnutls_url_is_supported()' , 'gnutls_privkey_import_url()' ,
5867 gnutls_pubkey_import_url, 'gnutls_x509_crt_import_url()' and all
5868 functions that depend on them, e.g.,
5869 'gnutls_certificate_set_x509_key_file2()' .
5871 The provided structure and callback functions must be valid
5872 throughout the lifetime of the process. The registration of an
5873 existing URL type will fail with 'GNUTLS_E_INVALID_REQUEST' .
5875 This function is not thread safe.
5877 *Returns:* returns zero if the given structure was imported or a
5878 negative value otherwise.
5882 The input to this function are three callback functions as well as the
5883 prefix of the URL, (e.g., "mypkcs11:") and the length of the prefix.
5884 The types of the callbacks are shown below, and are expected to use the
5885 exported gnutls functions to import the keys and certificates. E.g., a
5886 typical 'import_key' callback should use *note
5887 gnutls_privkey_import_ext3::.
5889 typedef int (*gnutls_privkey_import_url_func)(gnutls_privkey_t pkey,
5893 typedef int (*gnutls_x509_crt_import_url_func)(gnutls_x509_crt_t pkey,
5897 /* The following callbacks are optional */
5899 /* This is to enable gnutls_pubkey_import_url() */
5900 typedef int (*gnutls_pubkey_import_url_func)(gnutls_pubkey_t pkey,
5901 const char *url, unsigned flags);
5903 /* This is to allow constructing a certificate chain. It will be provided
5904 * the initial certificate URL and the certificate to find its issuer, and must
5905 * return zero and the DER encoding of the issuer's certificate. If not available,
5906 * it should return GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE. */
5907 typedef int (*gnutls_get_raw_issuer_func)(const char *url, gnutls_x509_crt_t crt,
5908 gnutls_datum_t *issuer_der, unsigned flags);
5910 typedef struct custom_url_st {
5913 gnutls_privkey_import_url_func import_key;
5914 gnutls_x509_crt_import_url_func import_crt;
5915 gnutls_pubkey_import_url_func import_pubkey;
5916 gnutls_get_raw_issuer_func get_issuer;
5917 } gnutls_custom_url_st;
5920 File: gnutls.info, Node: Smart cards and HSMs, Next: Trusted Platform Module, Prev: Application-specific keys, Up: Hardware security modules and abstract key types
5922 5.3 Smart cards and HSMs
5923 ========================
5925 In this section we present the smart-card and hardware security module
5926 (HSM) support in GnuTLS using PKCS #11 [_PKCS11_]. Hardware security
5927 modules and smart cards provide a way to store private keys and perform
5928 operations on them without exposing them. This decouples cryptographic
5929 keys from the applications that use them and provide an additional
5930 security layer against cryptographic key extraction. Since this can
5931 also be achieved in software components such as in Gnome keyring, we
5932 will use the term security module to describe any cryptographic key
5933 separation subsystem.
5935 PKCS #11 is plugin API allowing applications to access cryptographic
5936 operations on a security module, as well as to objects residing on it.
5937 PKCS #11 modules exist for hardware tokens such as smart cards(1),
5938 cryptographic tokens, as well as for software modules like Gnome
5939 Keyring. The objects residing on a security module may be certificates,
5940 public keys, private keys or secret keys. Of those certificates and
5941 public/private key pairs can be used with GnuTLS. PKCS #11's main
5942 advantage is that it allows operations on private key objects such as
5943 decryption and signing without exposing the key. In GnuTLS the PKCS #11
5944 functionality is available in 'gnutls/pkcs11.h'.
5946 Moreover PKCS #11 can be (ab)used to allow all applications in the same
5947 operating system to access shared cryptographic keys and certificates in
5948 a uniform way, as in *note Figure 5.1: fig-pkcs11-vision. That way
5949 applications could load their trusted certificate list, as well as user
5950 certificates from a common PKCS #11 module. Such a provider is the
5951 p11-kit trust storage module(2).
5953 \0\b[image src="pkcs11-vision.png"
\0\b]
5955 Figure 5.1: PKCS #11 module usage.
5959 * PKCS11 Initialization::
5960 * Accessing objects that require a PIN::
5963 * Using a PKCS11 token with TLS::
5964 * p11tool Invocation::
5966 ---------- Footnotes ----------
5968 (1) For example, OpenSC-supported cards.
5970 (2) <http://p11-glue.freedesktop.org/trust-module.html>
5973 File: gnutls.info, Node: PKCS11 Initialization, Next: Accessing objects that require a PIN, Up: Smart cards and HSMs
5975 5.3.1 Initialization
5976 --------------------
5978 To allow all GnuTLS applications to transparently access smart cards and
5979 tokens, PKCS #11 is automatically initialized during the first call of a
5980 PKCS #11 related function. The initialization process, based on p11-kit
5981 configuration, loads any appropriate modules. The p11-kit configuration
5982 files(1) are typically stored in '/etc/pkcs11/modules/'. For example a
5983 file that will instruct GnuTLS to load the OpenSC module, could be named
5984 '/etc/pkcs11/modules/opensc.module' and contain the following:
5986 module: /usr/lib/opensc-pkcs11.so
5988 If you use these configuration files, then there is no need for other
5989 initialization in GnuTLS, except for the PIN and token callbacks (see
5990 next section). In several cases, however, it is desirable to limit
5991 badly behaving modules (e.g., modules that add an unacceptable delay on
5992 initialization) to single applications. That can be done using the
5993 "enable-in:" option followed by the base name of applications that this
5994 module should be used.
5996 It is also possible to manually initialize the PKCS #11 subsystem if the
5997 default settings are not desirable. To completely disable PKCS #11
5998 support you need to call *note gnutls_pkcs11_init:: with the flag
5999 'GNUTLS_PKCS11_FLAG_MANUAL' prior to *note gnutls_global_init::.
6001 -- Function: int gnutls_pkcs11_init (unsigned int FLAGS, const char *
6002 DEPRECATED_CONFIG_FILE)
6003 FLAGS: An ORed sequence of 'GNUTLS_PKCS11_FLAG_' *
6005 DEPRECATED_CONFIG_FILE: either NULL or the location of a deprecated
6008 This function will initialize the PKCS 11 subsystem in gnutls. It
6009 will read configuration files if 'GNUTLS_PKCS11_FLAG_AUTO' is used
6010 or allow you to independently load PKCS 11 modules using
6011 'gnutls_pkcs11_add_provider()' if 'GNUTLS_PKCS11_FLAG_MANUAL' is
6014 You don't need to call this function since GnuTLS 3.3.0 because it
6015 is being called during the first request PKCS 11 operation. That
6016 call will assume the 'GNUTLS_PKCS11_FLAG_AUTO' flag. If another
6017 flags are required then it must be called independently prior to
6018 any PKCS 11 operation.
6020 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6021 otherwise a negative error value.
6025 Note that, PKCS #11 modules behave in a peculiar way after a fork; they
6026 require a reinitialization of all the used PKCS #11 resources. While
6027 GnuTLS automates that process, there are corner cases where it is not
6028 possible to handle it correctly in an automated way(2). For that
6029 reasons it is recommended not to mix fork() and PKCS #11 module usage.
6030 It is recommended to initialize and use any PKCS #11 resources in a
6033 Older versions of GnuTLS required to call *note gnutls_pkcs11_reinit::
6034 after a fork() call; since 3.3.0 this is no longer required.
6036 ---------- Footnotes ----------
6038 (1) <http://p11-glue.freedesktop.org/>
6040 (2) For example when an open session is to be reinitialized, but the
6041 PIN is not available to GnuTLS (e.g., it was entered at a pinpad).
6044 File: gnutls.info, Node: Accessing objects that require a PIN, Next: Reading objects, Prev: PKCS11 Initialization, Up: Smart cards and HSMs
6046 5.3.2 Accessing objects that require a PIN
6047 ------------------------------------------
6049 Objects stored in token such as a private keys are typically protected
6050 from access by a PIN or password. This PIN may be required to either
6051 read the object (if allowed) or to perform operations with it. To allow
6052 obtaining the PIN when accessing a protected object, as well as probe
6053 the user to insert the token the following functions allow to set a
6056 'VOID *note gnutls_pkcs11_set_token_function:: (gnutls_pkcs11_token_callback_t FN, void * USERDATA)'
6057 'VOID *note gnutls_pkcs11_set_pin_function:: (gnutls_pin_callback_t FN, void * USERDATA)'
6058 'INT *note gnutls_pkcs11_add_provider:: (const char * NAME, const char * PARAMS)'
6059 'GNUTLS_PIN_CALLBACK_T *note gnutls_pkcs11_get_pin_function:: (void ** USERDATA)'
6061 The callback is of type 'gnutls_pin_callback_t' and will have as input
6062 the provided userdata, the PIN attempt number, a URL describing the
6063 token, a label describing the object and flags. The PIN must be at most
6064 of 'pin_max' size and must be copied to pin variable. The function must
6065 return 0 on success or a negative error code otherwise.
6067 typedef int (*gnutls_pin_callback_t) (void *userdata, int attempt,
6068 const char *token_url,
6069 const char *token_label,
6071 char *pin, size_t pin_max);
6073 The flags are of 'gnutls_pin_flag_t' type and are explained below.
6076 The PIN for the user.
6078 The PIN for the security officer (admin).
6079 'GNUTLS_PIN_FINAL_TRY'
6080 This is the final try before blocking.
6081 'GNUTLS_PIN_COUNT_LOW'
6082 Few tries remain before token blocks.
6083 'GNUTLS_PIN_CONTEXT_SPECIFIC'
6084 The PIN is for a specific action and key like signing.
6086 Last given PIN was not correct.
6088 Figure 5.2: The 'gnutls_pin_flag_t' enumeration.
6090 Note that due to limitations of PKCS #11 there are issues when multiple
6091 libraries are sharing a module. To avoid this problem GnuTLS uses
6092 p11-kit that provides a middleware to control access to resources over
6095 To avoid conflicts with multiple registered callbacks for PIN functions,
6096 *note gnutls_pkcs11_get_pin_function:: may be used to check for any
6097 previously set functions. In addition context specific PIN functions
6098 are allowed, e.g., by using functions below.
6100 'VOID *note gnutls_certificate_set_pin_function:: (gnutls_certificate_credentials_t CRED, gnutls_pin_callback_t FN, void * USERDATA)'
6101 'VOID *note gnutls_pubkey_set_pin_function:: (gnutls_pubkey_t KEY, gnutls_pin_callback_t FN, void * USERDATA)'
6102 'VOID *note gnutls_privkey_set_pin_function:: (gnutls_privkey_t KEY, gnutls_pin_callback_t FN, void * USERDATA)'
6103 'VOID *note gnutls_pkcs11_obj_set_pin_function:: (gnutls_pkcs11_obj_t OBJ, gnutls_pin_callback_t FN, void * USERDATA)'
6104 'VOID *note gnutls_x509_crt_set_pin_function:: (gnutls_x509_crt_t CRT, gnutls_pin_callback_t FN, void * USERDATA)'
6107 File: gnutls.info, Node: Reading objects, Next: Writing objects, Prev: Accessing objects that require a PIN, Up: Smart cards and HSMs
6109 5.3.3 Reading objects
6110 ---------------------
6112 All PKCS #11 objects are referenced by GnuTLS functions by URLs as
6113 described in [_PKCS11URI_]. This allows for a consistent naming of
6114 objects across systems and applications in the same system. For example
6115 a public key on a smart card may be referenced as:
6117 pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
6118 manufacturer=EnterSafe;object=test1;type=public;\
6119 id=32f153f3e37990b08624141077ca5dec2d15faed
6121 while the smart card itself can be referenced as:
6122 pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
6124 Objects stored in a PKCS #11 token can be extracted if they are not
6125 marked as sensitive. Usually only private keys are marked as sensitive
6126 and cannot be extracted, while certificates and other data can be
6127 retrieved. The functions that can be used to access objects are shown
6130 'INT *note gnutls_pkcs11_obj_import_url:: (gnutls_pkcs11_obj_t OBJ, const char * URL, unsigned int FLAGS)'
6131 'INT *note gnutls_pkcs11_obj_export_url:: (gnutls_pkcs11_obj_t OBJ, gnutls_pkcs11_url_type_t DETAILED, char ** URL)'
6133 -- Function: int gnutls_pkcs11_obj_get_info (gnutls_pkcs11_obj_t OBJ,
6134 gnutls_pkcs11_obj_info_t ITYPE, void * OUTPUT, size_t *
6136 OBJ: should contain a 'gnutls_pkcs11_obj_t' type
6138 ITYPE: Denotes the type of information requested
6140 OUTPUT: where output will be stored
6142 OUTPUT_SIZE: contains the maximum size of the output and will be
6143 overwritten with actual
6145 This function will return information about the PKCS11 certificate
6146 such as the label, id as well as token information where the key is
6147 stored. When output is text it returns null terminated string
6148 although 'output_size' contains the size of the actual data only.
6150 *Returns:* 'GNUTLS_E_SUCCESS' (0) on success or a negative error
6155 'INT *note gnutls_x509_crt_import_pkcs11:: (gnutls_x509_crt_t CRT, gnutls_pkcs11_obj_t PKCS11_CRT)'
6156 'INT *note gnutls_x509_crt_import_url:: (gnutls_x509_crt_t CRT, const char * URL, unsigned int FLAGS)'
6157 'INT *note gnutls_x509_crt_list_import_pkcs11:: (gnutls_x509_crt_t * CERTS, unsigned int CERT_MAX, gnutls_pkcs11_obj_t * const OBJS, unsigned int FLAGS)'
6159 Properties of the physical token can also be accessed and altered with
6160 GnuTLS. For example data in a token can be erased (initialized), PIN
6161 can be altered, etc.
6163 'INT *note gnutls_pkcs11_token_init:: (const char * TOKEN_URL, const char * SO_PIN, const char * LABEL)'
6164 'INT *note gnutls_pkcs11_token_get_url:: (unsigned int SEQ, gnutls_pkcs11_url_type_t DETAILED, char ** URL)'
6165 'INT *note gnutls_pkcs11_token_get_info:: (const char * URL, gnutls_pkcs11_token_info_t TTYPE, void * OUTPUT, size_t * OUTPUT_SIZE)'
6166 'INT *note gnutls_pkcs11_token_get_flags:: (const char * URL, unsigned int * FLAGS)'
6167 'INT *note gnutls_pkcs11_token_set_pin:: (const char * TOKEN_URL, const char * OLDPIN, const char * NEWPIN, unsigned int FLAGS)'
6169 The following examples demonstrate the usage of the API. The first
6170 example will list all available PKCS #11 tokens in a system and the
6171 latter will list all certificates in a token that have a corresponding
6177 gnutls_global_init();
6181 ret = gnutls_pkcs11_token_get_url(i, &url);
6182 if (ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
6188 fprintf(stdout, "Token[%d]: URL: %s\n", i, url);
6191 gnutls_global_deinit();
6193 /* This example code is placed in the public domain. */
6196 #include <gnutls/gnutls.h>
6197 #include <gnutls/pkcs11.h>
6201 #define URL "pkcs11:URL"
6203 int main(int argc, char **argv)
6205 gnutls_pkcs11_obj_t *obj_list;
6206 gnutls_x509_crt_t xcrt;
6207 unsigned int obj_list_size = 0;
6208 gnutls_datum_t cinfo;
6212 ret = gnutls_pkcs11_obj_list_import_url4(&obj_list, &obj_list_size, URL,
6213 GNUTLS_PKCS11_OBJ_FLAG_CRT|
6214 GNUTLS_PKCS11_OBJ_FLAG_WITH_PRIVKEY);
6218 /* now all certificates are in obj_list */
6219 for (i = 0; i < obj_list_size; i++) {
6221 gnutls_x509_crt_init(&xcrt);
6223 gnutls_x509_crt_import_pkcs11(xcrt, obj_list[i]);
6225 gnutls_x509_crt_print(xcrt, GNUTLS_CRT_PRINT_FULL, &cinfo);
6227 fprintf(stdout, "cert[%d]:\n %s\n\n", i, cinfo.data);
6229 gnutls_free(cinfo.data);
6230 gnutls_x509_crt_deinit(xcrt);
6233 for (i = 0; i < obj_list_size; i++)
6234 gnutls_pkcs11_obj_deinit(obj_list[i]);
6235 gnutls_free(obj_list);
6241 File: gnutls.info, Node: Writing objects, Next: Using a PKCS11 token with TLS, Prev: Reading objects, Up: Smart cards and HSMs
6243 5.3.4 Writing objects
6244 ---------------------
6246 With GnuTLS you can copy existing private keys and certificates to a
6247 token. Note that when copying private keys it is recommended to mark
6248 them as sensitive using the 'GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE' to
6249 prevent its extraction. An object can be marked as private using the
6250 flag 'GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE', to require PIN to be entered
6251 before accessing the object (for operations or otherwise).
6253 -- Function: int gnutls_pkcs11_copy_x509_privkey2 (const char *
6254 TOKEN_URL, gnutls_x509_privkey_t KEY, const char * LABEL,
6255 const gnutls_datum_t * CID, unsigned int KEY_USAGE, unsigned
6257 TOKEN_URL: A PKCS '11' URL specifying a token
6261 LABEL: A name to be used for the stored data
6263 CID: The CKA_ID to set for the object -if NULL, the ID will be
6264 derived from the public key
6266 KEY_USAGE: One of GNUTLS_KEY_*
6268 FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
6270 This function will copy a private key into a PKCS '11' token
6271 specified by a URL. It is highly recommended flags to contain
6272 'GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE' unless there is a strong
6275 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6276 otherwise a negative error value.
6280 -- Function: int gnutls_pkcs11_copy_x509_crt2 (const char * TOKEN_URL,
6281 gnutls_x509_crt_t CRT, const char * LABEL, const
6282 gnutls_datum_t * CID, unsigned int FLAGS)
6283 TOKEN_URL: A PKCS '11' URL specifying a token
6285 CRT: The certificate to copy
6287 LABEL: The name to be used for the stored data
6289 CID: The CKA_ID to set for the object -if NULL, the ID will be
6290 derived from the public key
6292 FLAGS: One of GNUTLS_PKCS11_OBJ_FLAG_*
6294 This function will copy a certificate into a PKCS '11' token
6295 specified by a URL. Valid flags to mark the certificate:
6296 'GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED' ,
6297 'GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE' ,
6298 'GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE' ,
6299 'GNUTLS_PKCS11_OBJ_FLAG_MARK_CA' ,
6300 'GNUTLS_PKCS11_OBJ_FLAG_MARK_ALWAYS_AUTH' .
6302 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6303 otherwise a negative error value.
6307 -- Function: int gnutls_pkcs11_delete_url (const char * OBJECT_URL,
6309 OBJECT_URL: The URL of the object to delete.
6311 FLAGS: One of GNUTLS_PKCS11_OBJ_* flags
6313 This function will delete objects matching the given URL. Note that
6314 not all tokens support the delete operation.
6316 *Returns:* On success, the number of objects deleted is returned,
6317 otherwise a negative error value.
6322 File: gnutls.info, Node: Using a PKCS11 token with TLS, Next: p11tool Invocation, Prev: Writing objects, Up: Smart cards and HSMs
6324 5.3.5 Using a PKCS #11 token with TLS
6325 -------------------------------------
6327 It is possible to use a PKCS #11 token to a TLS session, as shown in
6328 *note ex-pkcs11-client::. In addition the following functions can be
6329 used to load PKCS #11 key and certificates by specifying a PKCS #11 URL
6330 instead of a filename.
6332 'INT *note gnutls_certificate_set_x509_trust_file:: (gnutls_certificate_credentials_t CRED, const char * CAFILE, gnutls_x509_crt_fmt_t TYPE)'
6333 'INT *note gnutls_certificate_set_x509_key_file2:: (gnutls_certificate_credentials_t RES, const char * CERTFILE, const char * KEYFILE, gnutls_x509_crt_fmt_t TYPE, const char * PASS, unsigned int FLAGS)'
6335 -- Function: int gnutls_certificate_set_x509_system_trust
6336 (gnutls_certificate_credentials_t CRED)
6337 CRED: is a 'gnutls_certificate_credentials_t' type.
6339 This function adds the system's default trusted CAs in order to
6340 verify client or server certificates.
6342 In the case the system is currently unsupported
6343 'GNUTLS_E_UNIMPLEMENTED_FEATURE' is returned.
6345 *Returns:* the number of certificates processed or a negative error
6351 File: gnutls.info, Node: p11tool Invocation, Prev: Using a PKCS11 token with TLS, Up: Smart cards and HSMs
6353 5.3.6 Invoking p11tool
6354 ----------------------
6356 Program that allows operations on PKCS #11 smart cards and security
6359 To use PKCS #11 tokens with GnuTLS the p11-kit configuration files need
6360 to be setup. That is create a .module file in /etc/pkcs11/modules with
6361 the contents 'module: /path/to/pkcs11.so'. Alternatively the
6362 configuration file /etc/gnutls/pkcs11.conf has to exist and contain a
6363 number of lines of the form 'load=/usr/lib/opensc-pkcs11.so'.
6365 You can provide the PIN to be used for the PKCS #11 operations with the
6366 environment variables GNUTLS_PIN and GNUTLS_SO_PIN.
6368 This section was generated by *AutoGen*, using the 'agtexi-cmd' template
6369 and the option descriptions for the 'p11tool' program. This software is
6370 released under the GNU General Public License, version 3 or later.
6372 5.3.7 p11tool help/usage ('--help')
6373 -----------------------------------
6375 This is the automatically generated usage text for p11tool.
6377 The text printed is the same whether selected with the 'help' option
6378 ('--help') or the 'more-help' option ('--more-help'). 'more-help' will
6379 print the usage text by passing it through a pager program. 'more-help'
6380 is disabled on platforms without a working 'fork(2)' function. The
6381 'PAGER' environment variable is used to select the program, defaulting
6382 to 'more'. Both will exit with a status code of 0.
6384 p11tool - GnuTLS PKCS #11 tool
6385 Usage: p11tool [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [url]
6390 --list-tokens List all available tokens
6391 --list-token-urls List the URLs available tokens
6392 --list-mechanisms List all available mechanisms in a token
6393 --initialize Initializes a PKCS #11 token
6394 --set-pin=str Specify the PIN to use on token initialization
6395 --set-so-pin=str Specify the Security Officer's PIN to use on token initialization
6399 --list-all List all available objects in a token
6400 --list-all-certs List all available certificates in a token
6401 --list-certs List all certificates that have an associated private key
6402 --list-all-privkeys List all available private keys in a token
6403 --list-privkeys an alias for the 'list-all-privkeys' option
6404 --list-keys an alias for the 'list-all-privkeys' option
6405 --list-all-trusted List all available certificates marked as trusted
6406 --export Export the object specified by the URL
6407 --export-chain Export the certificate specified by the URL and its chain of trust
6408 --export-pubkey Export the public key for a private key
6409 --info List information on an available object in a token
6413 --generate-rsa Generate an RSA private-public key pair
6414 --generate-dsa Generate a DSA private-public key pair
6415 --generate-ecc Generate an ECDSA private-public key pair
6416 --bits=num Specify the number of bits for key generate
6417 --curve=str Specify the curve used for EC key generation
6418 --sec-param=str Specify the security level
6422 --set-id=str Set the CKA_ID (in hex) for the specified by the URL object
6423 - prohibits the option 'write'
6424 --set-label=str Set the CKA_LABEL for the specified by the URL object
6425 - prohibits these options:
6428 --write Writes the loaded objects to a PKCS #11 token
6429 --delete Deletes the objects matching the given PKCS #11 URL
6430 --label=str Sets a label for the write operation
6431 --id=str Sets an ID for the write operation
6432 --mark-wrap Marks the generated key to be a wrapping key
6433 - disabled as '--no-mark-wrap'
6434 --mark-trusted Marks the object to be written as trusted
6435 - disabled as '--no-mark-trusted'
6436 --mark-decrypt Marks the object to be written for decryption
6437 - disabled as '--no-mark-decrypt'
6438 -!, --mark-sign Marks the object to be written for signature generation
6439 - disabled as '--no-mark-sign'
6440 -", --mark-ca Marks the object to be written as a CA
6441 - disabled as '--no-mark-ca'
6442 -#, --mark-private Marks the object to be written as private
6443 - disabled as '--no-mark-private'
6444 - enabled by default
6445 -$, --trusted an alias for the 'mark-trusted' option
6446 -%, --ca an alias for the 'mark-ca' option
6447 -&, --private an alias for the 'mark-private' option
6448 - enabled by default
6449 -', --secret-key=str Provide a hex encoded secret key
6450 -(, --load-privkey=file Private key file to use
6451 - file must pre-exist
6452 -), --load-pubkey=file Public key file to use
6453 - file must pre-exist
6454 -*, --load-certificate=file Certificate file to use
6455 - file must pre-exist
6459 -d, --debug=num Enable debugging
6460 - it must be in the range:
6462 -+, --outfile=str Output file
6463 -,, --login Force (user) login to token
6464 - disabled as '--no-login'
6465 --, --so-login Force security officer login to token
6466 - disabled as '--no-so-login'
6467 -., --admin-login an alias for the 'so-login' option
6468 -/, --test-sign Tests the signature operation of the provided object
6469 -0, --generate-random=num Generate random data
6470 -8, --pkcs8 Use PKCS #8 format for private keys
6471 -1, --inder Use DER/RAW format for input
6472 - disabled as '--no-inder'
6473 -2, --inraw an alias for the 'inder' option
6474 -3, --outder Use DER format for output certificates, private keys, and DH parameters
6475 - disabled as '--no-outder'
6476 -4, --outraw an alias for the 'outder' option
6477 -5, --provider=file Specify the PKCS #11 provider library
6478 -6, --detailed-url Print detailed URLs
6479 - disabled as '--no-detailed-url'
6480 -7, --only-urls Print a compact listing using only the URLs
6481 -8, --batch Disable all interaction with the tool
6483 Version, usage and configuration options:
6485 -v, --version[=arg] output version information and exit
6486 -h, --help display extended usage information and exit
6487 -!, --more-help extended usage information passed thru pager
6489 Options are specified by doubled hyphens and their name or by a single
6490 hyphen and the flag character.
6491 Operands and options may be intermixed. They will be reordered.
6493 Program that allows operations on PKCS #11 smart cards and security
6496 To use PKCS #11 tokens with GnuTLS the p11-kit configuration files need to
6497 be setup. That is create a .module file in /etc/pkcs11/modules with the
6498 contents 'module: /path/to/pkcs11.so'. Alternatively the configuration
6499 file /etc/gnutls/pkcs11.conf has to exist and contain a number of lines of
6500 the form 'load=/usr/lib/opensc-pkcs11.so'.
6502 You can provide the PIN to be used for the PKCS #11 operations with the
6503 environment variables GNUTLS_PIN and GNUTLS_SO_PIN.
6506 5.3.8 token-related-options options
6507 -----------------------------------
6511 list-token-urls option.
6512 .......................
6514 This is the "list the urls available tokens" option. This is a more
6515 compact version of -list-tokens.
6520 This is the "specify the pin to use on token initialization" option.
6521 This option takes a string argument. Alternatively the GNUTLS_PIN
6522 environment variable may be used.
6527 This is the "specify the security officer's pin to use on token
6528 initialization" option. This option takes a string argument.
6529 Alternatively the GNUTLS_SO_PIN environment variable may be used.
6531 5.3.9 object-list-related-options options
6532 -----------------------------------------
6536 list-all-privkeys option.
6537 .........................
6539 This is the "list all available private keys in a token" option. Lists
6540 all the private keys in a token that match the specified URL.
6542 list-privkeys option.
6543 .....................
6545 This is an alias for the 'list-all-privkeys' option, *note the
6546 list-all-privkeys option documentation: p11tool list-all-privkeys.
6551 This is an alias for the 'list-all-privkeys' option, *note the
6552 list-all-privkeys option documentation: p11tool list-all-privkeys.
6554 export-chain option.
6555 ....................
6557 This is the "export the certificate specified by the url and its chain
6558 of trust" option. Exports the certificate specified by the URL and
6559 generates its chain of trust based on the stored certificates in the
6562 export-pubkey option.
6563 .....................
6565 This is the "export the public key for a private key" option. Exports
6566 the public key for the specified private key
6568 5.3.10 keygen-related-options options
6569 -------------------------------------
6573 generate-rsa option.
6574 ....................
6576 This is the "generate an rsa private-public key pair" option. Generates
6577 an RSA private-public key pair on the specified token.
6579 generate-dsa option.
6580 ....................
6582 This is the "generate a dsa private-public key pair" option. Generates
6583 a DSA private-public key pair on the specified token.
6585 generate-ecc option.
6586 ....................
6588 This is the "generate an ecdsa private-public key pair" option.
6589 Generates an ECDSA private-public key pair on the specified token.
6594 This is the "specify the curve used for ec key generation" option. This
6595 option takes a string argument. Supported values are secp192r1,
6596 secp224r1, secp256r1, secp384r1 and secp521r1.
6601 This is the "specify the security level" option. This option takes a
6602 string argument 'Security parameter'. This is alternative to the bits
6603 option. Available options are [low, legacy, medium, high, ultra].
6605 5.3.11 write-object-related-options options
6606 -------------------------------------------
6613 This is the "set the cka_id (in hex) for the specified by the url
6614 object" option. This option takes a string argument.
6616 This option has some usage constraints. It:
6617 * must not appear in combination with any of the following options:
6620 Modifies or sets the CKA_ID in the specified by the URL object. The ID
6621 should be specified in hexadecimal format without a '0x' prefix.
6626 This is the "set the cka_label for the specified by the url object"
6627 option. This option takes a string argument.
6629 This option has some usage constraints. It:
6630 * must not appear in combination with any of the following options:
6633 Modifies or sets the CKA_LABEL in the specified by the URL object
6638 This is the "writes the loaded objects to a pkcs #11 token" option. It
6639 can be used to write private keys, certificates or secret keys to a
6640 token. Must be combined with a -load option.
6645 This is the "sets an id for the write operation" option. This option
6646 takes a string argument. Sets the CKA_ID to be set by the write
6647 operation. The ID should be specified in hexadecimal format without a
6653 This is the "marks the generated key to be a wrapping key" option.
6655 This option has some usage constraints. It:
6656 * can be disabled with -no-mark-wrap.
6658 Marks the generated key with the CKA_WRAP flag.
6660 mark-trusted option.
6661 ....................
6663 This is the "marks the object to be written as trusted" option.
6665 This option has some usage constraints. It:
6666 * can be disabled with -no-mark-trusted.
6668 Marks the object to be generated/written with the CKA_TRUST flag.
6670 mark-decrypt option.
6671 ....................
6673 This is the "marks the object to be written for decryption" option.
6675 This option has some usage constraints. It:
6676 * can be disabled with -no-mark-decrypt.
6678 Marks the object to be generated/written with the CKA_DECRYPT flag set
6684 This is the "marks the object to be written for signature generation"
6687 This option has some usage constraints. It:
6688 * can be disabled with -no-mark-sign.
6690 Marks the object to be generated/written with the CKA_SIGN flag set to
6696 This is the "marks the object to be written as a ca" option.
6698 This option has some usage constraints. It:
6699 * can be disabled with -no-mark-ca.
6701 Marks the object to be generated/written with the
6702 CKA_CERTIFICATE_CATEGORY as CA.
6704 mark-private option.
6705 ....................
6707 This is the "marks the object to be written as private" option.
6709 This option has some usage constraints. It:
6710 * can be disabled with -no-mark-private.
6711 * It is enabled by default.
6713 Marks the object to be generated/written with the CKA_PRIVATE flag. The
6714 written object will require a PIN to be used.
6719 This is an alias for the 'mark-trusted' option, *note the mark-trusted
6720 option documentation: p11tool mark-trusted.
6725 This is an alias for the 'mark-ca' option, *note the mark-ca option
6726 documentation: p11tool mark-ca.
6731 This is an alias for the 'mark-private' option, *note the mark-private
6732 option documentation: p11tool mark-private.
6737 This is the "provide a hex encoded secret key" option. This option
6738 takes a string argument. This secret key will be written to the module
6739 if -write is specified.
6741 5.3.12 other-options options
6742 ----------------------------
6749 This is the "enable debugging" option. This option takes a number
6750 argument. Specifies the debug level.
6755 This is the "force security officer login to token" option.
6757 This option has some usage constraints. It:
6758 * can be disabled with -no-so-login.
6760 Forces login to the token as security officer (admin).
6765 This is an alias for the 'so-login' option, *note the so-login option
6766 documentation: p11tool so-login.
6771 This is the "tests the signature operation of the provided object"
6772 option. It can be used to test the correct operation of the signature
6773 operation. If both a private and a public key are available this
6774 operation will sign and verify the signed data.
6776 generate-random option.
6777 .......................
6779 This is the "generate random data" option. This option takes a number
6780 argument. Asks the token to generate a number of bytes of random bytes.
6785 This is the "use der/raw format for input" option.
6787 This option has some usage constraints. It:
6788 * can be disabled with -no-inder.
6790 Use DER/RAW format for input certificates and private keys.
6795 This is an alias for the 'inder' option, *note the inder option
6796 documentation: p11tool inder.
6801 This is the "use der format for output certificates, private keys, and
6802 dh parameters" option.
6804 This option has some usage constraints. It:
6805 * can be disabled with -no-outder.
6807 The output will be in DER or RAW format.
6812 This is an alias for the 'outder' option, *note the outder option
6813 documentation: p11tool outder.
6818 This is the "specify the pkcs #11 provider library" option. This option
6819 takes a file argument. This will override the default options in
6820 /etc/gnutls/pkcs11.conf
6825 This is the "disable all interaction with the tool" option. In batch
6826 mode there will be no prompts, all parameters need to be specified on
6829 5.3.13 p11tool exit status
6830 --------------------------
6832 One of the following exit values will be returned:
6834 Successful program execution.
6836 The operation failed or the command syntax was not valid.
6838 5.3.14 p11tool See Also
6839 -----------------------
6843 5.3.15 p11tool Examples
6844 -----------------------
6846 To view all tokens in your system use:
6847 $ p11tool --list-tokens
6849 To view all objects in a token use:
6850 $ p11tool --login --list-all "pkcs11:TOKEN-URL"
6852 To store a private key and a certificate in a token run:
6853 $ p11tool --login --write "pkcs11:URL" --load-privkey key.pem \
6855 $ p11tool --login --write "pkcs11:URL" --load-certificate cert.pem \
6857 Note that some tokens require the same label to be used for the
6858 certificate and its corresponding private key.
6860 To generate an RSA private key inside the token use:
6861 $ p11tool --login --generate-rsa --bits 1024 --label "MyNewKey" \
6862 --outfile MyNewKey.pub "pkcs11:TOKEN-URL"
6863 The bits parameter in the above example is explicitly set because some
6864 tokens only support limited choices in the bit length. The output file
6865 is the corresponding public key. This key can be used to general a
6866 certificate request with certtool.
6867 certtool --generate-request --load-privkey "pkcs11:KEY-URL" \
6868 --load-pubkey MyNewKey.pub --outfile request.pem
6871 File: gnutls.info, Node: Trusted Platform Module, Prev: Smart cards and HSMs, Up: Hardware security modules and abstract key types
6873 5.4 Trusted Platform Module (TPM)
6874 =================================
6876 In this section we present the Trusted Platform Module (TPM) support in
6879 There was a big hype when the TPM chip was introduced into computers.
6880 Briefly it is a co-processor in your PC that allows it to perform
6881 calculations independently of the main processor. This has good and bad
6882 side-effects. In this section we focus on the good ones; these are the
6883 fact that you can use the TPM chip to perform cryptographic operations
6884 on keys stored in it, without accessing them. That is very similar to
6885 the operation of a PKCS #11 smart card. The chip allows for storage and
6886 usage of RSA keys, but has quite some operational differences from PKCS
6887 #11 module, and thus require different handling. The basic TPM
6888 operations supported and used by GnuTLS, are key generation and signing.
6890 The next sections assume that the TPM chip in the system is already
6891 initialized and in a operational state.
6893 In GnuTLS the TPM functionality is available in 'gnutls/tpm.h'.
6900 * tpmtool Invocation::
6903 File: gnutls.info, Node: Keys in TPM, Next: Key generation, Up: Trusted Platform Module
6908 The RSA keys in the TPM module may either be stored in a flash memory
6909 within TPM or stored in a file in disk. In the former case the key can
6910 provide operations as with PKCS #11 and is identified by a URL. The URL
6911 is described in [_TPMURI_] and is of the following form.
6912 tpmkey:uuid=42309df8-d101-11e1-a89a-97bb33c23ad1;storage=user
6914 It consists from a unique identifier of the key as well as the part of
6915 the flash memory the key is stored at. The two options for the storage
6916 field are 'user' and 'system'. The user keys are typically only
6917 available to the generating user and the system keys to all users. The
6918 stored in TPM keys are called registered keys.
6920 The keys that are stored in the disk are exported from the TPM but in an
6921 encrypted form. To access them two passwords are required. The first
6922 is the TPM Storage Root Key (SRK), and the other is a key-specific
6923 password. Also those keys are identified by a URL of the form:
6924 tpmkey:file=/path/to/file
6926 When objects require a PIN to be accessed the same callbacks as with
6927 PKCS #11 objects are expected (see *note Accessing objects that require
6928 a PIN::). Note that the PIN function may be called multiple times to
6929 unlock the SRK and the specific key in use. The label in the key
6930 function will then be set to 'SRK' when unlocking the SRK key, or to
6931 'TPM' when unlocking any other key.
6934 File: gnutls.info, Node: Key generation, Next: Using keys, Prev: Keys in TPM, Up: Trusted Platform Module
6936 5.4.2 Key generation
6937 --------------------
6939 All keys used by the TPM must be generated by the TPM. This can be done
6940 using *note gnutls_tpm_privkey_generate::.
6942 -- Function: int gnutls_tpm_privkey_generate (gnutls_pk_algorithm_t PK,
6943 unsigned int BITS, const char * SRK_PASSWORD, const char *
6944 KEY_PASSWORD, gnutls_tpmkey_fmt_t FORMAT,
6945 gnutls_x509_crt_fmt_t PUB_FORMAT, gnutls_datum_t * PRIVKEY,
6946 gnutls_datum_t * PUBKEY, unsigned int FLAGS)
6947 PK: the public key algorithm
6949 BITS: the security bits
6951 SRK_PASSWORD: a password to protect the exported key (optional)
6953 KEY_PASSWORD: the password for the TPM (optional)
6955 FORMAT: the format of the private key
6957 PUB_FORMAT: the format of the public key
6959 PRIVKEY: the generated key
6961 PUBKEY: the corresponding public key (may be null)
6963 FLAGS: should be a list of GNUTLS_TPM_* flags
6965 This function will generate a private key in the TPM chip. The
6966 private key will be generated within the chip and will be exported
6967 in a wrapped with TPM's master key form. Furthermore the wrapped
6968 key can be protected with the provided 'password' .
6970 Note that bits in TPM is quantized value. If the input value is
6971 not one of the allowed values, then it will be quantized to one of
6972 512, 1024, 2048, 4096, 8192 and 16384.
6976 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6977 otherwise a negative error value.
6981 'INT *note gnutls_tpm_get_registered:: (gnutls_tpm_key_list_t * LIST)'
6982 'VOID *note gnutls_tpm_key_list_deinit:: (gnutls_tpm_key_list_t LIST)'
6983 'INT *note gnutls_tpm_key_list_get_url:: (gnutls_tpm_key_list_t LIST, unsigned int IDX, char ** URL, unsigned int FLAGS)'
6985 -- Function: int gnutls_tpm_privkey_delete (const char * URL, const
6986 char * SRK_PASSWORD)
6987 URL: the URL describing the key
6989 SRK_PASSWORD: a password for the SRK key
6991 This function will unregister the private key from the TPM chip.
6993 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
6994 otherwise a negative error value.
6999 File: gnutls.info, Node: Using keys, Next: tpmtool Invocation, Prev: Key generation, Up: Trusted Platform Module
7007 The TPM keys can be used directly by the abstract key types and do not
7008 require any special structures. Moreover functions like *note
7009 gnutls_certificate_set_x509_key_file2:: can access TPM URLs.
7011 'INT *note gnutls_privkey_import_tpm_raw:: (gnutls_privkey_t PKEY, const gnutls_datum_t * FDATA, gnutls_tpmkey_fmt_t FORMAT, const char * SRK_PASSWORD, const char * KEY_PASSWORD, unsigned int FLAGS)'
7012 'INT *note gnutls_pubkey_import_tpm_raw:: (gnutls_pubkey_t PKEY, const gnutls_datum_t * FDATA, gnutls_tpmkey_fmt_t FORMAT, const char * SRK_PASSWORD, unsigned int FLAGS)'
7014 -- Function: int gnutls_privkey_import_tpm_url (gnutls_privkey_t PKEY,
7015 const char * URL, const char * SRK_PASSWORD, const char *
7016 KEY_PASSWORD, unsigned int FLAGS)
7017 PKEY: The private key
7019 URL: The URL of the TPM key to be imported
7021 SRK_PASSWORD: The password for the SRK key (optional)
7023 KEY_PASSWORD: A password for the key (optional)
7025 FLAGS: One of the GNUTLS_PRIVKEY_* flags
7027 This function will import the given private key to the abstract
7028 'gnutls_privkey_t' type.
7030 Note that unless 'GNUTLS_PRIVKEY_DISABLE_CALLBACKS' is specified,
7031 if incorrect (or NULL) passwords are given the PKCS11 callback
7032 functions will be used to obtain the correct passwords. Otherwise
7033 if the SRK password is wrong 'GNUTLS_E_TPM_SRK_PASSWORD_ERROR' is
7034 returned and if the key password is wrong or not provided then
7035 'GNUTLS_E_TPM_KEY_PASSWORD_ERROR' is returned.
7037 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7038 otherwise a negative error value.
7042 -- Function: int gnutls_pubkey_import_tpm_url (gnutls_pubkey_t PKEY,
7043 const char * URL, const char * SRK_PASSWORD, unsigned int
7045 PKEY: The public key
7047 URL: The URL of the TPM key to be imported
7049 SRK_PASSWORD: The password for the SRK key (optional)
7051 FLAGS: should be zero
7053 This function will import the given private key to the abstract
7054 'gnutls_privkey_t' type.
7056 Note that unless 'GNUTLS_PUBKEY_DISABLE_CALLBACKS' is specified, if
7057 incorrect (or NULL) passwords are given the PKCS11 callback
7058 functions will be used to obtain the correct passwords. Otherwise
7059 if the SRK password is wrong 'GNUTLS_E_TPM_SRK_PASSWORD_ERROR' is
7062 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7063 otherwise a negative error value.
7067 Listing and deleting keys
7068 .........................
7070 The registered keys (that are stored in the TPM) can be listed using one
7071 of the following functions. Those keys are unfortunately only
7072 identified by their UUID and have no label or other human friendly
7073 identifier. Keys can be deleted from permament storage using *note
7074 gnutls_tpm_privkey_delete::.
7076 'INT *note gnutls_tpm_get_registered:: (gnutls_tpm_key_list_t * LIST)'
7077 'VOID *note gnutls_tpm_key_list_deinit:: (gnutls_tpm_key_list_t LIST)'
7078 'INT *note gnutls_tpm_key_list_get_url:: (gnutls_tpm_key_list_t LIST, unsigned int IDX, char ** URL, unsigned int FLAGS)'
7080 -- Function: int gnutls_tpm_privkey_delete (const char * URL, const
7081 char * SRK_PASSWORD)
7082 URL: the URL describing the key
7084 SRK_PASSWORD: a password for the SRK key
7086 This function will unregister the private key from the TPM chip.
7088 *Returns:* On success, 'GNUTLS_E_SUCCESS' (0) is returned,
7089 otherwise a negative error value.
7094 File: gnutls.info, Node: tpmtool Invocation, Prev: Using keys, Up: Trusted Platform Module
7096 5.4.4 Invoking tpmtool
7097 ----------------------
7099 Program that allows handling cryptographic data from the TPM chip.
7101 This section was generated by *AutoGen*, using the 'agtexi-cmd' template
7102 and the option descriptions for the 'tpmtool' program. This software is
7103 released under the GNU General Public License, version 3 or later.
7105 5.4.5 tpmtool help/usage ('--help')
7106 -----------------------------------
7108 This is the automatically generated usage text for tpmtool.
7110 The text printed is the same whether selected with the 'help' option
7111 ('--help') or the 'more-help' option ('--more-help'). 'more-help' will
7112 print the usage text by passing it through a pager program. 'more-help'
7113 is disabled on platforms without a working 'fork(2)' function. The
7114 'PAGER' environment variable is used to select the program, defaulting
7115 to 'more'. Both will exit with a status code of 0.
7117 tpmtool - GnuTLS TPM tool
7118 Usage: tpmtool [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
7120 -d, --debug=num Enable debugging
7121 - it must be in the range:
7123 --infile=file Input file
7124 - file must pre-exist
7125 --outfile=str Output file
7126 --generate-rsa Generate an RSA private-public key pair
7127 --register Any generated key will be registered in the TPM
7128 - requires the option 'generate-rsa'
7129 --signing Any generated key will be a signing key
7130 - requires the option 'generate-rsa'
7131 -- and prohibits the option 'legacy'
7132 --legacy Any generated key will be a legacy key
7133 - requires the option 'generate-rsa'
7134 -- and prohibits the option 'signing'
7135 --user Any registered key will be a user key
7136 - requires the option 'register'
7137 -- and prohibits the option 'system'
7138 --system Any registered key will be a system key
7139 - requires the option 'register'
7140 -- and prohibits the option 'user'
7141 --pubkey=str Prints the public key of the provided key
7142 --list Lists all stored keys in the TPM
7143 --delete=str Delete the key identified by the given URL (UUID).
7144 --test-sign=str Tests the signature operation of the provided object
7145 --sec-param=str Specify the security level [low, legacy, medium, high, ultra].
7146 --bits=num Specify the number of bits for key generate
7147 --inder Use the DER format for keys.
7148 - disabled as '--no-inder'
7149 --outder Use DER format for output keys
7150 - disabled as '--no-outder'
7151 -v, --version[=arg] output version information and exit
7152 -h, --help display extended usage information and exit
7153 -!, --more-help extended usage information passed thru pager
7155 Options are specified by doubled hyphens and their name or by a single
7156 hyphen and the flag character.
7158 Program that allows handling cryptographic data from the TPM chip.
7161 5.4.6 debug option (-d)
7162 -----------------------
7164 This is the "enable debugging" option. This option takes a number
7165 argument. Specifies the debug level.
7167 5.4.7 generate-rsa option
7168 -------------------------
7170 This is the "generate an rsa private-public key pair" option. Generates
7171 an RSA private-public key pair in the TPM chip. The key may be stored
7172 in filesystem and protected by a PIN, or stored (registered) in the TPM
7178 This is the "any registered key will be a user key" option.
7180 This option has some usage constraints. It:
7181 * must appear in combination with the following options: register.
7182 * must not appear in combination with any of the following options:
7185 The generated key will be stored in a user specific persistent storage.
7190 This is the "any registered key will be a system key" option.
7192 This option has some usage constraints. It:
7193 * must appear in combination with the following options: register.
7194 * must not appear in combination with any of the following options:
7197 The generated key will be stored in system persistent storage.
7199 5.4.10 test-sign option
7200 -----------------------
7202 This is the "tests the signature operation of the provided object"
7203 option. This option takes a string argument 'url'. It can be used to
7204 test the correct operation of the signature operation. This operation
7205 will sign and verify the signed data.
7207 5.4.11 sec-param option
7208 -----------------------
7210 This is the "specify the security level [low, legacy, medium, high,
7211 ultra]." option. This option takes a string argument 'Security
7212 parameter'. This is alternative to the bits option. Note however that
7213 the values allowed by the TPM chip are quantized and given values may be
7219 This is the "use the der format for keys." option.
7221 This option has some usage constraints. It:
7222 * can be disabled with -no-inder.
7224 The input files will be assumed to be in the portable DER format of TPM.
7225 The default format is a custom format used by various TPM tools
7227 5.4.13 outder option
7228 --------------------
7230 This is the "use der format for output keys" option.
7232 This option has some usage constraints. It:
7233 * can be disabled with -no-outder.
7235 The output will be in the TPM portable DER format.
7237 5.4.14 tpmtool exit status
7238 --------------------------
7240 One of the following exit values will be returned:
7242 Successful program execution.
7244 The operation failed or the command syntax was not valid.
7246 5.4.15 tpmtool See Also
7247 -----------------------
7249 p11tool (1), certtool (1)
7251 5.4.16 tpmtool Examples
7252 -----------------------
7254 To generate a key that is to be stored in filesystem use:
7255 $ tpmtool --generate-rsa --bits 2048 --outfile tpmkey.pem
7257 To generate a key that is to be stored in TPM's flash use:
7258 $ tpmtool --generate-rsa --bits 2048 --register --user
7260 To get the public key of a TPM key use:
7261 $ tpmtool --pubkey tpmkey:uuid=58ad734b-bde6-45c7-89d8-756a55ad1891;storage=user \
7262 --outfile pubkey.pem
7264 or if the key is stored in the filesystem:
7265 $ tpmtool --pubkey tpmkey:file=tmpkey.pem --outfile pubkey.pem
7267 To list all keys stored in TPM use:
projects / platform / upstream / gnutls.git / blob