2 * Copyright (C) 2002-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 #include <gnutls_int.h>
24 #include "gnutls_auth.h"
25 #include "gnutls_errors.h"
26 #include <auth/cert.h>
27 #include "gnutls_dh.h"
28 #include "gnutls_num.h"
29 #include "gnutls_datum.h"
30 #include <gnutls_pk.h>
31 #include <algorithms.h>
32 #include <gnutls_global.h>
33 #include <gnutls_record.h>
34 #include <gnutls_sig.h>
35 #include <gnutls_state.h>
36 #include <gnutls_pk.h>
37 #include <gnutls_str.h>
40 #include <gnutls_x509.h>
41 #include <gnutls/ocsp.h>
42 #include "x509/common.h"
43 #include "x509/x509_int.h"
44 #include <gnutls_str_array.h>
45 #include "read-file.h"
47 # include <wincrypt.h>
51 * some x509 certificate parsing functions.
54 /* Check if the number of bits of the key in the certificate
58 check_bits (gnutls_session_t session
, gnutls_x509_crt_t crt
, unsigned int max_bits
)
63 ret
= gnutls_x509_crt_get_pk_algorithm (crt
, &bits
);
71 if (bits
> max_bits
&& max_bits
> 0)
74 return GNUTLS_E_CONSTRAINT_ERROR
;
77 if (gnutls_pk_bits_to_sec_param(pk
, bits
) == GNUTLS_SEC_PARAM_INSECURE
)
80 _gnutls_audit_log(session
, "The security level of the certificate (%s: %u) is weak\n", gnutls_pk_get_name(pk
), bits
);
81 if (session
->internals
.priorities
.allow_weak_keys
== 0)
82 return gnutls_assert_val(GNUTLS_E_CERTIFICATE_ERROR
);
89 #define MAX_OCSP_VALIDITY_SECS (3*60*60*24)
91 /* If the certificate is revoked status will be GNUTLS_CERT_REVOKED.
94 * Zero on success, a negative error code otherwise.
97 check_ocsp_response (gnutls_session_t session
, gnutls_x509_crt_t cert
,
98 gnutls_x509_crt_t issuer
,
99 gnutls_datum_t
*data
, unsigned int * ostatus
)
101 gnutls_ocsp_resp_t resp
;
103 unsigned int status
, cert_status
;
104 time_t rtime
, vtime
, ntime
, now
;
106 now
= gnutls_time(0);
108 ret
= gnutls_ocsp_resp_init (&resp
);
110 return gnutls_assert_val(ret
);
112 ret
= gnutls_ocsp_resp_import (resp
, data
);
114 return gnutls_assert_val(ret
);
116 ret
= gnutls_ocsp_resp_check_crt(resp
, 0, cert
);
119 _gnutls_audit_log (session
, "Got OCSP response on an unrelated certificate.\n");
123 ret
= gnutls_ocsp_resp_verify_direct( resp
, issuer
, &status
, 0);
125 return gnutls_assert_val(ret
);
127 /* do not consider revocation data if response was not verified */
130 ret
= gnutls_assert_val(0);
134 ret
= gnutls_ocsp_resp_get_single(resp
, 0, NULL
, NULL
, NULL
, NULL
,
135 &cert_status
, &vtime
, &ntime
, &rtime
, NULL
);
138 ret
= gnutls_assert_val(0);
139 *ostatus
|= GNUTLS_CERT_REVOCATION_DATA_INVALID
;
143 if (cert_status
== GNUTLS_OCSP_CERT_REVOKED
)
145 _gnutls_audit_log(session
, "The certificate was revoked via OCSP\n");
146 *ostatus
|= GNUTLS_CERT_REVOKED
;
147 ret
= gnutls_assert_val(0);
153 if (now
- vtime
> MAX_OCSP_VALIDITY_SECS
)
155 _gnutls_audit_log(session
, "The OCSP response is old\n");
160 /* there is a newer OCSP answer, don't trust this one */
163 _gnutls_audit_log(session
, "There is a newer OCSP response but was not provided by the server\n");
164 if (now
-ntime
> MAX_OCSP_VALIDITY_SECS
)
165 *ostatus
|= GNUTLS_CERT_REVOCATION_DATA_TOO_OLD
;
171 gnutls_ocsp_resp_deinit (resp
);
177 #define CLEAR_CERTS for(x=0;x<peer_certificate_list_size;x++) { \
178 if (peer_certificate_list[x]) \
179 gnutls_x509_crt_deinit(peer_certificate_list[x]); \
181 gnutls_free( peer_certificate_list)
184 * _gnutls_x509_cert_verify_peers - return the peer's certificate status
185 * @session: is a gnutls session
187 * This function will try to verify the peer's certificate and return its status (TRUSTED, REVOKED etc.).
188 * The return value (status) should be one of the gnutls_certificate_status_t enumerated elements.
189 * However you must also check the peer's name in order to check if the verified certificate belongs to the
190 * actual peer. Returns a negative error code in case of an error, or GNUTLS_E_NO_CERTIFICATE_FOUND if no certificate was sent.
193 _gnutls_x509_cert_verify_peers (gnutls_session_t session
,
194 const char* hostname
,
195 unsigned int *status
)
197 cert_auth_info_t info
;
198 gnutls_certificate_credentials_t cred
;
199 gnutls_x509_crt_t
*peer_certificate_list
;
201 int peer_certificate_list_size
, i
, x
, ret
;
202 gnutls_x509_crt_t issuer
;
203 unsigned int ocsp_status
= 0;
204 unsigned int verify_flags
;
206 CHECK_AUTH (GNUTLS_CRD_CERTIFICATE
, GNUTLS_E_INVALID_REQUEST
);
208 info
= _gnutls_get_auth_info (session
);
212 return GNUTLS_E_INVALID_REQUEST
;
215 cred
= (gnutls_certificate_credentials_t
)
216 _gnutls_get_cred (session
, GNUTLS_CRD_CERTIFICATE
, NULL
);
220 return GNUTLS_E_INSUFFICIENT_CREDENTIALS
;
223 if (info
->raw_certificate_list
== NULL
|| info
->ncerts
== 0)
224 return GNUTLS_E_NO_CERTIFICATE_FOUND
;
226 if (info
->ncerts
> cred
->verify_depth
&& cred
->verify_depth
> 0)
229 return GNUTLS_E_CONSTRAINT_ERROR
;
232 verify_flags
= cred
->verify_flags
| session
->internals
.priorities
.additional_verify_flags
;
233 /* generate a list of gnutls_certs based on the auth info
236 peer_certificate_list_size
= info
->ncerts
;
237 peer_certificate_list
=
238 gnutls_calloc (peer_certificate_list_size
, sizeof (gnutls_x509_crt_t
));
239 if (peer_certificate_list
== NULL
)
242 return GNUTLS_E_MEMORY_ERROR
;
245 for (i
= 0; i
< peer_certificate_list_size
; i
++)
247 ret
= gnutls_x509_crt_init (&peer_certificate_list
[i
]);
256 gnutls_x509_crt_import (peer_certificate_list
[i
],
257 &info
->raw_certificate_list
[i
],
258 GNUTLS_X509_FMT_DER
);
266 ret
= check_bits (session
, peer_certificate_list
[i
], cred
->verify_bits
);
276 /* Use the OCSP extension if any */
277 if (verify_flags
& GNUTLS_VERIFY_DISABLE_CRL_CHECKS
)
280 ret
= gnutls_ocsp_status_request_get(session
, &resp
);
284 if (peer_certificate_list_size
> 1)
285 issuer
= peer_certificate_list
[1];
288 ret
= gnutls_x509_trust_list_get_issuer(cred
->tlist
, peer_certificate_list
[0],
296 ret
= check_ocsp_response(session
, peer_certificate_list
[0], issuer
, &resp
, &ocsp_status
);
300 return gnutls_assert_val(ret
);
304 /* Verify certificate
306 ret
= gnutls_x509_trust_list_verify_crt (cred
->tlist
, peer_certificate_list
,
307 peer_certificate_list_size
,
308 verify_flags
, status
, NULL
);
319 ret
= gnutls_x509_crt_check_hostname( peer_certificate_list
[0], hostname
);
321 *status
|= GNUTLS_CERT_UNEXPECTED_OWNER
;
326 *status
|= ocsp_status
;
331 /* Returns the name of the certificate of a null name
333 static int get_x509_name(gnutls_x509_crt_t crt
, gnutls_str_array_t
*names
)
336 int i
, ret
= 0, ret2
;
339 for (i
= 0; !(ret
< 0); i
++)
341 max_size
= sizeof(name
);
343 ret
= gnutls_x509_crt_get_subject_alt_name(crt
, i
, name
, &max_size
, NULL
);
344 if (ret
== GNUTLS_SAN_DNSNAME
)
346 ret2
= _gnutls_str_array_append(names
, name
, max_size
);
349 _gnutls_str_array_clear(names
);
350 return gnutls_assert_val(ret2
);
355 max_size
= sizeof(name
);
356 ret
= gnutls_x509_crt_get_dn_by_oid (crt
, OID_X520_COMMON_NAME
, 0, 0, name
, &max_size
);
359 ret
= _gnutls_str_array_append(names
, name
, max_size
);
362 _gnutls_str_array_clear(names
);
363 return gnutls_assert_val(ret
);
370 static int get_x509_name_raw(gnutls_datum_t
*raw
, gnutls_x509_crt_fmt_t type
, gnutls_str_array_t
*names
)
373 gnutls_x509_crt_t crt
;
375 ret
= gnutls_x509_crt_init (&crt
);
382 ret
= gnutls_x509_crt_import (crt
, raw
, type
);
386 gnutls_x509_crt_deinit (crt
);
390 ret
= get_x509_name(crt
, names
);
391 gnutls_x509_crt_deinit (crt
);
395 /* Reads a DER encoded certificate list from memory and stores it to a
396 * gnutls_cert structure. Returns the number of certificates parsed.
399 parse_der_cert_mem (gnutls_certificate_credentials_t res
,
400 const void *input_cert
, int input_cert_size
)
403 gnutls_x509_crt_t crt
;
404 gnutls_pcert_st
*ccert
;
406 gnutls_str_array_t names
;
408 _gnutls_str_array_init(&names
);
410 ccert
= gnutls_malloc (sizeof (*ccert
));
414 return GNUTLS_E_MEMORY_ERROR
;
417 ret
= gnutls_x509_crt_init (&crt
);
424 tmp
.data
= (uint8_t *) input_cert
;
425 tmp
.size
= input_cert_size
;
427 ret
= gnutls_x509_crt_import (crt
, &tmp
, GNUTLS_X509_FMT_DER
);
431 gnutls_x509_crt_deinit (crt
);
435 ret
= get_x509_name(crt
, &names
);
439 gnutls_x509_crt_deinit (crt
);
443 ret
= gnutls_pcert_import_x509 (ccert
, crt
, 0);
444 gnutls_x509_crt_deinit (crt
);
452 ret
= certificate_credential_append_crt_list (res
, names
, ccert
, 1);
462 _gnutls_str_array_clear(&names
);
467 /* Reads a base64 encoded certificate list from memory and stores it to
468 * a gnutls_cert structure. Returns the number of certificate parsed.
471 parse_pem_cert_mem (gnutls_certificate_credentials_t res
,
472 const char *input_cert
, int input_cert_size
)
478 gnutls_pcert_st
*certs
= NULL
;
479 gnutls_str_array_t names
;
481 _gnutls_str_array_init(&names
);
483 /* move to the certificate
485 ptr
= memmem (input_cert
, input_cert_size
,
486 PEM_CERT_SEP
, sizeof (PEM_CERT_SEP
) - 1);
488 ptr
= memmem (input_cert
, input_cert_size
,
489 PEM_CERT_SEP2
, sizeof (PEM_CERT_SEP2
) - 1);
494 return GNUTLS_E_BASE64_DECODING_ERROR
;
496 size
= input_cert_size
- (ptr
- input_cert
);
502 certs
= gnutls_realloc_fast (certs
, (count
+ 1) * sizeof (gnutls_pcert_st
));
507 ret
= GNUTLS_E_MEMORY_ERROR
;
511 tmp
.data
= (void*)ptr
;
516 ret
= get_x509_name_raw(&tmp
, GNUTLS_X509_FMT_PEM
, &names
);
524 ret
= gnutls_pcert_import_x509_raw (&certs
[count
], &tmp
, GNUTLS_X509_FMT_PEM
, 0);
531 /* now we move ptr after the pem header
534 /* find the next certificate (if any)
536 size
= input_cert_size
- (ptr
- input_cert
);
542 ptr3
= memmem (ptr
, size
, PEM_CERT_SEP
, sizeof (PEM_CERT_SEP
) - 1);
544 ptr3
= memmem (ptr
, size
, PEM_CERT_SEP2
,
545 sizeof (PEM_CERT_SEP2
) - 1);
557 ret
= certificate_credential_append_crt_list (res
, names
, certs
, count
);
567 _gnutls_str_array_clear(&names
);
568 for (i
=0;i
<count
;i
++)
569 gnutls_pcert_deinit(&certs
[i
]);
576 /* Reads a DER or PEM certificate from memory
579 read_cert_mem (gnutls_certificate_credentials_t res
, const void *cert
,
580 int cert_size
, gnutls_x509_crt_fmt_t type
)
584 if (type
== GNUTLS_X509_FMT_DER
)
585 ret
= parse_der_cert_mem (res
, cert
, cert_size
);
587 ret
= parse_pem_cert_mem (res
, cert
, cert_size
);
598 /* Reads a PEM encoded PKCS-1 RSA/DSA private key from memory. Type
599 * indicates the certificate format. KEY can be NULL, to indicate
600 * that GnuTLS doesn't know the private key.
603 read_key_mem (gnutls_certificate_credentials_t res
,
604 const void *key
, int key_size
, gnutls_x509_crt_fmt_t type
)
608 gnutls_privkey_t privkey
;
612 tmp
.data
= (uint8_t *) key
;
615 ret
= gnutls_privkey_init(&privkey
);
623 gnutls_privkey_set_pin_function(privkey
, res
->pin
.cb
, res
->pin
.data
);
625 ret
= gnutls_privkey_import_x509_raw (privkey
, &tmp
, type
, NULL
, 0);
632 ret
= certificate_credentials_append_pkey (res
, privkey
);
636 gnutls_privkey_deinit (privkey
);
644 return GNUTLS_E_INVALID_REQUEST
;
652 /* Reads a private key from a token.
655 read_key_url (gnutls_certificate_credentials_t res
, const char *url
)
658 gnutls_privkey_t pkey
= NULL
;
660 /* allocate space for the pkey list
662 ret
= gnutls_privkey_init (&pkey
);
670 gnutls_privkey_set_pin_function(pkey
, res
->pin
.cb
, res
->pin
.data
);
672 ret
= gnutls_privkey_import_url (pkey
, url
, 0);
679 ret
= certificate_credentials_append_pkey (res
, pkey
);
690 gnutls_privkey_deinit (pkey
);
696 /* Reads a private key from a token.
699 read_cas_url (gnutls_certificate_credentials_t res
, const char *url
)
702 gnutls_x509_crt_t
*xcrt_list
= NULL
;
703 gnutls_pkcs11_obj_t
*pcrt_list
= NULL
;
704 unsigned int pcrt_list_size
= 0;
706 /* FIXME: should we use login? */
708 gnutls_pkcs11_obj_list_import_url (NULL
, &pcrt_list_size
, url
,
709 GNUTLS_PKCS11_OBJ_ATTR_CRT_TRUSTED
, 0);
710 if (ret
< 0 && ret
!= GNUTLS_E_SHORT_MEMORY_BUFFER
)
716 if (pcrt_list_size
== 0)
722 pcrt_list
= gnutls_malloc (sizeof (*pcrt_list
) * pcrt_list_size
);
723 if (pcrt_list
== NULL
)
726 return GNUTLS_E_MEMORY_ERROR
;
730 gnutls_pkcs11_obj_list_import_url (pcrt_list
, &pcrt_list_size
, url
,
731 GNUTLS_PKCS11_OBJ_ATTR_CRT_TRUSTED
, 0);
738 xcrt_list
= gnutls_malloc (sizeof (*xcrt_list
) * pcrt_list_size
);
739 if (xcrt_list
== NULL
)
742 ret
= GNUTLS_E_MEMORY_ERROR
;
747 gnutls_x509_crt_list_import_pkcs11 (xcrt_list
, pcrt_list_size
, pcrt_list
,
755 ret
= gnutls_x509_trust_list_add_cas(res
->tlist
, xcrt_list
, pcrt_list_size
, 0);
763 gnutls_free (xcrt_list
);
764 gnutls_free (pcrt_list
);
771 /* Reads a certificate key from a token.
774 read_cert_url (gnutls_certificate_credentials_t res
, const char *url
)
777 gnutls_x509_crt_t crt
;
778 gnutls_pcert_st
*ccert
;
779 gnutls_str_array_t names
;
781 _gnutls_str_array_init(&names
);
783 ccert
= gnutls_malloc (sizeof (*ccert
));
787 return GNUTLS_E_MEMORY_ERROR
;
790 ret
= gnutls_x509_crt_init (&crt
);
798 gnutls_x509_crt_set_pin_function(crt
, res
->pin
.cb
, res
->pin
.data
);
800 ret
= gnutls_x509_crt_import_pkcs11_url (crt
, url
, 0);
801 if (ret
== GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
)
803 gnutls_x509_crt_import_pkcs11_url (crt
, url
,
804 GNUTLS_PKCS11_OBJ_FLAG_LOGIN
);
809 gnutls_x509_crt_deinit (crt
);
813 ret
= get_x509_name(crt
, &names
);
817 gnutls_x509_crt_deinit (crt
);
821 ret
= gnutls_pcert_import_x509 (ccert
, crt
, 0);
822 gnutls_x509_crt_deinit (crt
);
830 ret
= certificate_credential_append_crt_list (res
, names
, ccert
, 1);
840 _gnutls_str_array_clear(&names
);
846 /* Reads a certificate file
849 read_cert_file (gnutls_certificate_credentials_t res
,
850 const char *certfile
, gnutls_x509_crt_fmt_t type
)
857 if (strncmp (certfile
, "pkcs11:", 7) == 0)
859 return read_cert_url (res
, certfile
);
861 #endif /* ENABLE_PKCS11 */
863 data
= read_binary_file (certfile
, &size
);
868 return GNUTLS_E_FILE_ERROR
;
871 ret
= read_cert_mem (res
, data
, size
, type
);
880 /* Reads PKCS-1 RSA private key file or a DSA file (in the format openssl
884 read_key_file (gnutls_certificate_credentials_t res
,
885 const char *keyfile
, gnutls_x509_crt_fmt_t type
)
891 if (gnutls_url_is_supported(keyfile
))
893 return read_key_url (res
, keyfile
);
896 data
= read_binary_file (keyfile
, &size
);
901 return GNUTLS_E_FILE_ERROR
;
904 ret
= read_key_mem (res
, data
, size
, type
);
911 * gnutls_certificate_set_x509_key_mem:
912 * @res: is a #gnutls_certificate_credentials_t structure.
913 * @cert: contains a certificate list (path) for the specified private key
914 * @key: is the private key, or %NULL
915 * @type: is PEM or DER
917 * This function sets a certificate/private key pair in the
918 * gnutls_certificate_credentials_t structure. This function may be called
919 * more than once, in case multiple keys/certificates exist for the
922 * Note that the keyUsage (2.5.29.15) PKIX extension in X.509 certificates
923 * is supported. This means that certificates intended for signing cannot
924 * be used for ciphersuites that require encryption.
926 * If the certificate and the private key are given in PEM encoding
927 * then the strings that hold their values must be null terminated.
929 * The @key may be %NULL if you are using a sign callback, see
930 * gnutls_sign_callback_set().
932 * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
935 gnutls_certificate_set_x509_key_mem (gnutls_certificate_credentials_t res
,
936 const gnutls_datum_t
* cert
,
937 const gnutls_datum_t
* key
,
938 gnutls_x509_crt_fmt_t type
)
942 /* this should be first
944 if ((ret
= read_key_mem (res
, key
? key
->data
: NULL
,
945 key
? key
->size
: 0, type
)) < 0)
948 if ((ret
= read_cert_mem (res
, cert
->data
, cert
->size
, type
)) < 0)
953 if (key
&& (ret
= _gnutls_check_key_cert_match (res
)) < 0)
962 static int check_if_sorted(gnutls_pcert_st
* crt
, int nr
)
964 gnutls_x509_crt_t x509
;
965 char prev_dn
[MAX_DN
];
967 size_t prev_dn_size
, dn_size
;
970 /* check if the X.509 list is ordered */
971 if (nr
> 1 && crt
[0].type
== GNUTLS_CRT_X509
)
976 ret
= gnutls_x509_crt_init(&x509
);
978 return gnutls_assert_val(ret
);
980 ret
= gnutls_x509_crt_import(x509
, &crt
[i
].cert
, GNUTLS_X509_FMT_DER
);
983 ret
= gnutls_assert_val(ret
);
989 dn_size
= sizeof(dn
);
990 ret
= gnutls_x509_crt_get_dn(x509
, dn
, &dn_size
);
993 ret
= gnutls_assert_val(ret
);
997 if (dn_size
!= prev_dn_size
|| memcmp(dn
, prev_dn
, dn_size
) != 0)
999 ret
= gnutls_assert_val(GNUTLS_E_CERTIFICATE_LIST_UNSORTED
);
1004 prev_dn_size
= sizeof(prev_dn
);
1005 ret
= gnutls_x509_crt_get_issuer_dn(x509
, prev_dn
, &prev_dn_size
);
1008 ret
= gnutls_assert_val(ret
);
1012 gnutls_x509_crt_deinit(x509
);
1019 gnutls_x509_crt_deinit(x509
);
1024 certificate_credential_append_crt_list (gnutls_certificate_credentials_t res
,
1025 gnutls_str_array_t names
, gnutls_pcert_st
* crt
, int nr
)
1029 ret
= check_if_sorted(crt
, nr
);
1031 return gnutls_assert_val(ret
);
1033 res
->certs
= gnutls_realloc_fast (res
->certs
,
1036 if (res
->certs
== NULL
)
1039 return GNUTLS_E_MEMORY_ERROR
;
1042 res
->certs
[res
->ncerts
].cert_list
= crt
;
1043 res
->certs
[res
->ncerts
].cert_list_length
= nr
;
1044 res
->certs
[res
->ncerts
].names
= names
;
1051 certificate_credentials_append_pkey (gnutls_certificate_credentials_t res
,
1052 gnutls_privkey_t pkey
)
1054 res
->pkey
= gnutls_realloc_fast (res
->pkey
,
1056 sizeof (gnutls_privkey_t
));
1057 if (res
->pkey
== NULL
)
1060 return GNUTLS_E_MEMORY_ERROR
;
1062 res
->pkey
[res
->ncerts
] = pkey
;
1068 * gnutls_certificate_set_x509_key:
1069 * @res: is a #gnutls_certificate_credentials_t structure.
1070 * @cert_list: contains a certificate list (path) for the specified private key
1071 * @cert_list_size: holds the size of the certificate list
1072 * @key: is a #gnutls_x509_privkey_t key
1074 * This function sets a certificate/private key pair in the
1075 * gnutls_certificate_credentials_t structure. This function may be
1076 * called more than once, in case multiple keys/certificates exist for
1077 * the server. For clients that wants to send more than their own end
1078 * entity certificate (e.g., also an intermediate CA cert) then put
1079 * the certificate chain in @cert_list.
1081 * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
1086 gnutls_certificate_set_x509_key (gnutls_certificate_credentials_t res
,
1087 gnutls_x509_crt_t
* cert_list
,
1089 gnutls_x509_privkey_t key
)
1092 gnutls_privkey_t pkey
;
1093 gnutls_pcert_st
*pcerts
= NULL
;
1094 gnutls_str_array_t names
;
1096 _gnutls_str_array_init(&names
);
1098 /* this should be first
1100 ret
= gnutls_privkey_init (&pkey
);
1108 gnutls_privkey_set_pin_function(pkey
, res
->pin
.cb
, res
->pin
.data
);
1110 ret
= gnutls_privkey_import_x509 (pkey
, key
, GNUTLS_PRIVKEY_IMPORT_COPY
);
1117 ret
= certificate_credentials_append_pkey (res
, pkey
);
1124 /* load certificates */
1125 pcerts
= gnutls_malloc (sizeof (gnutls_pcert_st
) * cert_list_size
);
1129 return GNUTLS_E_MEMORY_ERROR
;
1132 ret
= get_x509_name(cert_list
[0], &names
);
1134 return gnutls_assert_val(ret
);
1136 for (i
= 0; i
< cert_list_size
; i
++)
1138 ret
= gnutls_pcert_import_x509 (&pcerts
[i
], cert_list
[i
], 0);
1146 ret
= certificate_credential_append_crt_list (res
, names
, pcerts
, cert_list_size
);
1155 if ((ret
= _gnutls_check_key_cert_match (res
)) < 0)
1164 _gnutls_str_array_clear(&names
);
1169 * gnutls_certificate_set_key:
1170 * @res: is a #gnutls_certificate_credentials_t structure.
1171 * @names: is an array of DNS name of the certificate (NULL if none)
1172 * @names_size: holds the size of the names list
1173 * @pcert_list: contains a certificate list (path) for the specified private key
1174 * @pcert_list_size: holds the size of the certificate list
1175 * @key: is a #gnutls_privkey_t key
1177 * This function sets a certificate/private key pair in the
1178 * gnutls_certificate_credentials_t structure. This function may be
1179 * called more than once, in case multiple keys/certificates exist for
1180 * the server. For clients that wants to send more than its own end
1181 * entity certificate (e.g., also an intermediate CA cert) then put
1182 * the certificate chain in @pcert_list. The @pcert_list and @key will
1183 * become part of the credentials structure and must not
1184 * be deallocated. They will be automatically deallocated when @res
1187 * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
1192 gnutls_certificate_set_key (gnutls_certificate_credentials_t res
,
1195 gnutls_pcert_st
* pcert_list
,
1196 int pcert_list_size
,
1197 gnutls_privkey_t key
)
1200 gnutls_str_array_t str_names
;
1202 _gnutls_str_array_init(&str_names
);
1204 if (names
!= NULL
&& names_size
> 0)
1206 for (i
=0;i
<names_size
;i
++)
1208 ret
= _gnutls_str_array_append(&str_names
, names
[i
], strlen(names
[i
]));
1211 ret
= gnutls_assert_val(ret
);
1218 gnutls_privkey_set_pin_function(key
, res
->pin
.cb
, res
->pin
.data
);
1220 ret
= certificate_credentials_append_pkey (res
, key
);
1227 ret
= certificate_credential_append_crt_list (res
, str_names
, pcert_list
, pcert_list_size
);
1236 if ((ret
= _gnutls_check_key_cert_match (res
)) < 0)
1245 _gnutls_str_array_clear(&str_names
);
1250 * gnutls_certificate_set_x509_key_file:
1251 * @res: is a #gnutls_certificate_credentials_t structure.
1252 * @certfile: is a file that containing the certificate list (path) for
1253 * the specified private key, in PKCS7 format, or a list of certificates
1254 * @keyfile: is a file that contains the private key
1255 * @type: is PEM or DER
1257 * This function sets a certificate/private key pair in the
1258 * gnutls_certificate_credentials_t structure. This function may be
1259 * called more than once, in case multiple keys/certificates exist for
1260 * the server. For clients that need to send more than its own end
1261 * entity certificate, e.g., also an intermediate CA cert, then the
1262 * @certfile must contain the ordered certificate chain.
1264 * This function can also accept URLs at @keyfile and @certfile. In that case it
1265 * will import the private key and certificate indicated by the URLs. Note
1266 * that the supported URLs are the ones indicated by gnutls_url_is_supported().
1268 * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
1271 gnutls_certificate_set_x509_key_file (gnutls_certificate_credentials_t res
,
1272 const char *certfile
,
1273 const char *keyfile
,
1274 gnutls_x509_crt_fmt_t type
)
1278 /* this should be first
1280 if ((ret
= read_key_file (res
, keyfile
, type
)) < 0)
1283 if ((ret
= read_cert_file (res
, certfile
, type
)) < 0)
1288 if ((ret
= _gnutls_check_key_cert_match (res
)) < 0)
1298 add_new_crt_to_rdn_seq (gnutls_certificate_credentials_t res
, gnutls_x509_crt_t
* crts
,
1299 unsigned int crt_size
)
1304 unsigned char *newdata
, *p
;
1307 /* Add DN of the last added CAs to the RDN sequence
1308 * This will be sent to clients when a certificate
1309 * request message is sent.
1312 /* FIXME: in case of a client it is not needed
1313 * to do that. This would save time and memory.
1314 * However we don't have that information available
1316 * Further, this function is now much more efficient,
1317 * so optimizing that is less important.
1320 for (i
= 0; i
< crt_size
; i
++)
1322 if ((ret
= gnutls_x509_crt_get_raw_dn (crts
[i
], &tmp
)) < 0)
1328 newsize
= res
->x509_rdn_sequence
.size
+ 2 + tmp
.size
;
1329 if (newsize
< res
->x509_rdn_sequence
.size
)
1332 _gnutls_free_datum (&tmp
);
1333 return GNUTLS_E_SHORT_MEMORY_BUFFER
;
1336 newdata
= gnutls_realloc (res
->x509_rdn_sequence
.data
, newsize
);
1337 if (newdata
== NULL
)
1340 _gnutls_free_datum (&tmp
);
1341 return GNUTLS_E_MEMORY_ERROR
;
1344 p
= newdata
+ res
->x509_rdn_sequence
.size
;
1345 _gnutls_write_uint16 (tmp
.size
, p
);
1346 if (tmp
.data
!= NULL
)
1347 memcpy (p
+2, tmp
.data
, tmp
.size
);
1349 _gnutls_free_datum (&tmp
);
1351 res
->x509_rdn_sequence
.size
= newsize
;
1352 res
->x509_rdn_sequence
.data
= newdata
;
1358 /* Returns 0 if it's ok to use the gnutls_kx_algorithm_t with this
1359 * certificate (uses the KeyUsage field).
1362 _gnutls_check_key_usage (const gnutls_pcert_st
* cert
, gnutls_kx_algorithm_t alg
)
1364 unsigned int key_usage
= 0;
1370 return GNUTLS_E_INTERNAL_ERROR
;
1373 if (_gnutls_map_kx_get_cred (alg
, 1) == GNUTLS_CRD_CERTIFICATE
||
1374 _gnutls_map_kx_get_cred (alg
, 0) == GNUTLS_CRD_CERTIFICATE
)
1377 gnutls_pubkey_get_key_usage(cert
->pubkey
, &key_usage
);
1379 encipher_type
= _gnutls_kx_encipher_type (alg
);
1381 if (key_usage
!= 0 && encipher_type
!= CIPHER_IGN
)
1383 /* If key_usage has been set in the certificate
1386 if (encipher_type
== CIPHER_ENCRYPT
)
1388 /* If the key exchange method requires an encipher
1389 * type algorithm, and key's usage does not permit
1390 * encipherment, then fail.
1392 if (!(key_usage
& GNUTLS_KEY_KEY_ENCIPHERMENT
))
1395 return GNUTLS_E_KEY_USAGE_VIOLATION
;
1399 if (encipher_type
== CIPHER_SIGN
)
1401 /* The same as above, but for sign only keys
1403 if (!(key_usage
& GNUTLS_KEY_DIGITAL_SIGNATURE
))
1406 return GNUTLS_E_KEY_USAGE_VIOLATION
;
1415 parse_pem_ca_mem (gnutls_certificate_credentials_t res
,
1416 const uint8_t * input_cert
, int input_cert_size
)
1418 gnutls_x509_crt_t
*x509_cert_list
;
1419 unsigned int x509_ncerts
;
1423 tmp
.data
= (void*)input_cert
;
1424 tmp
.size
= input_cert_size
;
1426 ret
= gnutls_x509_crt_list_import2( &x509_cert_list
, &x509_ncerts
, &tmp
,
1427 GNUTLS_X509_FMT_PEM
, 0);
1434 if ((ret
= add_new_crt_to_rdn_seq (res
, x509_cert_list
, x509_ncerts
)) < 0)
1440 ret
= gnutls_x509_trust_list_add_cas(res
->tlist
, x509_cert_list
, x509_ncerts
, 0);
1448 gnutls_free(x509_cert_list
);
1452 /* Reads a DER encoded certificate list from memory and stores it to a
1453 * gnutls_cert structure. Returns the number of certificates parsed.
1456 parse_der_ca_mem (gnutls_certificate_credentials_t res
,
1457 const void *input_cert
, int input_cert_size
)
1459 gnutls_x509_crt_t crt
;
1463 tmp
.data
= (void*)input_cert
;
1464 tmp
.size
= input_cert_size
;
1466 ret
= gnutls_x509_crt_init( &crt
);
1473 ret
= gnutls_x509_crt_import( crt
, &tmp
, GNUTLS_X509_FMT_DER
);
1480 if ((ret
= add_new_crt_to_rdn_seq (res
, &crt
, 1)) < 0)
1486 ret
= gnutls_x509_trust_list_add_cas(res
->tlist
, &crt
, 1, 0);
1496 gnutls_x509_crt_deinit(crt
);
1501 * gnutls_certificate_set_x509_trust_mem:
1502 * @res: is a #gnutls_certificate_credentials_t structure.
1503 * @ca: is a list of trusted CAs or a DER certificate
1504 * @type: is DER or PEM
1506 * This function adds the trusted CAs in order to verify client or
1507 * server certificates. In case of a client this is not required to be
1508 * called if the certificates are not verified using
1509 * gnutls_certificate_verify_peers2(). This function may be called
1512 * In case of a server the CAs set here will be sent to the client if
1513 * a certificate request is sent. This can be disabled using
1514 * gnutls_certificate_send_x509_rdn_sequence().
1516 * Returns: the number of certificates processed or a negative error code
1520 gnutls_certificate_set_x509_trust_mem (gnutls_certificate_credentials_t res
,
1521 const gnutls_datum_t
* ca
,
1522 gnutls_x509_crt_fmt_t type
)
1526 if (type
== GNUTLS_X509_FMT_DER
)
1527 ret
= parse_der_ca_mem (res
,
1528 ca
->data
, ca
->size
);
1530 ret
= parse_pem_ca_mem (res
,
1531 ca
->data
, ca
->size
);
1533 if (ret
== GNUTLS_E_NO_CERTIFICATE_FOUND
)
1540 * gnutls_certificate_set_x509_trust:
1541 * @res: is a #gnutls_certificate_credentials_t structure.
1542 * @ca_list: is a list of trusted CAs
1543 * @ca_list_size: holds the size of the CA list
1545 * This function adds the trusted CAs in order to verify client
1546 * or server certificates. In case of a client this is not required
1547 * to be called if the certificates are not verified using
1548 * gnutls_certificate_verify_peers2().
1549 * This function may be called multiple times.
1551 * In case of a server the CAs set here will be sent to the client if
1552 * a certificate request is sent. This can be disabled using
1553 * gnutls_certificate_send_x509_rdn_sequence().
1555 * Returns: the number of certificates processed or a negative error code
1561 gnutls_certificate_set_x509_trust (gnutls_certificate_credentials_t res
,
1562 gnutls_x509_crt_t
* ca_list
,
1566 gnutls_x509_crt_t new_list
[ca_list_size
];
1568 for (i
= 0; i
< ca_list_size
; i
++)
1570 ret
= gnutls_x509_crt_init (&new_list
[i
]);
1577 ret
= _gnutls_x509_crt_cpy (new_list
[i
], ca_list
[i
]);
1585 if ((ret
= add_new_crt_to_rdn_seq (res
, new_list
, ca_list_size
)) < 0)
1591 ret
= gnutls_x509_trust_list_add_cas(res
->tlist
, new_list
, ca_list_size
, 0);
1602 gnutls_x509_crt_deinit(new_list
[j
]);
1609 * gnutls_certificate_set_x509_trust_file:
1610 * @cred: is a #gnutls_certificate_credentials_t structure.
1611 * @cafile: is a file containing the list of trusted CAs (DER or PEM list)
1612 * @type: is PEM or DER
1614 * This function adds the trusted CAs in order to verify client or
1615 * server certificates. In case of a client this is not required to
1616 * be called if the certificates are not verified using
1617 * gnutls_certificate_verify_peers2(). This function may be called
1620 * In case of a server the names of the CAs set here will be sent to
1621 * the client if a certificate request is sent. This can be disabled
1622 * using gnutls_certificate_send_x509_rdn_sequence().
1624 * This function can also accept URLs. In that case it
1625 * will import all certificates that are marked as trusted. Note
1626 * that the supported URLs are the ones indicated by gnutls_url_is_supported().
1628 * Returns: number of certificates processed, or a negative error code on
1632 gnutls_certificate_set_x509_trust_file (gnutls_certificate_credentials_t cred
,
1634 gnutls_x509_crt_fmt_t type
)
1640 #ifdef ENABLE_PKCS11
1641 if (strncmp (cafile
, "pkcs11:", 7) == 0)
1643 return read_cas_url (cred
, cafile
);
1647 cas
.data
= (void*)read_binary_file (cafile
, &size
);
1648 if (cas
.data
== NULL
)
1651 return GNUTLS_E_FILE_ERROR
;
1656 ret
= gnutls_certificate_set_x509_trust_mem(cred
, &cas
, type
);
1670 * gnutls_certificate_set_x509_system_trust:
1671 * @cred: is a #gnutls_certificate_credentials_t structure.
1673 * This function adds the system's default trusted CAs in order to
1674 * verify client or server certificates.
1676 * In the case the system is currently unsupported %GNUTLS_E_UNIMPLEMENTED_FEATURE
1679 * Returns: the number of certificates processed or a negative error code
1685 gnutls_certificate_set_x509_system_trust (gnutls_certificate_credentials_t cred
)
1687 return gnutls_x509_trust_list_add_system_trust(cred
->tlist
, 0, 0);
1691 parse_pem_crl_mem (gnutls_x509_trust_list_t tlist
,
1692 const char * input_crl
, unsigned int input_crl_size
)
1694 gnutls_x509_crl_t
*x509_crl_list
;
1695 unsigned int x509_ncrls
;
1699 tmp
.data
= (void*)input_crl
;
1700 tmp
.size
= input_crl_size
;
1702 ret
= gnutls_x509_crl_list_import2( &x509_crl_list
, &x509_ncrls
, &tmp
,
1703 GNUTLS_X509_FMT_PEM
, 0);
1710 ret
= gnutls_x509_trust_list_add_crls(tlist
, x509_crl_list
, x509_ncrls
, 0, 0);
1718 gnutls_free(x509_crl_list
);
1722 /* Reads a DER encoded certificate list from memory and stores it to a
1723 * gnutls_cert structure. Returns the number of certificates parsed.
1726 parse_der_crl_mem (gnutls_x509_trust_list_t tlist
,
1727 const void *input_crl
, unsigned int input_crl_size
)
1729 gnutls_x509_crl_t crl
;
1733 tmp
.data
= (void*)input_crl
;
1734 tmp
.size
= input_crl_size
;
1736 ret
= gnutls_x509_crl_init( &crl
);
1743 ret
= gnutls_x509_crl_import( crl
, &tmp
, GNUTLS_X509_FMT_DER
);
1750 ret
= gnutls_x509_trust_list_add_crls(tlist
, &crl
, 1, 0, 0);
1760 gnutls_x509_crl_deinit(crl
);
1766 /* Reads a DER or PEM CRL from memory
1769 read_crl_mem (gnutls_certificate_credentials_t res
, const void *crl
,
1770 int crl_size
, gnutls_x509_crt_fmt_t type
)
1774 if (type
== GNUTLS_X509_FMT_DER
)
1775 ret
= parse_der_crl_mem (res
->tlist
, crl
, crl_size
);
1777 ret
= parse_pem_crl_mem (res
->tlist
, crl
, crl_size
);
1788 * gnutls_certificate_set_x509_crl_mem:
1789 * @res: is a #gnutls_certificate_credentials_t structure.
1790 * @CRL: is a list of trusted CRLs. They should have been verified before.
1791 * @type: is DER or PEM
1793 * This function adds the trusted CRLs in order to verify client or
1794 * server certificates. In case of a client this is not required to
1795 * be called if the certificates are not verified using
1796 * gnutls_certificate_verify_peers2(). This function may be called
1799 * Returns: number of CRLs processed, or a negative error code on error.
1802 gnutls_certificate_set_x509_crl_mem (gnutls_certificate_credentials_t res
,
1803 const gnutls_datum_t
* CRL
,
1804 gnutls_x509_crt_fmt_t type
)
1806 return read_crl_mem (res
, CRL
->data
, CRL
->size
, type
);
1810 * gnutls_certificate_set_x509_crl:
1811 * @res: is a #gnutls_certificate_credentials_t structure.
1812 * @crl_list: is a list of trusted CRLs. They should have been verified before.
1813 * @crl_list_size: holds the size of the crl_list
1815 * This function adds the trusted CRLs in order to verify client or
1816 * server certificates. In case of a client this is not required to
1817 * be called if the certificates are not verified using
1818 * gnutls_certificate_verify_peers2(). This function may be called
1821 * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
1826 gnutls_certificate_set_x509_crl (gnutls_certificate_credentials_t res
,
1827 gnutls_x509_crl_t
* crl_list
,
1831 gnutls_x509_crl_t new_crl
[crl_list_size
];
1833 for (i
= 0; i
< crl_list_size
; i
++)
1835 ret
= gnutls_x509_crl_init (&new_crl
[i
]);
1842 ret
= _gnutls_x509_crl_cpy (new_crl
[i
], crl_list
[i
]);
1850 ret
= gnutls_x509_trust_list_add_crls(res
->tlist
, new_crl
, crl_list_size
, 0, 0);
1861 gnutls_x509_crl_deinit(new_crl
[j
]);
1867 * gnutls_certificate_set_x509_crl_file:
1868 * @res: is a #gnutls_certificate_credentials_t structure.
1869 * @crlfile: is a file containing the list of verified CRLs (DER or PEM list)
1870 * @type: is PEM or DER
1872 * This function adds the trusted CRLs in order to verify client or server
1873 * certificates. In case of a client this is not required
1874 * to be called if the certificates are not verified using
1875 * gnutls_certificate_verify_peers2().
1876 * This function may be called multiple times.
1878 * Returns: number of CRLs processed or a negative error code on error.
1881 gnutls_certificate_set_x509_crl_file (gnutls_certificate_credentials_t res
,
1882 const char *crlfile
,
1883 gnutls_x509_crt_fmt_t type
)
1887 char *data
= (void*)read_binary_file (crlfile
, &size
);
1892 return GNUTLS_E_FILE_ERROR
;
1895 if (type
== GNUTLS_X509_FMT_DER
)
1896 ret
= parse_der_crl_mem (res
->tlist
, data
, size
);
1898 ret
= parse_pem_crl_mem (res
->tlist
, data
, size
);
1911 #include <gnutls/pkcs12.h>
1915 * gnutls_certificate_set_x509_simple_pkcs12_file:
1916 * @res: is a #gnutls_certificate_credentials_t structure.
1917 * @pkcs12file: filename of file containing PKCS#12 blob.
1918 * @type: is PEM or DER of the @pkcs12file.
1919 * @password: optional password used to decrypt PKCS#12 file, bags and keys.
1921 * This function sets a certificate/private key pair and/or a CRL in
1922 * the gnutls_certificate_credentials_t structure. This function may
1923 * be called more than once (in case multiple keys/certificates exist
1926 * PKCS#12 files with a MAC, encrypted bags and PKCS #8
1927 * private keys are supported. However,
1928 * only password based security, and the same password for all
1929 * operations, are supported.
1931 * PKCS#12 file may contain many keys and/or certificates, and there
1932 * is no way to identify which key/certificate pair you want. You
1933 * should make sure the PKCS#12 file only contain one key/certificate
1934 * pair and/or one CRL.
1936 * It is believed that the limitations of this function is acceptable
1937 * for most usage, and that any more flexibility would introduce
1938 * complexity that would make it harder to use this functionality at
1941 * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
1944 gnutls_certificate_set_x509_simple_pkcs12_file
1945 (gnutls_certificate_credentials_t res
, const char *pkcs12file
,
1946 gnutls_x509_crt_fmt_t type
, const char *password
)
1948 gnutls_datum_t p12blob
;
1952 p12blob
.data
= (void*)read_binary_file (pkcs12file
, &size
);
1953 p12blob
.size
= (unsigned int) size
;
1954 if (p12blob
.data
== NULL
)
1957 return GNUTLS_E_FILE_ERROR
;
1961 gnutls_certificate_set_x509_simple_pkcs12_mem (res
, &p12blob
, type
,
1963 free (p12blob
.data
);
1969 * gnutls_certificate_set_x509_simple_pkcs12_mem:
1970 * @res: is a #gnutls_certificate_credentials_t structure.
1971 * @p12blob: the PKCS#12 blob.
1972 * @type: is PEM or DER of the @pkcs12file.
1973 * @password: optional password used to decrypt PKCS#12 file, bags and keys.
1975 * This function sets a certificate/private key pair and/or a CRL in
1976 * the gnutls_certificate_credentials_t structure. This function may
1977 * be called more than once (in case multiple keys/certificates exist
1980 * Encrypted PKCS#12 bags and PKCS#8 private keys are supported. However,
1981 * only password based security, and the same password for all
1982 * operations, are supported.
1984 * PKCS#12 file may contain many keys and/or certificates, and there
1985 * is no way to identify which key/certificate pair you want. You
1986 * should make sure the PKCS#12 file only contain one key/certificate
1987 * pair and/or one CRL.
1989 * It is believed that the limitations of this function is acceptable
1990 * for most usage, and that any more flexibility would introduce
1991 * complexity that would make it harder to use this functionality at
1994 * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
1999 gnutls_certificate_set_x509_simple_pkcs12_mem
2000 (gnutls_certificate_credentials_t res
, const gnutls_datum_t
* p12blob
,
2001 gnutls_x509_crt_fmt_t type
, const char *password
)
2003 gnutls_pkcs12_t p12
;
2004 gnutls_x509_privkey_t key
= NULL
;
2005 gnutls_x509_crt_t
*chain
= NULL
;
2006 gnutls_x509_crl_t crl
= NULL
;
2007 unsigned int chain_size
= 0, i
;
2010 ret
= gnutls_pkcs12_init (&p12
);
2017 ret
= gnutls_pkcs12_import (p12
, p12blob
, type
, 0);
2021 gnutls_pkcs12_deinit (p12
);
2027 ret
= gnutls_pkcs12_verify_mac (p12
, password
);
2031 gnutls_pkcs12_deinit (p12
);
2036 ret
= gnutls_pkcs12_simple_parse (p12
, password
, &key
, &chain
, &chain_size
,
2037 NULL
, NULL
, &crl
, 0);
2038 gnutls_pkcs12_deinit (p12
);
2047 ret
= gnutls_certificate_set_x509_key (res
, chain
, chain_size
, key
);
2057 ret
= GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
;
2063 ret
= gnutls_certificate_set_x509_crl (res
, &crl
, 1);
2076 for (i
=0;i
<chain_size
;i
++)
2077 gnutls_x509_crt_deinit (chain
[i
]);
2081 gnutls_x509_privkey_deinit (key
);
2083 gnutls_x509_crl_deinit (crl
);
2091 * gnutls_certificate_free_crls:
2092 * @sc: is a #gnutls_certificate_credentials_t structure.
2094 * This function will delete all the CRLs associated
2095 * with the given credentials.
2098 gnutls_certificate_free_crls (gnutls_certificate_credentials_t sc
)
2100 /* do nothing for now */
2105 * gnutls_certificate_credentials_t:
2106 * @cred: is a #gnutls_certificate_credentials_t structure.
2107 * @fn: A PIN callback
2108 * @userdata: Data to be passed in the callback
2110 * This function will set a callback function to be used when
2111 * required to access a protected object. This function overrides any other
2112 * global PIN functions.
2114 * Note that this function must be called right after initialization
2119 void gnutls_certificate_set_pin_function (gnutls_certificate_credentials_t cred
,
2120 gnutls_pin_callback_t fn
, void *userdata
)
2123 cred
->pin
.data
= userdata
;