abstract

## abstract abstract |

## Synopsis

    #define             GNUTLS_PCERT_NO_CERT
    #define             GNUTLS_PUBKEY_VERIFY_FLAG_TLS_RSA
    int                 gnutls_certificate_set_key          (gnutls_certificate_credentials_t res,
                                                             const char **names,
                                                             int names_size,
                                                             gnutls_pcert_st *pcert_list,
                                                             int pcert_list_size,
                                                             gnutls_privkey_t key);
    void                gnutls_certificate_set_retrieve_function2
                                                            (gnutls_certificate_credentials_t cred,
                                                             gnutls_certificate_retrieve_function2 *func);
    void                gnutls_pcert_deinit                 (gnutls_pcert_st *pcert);
    int                 gnutls_pcert_import_openpgp         (gnutls_pcert_st *pcert,
                                                             gnutls_openpgp_crt_t crt,
                                                             unsigned int flags);
    int                 gnutls_pcert_import_openpgp_raw     (gnutls_pcert_st *pcert,
                                                             const gnutls_datum_t *cert,
                                                             gnutls_openpgp_crt_fmt_t format,
                                                             gnutls_openpgp_keyid_t keyid,
                                                             unsigned int flags);
    int                 gnutls_pcert_import_x509            (gnutls_pcert_st *pcert,
                                                             gnutls_x509_crt_t crt,
                                                             unsigned int flags);
    int                 gnutls_pcert_import_x509_raw        (gnutls_pcert_st *pcert,
                                                             const gnutls_datum_t *cert,
                                                             gnutls_x509_crt_fmt_t format,
                                                             unsigned int flags);
    int                 gnutls_pcert_list_import_x509_raw   (gnutls_pcert_st *pcerts,
                                                             unsigned int *pcert_max,
                                                             const gnutls_datum_t *data,
                                                             gnutls_x509_crt_fmt_t format,
                                                             unsigned int flags);
    int                 gnutls_privkey_decrypt_data         (gnutls_privkey_t key,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *ciphertext,
                                                             gnutls_datum_t *plaintext);
    int                 (*gnutls_privkey_decrypt_func)      (gnutls_privkey_t key,
                                                             void *userdata,
                                                             const gnutls_datum_t *ciphertext,
                                                             gnutls_datum_t *plaintext);
    void                gnutls_privkey_deinit               (gnutls_privkey_t key);
    void                (*gnutls_privkey_deinit_func)       (gnutls_privkey_t key,
                                                             void *userdata);
    enum                gnutls_privkey_flags_t;
    int                 gnutls_privkey_get_pk_algorithm     (gnutls_privkey_t key,
                                                             unsigned int *bits);
    int                 gnutls_privkey_import_ext           (gnutls_privkey_t pkey,
                                                             gnutls_pk_algorithm_t pk,
                                                             void *userdata,
                                                             gnutls_privkey_sign_func sign_func,
                                                             gnutls_privkey_decrypt_func decrypt_func,
                                                             unsigned int flags);
    int                 gnutls_privkey_import_ext2          (gnutls_privkey_t pkey,
                                                             gnutls_pk_algorithm_t pk,
                                                             void *userdata,
                                                             gnutls_privkey_sign_func sign_func,
                                                             gnutls_privkey_decrypt_func decrypt_func,
                                                             gnutls_privkey_deinit_func deinit_func,
                                                             unsigned int flags);
    int                 gnutls_privkey_import_openpgp       (gnutls_privkey_t pkey,
                                                             gnutls_openpgp_privkey_t key,
                                                             unsigned int flags);
    int                 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);
    int                 gnutls_privkey_import_pkcs11        (gnutls_privkey_t pkey,
                                                             gnutls_pkcs11_privkey_t key,
                                                             unsigned int flags);
    int                 gnutls_privkey_import_pkcs11_url    (gnutls_privkey_t key,
                                                             const char *url);
    int                 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);
    int                 gnutls_privkey_import_tpm_url       (gnutls_privkey_t pkey,
                                                             const char *url,
                                                             const char *srk_password,
                                                             const char *key_password,
                                                             unsigned int flags);
    int                 gnutls_privkey_import_url           (gnutls_privkey_t key,
                                                             const char *url,
                                                             unsigned int flags);
    int                 gnutls_privkey_import_x509          (gnutls_privkey_t pkey,
                                                             gnutls_x509_privkey_t key,
                                                             unsigned int flags);
    int                 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);
    int                 gnutls_privkey_init                 (gnutls_privkey_t *key);
    void                gnutls_privkey_set_pin_function     (gnutls_privkey_t key,
                                                             gnutls_pin_callback_t fn,
                                                             void *userdata);
    int                 gnutls_privkey_sign_data            (gnutls_privkey_t signer,
                                                             gnutls_digest_algorithm_t hash,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *data,
                                                             gnutls_datum_t *signature);
    int                 (*gnutls_privkey_sign_func)         (gnutls_privkey_t key,
                                                             void *userdata,
                                                             const gnutls_datum_t *raw_data,
                                                             gnutls_datum_t *signature);
    int                 gnutls_privkey_sign_hash            (gnutls_privkey_t signer,
                                                             gnutls_digest_algorithm_t hash_algo,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *hash_data,
                                                             gnutls_datum_t *signature);
    int                 gnutls_privkey_status               (gnutls_privkey_t key);
    void                gnutls_pubkey_deinit                (gnutls_pubkey_t key);
    int                 gnutls_pubkey_encrypt_data          (gnutls_pubkey_t key,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *plaintext,
                                                             gnutls_datum_t *ciphertext);
    int                 gnutls_pubkey_export                (gnutls_pubkey_t key,
                                                             gnutls_x509_crt_fmt_t format,
                                                             void *output_data,
                                                             size_t *output_data_size);
    int                 gnutls_pubkey_export2               (gnutls_pubkey_t key,
                                                             gnutls_x509_crt_fmt_t format,
                                                             gnutls_datum_t *out);
    enum                gnutls_pubkey_flags_t;
    int                 gnutls_pubkey_get_key_id            (gnutls_pubkey_t key,
                                                             unsigned int flags,
                                                             unsigned char *output_data,
                                                             size_t *output_data_size);
    int                 gnutls_pubkey_get_key_usage         (gnutls_pubkey_t key,
                                                             unsigned int *usage);
    int                 gnutls_pubkey_get_openpgp_key_id    (gnutls_pubkey_t key,
                                                             unsigned int flags,
                                                             unsigned char *output_data,
                                                             size_t *output_data_size,
                                                             unsigned int *subkey);
    int                 gnutls_pubkey_get_pk_algorithm      (gnutls_pubkey_t key,
                                                             unsigned int *bits);
    int                 gnutls_pubkey_get_pk_dsa_raw        (gnutls_pubkey_t key,
                                                             gnutls_datum_t *p,
                                                             gnutls_datum_t *q,
                                                             gnutls_datum_t *g,
                                                             gnutls_datum_t *y);
    int                 gnutls_pubkey_get_pk_ecc_raw        (gnutls_pubkey_t key,
                                                             gnutls_ecc_curve_t *curve,
                                                             gnutls_datum_t *x,
                                                             gnutls_datum_t *y);
    int                 gnutls_pubkey_get_pk_ecc_x962       (gnutls_pubkey_t key,
                                                             gnutls_datum_t *parameters,
                                                             gnutls_datum_t *ecpoint);
    int                 gnutls_pubkey_get_pk_rsa_raw        (gnutls_pubkey_t key,
                                                             gnutls_datum_t *m,
                                                             gnutls_datum_t *e);
    int                 gnutls_pubkey_get_preferred_hash_algorithm
                                                            (gnutls_pubkey_t key,
                                                             gnutls_digest_algorithm_t *hash,
                                                             unsigned int *mand);
    int                 gnutls_pubkey_get_verify_algorithm  (gnutls_pubkey_t key,
                                                             const gnutls_datum_t *signature,
                                                             gnutls_digest_algorithm_t *hash);
    int                 gnutls_pubkey_import                (gnutls_pubkey_t key,
                                                             const gnutls_datum_t *data,
                                                             gnutls_x509_crt_fmt_t format);
    int                 gnutls_pubkey_import_dsa_raw        (gnutls_pubkey_t key,
                                                             const gnutls_datum_t *p,
                                                             const gnutls_datum_t *q,
                                                             const gnutls_datum_t *g,
                                                             const gnutls_datum_t *y);
    int                 gnutls_pubkey_import_ecc_raw        (gnutls_pubkey_t key,
                                                             gnutls_ecc_curve_t curve,
                                                             const gnutls_datum_t *x,
                                                             const gnutls_datum_t *y);
    int                 gnutls_pubkey_import_ecc_x962       (gnutls_pubkey_t key,
                                                             const gnutls_datum_t *parameters,
                                                             const gnutls_datum_t *ecpoint);
    int                 gnutls_pubkey_import_openpgp        (gnutls_pubkey_t key,
                                                             gnutls_openpgp_crt_t crt,
                                                             unsigned int flags);
    int                 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);
    int                 gnutls_pubkey_import_pkcs11         (gnutls_pubkey_t key,
                                                             gnutls_pkcs11_obj_t obj,
                                                             unsigned int flags);
    int                 gnutls_pubkey_import_pkcs11_url     (gnutls_pubkey_t key,
                                                             const char *url,
                                                             unsigned int flags);
    int                 gnutls_pubkey_import_privkey        (gnutls_pubkey_t key,
                                                             gnutls_privkey_t pkey,
                                                             unsigned int usage,
                                                             unsigned int flags);
    int                 gnutls_pubkey_import_rsa_raw        (gnutls_pubkey_t key,
                                                             const gnutls_datum_t *m,
                                                             const gnutls_datum_t *e);
    int                 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);
    int                 gnutls_pubkey_import_tpm_url        (gnutls_pubkey_t pkey,
                                                             const char *url,
                                                             const char *srk_password,
                                                             unsigned int flags);
    int                 gnutls_pubkey_import_url            (gnutls_pubkey_t key,
                                                             const char *url,
                                                             unsigned int flags);
    int                 gnutls_pubkey_import_x509           (gnutls_pubkey_t key,
                                                             gnutls_x509_crt_t crt,
                                                             unsigned int flags);
    int                 gnutls_pubkey_import_x509_crq       (gnutls_pubkey_t key,
                                                             gnutls_x509_crq_t crq,
                                                             unsigned int flags);
    int                 gnutls_pubkey_import_x509_raw       (gnutls_pubkey_t pkey,
                                                             const gnutls_datum_t *data,
                                                             gnutls_x509_crt_fmt_t format,
                                                             unsigned int flags);
    int                 gnutls_pubkey_init                  (gnutls_pubkey_t *key);
    int                 gnutls_pubkey_set_key_usage         (gnutls_pubkey_t key,
                                                             unsigned int usage);
    void                gnutls_pubkey_set_pin_function      (gnutls_pubkey_t key,
                                                             gnutls_pin_callback_t fn,
                                                             void *userdata);
    int                 gnutls_pubkey_verify_data           (gnutls_pubkey_t pubkey,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *data,
                                                             const gnutls_datum_t *signature);
    int                 gnutls_pubkey_verify_data2          (gnutls_pubkey_t pubkey,
                                                             gnutls_sign_algorithm_t algo,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *data,
                                                             const gnutls_datum_t *signature);
    int                 gnutls_pubkey_verify_hash2          (gnutls_pubkey_t key,
                                                             gnutls_sign_algorithm_t algo,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *hash,
                                                             const gnutls_datum_t *signature);
    int                 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);
    int                 gnutls_x509_crq_privkey_sign        (gnutls_x509_crq_t crq,
                                                             gnutls_privkey_t key,
                                                             gnutls_digest_algorithm_t dig,
                                                             unsigned int flags);
    int                 gnutls_x509_crq_set_pubkey          (gnutls_x509_crq_t crq,
                                                             gnutls_pubkey_t key);
    int                 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);
    int                 gnutls_x509_crt_set_pubkey          (gnutls_x509_crt_t crt,
                                                             gnutls_pubkey_t key);

