Loading...
Searching...
No Matches
Server TLS
Server

Server-side settings for TLS connections. More...

Collaboration diagram for Server TLS:

## Functions

int | nc_server_tls_endpt_add_ctn (const char *endpt_name, uint32_t id, const char *fingerprint, NC_TLS_CTN_MAPTYPE map_type, const char *name)
| Add a cert-to-name entry.
int | nc_server_tls_endpt_add_trusted_cert_list (const char *endpt_name, const char *name)
| Add a trusted certificate list. Can be both a CA or a client one. Can be safely used together with nc_server_tls_endpt_set_trusted_ca_paths().
void | nc_server_tls_endpt_clear_crls (const char *endpt_name)
| Destroy and clean CRLs. Certificates, private keys, and CTN entries are not affected.
int | nc_server_tls_endpt_del_ctn (const char *endpt_name, int64_t id, const char *fingerprint, NC_TLS_CTN_MAPTYPE map_type, const char *name)
| Remove a cert-to-name entry.
int | nc_server_tls_endpt_del_trusted_cert_list (const char *endpt_name, const char *name)
| Remove a trusted certificate.
int | nc_server_tls_endpt_get_ctn (const char *endpt_name, uint32_t *id, char **fingerprint, NC_TLS_CTN_MAPTYPE *map_type, char **name)
| Get a cert-to-name entry.
int | nc_server_tls_endpt_set_crl_paths (const char *endpt_name, const char *crl_file, const char *crl_dir)
| Set Certificate Revocation List locations. There can only be one file and one directory, they are replaced if already set.
int | nc_server_tls_endpt_set_server_cert (const char *endpt_name, const char *name)
| Set the server TLS certificate. Only the name is set, the certificate itself wil be retrieved using a callback.
int | nc_server_tls_endpt_set_trusted_ca_paths (const char *endpt_name, const char *ca_file, const char *ca_dir)
| Set trusted Certificate Authority certificate locations. There can only be one file and one directory, they are replaced if already set. Can be safely used with nc_server_tls_endpt_add_trusted_cert() or its _path variant.
void | nc_server_tls_set_server_cert_chain_clb (int(*cert_chain_clb)(const char *name, void *user_data, char ***cert_paths, int *cert_path_count, char ***cert_data, int *cert_data_count), void *user_data, void(*free_user_data)(void *user_data))
| Set the callback for retrieving server certificate chain.
void | nc_server_tls_set_server_cert_clb (int(*cert_clb)(const char *name, void *user_data, char **cert_path, char **cert_data, char **privkey_path, char **privkey_data, NC_SSH_KEY_TYPE *privkey_type), void *user_data, void(*free_user_data)(void *user_data))
| Set the callback for retrieving server certificate and matching private key.
void | nc_server_tls_set_trusted_cert_list_clb (int(*cert_list_clb)(const char *name, void *user_data, char ***cert_paths, int *cert_path_count, char ***cert_data, int *cert_data_count), void *user_data, void(*free_user_data)(void *user_data))
| Set the callback for retrieving trusted certificates.
void | nc_server_tls_set_verify_clb (int(*verify_clb)(const struct nc_session *session))
| Set TLS authentication additional verify callback.
const X509 * | nc_session_get_client_cert (const struct nc_session *session)
| Get client certificate.

## Detailed Description

Server-side settings for TLS connections.

## Function Documentation

## nc_server_tls_endpt_add_ctn()

int nc_server_tls_endpt_add_ctn | ( | const char * | endpt_name,
|  | uint32_t | id,
|  | const char * | fingerprint,
|  | NC_TLS_CTN_MAPTYPE | map_type,
|  | const char * | name
| ) |  |

Add a cert-to-name entry.

It is possible to add an entry step-by-step, specifying first only `ip` and in later calls `fingerprint`, `map_type`, and optionally `name` spearately.

Parameters

  [in] | endpt_name | Existing endpoint name.
  [in] | id | Priority of the entry. It must be unique. If already exists, the entry with this id is modified.
  [in] | fingerprint | Matching certificate fingerprint. If NULL, kept temporarily unset.
  [in] | map_type | Type of username-certificate mapping. If 0, kept temporarily unset.
  [in] | name | Specific username used only if `map_type` == NC_TLS_CTN_SPECIFED.

Returns
  0 on success, -1 on error.

