app: XML Security Library Reference Manual

## app app — Application support functions for GnuTLS. |

## Stability Level

Stable, unless otherwise indicated

## Functions

int | xmlSecGnuTLSAppInit ()
int | xmlSecGnuTLSAppShutdown ()
int | xmlSecGnuTLSAppDefaultKeysMngrInit ()
int | xmlSecGnuTLSAppDefaultKeysMngrAdoptKey ()
int | xmlSecGnuTLSAppDefaultKeysMngrLoad ()
int | xmlSecGnuTLSAppDefaultKeysMngrSave ()
int | xmlSecGnuTLSAppKeysMngrCertLoad ()
int | xmlSecGnuTLSAppKeysMngrCertLoadMemory ()
xmlSecKeyPtr | xmlSecGnuTLSAppKeyLoad ()
xmlSecKeyPtr | xmlSecGnuTLSAppKeyLoadMemory ()
xmlSecKeyPtr | xmlSecGnuTLSAppPkcs12Load ()
xmlSecKeyPtr | xmlSecGnuTLSAppPkcs12LoadMemory ()
int | xmlSecGnuTLSAppKeyCertLoad ()
int | xmlSecGnuTLSAppKeyCertLoadMemory ()
void * | xmlSecGnuTLSAppGetDefaultPwdCallback ()

## Description

## Functions

### xmlSecGnuTLSAppInit ()

    int
    xmlSecGnuTLSAppInit (const char *config);

General crypto engine initialization. This function is used by XMLSec command line utility and called before `xmlSecInit` function.

#### Parameters

config | the path to GnuTLS configuration (unused). |

#### Returns

0 on success or a negative value otherwise.

### xmlSecGnuTLSAppShutdown ()

    int
    xmlSecGnuTLSAppShutdown (void);

General crypto engine shutdown. This function is used by XMLSec command line utility and called after `xmlSecShutdown` function.

#### Returns

0 on success or a negative value otherwise.

### xmlSecGnuTLSAppDefaultKeysMngrInit ()

    int
    xmlSecGnuTLSAppDefaultKeysMngrInit (xmlSecKeysMngrPtr mngr);

Initializes `mngr` with simple keys store xmlSecSimpleKeysStoreId and a default GnuTLS crypto key data stores.

#### Parameters

mngr | the pointer to keys manager. |

#### Returns

0 on success or a negative value otherwise.

### xmlSecGnuTLSAppDefaultKeysMngrAdoptKey ()

    int
    xmlSecGnuTLSAppDefaultKeysMngrAdoptKey
                                   (xmlSecKeysMngrPtr mngr,
                                    xmlSecKeyPtr key);

Adds `key` to the keys manager `mngr` created with xmlSecGnuTLSAppDefaultKeysMngrInit function.

#### Parameters

mngr | the pointer to keys manager. |
key | the pointer to key. |

#### Returns

0 on success or a negative value otherwise.

### xmlSecGnuTLSAppDefaultKeysMngrLoad ()

    int
    xmlSecGnuTLSAppDefaultKeysMngrLoad (xmlSecKeysMngrPtr mngr,
                                        const char *uri);

Loads XML keys file from `uri` to the keys manager `mngr` created with xmlSecGnuTLSAppDefaultKeysMngrInit function.

#### Parameters

mngr | the pointer to keys manager. |
uri | the uri. |

#### Returns

0 on success or a negative value otherwise.

### xmlSecGnuTLSAppDefaultKeysMngrSave ()

    int
    xmlSecGnuTLSAppDefaultKeysMngrSave (xmlSecKeysMngrPtr mngr,
                                        const char *filename,
                                        xmlSecKeyDataType type);

Saves keys from `mngr` to XML keys file.

#### Parameters

mngr | the pointer to keys manager. |
filename | the destination filename. |
type | the type of keys to save (public/private/symmetric). |

#### Returns

0 on success or a negative value otherwise.

### xmlSecGnuTLSAppKeysMngrCertLoad ()

    int
    xmlSecGnuTLSAppKeysMngrCertLoad (xmlSecKeysMngrPtr mngr,
                                     const char *filename,
                                     xmlSecKeyDataFormat format,
                                     xmlSecKeyDataType type);

Reads cert from `filename` and adds to the list of trusted or known untrusted certs in `store` .

#### Parameters

mngr | the keys manager. |
filename | the certificate file. |
format | the certificate file format. |
type | the flag that indicates is the certificate in `filename` trusted or not. |

#### Returns

0 on success or a negative value otherwise.