## Description

## Details

### GNUTLS_PCERT_NO_CERT

    #define GNUTLS_PCERT_NO_CERT 1

### GNUTLS_PUBKEY_VERIFY_FLAG_TLS_RSA

    #define GNUTLS_PUBKEY_VERIFY_FLAG_TLS_RSA GNUTLS_PUBKEY_VERIFY_FLAG_TLS1_RSA

### gnutls_certificate_set_key ()

    int                 gnutls_certificate_set_key          (gnutls_certificate_credentials_t res,
                                                             const char **names,
                                                             int names_size,
                                                             gnutls_pcert_st *pcert_list,
                                                             int pcert_list_size,
                                                             gnutls_privkey_t key);

This function sets a certificate/private key pair in the gnutls_certificate_credentials_t structure. This function may be called more than once, in case multiple keys/certificates exist for the server. For clients that wants to send more than its own end entity certificate (e.g., also an intermediate CA cert) then put the certificate chain in `pcert_list`.

Note that the `pcert_list` and `key` will become part of the credentials structure and must not be deallocated. They will be automatically deallocated when the `res` structure is deinitialized.

`res` : | is a gnutls_certificate_credentials_t structure.
`names` : | is an array of DNS name of the certificate (NULL if none)
`names_size` : | holds the size of the names list
`pcert_list` : | contains a certificate list (path) for the specified private key
`pcert_list_size` : | holds the size of the certificate list
`key` : | is a gnutls_privkey_t key
Returns : | `GNUTLS_E_SUCCESS` (0) on success, or a negative error code.

