2 * Copyright (C) 2001-2012 Free Software Foundation, Inc.
4 * Author: Nikos Mavrogiannopoulos
6 * This file is part of GnuTLS.
8 * The GnuTLS is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public License
10 * as published by the Free Software Foundation; either version 3 of
11 * the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful, but
14 * WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with this program. If not, see <http://www.gnu.org/licenses/>
23 /* Some of the stuff needed for Certificate authentication is contained
27 #include <gnutls_int.h>
28 #include <gnutls_errors.h>
29 #include <auth/cert.h>
30 #include <gnutls_datum.h>
31 #include <gnutls_mpi.h>
32 #include <gnutls_global.h>
33 #include <algorithms.h>
34 #include <gnutls_dh.h>
35 #include <gnutls_str.h>
36 #include <gnutls_state.h>
37 #include <gnutls_auth.h>
38 #include <gnutls_x509.h>
39 #include <gnutls_str_array.h>
40 #include "x509/x509_int.h"
42 #include "openpgp/gnutls_openpgp.h"
46 * gnutls_certificate_free_keys:
47 * @sc: is a #gnutls_certificate_credentials_t structure.
49 * This function will delete all the keys and the certificates associated
50 * with the given credentials. This function must not be called when a
51 * TLS negotiation that uses the credentials is in progress.
55 gnutls_certificate_free_keys (gnutls_certificate_credentials_t sc
)
59 for (i
= 0; i
< sc
->ncerts
; i
++)
61 for (j
= 0; j
< sc
->certs
[i
].cert_list_length
; j
++)
63 gnutls_pcert_deinit (&sc
->certs
[i
].cert_list
[j
]);
65 gnutls_free (sc
->certs
[i
].cert_list
);
66 _gnutls_str_array_clear (&sc
->certs
[i
].names
);
69 gnutls_free (sc
->certs
);
72 for (i
= 0; i
< sc
->ncerts
; i
++)
74 gnutls_privkey_deinit (sc
->pkey
[i
]);
77 gnutls_free (sc
->pkey
);
84 * gnutls_certificate_free_cas:
85 * @sc: is a #gnutls_certificate_credentials_t structure.
87 * This function will delete all the CAs associated with the given
88 * credentials. Servers that do not use
89 * gnutls_certificate_verify_peers2() may call this to save some
93 gnutls_certificate_free_cas (gnutls_certificate_credentials_t sc
)
95 /* FIXME: do nothing for now */
100 * gnutls_certificate_get_issuer:
101 * @sc: is a #gnutls_certificate_credentials_t structure.
102 * @cert: is the certificate to find issuer for
103 * @issuer: Will hold the issuer if any. Should be treated as constant.
106 * This function will return the issuer of a given certificate.
108 * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
109 * negative error value.
114 gnutls_certificate_get_issuer (gnutls_certificate_credentials_t sc
,
115 gnutls_x509_crt_t cert
, gnutls_x509_crt_t
* issuer
, unsigned int flags
)
117 return gnutls_x509_trust_list_get_issuer(sc
->tlist
, cert
, issuer
, flags
);
121 * gnutls_certificate_free_ca_names:
122 * @sc: is a #gnutls_certificate_credentials_t structure.
124 * This function will delete all the CA name in the given
125 * credentials. Clients may call this to save some memory since in
126 * client side the CA names are not used. Servers might want to use
127 * this function if a large list of trusted CAs is present and
128 * sending the names of it would just consume bandwidth without providing
129 * information to client.
131 * CA names are used by servers to advertise the CAs they support to
135 gnutls_certificate_free_ca_names (gnutls_certificate_credentials_t sc
)
137 _gnutls_free_datum (&sc
->x509_rdn_sequence
);
141 * _gnutls_certificate_get_rsa_params - Returns the RSA parameters pointer
142 * @rsa_params: holds the RSA parameters or NULL.
143 * @func: function to retrieve the parameters or NULL.
144 * @session: The session.
146 * This function will return the rsa parameters pointer.
149 _gnutls_certificate_get_rsa_params (gnutls_rsa_params_t rsa_params
,
150 gnutls_params_function
* func
,
151 gnutls_session_t session
)
153 gnutls_params_st params
;
156 if (session
->internals
.params
.rsa_params
)
158 return session
->internals
.params
.rsa_params
;
163 session
->internals
.params
.rsa_params
= rsa_params
;
167 ret
= func (session
, GNUTLS_PARAMS_RSA_EXPORT
, ¶ms
);
168 if (ret
== 0 && params
.type
== GNUTLS_PARAMS_RSA_EXPORT
)
170 session
->internals
.params
.rsa_params
= params
.params
.rsa_export
;
171 session
->internals
.params
.free_rsa_params
= params
.deinit
;
175 return session
->internals
.params
.rsa_params
;
180 * gnutls_certificate_free_credentials:
181 * @sc: is a #gnutls_certificate_credentials_t structure.
183 * This structure is complex enough to manipulate directly thus this
184 * helper function is provided in order to free (deallocate) it.
186 * This function does not free any temporary parameters associated
187 * with this structure (ie RSA and DH parameters are not freed by this
191 gnutls_certificate_free_credentials (gnutls_certificate_credentials_t sc
)
193 gnutls_x509_trust_list_deinit(sc
->tlist
, 1);
194 gnutls_certificate_free_keys (sc
);
195 gnutls_certificate_free_ca_names (sc
);
197 #ifdef ENABLE_OPENPGP
198 gnutls_openpgp_keyring_deinit (sc
->keyring
);
206 * gnutls_certificate_allocate_credentials:
207 * @res: is a pointer to a #gnutls_certificate_credentials_t structure.
209 * This structure is complex enough to manipulate directly thus this
210 * helper function is provided in order to allocate it.
212 * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
215 gnutls_certificate_allocate_credentials (gnutls_certificate_credentials_t
*
220 *res
= gnutls_calloc (1, sizeof (certificate_credentials_st
));
223 return GNUTLS_E_MEMORY_ERROR
;
225 ret
= gnutls_x509_trust_list_init( &(*res
)->tlist
, 0);
230 return GNUTLS_E_MEMORY_ERROR
;
232 (*res
)->verify_bits
= DEFAULT_MAX_VERIFY_BITS
;
233 (*res
)->verify_depth
= DEFAULT_MAX_VERIFY_DEPTH
;
234 (*res
)->verify_flags
= GNUTLS_VERIFY_ALLOW_UNSORTED_CHAIN
;
240 /* returns the KX algorithms that are supported by a
241 * certificate. (Eg a certificate with RSA params, supports
242 * GNUTLS_KX_RSA algorithm).
243 * This function also uses the KeyUsage field of the certificate
244 * extensions in order to disable unneded algorithms.
247 _gnutls_selected_cert_supported_kx (gnutls_session_t session
,
248 gnutls_kx_algorithm_t
* alg
,
251 gnutls_kx_algorithm_t kx
;
252 gnutls_pk_algorithm_t pk
, cert_pk
;
253 gnutls_pcert_st
*cert
;
256 if (session
->internals
.selected_cert_list_length
== 0)
262 cert
= &session
->internals
.selected_cert_list
[0];
263 cert_pk
= gnutls_pubkey_get_pk_algorithm(cert
->pubkey
, NULL
);
266 for (kx
= 0; kx
< MAX_ALGOS
; kx
++)
268 pk
= _gnutls_map_pk_get_pk (kx
);
271 /* then check key usage */
272 if (_gnutls_check_key_usage (cert
, kx
) == 0)
278 return gnutls_assert_val(GNUTLS_E_INTERNAL_ERROR
);
286 return GNUTLS_E_INVALID_REQUEST
;
296 * gnutls_certificate_server_set_request:
297 * @session: is a #gnutls_session_t structure.
298 * @req: is one of GNUTLS_CERT_REQUEST, GNUTLS_CERT_REQUIRE
300 * This function specifies if we (in case of a server) are going to
301 * send a certificate request message to the client. If @req is
302 * GNUTLS_CERT_REQUIRE then the server will return an error if the
303 * peer does not provide a certificate. If you do not call this
304 * function then the client will not be asked to send a certificate.
307 gnutls_certificate_server_set_request (gnutls_session_t session
,
308 gnutls_certificate_request_t req
)
310 session
->internals
.send_cert_req
= req
;
314 * gnutls_certificate_client_set_retrieve_function:
315 * @cred: is a #gnutls_certificate_credentials_t structure.
316 * @func: is the callback function
318 * This function sets a callback to be called in order to retrieve the
319 * certificate to be used in the handshake.
320 * You are advised to use gnutls_certificate_set_retrieve_function2() because it
321 * is much more efficient in the processing it requires from gnutls.
323 * The callback's function prototype is:
324 * int (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int nreqs,
325 * const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length, gnutls_retr_st* st);
327 * @req_ca_cert is only used in X.509 certificates.
328 * Contains a list with the CA names that the server considers trusted.
329 * Normally we should send a certificate that is signed
330 * by one of these CAs. These names are DER encoded. To get a more
331 * meaningful value use the function gnutls_x509_rdn_get().
333 * @pk_algos contains a list with server's acceptable signature algorithms.
334 * The certificate returned should support the server's given algorithms.
336 * @st should contain the certificates and private keys.
338 * If the callback function is provided then gnutls will call it, in the
339 * handshake, if a certificate is requested by the server (and after the
340 * certificate request message has been received).
342 * The callback function should set the certificate list to be sent,
343 * and return 0 on success. If no certificate was selected then the
344 * number of certificates should be set to zero. The value (-1)
345 * indicates error and the handshake will be terminated.
347 void gnutls_certificate_client_set_retrieve_function
348 (gnutls_certificate_credentials_t cred
,
349 gnutls_certificate_client_retrieve_function
* func
)
351 cred
->client_get_cert_callback
= func
;
355 * gnutls_certificate_server_set_retrieve_function:
356 * @cred: is a #gnutls_certificate_credentials_t structure.
357 * @func: is the callback function
359 * This function sets a callback to be called in order to retrieve the
360 * certificate to be used in the handshake.
361 * You are advised to use gnutls_certificate_set_retrieve_function2() because it
362 * is much more efficient in the processing it requires from gnutls.
364 * The callback's function prototype is:
365 * int (*callback)(gnutls_session_t, gnutls_retr_st* st);
367 * @st should contain the certificates and private keys.
369 * If the callback function is provided then gnutls will call it, in the
370 * handshake, after the certificate request message has been received.
372 * The callback function should set the certificate list to be sent, and
373 * return 0 on success. The value (-1) indicates error and the handshake
374 * will be terminated.
376 void gnutls_certificate_server_set_retrieve_function
377 (gnutls_certificate_credentials_t cred
,
378 gnutls_certificate_server_retrieve_function
* func
)
380 cred
->server_get_cert_callback
= func
;
384 * gnutls_certificate_set_retrieve_function:
385 * @cred: is a #gnutls_certificate_credentials_t structure.
386 * @func: is the callback function
388 * This function sets a callback to be called in order to retrieve the
389 * certificate to be used in the handshake. You are advised
390 * to use gnutls_certificate_set_retrieve_function2() because it
391 * is much more efficient in the processing it requires from gnutls.
393 * The callback's function prototype is:
394 * int (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int nreqs,
395 * const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length, gnutls_retr2_st* st);
397 * @req_ca_cert is only used in X.509 certificates.
398 * Contains a list with the CA names that the server considers trusted.
399 * Normally we should send a certificate that is signed
400 * by one of these CAs. These names are DER encoded. To get a more
401 * meaningful value use the function gnutls_x509_rdn_get().
403 * @pk_algos contains a list with server's acceptable signature algorithms.
404 * The certificate returned should support the server's given algorithms.
406 * @st should contain the certificates and private keys.
408 * If the callback function is provided then gnutls will call it, in the
409 * handshake, after the certificate request message has been received.
411 * In server side pk_algos and req_ca_dn are NULL.
413 * The callback function should set the certificate list to be sent,
414 * and return 0 on success. If no certificate was selected then the
415 * number of certificates should be set to zero. The value (-1)
416 * indicates error and the handshake will be terminated.
420 void gnutls_certificate_set_retrieve_function
421 (gnutls_certificate_credentials_t cred
,
422 gnutls_certificate_retrieve_function
* func
)
424 cred
->get_cert_callback
= func
;
428 * gnutls_certificate_set_retrieve_function2:
429 * @cred: is a #gnutls_certificate_credentials_t structure.
430 * @func: is the callback function
432 * This function sets a callback to be called in order to retrieve the
433 * certificate to be used in the handshake.
435 * The callback's function prototype is:
436 * int (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int nreqs,
437 * const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length, gnutls_pcert_st** pcert,
438 * unsigned int *pcert_length, gnutls_privkey_t * pkey);
440 * @req_ca_cert is only used in X.509 certificates.
441 * Contains a list with the CA names that the server considers trusted.
442 * Normally we should send a certificate that is signed
443 * by one of these CAs. These names are DER encoded. To get a more
444 * meaningful value use the function gnutls_x509_rdn_get().
446 * @pk_algos contains a list with server's acceptable signature algorithms.
447 * The certificate returned should support the server's given algorithms.
449 * @pcert should contain a single certificate and public or a list of them.
451 * @pcert_length is the size of the previous list.
453 * @pkey is the private key.
455 * If the callback function is provided then gnutls will call it, in the
456 * handshake, after the certificate request message has been received.
458 * In server side pk_algos and req_ca_dn are NULL.
460 * The callback function should set the certificate list to be sent,
461 * and return 0 on success. If no certificate was selected then the
462 * number of certificates should be set to zero. The value (-1)
463 * indicates error and the handshake will be terminated.
467 void gnutls_certificate_set_retrieve_function2
468 (gnutls_certificate_credentials_t cred
,
469 gnutls_certificate_retrieve_function2
* func
)
471 cred
->get_cert_callback2
= func
;
475 * gnutls_certificate_set_verify_function:
476 * @cred: is a #gnutls_certificate_credentials_t structure.
477 * @func: is the callback function
479 * This function sets a callback to be called when peer's certificate
480 * has been received in order to verify it on receipt rather than
481 * doing after the handshake is completed.
483 * The callback's function prototype is:
484 * int (*callback)(gnutls_session_t);
486 * If the callback function is provided then gnutls will call it, in the
487 * handshake, just after the certificate message has been received.
488 * To verify or obtain the certificate the gnutls_certificate_verify_peers2(),
489 * gnutls_certificate_type_get(), gnutls_certificate_get_peers() functions
492 * The callback function should return 0 for the handshake to continue
493 * or non-zero to terminate.
498 gnutls_certificate_set_verify_function
499 (gnutls_certificate_credentials_t cred
,
500 gnutls_certificate_verify_function
* func
)
502 cred
->verify_callback
= func
;
506 * _gnutls_x509_extract_certificate_activation_time - return the peer's certificate activation time
507 * @cert: should contain an X.509 DER encoded certificate
509 * This function will return the certificate's activation time in UNIX time
510 * (ie seconds since 00:00:00 UTC January 1, 1970).
512 * Returns a (time_t) -1 in case of an error.
516 _gnutls_x509_get_raw_crt_activation_time (const gnutls_datum_t
* cert
)
518 gnutls_x509_crt_t xcert
;
521 result
= gnutls_x509_crt_init (&xcert
);
525 result
= gnutls_x509_crt_import (xcert
, cert
, GNUTLS_X509_FMT_DER
);
528 gnutls_x509_crt_deinit (xcert
);
532 result
= gnutls_x509_crt_get_activation_time (xcert
);
534 gnutls_x509_crt_deinit (xcert
);
540 * gnutls_x509_extract_certificate_expiration_time:
541 * @cert: should contain an X.509 DER encoded certificate
543 * This function will return the certificate's expiration time in UNIX
544 * time (ie seconds since 00:00:00 UTC January 1, 1970). Returns a
546 * (time_t) -1 in case of an error.
550 _gnutls_x509_get_raw_crt_expiration_time (const gnutls_datum_t
* cert
)
552 gnutls_x509_crt_t xcert
;
555 result
= gnutls_x509_crt_init (&xcert
);
559 result
= gnutls_x509_crt_import (xcert
, cert
, GNUTLS_X509_FMT_DER
);
562 gnutls_x509_crt_deinit (xcert
);
566 result
= gnutls_x509_crt_get_expiration_time (xcert
);
568 gnutls_x509_crt_deinit (xcert
);
573 #ifdef ENABLE_OPENPGP
575 * _gnutls_openpgp_crt_verify_peers - return the peer's certificate status
576 * @session: is a gnutls session
578 * This function will try to verify the peer's certificate and return its status (TRUSTED, INVALID etc.).
579 * Returns a negative error code in case of an error, or GNUTLS_E_NO_CERTIFICATE_FOUND if no certificate was sent.
582 _gnutls_openpgp_crt_verify_peers (gnutls_session_t session
,
583 unsigned int *status
)
585 cert_auth_info_t info
;
586 gnutls_certificate_credentials_t cred
;
587 int peer_certificate_list_size
, ret
;
589 CHECK_AUTH (GNUTLS_CRD_CERTIFICATE
, GNUTLS_E_INVALID_REQUEST
);
591 info
= _gnutls_get_auth_info (session
);
593 return GNUTLS_E_INVALID_REQUEST
;
595 cred
= (gnutls_certificate_credentials_t
)
596 _gnutls_get_cred (session
->key
, GNUTLS_CRD_CERTIFICATE
, NULL
);
600 return GNUTLS_E_INSUFFICIENT_CREDENTIALS
;
603 if (info
->raw_certificate_list
== NULL
|| info
->ncerts
== 0)
606 return GNUTLS_E_NO_CERTIFICATE_FOUND
;
609 /* generate a list of gnutls_certs based on the auth info
612 peer_certificate_list_size
= info
->ncerts
;
614 if (peer_certificate_list_size
!= 1)
617 return GNUTLS_E_INTERNAL_ERROR
;
620 /* Verify certificate
623 _gnutls_openpgp_verify_key (cred
, &info
->raw_certificate_list
[0],
624 peer_certificate_list_size
, status
);
637 * gnutls_certificate_verify_peers2:
638 * @session: is a gnutls session
639 * @status: is the output of the verification
641 * This function will try to verify the peer's certificate and return
642 * its status (trusted, invalid etc.). The value of @status should
643 * be one or more of the gnutls_certificate_status_t enumerated
644 * elements bitwise or'd. To avoid denial of service attacks some
645 * default upper limits regarding the certificate key size and chain
646 * size are set. To override them use
647 * gnutls_certificate_set_verify_limits().
649 * Note that you must also check the peer's name in order to check if
650 * the verified certificate belongs to the actual peer, see gnutls_x509_crt_check_hostname().
652 * Returns: a negative error code on error and %GNUTLS_E_SUCCESS (0) on success.
655 gnutls_certificate_verify_peers2 (gnutls_session_t session
,
656 unsigned int *status
)
658 cert_auth_info_t info
;
660 CHECK_AUTH (GNUTLS_CRD_CERTIFICATE
, GNUTLS_E_INVALID_REQUEST
);
662 info
= _gnutls_get_auth_info (session
);
665 return GNUTLS_E_NO_CERTIFICATE_FOUND
;
668 if (info
->raw_certificate_list
== NULL
|| info
->ncerts
== 0)
669 return GNUTLS_E_NO_CERTIFICATE_FOUND
;
671 switch (gnutls_certificate_type_get (session
))
673 case GNUTLS_CRT_X509
:
674 return _gnutls_x509_cert_verify_peers (session
, status
);
675 #ifdef ENABLE_OPENPGP
676 case GNUTLS_CRT_OPENPGP
:
677 return _gnutls_openpgp_crt_verify_peers (session
, status
);
680 return GNUTLS_E_INVALID_REQUEST
;
685 * gnutls_certificate_expiration_time_peers:
686 * @session: is a gnutls session
688 * This function will return the peer's certificate expiration time.
690 * Returns: (time_t)-1 on error.
692 * Deprecated: gnutls_certificate_verify_peers2() now verifies expiration times.
695 gnutls_certificate_expiration_time_peers (gnutls_session_t session
)
697 cert_auth_info_t info
;
699 CHECK_AUTH (GNUTLS_CRD_CERTIFICATE
, GNUTLS_E_INVALID_REQUEST
);
701 info
= _gnutls_get_auth_info (session
);
707 if (info
->raw_certificate_list
== NULL
|| info
->ncerts
== 0)
713 switch (gnutls_certificate_type_get (session
))
715 case GNUTLS_CRT_X509
:
717 _gnutls_x509_get_raw_crt_expiration_time (&info
->raw_certificate_list
719 #ifdef ENABLE_OPENPGP
720 case GNUTLS_CRT_OPENPGP
:
722 _gnutls_openpgp_get_raw_key_expiration_time
723 (&info
->raw_certificate_list
[0]);
731 * gnutls_certificate_activation_time_peers:
732 * @session: is a gnutls session
734 * This function will return the peer's certificate activation time.
735 * This is the creation time for openpgp keys.
737 * Returns: (time_t)-1 on error.
739 * Deprecated: gnutls_certificate_verify_peers2() now verifies activation times.
742 gnutls_certificate_activation_time_peers (gnutls_session_t session
)
744 cert_auth_info_t info
;
746 CHECK_AUTH (GNUTLS_CRD_CERTIFICATE
, GNUTLS_E_INVALID_REQUEST
);
748 info
= _gnutls_get_auth_info (session
);
754 if (info
->raw_certificate_list
== NULL
|| info
->ncerts
== 0)
760 switch (gnutls_certificate_type_get (session
))
762 case GNUTLS_CRT_X509
:
764 _gnutls_x509_get_raw_crt_activation_time (&info
->raw_certificate_list
766 #ifdef ENABLE_OPENPGP
767 case GNUTLS_CRT_OPENPGP
:
769 _gnutls_openpgp_get_raw_key_creation_time (&info
->raw_certificate_list
778 * gnutls_sign_callback_set:
779 * @session: is a gnutls session
780 * @sign_func: function pointer to application's sign callback.
781 * @userdata: void pointer that will be passed to sign callback.
783 * Set the callback function. The function must have this prototype:
785 * typedef int (*gnutls_sign_func) (gnutls_session_t session,
787 * gnutls_certificate_type_t cert_type,
788 * const gnutls_datum_t * cert,
789 * const gnutls_datum_t * hash,
790 * gnutls_datum_t * signature);
792 * The @userdata parameter is passed to the @sign_func verbatim, and
793 * can be used to store application-specific data needed in the
794 * callback function. See also gnutls_sign_callback_get().
796 * Deprecated: Use the PKCS 11 or #gnutls_privkey_t interfacess like gnutls_privkey_import_ext() instead.
799 gnutls_sign_callback_set (gnutls_session_t session
,
800 gnutls_sign_func sign_func
, void *userdata
)
802 session
->internals
.sign_func
= sign_func
;
803 session
->internals
.sign_func_userdata
= userdata
;
807 * gnutls_sign_callback_get:
808 * @session: is a gnutls session
809 * @userdata: if non-%NULL, will be set to abstract callback pointer.
811 * Retrieve the callback function, and its userdata pointer.
813 * Returns: The function pointer set by gnutls_sign_callback_set(), or
816 * Deprecated: Use the PKCS 11 interfaces instead.
819 gnutls_sign_callback_get (gnutls_session_t session
, void **userdata
)
822 *userdata
= session
->internals
.sign_func_userdata
;
823 return session
->internals
.sign_func
;
826 /* returns error if the certificate has different algorithm than
827 * the given key parameters.
830 _gnutls_check_key_cert_match (gnutls_certificate_credentials_t res
)
832 int pk
= gnutls_pubkey_get_pk_algorithm(res
->certs
[res
->ncerts
-1].cert_list
[0].pubkey
, NULL
);
833 int pk2
= gnutls_privkey_get_pk_algorithm (res
->pkey
[res
->ncerts
- 1], NULL
);
838 return GNUTLS_E_CERTIFICATE_KEY_MISMATCH
;