## nc_server_tls_endpt_add_trusted_cert_list()

int nc_server_tls_endpt_add_trusted_cert_list | ( | const char * | endpt_name,
|  | const char * | name
| ) |  |

Add a trusted certificate list. Can be both a CA or a client one. Can be safely used together with nc_server_tls_endpt_set_trusted_ca_paths().

Parameters

  [in] | endpt_name | Existing endpoint name.
  [in] | name | Arbitary name identifying this certificate list.

Returns
  0 on success, -1 on error.

## nc_server_tls_endpt_clear_crls()

void nc_server_tls_endpt_clear_crls | ( | const char * | endpt_name | ) |

Destroy and clean CRLs. Certificates, private keys, and CTN entries are not affected.

Parameters

  [in] | endpt_name | Existing endpoint name.

## nc_server_tls_endpt_del_ctn()

int nc_server_tls_endpt_del_ctn | ( | const char * | endpt_name,
|  | int64_t | id,
|  | const char * | fingerprint,
|  | NC_TLS_CTN_MAPTYPE | map_type,
|  | const char * | name
| ) |  |

Remove a cert-to-name entry.

Parameters

  [in] | endpt_name | Existing endpoint name.
  [in] | id | Priority of the entry. -1 matches all the priorities.
  [in] | fingerprint | Fingerprint fo the entry. NULL matches all the fingerprints.
  [in] | map_type | Mapping type of the entry. 0 matches all the mapping types.
  [in] | name | Specific username for the entry. NULL matches all the usernames.

Returns
  0 on success, -1 on not finding any match.

## nc_server_tls_endpt_del_trusted_cert_list()

int nc_server_tls_endpt_del_trusted_cert_list | ( | const char * | endpt_name,
|  | const char * | name
| ) |  |

Remove a trusted certificate.

Parameters

  [in] | endpt_name | Existing endpoint name.
  [in] | name | Name of the certificate list to delete. NULL deletes all the lists.

Returns
  0 on success, -1 on not found.

## nc_server_tls_endpt_get_ctn()

int nc_server_tls_endpt_get_ctn | ( | const char * | endpt_name,
|  | uint32_t * | id,
|  | char ** | fingerprint,
|  | NC_TLS_CTN_MAPTYPE * | map_type,
|  | char ** | name
| ) |  |

Get a cert-to-name entry.

If a parameter is NULL, it is ignored. If its dereferenced value is NULL, it is filled and returned. If the value is set, it is used as a filter. Returns first matching entry.

Parameters

  [in] | endpt_name | Existing endpoint name.
  [in,out] | id | Priority of the entry.
  [in,out] | fingerprint | Fingerprint fo the entry.
  [in,out] | map_type | Mapping type of the entry.
  [in,out] | name | Specific username for the entry.

Returns
  0 on success, -1 on not finding any match.

## nc_server_tls_endpt_set_crl_paths()

int nc_server_tls_endpt_set_crl_paths | ( | const char * | endpt_name,
|  | const char * | crl_file,
|  | const char * | crl_dir
| ) |  |

Set Certificate Revocation List locations. There can only be one file and one directory, they are replaced if already set.

Parameters

  [in] | endpt_name | Existing endpoint name.
  [in] | crl_file | Path to a CRL store file in PEM format. Can be NULL.
  [in] | crl_dir | Path to a CRL store hashed directory (c_rehash utility can be used to create hashes) with PEM files. Can be NULL.

Returns
  0 on success, -1 on error.

## nc_server_tls_endpt_set_server_cert()

int nc_server_tls_endpt_set_server_cert | ( | const char * | endpt_name,
|  | const char * | name
| ) |  |

Set the server TLS certificate. Only the name is set, the certificate itself wil be retrieved using a callback.

Parameters

  [in] | endpt_name | Existing endpoint name.
  [in] | name | Arbitrary certificate name.

Returns
  0 on success, -1 on error.

## nc_server_tls_endpt_set_trusted_ca_paths()

int nc_server_tls_endpt_set_trusted_ca_paths | ( | const char * | endpt_name,
|  | const char * | ca_file,
|  | const char * | ca_dir
| ) |  |

Set trusted Certificate Authority certificate locations. There can only be one file and one directory, they are replaced if already set. Can be safely used with nc_server_tls_endpt_add_trusted_cert() or its _path variant.