Since 3.0

### gnutls_certificate_set_retrieve_function2 ()

    void                gnutls_certificate_set_retrieve_function2
                                                            (gnutls_certificate_credentials_t cred,
                                                             gnutls_certificate_retrieve_function2 *func);

This function sets a callback to be called in order to retrieve the certificate to be used in the handshake.

The callback's function prototype is: int (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int nreqs, const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length, gnutls_pcert_st** pcert, unsigned int *pcert_length, gnutls_privkey_t * pkey);

`req_ca_cert` is only used in X.509 certificates. Contains a list with the CA names that the server considers trusted. Normally we should send a certificate that is signed by one of these CAs. These names are DER encoded. To get a more meaningful value use the function `gnutls_x509_rdn_get()`.

`pk_algos` contains a list with server's acceptable signature algorithms. The certificate returned should support the server's given algorithms.

`pcert` should contain a single certificate and public or a list of them.

`pcert_length` is the size of the previous list.

`pkey` is the private key.

If the callback function is provided then gnutls will call it, in the handshake, after the certificate request message has been received.

In server side pk_algos and req_ca_dn are NULL.

The callback function should set the certificate list to be sent, and return 0 on success. If no certificate was selected then the number of certificates should be set to zero. The value (-1) indicates error and the handshake will be terminated.

`cred` : | is a gnutls_certificate_credentials_t structure.
`func` : | is the callback function

Since 3.0

### gnutls_pcert_deinit ()

    void                gnutls_pcert_deinit                 (gnutls_pcert_st *pcert);

This function will deinitialize a pcert structure.

`pcert` : | The structure to be deinitialized

Since 3.0

### gnutls_pcert_import_openpgp ()

    int                 gnutls_pcert_import_openpgp         (gnutls_pcert_st *pcert,
                                                             gnutls_openpgp_crt_t crt,
                                                             unsigned int flags);

This convenience function will import the given certificate to a gnutls_pcert_st structure. The structure must be deinitialized afterwards using `gnutls_pcert_deinit()`;

`pcert` : | The pcert structure
`crt` : | The raw certificate to be imported
`flags` : | zero for now
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.0

### gnutls_pcert_import_openpgp_raw ()

    int                 gnutls_pcert_import_openpgp_raw     (gnutls_pcert_st *pcert,
                                                             const gnutls_datum_t *cert,
                                                             gnutls_openpgp_crt_fmt_t format,
                                                             gnutls_openpgp_keyid_t keyid,
                                                             unsigned int flags);

This convenience function will import the given certificate to a gnutls_pcert_st structure. The structure must be deinitialized afterwards using `gnutls_pcert_deinit()`;

`pcert` : | The pcert structure
`cert` : | The raw certificate to be imported
`format` : | The format of the certificate
`keyid` : | The key ID to use (NULL for the master key)
`flags` : | zero for now
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.0

### gnutls_pcert_import_x509 ()

    int                 gnutls_pcert_import_x509            (gnutls_pcert_st *pcert,
                                                             gnutls_x509_crt_t crt,
                                                             unsigned int flags);

This convenience function will import the given certificate to a gnutls_pcert_st structure. The structure must be deinitialized afterwards using `gnutls_pcert_deinit()`;

`pcert` : | The pcert structure
`crt` : | The raw certificate to be imported
`flags` : | zero for now
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.0

### gnutls_pcert_import_x509_raw ()

    int                 gnutls_pcert_import_x509_raw        (gnutls_pcert_st *pcert,
                                                             const gnutls_datum_t *cert,
                                                             gnutls_x509_crt_fmt_t format,
                                                             unsigned int flags);

This convenience function will import the given certificate to a gnutls_pcert_st structure. The structure must be deinitialized afterwards using `gnutls_pcert_deinit()`;

`pcert` : | The pcert structure
`cert` : | The raw certificate to be imported
`format` : | The format of the certificate
`flags` : | zero for now
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.0

### gnutls_pcert_list_import_x509_raw ()

    int                 gnutls_pcert_list_import_x509_raw   (gnutls_pcert_st *pcerts,
                                                             unsigned int *pcert_max,
                                                             const gnutls_datum_t *data,
                                                             gnutls_x509_crt_fmt_t format,
                                                             unsigned int flags);

This function will convert the given PEM encoded certificate list to the native gnutls_x509_crt_t format. The output will be stored in `certs`. They will be automatically initialized.

If the Certificate is PEM encoded it should have a header of "X509 CERTIFICATE", or "CERTIFICATE".

`pcerts` : | The structures to store the parsed certificate. Must not be initialized.
`pcert_max` : | Initially must hold the maximum number of certs. It will be updated with the number of certs available.
`data` : | The certificates.
`format` : | One of DER or PEM.
`flags` : | must be (0) or an OR'd sequence of gnutls_certificate_import_flags.
Returns : | the number of certificates read or a negative error value.

Since 3.0

### gnutls_privkey_decrypt_data ()

    int                 gnutls_privkey_decrypt_data         (gnutls_privkey_t key,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *ciphertext,
                                                             gnutls_datum_t *plaintext);

This function will decrypt the given data using the algorithm supported by the private key.

`key` : | Holds the key
`flags` : | zero for now
`ciphertext` : | holds the data to be decrypted
`plaintext` : | will contain the decrypted data, allocated with `gnutls_malloc()`
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_privkey_decrypt_func ()

    int                 (*gnutls_privkey_decrypt_func)      (gnutls_privkey_t key,
                                                             void *userdata,
                                                             const gnutls_datum_t *ciphertext,
                                                             gnutls_datum_t *plaintext);

### gnutls_privkey_deinit ()

    void                gnutls_privkey_deinit               (gnutls_privkey_t key);

This function will deinitialize a private key structure.

`key` : | The structure to be deinitialized

Since 2.12.0

### gnutls_privkey_deinit_func ()

    void                (*gnutls_privkey_deinit_func)       (gnutls_privkey_t key,
                                                             void *userdata);

### enum gnutls_privkey_flags_t

    typedef enum {
    	GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE = 1,
    	GNUTLS_PRIVKEY_IMPORT_COPY = 1 << 1,
    	GNUTLS_PRIVKEY_DISABLE_CALLBACKS = 1 << 2,
    	GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA = 1 << 4,
    } gnutls_privkey_flags_t;

`GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE` |
`GNUTLS_PRIVKEY_IMPORT_COPY` |
`GNUTLS_PRIVKEY_DISABLE_CALLBACKS` |
`GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA` |

