app: XML Security Library Reference Manual

## app app — Application support functions for Microsoft Cryptography API: Next Generation (CNG). |

## Stability Level

Stable, unless otherwise indicated

## Functions

int | xmlSecMSCngAppInit ()
int | xmlSecMSCngAppShutdown ()
LPCTSTR | xmlSecMSCngAppGetCertStoreName ()
int | xmlSecMSCngAppDefaultKeysMngrInit ()
int | xmlSecMSCngAppDefaultKeysMngrAdoptKey ()
int | xmlSecMSCngAppDefaultKeysMngrLoad ()
int | xmlSecMSCngAppDefaultKeysMngrSave ()
int | xmlSecMSCngAppKeysMngrCertLoad ()
int | xmlSecMSCngAppKeysMngrCertLoadMemory ()
xmlSecKeyPtr | xmlSecMSCngAppKeyLoad ()
xmlSecKeyPtr | xmlSecMSCngAppKeyLoadMemory ()
xmlSecKeyPtr | xmlSecMSCngAppPkcs12Load ()
xmlSecKeyPtr | xmlSecMSCngAppPkcs12LoadMemory ()
int | xmlSecMSCngAppKeyCertLoad ()
int | xmlSecMSCngAppKeyCertLoadMemory ()
void * | xmlSecMSCngAppGetDefaultPwdCallback ()

## Description

## Functions

### xmlSecMSCngAppInit ()

    int
    xmlSecMSCngAppInit (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 MSCng configuration (unused). |

#### Returns

0 on success or a negative value otherwise.

### xmlSecMSCngAppShutdown ()

    int
    xmlSecMSCngAppShutdown (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.

### xmlSecMSCngAppGetCertStoreName ()

    LPCTSTR
    xmlSecMSCngAppGetCertStoreName (void);

Gets the MS Cng certs store name set by `xmlSecMSCngAppInit` function.

#### Returns

the MS Cng certs name used by xmlsec-mscng.

### xmlSecMSCngAppDefaultKeysMngrInit ()

    int
    xmlSecMSCngAppDefaultKeysMngrInit (xmlSecKeysMngrPtr mngr);

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

#### Parameters

mngr | the pointer to keys manager. |

#### Returns

0 on success or a negative value otherwise.

### xmlSecMSCngAppDefaultKeysMngrAdoptKey ()

    int
    xmlSecMSCngAppDefaultKeysMngrAdoptKey (xmlSecKeysMngrPtr mngr,
                                           xmlSecKeyPtr key);

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

#### Parameters

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

#### Returns

0 on success or a negative value otherwise.

### xmlSecMSCngAppDefaultKeysMngrLoad ()

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

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

#### Parameters

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

#### Returns

0 on success or a negative value otherwise.

### xmlSecMSCngAppDefaultKeysMngrSave ()

    int
    xmlSecMSCngAppDefaultKeysMngrSave (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.

### xmlSecMSCngAppKeysMngrCertLoad ()

    int
    xmlSecMSCngAppKeysMngrCertLoad (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` (not implemented yet).

#### 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.

### xmlSecMSCngAppKeysMngrCertLoadMemory ()

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

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

#### Parameters

mngr | the pointer to keys manager. |
data | the key binary data. |
dataSize | the key binary data size. |
format | the certificate format (PEM or DER). |
type | the certificate type (trusted/untrusted). |

#### Returns

0 on success or a negative value otherwise.

### xmlSecMSCngAppKeyLoad ()

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

Reads key from the a file (not implemented yet).

#### 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.

### xmlSecMSCngAppKeyLoadMemory ()

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

Reads key from a binary `data` .

#### Parameters

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

#### Returns

pointer to the key or NULL if an error occurs.

### xmlSecMSCngAppPkcs12Load ()

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

Reads key and all associated certificates from the PKCS12 file (not implemented yet). For uniformity, call xmlSecMSCngAppKeyLoad 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.

### xmlSecMSCngAppPkcs12LoadMemory ()

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

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

#### Parameters

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

#### Returns

pointer to the key or NULL if an error occurs.

### xmlSecMSCngAppKeyCertLoad ()

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

Reads the certificate from $`filename` and adds it to key (not implemented yet).

#### Parameters

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

#### Returns

0 on success or a negative value otherwise.

### xmlSecMSCngAppKeyCertLoadMemory ()

    int
    xmlSecMSCngAppKeyCertLoadMemory (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.

### xmlSecMSCngAppGetDefaultPwdCallback ()

    void *
    xmlSecMSCngAppGetDefaultPwdCallback (void);

Gets default password callback.

#### Returns

default password callback.