x509_schannel
=============

## Overview

x509_schannel aims at building schannel objects required by either winhttp or by schannel for x509 
authentication. The data structure to be build is a [PCCERT_CONTEXT](https://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k(WINCRYPT%2FPCCERT_CONTEXT) that can be used with
`WinHttpSetOption` or with `SCHANNEL_CRED` structure of SCHANNEL.

## References

[WinHttpSetOption function](https://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k(WINHTTP%2FWinHttpSetOption) - option `WINHTTP_OPTION_CLIENT_CERT_CONTEXT` 

[SCHANNEL_CRED](https://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k(SCHANNEL%2FSCHANNEL_CRED) - fields `cCreds` and `paCred`

```c
X509_SCHANNEL_HANDLE x509_schannel_create(const char* x509certificate, const char* x509privatekey);
void x509_schannel_destroy(X509_SCHANNEL_HANDLE, x509_schannel_handle);
PCCERT_CONTEXT x509_schannel_get_certificate_context(X509_SCHANNEL_HANDLE x509_schannel_handle);
```

###   x509_schannel_create
```c
X509_SCHANNEL_HANDLE x509_schannel_create(const char* x509certificate, const char* x509privatekey);
```

x509_schannel_create creates a handle wrapping a PCCERT_CONTEXT and other information. 

**SRS_X509_SCHANNEL_02_001: [** If `x509certificate` or `x509privatekey` are NULL then x509_schannel_create shall fail and return NULL. **]**

**SRS_X509_SCHANNEL_02_002: [** `x509_schannel_create` shall convert the certificate to binary form by calling `CryptStringToBinaryA`. **]**

**SRS_X509_SCHANNEL_02_003: [** `x509_schannel_create` shall convert the private key to binary form by calling `CryptStringToBinaryA`. **]**

**SRS_X509_SCHANNEL_02_004: [** `x509_schannel_create` shall decode the private key by calling `CryptDecodeObjectEx`. **]**

**SRS_X509_SCHANNEL_07_001: [** `x509_schannel_create` shall determine whether the certificate is of type RSA or ECC. **]** 

**SRS_X509_SCHANNEL_02_005: [** `x509_schannel_create` shall call `CryptAcquireContext`. **]**

**SRS_X509_SCHANNEL_02_006: [** `x509_schannel_create` shall import the private key by calling `CryptImportKey`. **]**

**SRS_X509_SCHANNEL_02_007: [** `x509_schannel_create` shall create a cerficate context by calling `CertCreateCertificateContext`. **]**

**SRS_X509_SCHANNEL_02_008: [** `x509_schannel_create` shall call set the certificate private key by calling `CertSetCertificateContextProperty`. **]**

**SRS_X509_SCHANNEL_02_009: [** If all the operations above succeed, then `x509_schannel_create` shall succeeds and return a non-NULL X509_SCHANNEL_HANDLE. **]**

**SRS_X509_SCHANNEL_02_010: [** Otherwise, `x509_schannel_create` shall fail and return a NULL X509_SCHANNEL_HANDLE. **]**


###  x509_schannel_destroy
```c
void x509_schannel_destroy(X509_SCHANNEL_HANDLE x509_schannel_handle)
```
`x509_schannel_destroy` frees the system resources used by a `X509_SCHANNEL_HANDLE`

**SRS_X509_SCHANNEL_02_011: [** If parameter `x509_schannel_handle` is NULL then `x509_schannel_destroy` shall do nothing. **]**

**SRS_X509_SCHANNEL_02_012: [** Otherwise, `x509_schannel_destroy` shall free all used resources. **]**

###   x509_schannel_get_certificate_context
```c
PCCERT_CONTEXT x509_schannel_get_certificate_context(X509_SCHANNEL_HANDLE x509_schannel_handle)
```

x509_schannel_get_certificate_context returns the constructed certificate context (PCCERT_CONTEXT)

**SRS_X509_SCHANNEL_02_013: [** If parameter `x509_schannel_handle` is NULL then x509_schannel_get_certificate_context shall return NULL. **]**

**SRS_X509_SCHANNEL_02_014: [** Otherwise, `x509_schannel_get_certificate_context` shall return a non-NULL PCCERT_CONTEXT pointer. **]**