### gnutls_privkey_get_pk_algorithm ()

    int                 gnutls_privkey_get_pk_algorithm     (gnutls_privkey_t key,
                                                             unsigned int *bits);

This function will return the public key algorithm of a private key and if possible will return a number of bits that indicates the security parameter of the key.

`key` : | should contain a gnutls_privkey_t structure
`bits` : | If set will return the number of bits of the parameters (may be NULL)
Returns : | a member of the gnutls_pk_algorithm_t enumeration on success, or a negative error code on error.

Since 2.12.0

### gnutls_privkey_import_ext ()

    int                 gnutls_privkey_import_ext           (gnutls_privkey_t pkey,
                                                             gnutls_pk_algorithm_t pk,
                                                             void *userdata,
                                                             gnutls_privkey_sign_func sign_func,
                                                             gnutls_privkey_decrypt_func decrypt_func,
                                                             unsigned int flags);

This function will associate the given callbacks with the gnutls_privkey_t structure. At least one of the two callbacks must be non-null.

See also `gnutls_privkey_import_ext2()`.

`pkey` : | The private key
`pk` : | The public key algorithm
`userdata` : | private data to be provided to the callbacks
`sign_func` : | callback for signature operations
`decrypt_func` : | callback for decryption operations
`flags` : | Flags for the import
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.0

### gnutls_privkey_import_ext2 ()

    int                 gnutls_privkey_import_ext2          (gnutls_privkey_t pkey,
                                                             gnutls_pk_algorithm_t pk,
                                                             void *userdata,
                                                             gnutls_privkey_sign_func sign_func,
                                                             gnutls_privkey_decrypt_func decrypt_func,
                                                             gnutls_privkey_deinit_func deinit_func,
                                                             unsigned int flags);

This function will associate the given callbacks with the gnutls_privkey_t structure. At least one of the two callbacks must be non-null. If a deinitialization function is provided then flags is assumed to contain `GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE`.

Note that the signing function is supposed to "raw" sign data, i.e., without any hashing or preprocessing. In case of RSA the DigestInfo will be provided, and the signing function is expected to do the PKCS #1 1.5 padding and the exponentiation.

`pkey` : | The private key
`pk` : | The public key algorithm
`userdata` : | private data to be provided to the callbacks
`sign_func` : | callback for signature operations
`decrypt_func` : | callback for decryption operations
`deinit_func` : | a deinitialization function
`flags` : | Flags for the import
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.1

### gnutls_privkey_import_openpgp ()

    int                 gnutls_privkey_import_openpgp       (gnutls_privkey_t pkey,
                                                             gnutls_openpgp_privkey_t key,
                                                             unsigned int flags);

This function will import the given private key to the abstract gnutls_privkey_t structure.

The gnutls_openpgp_privkey_t object must not be deallocated during the lifetime of this structure. The subkey set as preferred will be used, or the master key otherwise.

`flags` might be zero or one of `GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE` and `GNUTLS_PRIVKEY_IMPORT_COPY`.

`pkey` : | The private key
`key` : | The private key to be imported
`flags` : | Flags for the import
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_privkey_import_openpgp_raw ()

    int                 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);

This function will import the given private key to the abstract gnutls_privkey_t structure.

`pkey` : | The private key
`data` : | The private key data to be imported
`format` : | The format of the private key
`keyid` : | The key id to use (optional)
`password` : | A password (optional)
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.1.0

### gnutls_privkey_import_pkcs11 ()

    int                 gnutls_privkey_import_pkcs11        (gnutls_privkey_t pkey,
                                                             gnutls_pkcs11_privkey_t key,
                                                             unsigned int flags);

This function will import the given private key to the abstract gnutls_privkey_t structure.

The gnutls_pkcs11_privkey_t object must not be deallocated during the lifetime of this structure.

`flags` might be zero or one of `GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE` and `GNUTLS_PRIVKEY_IMPORT_COPY`.

`pkey` : | The private key
`key` : | The private key to be imported
`flags` : | Flags for the import
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_privkey_import_pkcs11_url ()

    int                 gnutls_privkey_import_pkcs11_url    (gnutls_privkey_t key,
                                                             const char *url);

This function will import a PKCS 11 private key to a gnutls_private_key_t structure.

`key` : | A key of type gnutls_pubkey_t
`url` : | A PKCS 11 url
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.1.0

### gnutls_privkey_import_tpm_raw ()

    int                 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);

This function will import the given private key to the abstract gnutls_privkey_t structure.

With respect to passwords the same as in `gnutls_privkey_import_tpm_url()` apply.

`pkey` : | The private key
`fdata` : | The TPM key to be imported
`format` : | The format of the private key
`srk_password` : | The password for the SRK key (optional)
`key_password` : | A password for the key (optional)
`flags` : | should be zero
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.1.0

### gnutls_privkey_import_tpm_url ()

    int                 gnutls_privkey_import_tpm_url       (gnutls_privkey_t pkey,
                                                             const char *url,
                                                             const char *srk_password,
                                                             const char *key_password,
                                                             unsigned int flags);

This function will import the given private key to the abstract gnutls_privkey_t structure.

Note that unless `GNUTLS_PRIVKEY_DISABLE_CALLBACKS` is specified, if incorrect (or NULL) passwords are given the PKCS11 callback functions will be used to obtain the correct passwords. Otherwise if the SRK password is wrong `GNUTLS_E_TPM_SRK_PASSWORD_ERROR` is returned and if the key password is wrong or not provided then `GNUTLS_E_TPM_KEY_PASSWORD_ERROR` is returned.

`pkey` : | The private key
`url` : | The URL of the TPM key to be imported
`srk_password` : | The password for the SRK key (optional)
`key_password` : | A password for the key (optional)
`flags` : | One of the GNUTLS_PRIVKEY_* flags
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.1.0

### gnutls_privkey_import_url ()

    int                 gnutls_privkey_import_url           (gnutls_privkey_t key,
                                                             const char *url,
                                                             unsigned int flags);

This function will import a PKCS11 or TPM URL as a private key. The supported URL types can be checked using `gnutls_url_is_supported()`.

`key` : | A key of type gnutls_privkey_t
`url` : | A PKCS 11 url
`flags` : | should be zero
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.1.0

### gnutls_privkey_import_x509 ()

    int                 gnutls_privkey_import_x509          (gnutls_privkey_t pkey,
                                                             gnutls_x509_privkey_t key,
                                                             unsigned int flags);

This function will import the given private key to the abstract gnutls_privkey_t structure.

The gnutls_x509_privkey_t object must not be deallocated during the lifetime of this structure.

`flags` might be zero or one of `GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE` and `GNUTLS_PRIVKEY_IMPORT_COPY`.

`pkey` : | The private key
`key` : | The private key to be imported
`flags` : | Flags for the import
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_privkey_import_x509_raw ()

    int                 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);

