# nettransportssl.h File Reference

`#include <gwenhywfar/nettransport.h>`
`#include <gwenhywfar/db.h>`

Go to the source code of this file.

## Certificate Functions

typedef GWEN_NETTRANSPORTSSL_ASKADDCERT_RESULT(* | GWEN_NETTRANSPORTSSL_ASKADDCERT_FN )(GWEN_NETTRANSPORT *tr, GWEN_DB_NODE *cert)
typedef GWEN_NETTRANSPORTSSL_ASKADDCERT_RESULT(* | GWEN_NETTRANSPORTSSL_ASKADDCERT_FN2 )(GWEN_NETTRANSPORT *tr, GWEN_DB_NODE *cert, void *user_data)
enum | GWEN_NETTRANSPORTSSL_ASKADDCERT_RESULT { GWEN_NetTransportSSL_AskAddCertResultError = 0, GWEN_NetTransportSSL_AskAddCertResultNo, GWEN_NetTransportSSL_AskAddCertResultTmp, GWEN_NetTransportSSL_AskAddCertResultPerm, GWEN_NetTransportSSL_AskAddCertResultIncoming }
GWENHYWFAR_API GWEN_NETTRANSPORTSSL_ASKADDCERT_FN | GWEN_NetTransportSSL_GetAskAddCertFn ()
GWENHYWFAR_API void | GWEN_NetTransportSSL_SetAskAddCertFn (GWEN_NETTRANSPORTSSL_ASKADDCERT_FN fn)
GWENHYWFAR_API void | GWEN_NetTransportSSL_SetAskAddCertFn2 (GWEN_NETTRANSPORTSSL_ASKADDCERT_FN2 fn, void *user_data)

## Password Functions

typedef int(* | GWEN_NETTRANSPORTSSL_GETPASSWD_FN )(GWEN_NETTRANSPORT *tr, char *buffer, int num, int rwflag)
GWENHYWFAR_API GWEN_NETTRANSPORTSSL_GETPASSWD_FN | GWEN_NetTransportSSL_GetGetPasswordFn ()
GWENHYWFAR_API void | GWEN_NetTransportSSL_SetGetPasswordFn (GWEN_NETTRANSPORTSSL_GETPASSWD_FN fn)

## Misc Functions around SSL connections

GWENHYWFAR_API int | GWEN_NetTransportSSL_GenerateCertAndKeyFile (const char *fname, int bits, int serial, int days, GWEN_DB_NODE *db)
GWENHYWFAR_API int | GWEN_NetTransportSSL_GenerateDhFile (const char *fname, int bits)
GWENHYWFAR_API GWEN_DB_NODE * | GWEN_NetTransportSSL_GetCipherList ()
GWENHYWFAR_API GWEN_DB_NODE * | GWEN_NetTransportSSL_GetPeerCertificate (const GWEN_NETTRANSPORT *tr)
GWENHYWFAR_API int | GWEN_NetTransportSSL_IsOfType (GWEN_NETTRANSPORT *tr)
GWENHYWFAR_API int | GWEN_NetTransportSSL_IsSecure (const GWEN_NETTRANSPORT *tr)
GWENHYWFAR_API void | GWEN_NetTransportSSL_SetCipherList (GWEN_NETTRANSPORT *tr, const char *ciphers)

## Functions

GWENHYWFAR_API GWEN_NETTRANSPORT * | GWEN_NetTransportSSL_new (GWEN_SOCKET *sk, const char *capath, const char *newcapath, const char *ownCertFile, const char *dhfile, int secure, int takeOver)

## Typedef Documentation

typedef GWEN_NETTRANSPORTSSL_ASKADDCERT_RESULT(* GWEN_NETTRANSPORTSSL_ASKADDCERT_FN)(GWEN_NETTRANSPORT *tr, GWEN_DB_NODE *cert)

This is the prototype of the callback which asks the user whether he wants to add the given certificate to the list of trusted ones.

Parameters:

  | tr | transport layer via which the certificate has been received
  | cert | a DB node containing information about the certificate

typedef GWEN_NETTRANSPORTSSL_ASKADDCERT_RESULT(* GWEN_NETTRANSPORTSSL_ASKADDCERT_FN2)(GWEN_NETTRANSPORT *tr, GWEN_DB_NODE *cert, void *user_data)

typedef int(* GWEN_NETTRANSPORTSSL_GETPASSWD_FN)(GWEN_NETTRANSPORT *tr, char *buffer, int num, int rwflag)

This is the prototype for the callback function which asks the user for a password.

Parameters:

  | tr | transport layer involved
  | buffer | destination buffer for the password
  | num | size of the password buffer
  | rwflag | if 1 then the password is to be created (in this case the function should let the user verify the password before writing it into the buffer).

## Enumeration Type Documentation

enum GWEN_NETTRANSPORTSSL_ASKADDCERT_RESULT