### xmlSecGnuTLSAppKeysMngrCertLoadMemory ()

    int
    xmlSecGnuTLSAppKeysMngrCertLoadMemory (xmlSecKeysMngrPtr mngr,
                                           const xmlSecByte *data,
                                           xmlSecSize dataSize,
                                           xmlSecKeyDataFormat format,
                                           xmlSecKeyDataType type);

Reads cert from binary buffer `data` and adds to the list of trusted or known untrusted certs in `store` .

#### Parameters

mngr | the keys manager. |
data | the certificate binary data. |
dataSize | the certificate binary data size. |
format | the certificate file format. |
type | the flag that indicates is the certificate trusted or not. |

#### Returns

0 on success or a negative value otherwise.

### xmlSecGnuTLSAppKeyLoad ()

    xmlSecKeyPtr
    xmlSecGnuTLSAppKeyLoad (const char *filename,
                            xmlSecKeyDataFormat format,
                            const char *pwd,
                            void *pwdCallback,
                            void *pwdCallbackCtx);

Reads key from the a file.

#### Parameters

filename | the key filename. |
format | the key file format. |
pwd | the key file password. |
pwdCallback | the key password callback. |
pwdCallbackCtx | the user context for password callback. |

#### Returns

pointer to the key or NULL if an error occurs.

### xmlSecGnuTLSAppKeyLoadMemory ()

    xmlSecKeyPtr
    xmlSecGnuTLSAppKeyLoadMemory (const xmlSecByte *data,
                                  xmlSecSize dataSize,
                                  xmlSecKeyDataFormat format,
                                  const char *pwd,
                                  void *pwdCallback,
                                  void *pwdCallbackCtx);

Reads key from the memory buffer.

#### Parameters

data | the binary key data. |
dataSize | the size of binary key. |
format | the key file format. |
pwd | the key file password. |
pwdCallback | the key password callback. |
pwdCallbackCtx | the user context for password callback. |

#### Returns

pointer to the key or NULL if an error occurs.

### xmlSecGnuTLSAppPkcs12Load ()

    xmlSecKeyPtr
    xmlSecGnuTLSAppPkcs12Load (const char *filename,
                               const char *pwd,
                               void *pwdCallback,
                               void *pwdCallbackCtx);

Reads key and all associated certificates from the PKCS12 file. For uniformity, call xmlSecGnuTLSAppKeyLoad instead of this function. Pass in format=xmlSecKeyDataFormatPkcs12.

#### Parameters

filename | the PKCS12 key filename. |
pwd | the PKCS12 file password. |
pwdCallback | the password callback. |
pwdCallbackCtx | the user context for password callback. |

#### Returns

pointer to the key or NULL if an error occurs.

### xmlSecGnuTLSAppPkcs12LoadMemory ()

    xmlSecKeyPtr
    xmlSecGnuTLSAppPkcs12LoadMemory (const xmlSecByte *data,
                                     xmlSecSize dataSize,
                                     const char *pwd,
                                     void *pwdCallback,
                                     void *pwdCallbackCtx);

Reads key and all associated certificates from the PKCS12 data in memory buffer. For uniformity, call xmlSecGnuTLSAppKeyLoadMemory instead of this function. Pass in format=xmlSecKeyDataFormatPkcs12.

#### Parameters

data | the PKCS12 binary data. |
dataSize | the PKCS12 binary data size. |
pwd | the PKCS12 file password. |
pwdCallback | the password callback. |
pwdCallbackCtx | the user context for password callback. |

#### Returns

pointer to the key or NULL if an error occurs.

### xmlSecGnuTLSAppKeyCertLoad ()

    int
    xmlSecGnuTLSAppKeyCertLoad (xmlSecKeyPtr key,
                                const char *filename,
                                xmlSecKeyDataFormat format);

Reads the certificate from $`filename` and adds it to key.

#### Parameters

key | the pointer to key. |
filename | the certificate filename. |
format | the certificate file format. |

#### Returns

0 on success or a negative value otherwise.

### xmlSecGnuTLSAppKeyCertLoadMemory ()

    int
    xmlSecGnuTLSAppKeyCertLoadMemory (xmlSecKeyPtr key,
                                      const xmlSecByte *data,
                                      xmlSecSize dataSize,
                                      xmlSecKeyDataFormat format);

Reads the certificate from memory buffer and adds it to key.

#### Parameters

key | the pointer to key. |
data | the certificate binary data. |
dataSize | the certificate binary data size. |
format | the certificate file format. |

#### Returns

0 on success or a negative value otherwise.

### xmlSecGnuTLSAppGetDefaultPwdCallback ()

    void *
    xmlSecGnuTLSAppGetDefaultPwdCallback (void);

Gets default password callback.

#### Returns

default password callback.