This function will import the given private key to the abstract gnutls_privkey_t structure.

The supported formats are basic unencrypted key, PKCS8, PKCS12, and the openssl format.

`pkey` : | The private key
`data` : | The private key data to be imported
`format` : | The format of the private key
`password` : | A password (optional)
`flags` : | an ORed sequence of gnutls_pkcs_encrypt_flags_t
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.1.0

### gnutls_privkey_init ()

    int                 gnutls_privkey_init                 (gnutls_privkey_t *key);

This function will initialize an private key structure.

`key` : | The structure to be initialized
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_privkey_set_pin_function ()

    void                gnutls_privkey_set_pin_function     (gnutls_privkey_t key,
                                                             gnutls_pin_callback_t fn,
                                                             void *userdata);

This function will set a callback function to be used when required to access the object. This function overrides any other global PIN functions.

Note that this function must be called right after initialization to have effect.

`key` : | A key of type gnutls_privkey_t
`fn` : | the callback
`userdata` : | data associated with the callback

Since 3.1.0

### gnutls_privkey_sign_data ()

    int                 gnutls_privkey_sign_data            (gnutls_privkey_t signer,
                                                             gnutls_digest_algorithm_t hash,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *data,
                                                             gnutls_datum_t *signature);

This function will sign the given data using a signature algorithm supported by the private key. Signature algorithms are always used together with a hash functions. Different hash functions may be used for the RSA algorithm, but only the SHA family for the DSA keys.

You may use `gnutls_pubkey_get_preferred_hash_algorithm()` to determine the hash algorithm.

`signer` : | Holds the key
`hash` : | should be a digest algorithm
`flags` : | Zero or one of `gnutls_privkey_flags_t`
`data` : | holds the data to be signed
`signature` : | will contain the signature allocate with `gnutls_malloc()`
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_privkey_sign_func ()

    int                 (*gnutls_privkey_sign_func)         (gnutls_privkey_t key,
                                                             void *userdata,
                                                             const gnutls_datum_t *raw_data,
                                                             gnutls_datum_t *signature);

### gnutls_privkey_sign_hash ()

    int                 gnutls_privkey_sign_hash            (gnutls_privkey_t signer,
                                                             gnutls_digest_algorithm_t hash_algo,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *hash_data,
                                                             gnutls_datum_t *signature);

This function will sign the given hashed data using a signature algorithm supported by the private key. Signature algorithms are always used together with a hash functions. Different hash functions may be used for the RSA algorithm, but only SHA-XXX for the DSA keys.

You may use `gnutls_pubkey_get_preferred_hash_algorithm()` to determine the hash algorithm.

Note that if `GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA` flag is specified this function will ignore `hash_algo` and perform a raw PKCS1 signature.

`signer` : | Holds the signer's key
`hash_algo` : | The hash algorithm used
`flags` : | Zero or one of `gnutls_privkey_flags_t`
`hash_data` : | holds the data to be signed
`signature` : | will contain newly allocated signature
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_privkey_status ()

    int                 gnutls_privkey_status               (gnutls_privkey_t key);

Checks the status of the private key token. This function is an actual wrapper over `gnutls_pkcs11_privkey_status()`, and if the private key is a PKCS 11 token it will check whether it is inserted or not.

`key` : | Holds the key
Returns : | this function will return non-zero if the token holding the private key is still available (inserted), and zero otherwise.

Since 3.1.10

### gnutls_pubkey_deinit ()

    void                gnutls_pubkey_deinit                (gnutls_pubkey_t key);

This function will deinitialize a public key structure.

`key` : | The structure to be deinitialized

Since 2.12.0

### gnutls_pubkey_encrypt_data ()

    int                 gnutls_pubkey_encrypt_data          (gnutls_pubkey_t key,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *plaintext,
                                                             gnutls_datum_t *ciphertext);

This function will encrypt the given data, using the public key.

`key` : | Holds the public key
`flags` : | should be 0 for now
`plaintext` : | The data to be encrypted
`ciphertext` : | contains the encrypted data
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.0

### gnutls_pubkey_export ()

    int                 gnutls_pubkey_export                (gnutls_pubkey_t key,
                                                             gnutls_x509_crt_fmt_t format,
                                                             void *output_data,
                                                             size_t *output_data_size);

This function will export the public key to DER or PEM format. The contents of the exported data is the SubjectPublicKeyInfo X.509 structure.

If the buffer provided is not long enough to hold the output, then *output_data_size is updated and `GNUTLS_E_SHORT_MEMORY_BUFFER` will be returned.

If the structure is PEM encoded, it will have a header of "BEGIN CERTIFICATE".

`key` : | Holds the certificate
`format` : | the format of output params. One of PEM or DER.
`output_data` : | will contain a certificate PEM or DER encoded
`output_data_size` : | holds the size of output_data (and will be replaced by the actual size of parameters)
Returns : | In case of failure a negative error code will be returned, and 0 on success.

Since 2.12.0

### gnutls_pubkey_export2 ()

    int                 gnutls_pubkey_export2               (gnutls_pubkey_t key,
                                                             gnutls_x509_crt_fmt_t format,
                                                             gnutls_datum_t *out);

This function will export the public key to DER or PEM format. The contents of the exported data is the SubjectPublicKeyInfo X.509 structure.

The output buffer will be allocated using `gnutls_malloc()`.

If the structure is PEM encoded, it will have a header of "BEGIN CERTIFICATE".

`key` : | Holds the certificate
`format` : | the format of output params. One of PEM or DER.
`out` : | will contain a certificate PEM or DER encoded
Returns : | In case of failure a negative error code will be returned, and 0 on success.

Since 3.1.3

### enum gnutls_pubkey_flags_t

    typedef enum {
    	GNUTLS_PUBKEY_VERIFY_FLAG_TLS1_RSA = 1,
    	GNUTLS_PUBKEY_DISABLE_CALLBACKS = 1 << 2,
    	GNUTLS_PUBKEY_GET_OPENPGP_FINGERPRINT = 1 << 3,
    } gnutls_pubkey_flags_t;

`GNUTLS_PUBKEY_VERIFY_FLAG_TLS1_RSA` |
`GNUTLS_PUBKEY_DISABLE_CALLBACKS` |
`GNUTLS_PUBKEY_GET_OPENPGP_FINGERPRINT` |

### gnutls_pubkey_get_key_id ()

    int                 gnutls_pubkey_get_key_id            (gnutls_pubkey_t key,
                                                             unsigned int flags,
                                                             unsigned char *output_data,
                                                             size_t *output_data_size);

This function will return a unique ID that depends on the public key parameters. This ID can be used in checking whether a certificate corresponds to the given public key.