Parameters

  [in] | endpt_name | Existing endpoint name.
  [in] | ca_file | Path to a trusted CA cert store file in PEM format. Can be NULL.
  [in] | ca_dir | Path to a trusted CA cert store hashed directory (c_rehash utility can be used to create hashes) with PEM files. Can be NULL.

Returns
  0 on success, -1 on error.

## nc_server_tls_set_server_cert_chain_clb()

void nc_server_tls_set_server_cert_chain_clb | ( | int(*)(const char *name, void *user_data, char ***cert_paths, int *cert_path_count, char ***cert_data, int *cert_data_count) | cert_chain_clb,
|  | void * | user_data,
|  | void(*)(void *user_data) | free_user_data
| ) |  |

Set the callback for retrieving server certificate chain.

Parameters

  [in]

  cert_chain_clb

  Callback that should return all the certificates of the chain. Zero return indicates success, non-zero an error. On success, `cert_paths` and `cert_data` are expected to be set or left NULL. Both will be (deeply) freed.
  - `cert_paths` expect an array of PEM files,
  - `cert_path_count` number of `cert_paths` array members,
  - `cert_data` expect an array of base-64 encoded ASN.1 DER cert data,
  - `cert_data_count` number of `cert_data` array members.

  [in] | user_data | Optional arbitrary user data that will be passed to `cert_clb`.
  [in] | free_user_data | Optional callback that will be called during cleanup to free any `user_data`.

## nc_server_tls_set_server_cert_clb()

void nc_server_tls_set_server_cert_clb | ( | int(*)(const char *name, void *user_data, char **cert_path, char **cert_data, char **privkey_path, char **privkey_data, NC_SSH_KEY_TYPE *privkey_type) | cert_clb,
|  | void * | user_data,
|  | void(*)(void *user_data) | free_user_data
| ) |  |

Set the callback for retrieving server certificate and matching private key.

Parameters

  [in]

  cert_clb

  Callback that should return the certificate and the key itself. Zero return indicates success, non-zero an error. On success exactly ONE of `cert_path` or `cert_data` and ONE of `privkey_path` and `privkey_data` is expected to be set. Those set will be freed.
  - `cert_path` expects a PEM file,
  - `cert_data` expects a base-64 encoded ASN.1 DER data,
  - `privkey_path` expects a PEM file,
  - `privkey_data` expects a base-64 encoded ANS.1 DER data,
  - `privkey_type` type of the key in `privkey_data`.

  [in] | user_data | Optional arbitrary user data that will be passed to `cert_clb`.
  [in] | free_user_data | Optional callback that will be called during cleanup to free any `user_data`.

## nc_server_tls_set_trusted_cert_list_clb()

void nc_server_tls_set_trusted_cert_list_clb | ( | int(*)(const char *name, void *user_data, char ***cert_paths, int *cert_path_count, char ***cert_data, int *cert_data_count) | cert_list_clb,
|  | void * | user_data,
|  | void(*)(void *user_data) | free_user_data
| ) |  |

Set the callback for retrieving trusted certificates.

Parameters

  [in]

  cert_list_clb

  Callback that should return all the certificates of a list. Zero return indicates success, non-zero an error. On success, `cert_paths` and `cert_data` are expected to be set or left NULL. Both will be (deeply) freed.
  - `cert_paths` expect an array of PEM files,
  - `cert_path_count` number of `cert_paths` array members,
  - `cert_data` expect an array of base-64 encoded ASN.1 DER cert data,
  - `cert_data_count` number of `cert_data` array members.

  [in] | user_data | Optional arbitrary user data that will be passed to `cert_clb`.
  [in] | free_user_data | Optional callback that will be called during cleanup to free any `user_data`.

## nc_server_tls_set_verify_clb()

void nc_server_tls_set_verify_clb | ( | int(*)(const struct nc_session *session) | verify_clb | ) |

Set TLS authentication additional verify callback.

Server will always perform cert-to-name based on its configuration. Only after it passes and this callback is set, it is also called. It should return exactly what OpenSSL verify callback meaning 1 for success, 0 to deny the user.

Parameters

  [in] | verify_clb | Additional user verify callback.

## nc_session_get_client_cert()

const X509 * nc_session_get_client_cert | ( | const struct nc_session * | session | ) |

Get client certificate.

Parameters

  [in] | session | Session to get the information from.

Returns
  Const session client certificate.