Enumerator:

  GWEN_NetTransportSSL_AskAddCertResultError | error asking the user
  GWEN_NetTransportSSL_AskAddCertResultNo | user does not trust the given certificate
  GWEN_NetTransportSSL_AskAddCertResultTmp | user trusts the given certificate for this session only
  GWEN_NetTransportSSL_AskAddCertResultPerm | user trusts the given certificate permanently
  GWEN_NetTransportSSL_AskAddCertResultIncoming | store the cert in an incoming directory, trust it for this session

## Function Documentation

GWENHYWFAR_API int GWEN_NetTransportSSL_GenerateCertAndKeyFile | ( | const char * | fname,
|  | int | bits,
|  | int | serial,
|  | int | days,
|  | GWEN_DB_NODE * | db
| ) |

Generates and signs a certificate to be used with the underlying crypto system (in most cases OpenSSL). This function may use whatever format it sees fit when storing the certificate.

The given DB should contain some data to be stored within the certificate, such as:

- countryName
- commonName
- organizationName
- organizationalUnitName
- localityName
- stateOrProvinceName

Parameters:

  | bits | number of bits to be used (you should use at least 1024 bits)
  | serial | serial number of the certificate (at your disposal)
  | day | if !=0 then this is the number of days the certificate is valid
  | db | GWEN_DB containing some information (see above)

GWENHYWFAR_API int GWEN_NetTransportSSL_GenerateDhFile | ( | const char * | fname,
|  | int | bits
| ) |

Generates parameters for the Diffie-Hellman key agreement protocol. See "man dh" for details.

This function may use whatever format it sees fit when storing the DH params.

Returns:
  0 if ok, != 0 otherwise

Parameters:

  | fname | name of the file to store the params in
  | bits | length in bits of the safe prime to be generated

GWENHYWFAR_API GWEN_NETTRANSPORTSSL_ASKADDCERT_FN GWEN_NetTransportSSL_GetAskAddCertFn | ( |  | ) |

| Returns the currently active callback function.

GWENHYWFAR_API GWEN_DB_NODE* GWEN_NetTransportSSL_GetCipherList | ( |  | ) |

This function returns a list of supported ciphers. For each supported cipher there is a group called "cipher" with the variables:

- name
- version
- description

You can use the namevariables to create the string for GWEN_NetTransportSSL_SetCipherList.

GWENHYWFAR_API GWEN_NETTRANSPORTSSL_GETPASSWD_FN GWEN_NetTransportSSL_GetGetPasswordFn | ( |  | ) |

| Returns the currently active callback function.

GWENHYWFAR_API GWEN_DB_NODE* GWEN_NetTransportSSL_GetPeerCertificate | ( | const GWEN_NETTRANSPORT * | tr | ) |

| Returns a DB containing the certificate of the current peer (or 0 if none). The caller MUST NOT free the DB returned (if any).

GWENHYWFAR_API int GWEN_NetTransportSSL_IsOfType | ( | GWEN_NETTRANSPORT * | tr | ) |

GWENHYWFAR_API int GWEN_NetTransportSSL_IsSecure | ( | const GWEN_NETTRANSPORT * | tr | ) |

GWENHYWFAR_API GWEN_NETTRANSPORT* GWEN_NetTransportSSL_new | ( | GWEN_SOCKET * | sk,
|  | const char * | capath,
|  | const char * | newcapath,
|  | const char * | ownCertFile,
|  | const char * | dhfile,
|  | int | secure,
|  | int | takeOver
| ) |

Creates a new SSL socket.

Parameters:

  | cadir | name of a folder containing trusted certificates (or 0)
  | ownCertFile | name of a file containing the certificate to be used (or 0)
  | secure | if !=0 then the peer is forced to authenticate
  | takeOver | if !=0 then the new object will take over the socket

GWENHYWFAR_API void GWEN_NetTransportSSL_SetAskAddCertFn | ( | GWEN_NETTRANSPORTSSL_ASKADDCERT_FN | fn | ) |

| Sets the callback function for asking the user whether to accept a given certificate.

GWENHYWFAR_API void GWEN_NetTransportSSL_SetAskAddCertFn2 | ( | GWEN_NETTRANSPORTSSL_ASKADDCERT_FN2 | fn,
|  | void * | user_data
| ) |

GWENHYWFAR_API void GWEN_NetTransportSSL_SetCipherList | ( | GWEN_NETTRANSPORT * | tr,
|  | const char * | ciphers
| ) |

| This function allows to set a list of allowed cipher algorithms. It is a colon separated list. For OpenSSL you can get a list of available ciphers via "openssl ciphers".

GWENHYWFAR_API void GWEN_NetTransportSSL_SetGetPasswordFn | ( | GWEN_NETTRANSPORTSSL_GETPASSWD_FN | fn | ) |

| Sets the callback function which asks the user for a password.