If the buffer provided is not long enough to hold the output, then *output_data_size is updated and `GNUTLS_E_SHORT_MEMORY_BUFFER` will be returned. The output will normally be a SHA-1 hash output, which is 20 bytes.

`key` : | Holds the public key
`flags` : | should be 0 for now
`output_data` : | will contain the key ID
`output_data_size` : | holds the size of output_data (and will be replaced by the actual size of parameters)
Returns : | In case of failure a negative error code will be returned, and 0 on success.

Since 2.12.0

### gnutls_pubkey_get_key_usage ()

    int                 gnutls_pubkey_get_key_usage         (gnutls_pubkey_t key,
                                                             unsigned int *usage);

This function will return the key usage of the public key.

`key` : | should contain a gnutls_pubkey_t structure
`usage` : | If set will return the number of bits of the parameters (may be NULL)
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_pubkey_get_openpgp_key_id ()

    int                 gnutls_pubkey_get_openpgp_key_id    (gnutls_pubkey_t key,
                                                             unsigned int flags,
                                                             unsigned char *output_data,
                                                             size_t *output_data_size,
                                                             unsigned int *subkey);

This function returns the OpenPGP key ID of the corresponding key. The key is a unique ID that depends on the public key parameters.

If the flag `GNUTLS_PUBKEY_GET_OPENPGP_FINGERPRINT` is specified this function returns the fingerprint of the master key.

If the buffer provided is not long enough to hold the output, then *output_data_size is updated and `GNUTLS_E_SHORT_MEMORY_BUFFER` will be returned. The output is `GNUTLS_OPENPGP_KEYID_SIZE` bytes long.

`key` : | Holds the public key
`flags` : | should be 0 or `GNUTLS_PUBKEY_GET_OPENPGP_FINGERPRINT`
`output_data` : | will contain the key ID
`output_data_size` : | holds the size of output_data (and will be replaced by the actual size of parameters)
`subkey` : | Will be non zero if the key ID corresponds to a subkey
Returns : | In case of failure a negative error code will be returned, and 0 on success.

Since 3.0

### gnutls_pubkey_get_pk_algorithm ()

    int                 gnutls_pubkey_get_pk_algorithm      (gnutls_pubkey_t key,
                                                             unsigned int *bits);

This function will return the public key algorithm of a public key and if possible will return a number of bits that indicates the security parameter of the key.

`key` : | should contain a gnutls_pubkey_t structure
`bits` : | If set will return the number of bits of the parameters (may be NULL)
Returns : | a member of the gnutls_pk_algorithm_t enumeration on success, or a negative error code on error.

Since 2.12.0

### gnutls_pubkey_get_pk_dsa_raw ()

    int                 gnutls_pubkey_get_pk_dsa_raw        (gnutls_pubkey_t key,
                                                             gnutls_datum_t *p,
                                                             gnutls_datum_t *q,
                                                             gnutls_datum_t *g,
                                                             gnutls_datum_t *y);

This function will export the DSA public key's parameters found in the given certificate. The new parameters will be allocated using `gnutls_malloc()` and will be stored in the appropriate datum.

`key` : | Holds the public key
`p` : | will hold the p
`q` : | will hold the q
`g` : | will hold the g
`y` : | will hold the y
Returns : | `GNUTLS_E_SUCCESS` on success, otherwise a negative error code.

Since 2.12.0

### gnutls_pubkey_get_pk_ecc_raw ()

    int                 gnutls_pubkey_get_pk_ecc_raw        (gnutls_pubkey_t key,
                                                             gnutls_ecc_curve_t *curve,
                                                             gnutls_datum_t *x,
                                                             gnutls_datum_t *y);

This function will export the ECC public key's parameters found in the given certificate. The new parameters will be allocated using `gnutls_malloc()` and will be stored in the appropriate datum.

`key` : | Holds the public key
`curve` : | will hold the curve
`x` : | will hold x
`y` : | will hold y
Returns : | `GNUTLS_E_SUCCESS` on success, otherwise a negative error code.

Since 3.0

### gnutls_pubkey_get_pk_ecc_x962 ()

    int                 gnutls_pubkey_get_pk_ecc_x962       (gnutls_pubkey_t key,
                                                             gnutls_datum_t *parameters,
                                                             gnutls_datum_t *ecpoint);

This function will export the ECC public key's parameters found in the given certificate. The new parameters will be allocated using `gnutls_malloc()` and will be stored in the appropriate datum.

`key` : | Holds the public key
`parameters` : | DER encoding of an ANSI X9.62 parameters
`ecpoint` : | DER encoding of ANSI X9.62 ECPoint
Returns : | `GNUTLS_E_SUCCESS` on success, otherwise a negative error code.

Since 3.0

### gnutls_pubkey_get_pk_rsa_raw ()

    int                 gnutls_pubkey_get_pk_rsa_raw        (gnutls_pubkey_t key,
                                                             gnutls_datum_t *m,
                                                             gnutls_datum_t *e);

This function will export the RSA public key's parameters found in the given structure. The new parameters will be allocated using `gnutls_malloc()` and will be stored in the appropriate datum.

`key` : | Holds the certificate
`m` : | will hold the modulus
`e` : | will hold the public exponent
Returns : | `GNUTLS_E_SUCCESS` on success, otherwise a negative error code.

Since 2.12.0

### gnutls_pubkey_get_preferred_hash_algorithm ()

    int                 gnutls_pubkey_get_preferred_hash_algorithm
                                                            (gnutls_pubkey_t key,
                                                             gnutls_digest_algorithm_t *hash,
                                                             unsigned int *mand);

This function will read the certifcate and return the appropriate digest algorithm to use for signing with this certificate. Some certificates (i.e. DSA might not be able to sign without the preferred algorithm).

To get the signature algorithm instead of just the hash use `gnutls_pk_to_sign()` with the algorithm of the certificate/key and the provided `hash`.

`key` : | Holds the certificate
`hash` : | The result of the call with the hash algorithm used for signature
`mand` : | If non zero it means that the algorithm MUST use this hash. May be NULL.
Returns : | the 0 if the hash algorithm is found. A negative error code is returned on error.

Since 2.12.0

### gnutls_pubkey_get_verify_algorithm ()

    int                 gnutls_pubkey_get_verify_algorithm  (gnutls_pubkey_t key,
                                                             const gnutls_datum_t *signature,
                                                             gnutls_digest_algorithm_t *hash);

This function will read the certifcate and the signed data to determine the hash algorithm used to generate the signature.

`key` : | Holds the certificate
`signature` : | contains the signature
`hash` : | The result of the call with the hash algorithm used for signature
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_pubkey_import ()

    int                 gnutls_pubkey_import                (gnutls_pubkey_t key,
                                                             const gnutls_datum_t *data,
                                                             gnutls_x509_crt_fmt_t format);

This function will import the provided public key in a SubjectPublicKeyInfo X.509 structure to a native `gnutls_pubkey_t` structure. The output will be stored in `key`. If the public key is PEM encoded it should have a header of "PUBLIC KEY".

`key` : | The structure to store the parsed public key.
`data` : | The DER or PEM encoded certificate.
`format` : | One of DER or PEM
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_pubkey_import_dsa_raw ()

    int                 gnutls_pubkey_import_dsa_raw        (gnutls_pubkey_t key,
                                                             const gnutls_datum_t *p,
                                                             const gnutls_datum_t *q,
                                                             const gnutls_datum_t *g,
                                                             const gnutls_datum_t *y);

This function will convert the given DSA raw parameters to the native gnutls_pubkey_t format. The output will be stored in `key`.

`key` : | The structure to store the parsed key
`p` : | holds the p
`q` : | holds the q
`g` : | holds the g
`y` : | holds the y
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_pubkey_import_ecc_raw ()

    int                 gnutls_pubkey_import_ecc_raw        (gnutls_pubkey_t key,
                                                             gnutls_ecc_curve_t curve,
                                                             const gnutls_datum_t *x,
                                                             const gnutls_datum_t *y);

This function will convert the given elliptic curve parameters to a gnutls_pubkey_t. The output will be stored in `key`.

`key` : | The structure to store the parsed key
`curve` : | holds the curve
`x` : | holds the x
`y` : | holds the y
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.0

### gnutls_pubkey_import_ecc_x962 ()

    int                 gnutls_pubkey_import_ecc_x962       (gnutls_pubkey_t key,
                                                             const gnutls_datum_t *parameters,
                                                             const gnutls_datum_t *ecpoint);

This function will convert the given elliptic curve parameters to a gnutls_pubkey_t. The output will be stored in `key`.

`key` : | The structure to store the parsed key
`parameters` : | DER encoding of an ANSI X9.62 parameters
`ecpoint` : | DER encoding of ANSI X9.62 ECPoint
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.0

### gnutls_pubkey_import_openpgp ()

    int                 gnutls_pubkey_import_openpgp        (gnutls_pubkey_t key,
                                                             gnutls_openpgp_crt_t crt,
                                                             unsigned int flags);

Imports a public key from an openpgp key. This function will import the given public key to the abstract gnutls_pubkey_t structure. The subkey set as preferred will be imported or the master key otherwise.

`key` : | The public key
`crt` : | The certificate to be imported
`flags` : | should be zero
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_pubkey_import_openpgp_raw ()

    int                 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);

This function will import the given public key to the abstract gnutls_pubkey_t structure.

`pkey` : | The public key
`data` : | The public key data to be imported
`format` : | The format of the public key
`keyid` : | The key id to use (optional)
`flags` : | Should be zero
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.1.3

### gnutls_pubkey_import_pkcs11 ()

    int                 gnutls_pubkey_import_pkcs11         (gnutls_pubkey_t key,
                                                             gnutls_pkcs11_obj_t obj,
                                                             unsigned int flags);

Imports a public key from a pkcs11 key. This function will import the given public key to the abstract gnutls_pubkey_t structure.

`key` : | The public key
`obj` : | The parameters to be imported
`flags` : | should be zero
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_pubkey_import_pkcs11_url ()

    int                 gnutls_pubkey_import_pkcs11_url     (gnutls_pubkey_t key,
                                                             const char *url,
                                                             unsigned int flags);

This function will import a PKCS 11 certificate to a gnutls_pubkey_t structure.

`key` : | A key of type gnutls_pubkey_t
`url` : | A PKCS 11 url
`flags` : | One of GNUTLS_PKCS11_OBJ_* flags
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_pubkey_import_privkey ()

    int                 gnutls_pubkey_import_privkey        (gnutls_pubkey_t key,
                                                             gnutls_privkey_t pkey,
                                                             unsigned int usage,
                                                             unsigned int flags);

Imports the public key from a private. This function will import the given public key to the abstract gnutls_pubkey_t structure.

`key` : | The public key
`pkey` : | The private key
`usage` : | GNUTLS_KEY_* key usage flags.
`flags` : | should be zero
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_pubkey_import_rsa_raw ()

    int                 gnutls_pubkey_import_rsa_raw        (gnutls_pubkey_t key,
                                                             const gnutls_datum_t *m,
                                                             const gnutls_datum_t *e);

This function will replace the parameters in the given structure. The new parameters should be stored in the appropriate gnutls_datum.

`key` : | Is a structure will hold the parameters
`m` : | holds the modulus
`e` : | holds the public exponent
Returns : | `GNUTLS_E_SUCCESS` on success, or an negative error code.

Since 2.12.0

### gnutls_pubkey_import_tpm_raw ()

    int                 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);

This function will import the public key from the provided TPM key structure.

With respect to passwords the same as in `gnutls_pubkey_import_tpm_url()` apply.

`pkey` : | The public key
`fdata` : | The TPM key to be imported
`format` : | The format of the private key
`srk_password` : | The password for the SRK key (optional)
`flags` : | One of the GNUTLS_PUBKEY_* flags
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.1.0

### gnutls_pubkey_import_tpm_url ()

    int                 gnutls_pubkey_import_tpm_url        (gnutls_pubkey_t pkey,
                                                             const char *url,
                                                             const char *srk_password,
                                                             unsigned int flags);

This function will import the given private key to the abstract gnutls_privkey_t structure.

Note that unless `GNUTLS_PUBKEY_DISABLE_CALLBACKS` is specified, if incorrect (or NULL) passwords are given the PKCS11 callback functions will be used to obtain the correct passwords. Otherwise if the SRK password is wrong `GNUTLS_E_TPM_SRK_PASSWORD_ERROR` is returned.

`pkey` : | The public key
`url` : | The URL of the TPM key to be imported
`srk_password` : | The password for the SRK key (optional)
`flags` : | should be zero
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.1.0

### gnutls_pubkey_import_url ()

    int                 gnutls_pubkey_import_url            (gnutls_pubkey_t key,
                                                             const char *url,
                                                             unsigned int flags);

This function will import a PKCS11 certificate or a TPM key as a public key.

`key` : | A key of type gnutls_pubkey_t
`url` : | A PKCS 11 url
`flags` : | One of GNUTLS_PKCS11_OBJ_* flags
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.1.0

### gnutls_pubkey_import_x509 ()

    int                 gnutls_pubkey_import_x509           (gnutls_pubkey_t key,
                                                             gnutls_x509_crt_t crt,
                                                             unsigned int flags);

This function will import the given public key to the abstract gnutls_pubkey_t structure.

`key` : | The public key
`crt` : | The certificate to be imported
`flags` : | should be zero
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_pubkey_import_x509_crq ()

    int                 gnutls_pubkey_import_x509_crq       (gnutls_pubkey_t key,
                                                             gnutls_x509_crq_t crq,
                                                             unsigned int flags);

This function will import the given public key to the abstract gnutls_pubkey_t structure.

`key` : | The public key
`crq` : | The certificate to be imported
`flags` : | should be zero
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.1.5

### gnutls_pubkey_import_x509_raw ()

    int                 gnutls_pubkey_import_x509_raw       (gnutls_pubkey_t pkey,
                                                             const gnutls_datum_t *data,
                                                             gnutls_x509_crt_fmt_t format,
                                                             unsigned int flags);

This function will import the given public key to the abstract gnutls_pubkey_t structure.

`pkey` : | The public key
`data` : | The public key data to be imported
`format` : | The format of the public key
`flags` : | should be zero
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 3.1.3

### gnutls_pubkey_init ()

    int                 gnutls_pubkey_init                  (gnutls_pubkey_t *key);

This function will initialize an public key structure.

`key` : | The structure to be initialized
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_pubkey_set_key_usage ()

    int                 gnutls_pubkey_set_key_usage         (gnutls_pubkey_t key,
                                                             unsigned int usage);

This function will set the key usage flags of the public key. This is only useful if the key is to be exported to a certificate or certificate request.

`key` : | a certificate of type gnutls_x509_crt_t
`usage` : | an ORed sequence of the GNUTLS_KEY_* elements.
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_pubkey_set_pin_function ()

    void                gnutls_pubkey_set_pin_function      (gnutls_pubkey_t key,
                                                             gnutls_pin_callback_t fn,
                                                             void *userdata);

This function will set a callback function to be used when required to access the object. This function overrides any other global PIN functions.

Note that this function must be called right after initialization to have effect.

`key` : | A key of type gnutls_pubkey_t
`fn` : | the callback
`userdata` : | data associated with the callback

Since 3.1.0

### gnutls_pubkey_verify_data ()

    int                 gnutls_pubkey_verify_data           (gnutls_pubkey_t pubkey,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *data,
                                                             const gnutls_datum_t *signature);

This function will verify the given signed data, using the parameters from the certificate.

Deprecated. This function cannot be easily used securely. Use `gnutls_pubkey_verify_data2()` instead.

`pubkey` : | Holds the public key
`flags` : | Zero or one of `gnutls_pubkey_flags_t`
`data` : | holds the signed data
`signature` : | contains the signature
Returns : | In case of a verification failure `GNUTLS_E_PK_SIG_VERIFY_FAILED` is returned, and zero or positive code on success.

Since 2.12.0

### gnutls_pubkey_verify_data2 ()

    int                 gnutls_pubkey_verify_data2          (gnutls_pubkey_t pubkey,
                                                             gnutls_sign_algorithm_t algo,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *data,
                                                             const gnutls_datum_t *signature);

This function will verify the given signed data, using the parameters from the certificate.

`pubkey` : | Holds the public key
`algo` : | The signature algorithm used
`flags` : | Zero or one of `gnutls_pubkey_flags_t`
`data` : | holds the signed data
`signature` : | contains the signature
Returns : | In case of a verification failure `GNUTLS_E_PK_SIG_VERIFY_FAILED` is returned, and zero or positive code on success.

Since 3.0

### gnutls_pubkey_verify_hash2 ()

    int                 gnutls_pubkey_verify_hash2          (gnutls_pubkey_t key,
                                                             gnutls_sign_algorithm_t algo,
                                                             unsigned int flags,
                                                             const gnutls_datum_t *hash,
                                                             const gnutls_datum_t *signature);

This function will verify the given signed digest, using the parameters from the public key.

`key` : | Holds the public key
`algo` : | The signature algorithm used
`flags` : | Zero or one of `gnutls_pubkey_flags_t`
`hash` : | holds the hash digest to be verified
`signature` : | contains the signature
Returns : | In case of a verification failure `GNUTLS_E_PK_SIG_VERIFY_FAILED` is returned, and zero or positive code on success.

Since 3.0

### gnutls_x509_crl_privkey_sign ()

    int                 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);

This function will sign the CRL with the issuer's private key, and will copy the issuer's information into the CRL.

This must be the last step in a certificate CRL since all the previously set parameters are now signed.

`crl` : | should contain a gnutls_x509_crl_t structure
`issuer` : | is the certificate of the certificate issuer
`issuer_key` : | holds the issuer's private key
`dig` : | The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you're doing.
`flags` : | must be 0
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value. Since 2.12.0

### gnutls_x509_crq_privkey_sign ()

    int                 gnutls_x509_crq_privkey_sign        (gnutls_x509_crq_t crq,
                                                             gnutls_privkey_t key,
                                                             gnutls_digest_algorithm_t dig,
                                                             unsigned int flags);

This function will sign the certificate request with a private key. This must be the same key as the one used in `gnutls_x509_crt_set_key()` since a certificate request is self signed.

This must be the last step in a certificate request generation since all the previously set parameters are now signed.

`crq` : | should contain a gnutls_x509_crq_t structure
`key` : | holds a private key
`dig` : | The message digest to use, i.e., `GNUTLS_DIG_SHA1`
`flags` : | must be 0
Returns : | `GNUTLS_E_SUCCESS` on success, otherwise a negative error code. `GNUTLS_E_ASN1_VALUE_NOT_FOUND` is returned if you didn't set all information in the certificate request (e.g., the version using `gnutls_x509_crq_set_version()`).

Since 2.12.0

### gnutls_x509_crq_set_pubkey ()

    int                 gnutls_x509_crq_set_pubkey          (gnutls_x509_crq_t crq,
                                                             gnutls_pubkey_t key);

This function will set the public parameters from the given public key to the request.

`crq` : | should contain a gnutls_x509_crq_t structure
`key` : | holds a public key
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0

### gnutls_x509_crt_privkey_sign ()

    int                 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);

This function will sign the certificate with the issuer's private key, and will copy the issuer's information into the certificate.

This must be the last step in a certificate generation since all the previously set parameters are now signed.

`crt` : | a certificate of type gnutls_x509_crt_t
`issuer` : | is the certificate of the certificate issuer
`issuer_key` : | holds the issuer's private key
`dig` : | The message digest to use, `GNUTLS_DIG_SHA1` is a safe choice
`flags` : | must be 0
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

### gnutls_x509_crt_set_pubkey ()

    int                 gnutls_x509_crt_set_pubkey          (gnutls_x509_crt_t crt,
                                                             gnutls_pubkey_t key);

This function will set the public parameters from the given public key to the request.

`crt` : | should contain a gnutls_x509_crt_t structure
`key` : | holds a public key
Returns : | On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise a negative error value.

Since 2.12.0