| 1 |
x509_schannel |
| 2 |
============= |
| 3 |
|
| 4 |
## Overview |
| 5 |
|
| 6 |
x509_schannel aims at building schannel objects required by either winhttp or by schannel for x509 |
| 7 |
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 |
| 8 |
`WinHttpSetOption` or with `SCHANNEL_CRED` structure of SCHANNEL. |
| 9 |
|
| 10 |
## References |
| 11 |
|
| 12 |
[WinHttpSetOption function](https://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k(WINHTTP%2FWinHttpSetOption) - option `WINHTTP_OPTION_CLIENT_CERT_CONTEXT` |
| 13 |
|
| 14 |
[SCHANNEL_CRED](https://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k(SCHANNEL%2FSCHANNEL_CRED) - fields `cCreds` and `paCred` |
| 15 |
|
| 16 |
```c |
| 17 |
X509_SCHANNEL_HANDLE x509_schannel_create(const char* x509certificate, const char* x509privatekey); |
| 18 |
void x509_schannel_destroy(X509_SCHANNEL_HANDLE, x509_schannel_handle); |
| 19 |
PCCERT_CONTEXT x509_schannel_get_certificate_context(X509_SCHANNEL_HANDLE x509_schannel_handle); |
| 20 |
``` |
| 21 |
|
| 22 |
### x509_schannel_create |
| 23 |
```c |
| 24 |
X509_SCHANNEL_HANDLE x509_schannel_create(const char* x509certificate, const char* x509privatekey); |
| 25 |
``` |
| 26 |
|
| 27 |
x509_schannel_create creates a handle wrapping a PCCERT_CONTEXT and other information. |
| 28 |
|
| 29 |
**SRS_X509_SCHANNEL_02_001: [** If `x509certificate` or `x509privatekey` are NULL then x509_schannel_create shall fail and return NULL. **]** |
| 30 |
|
| 31 |
**SRS_X509_SCHANNEL_02_002: [** `x509_schannel_create` shall convert the certificate to binary form by calling `CryptStringToBinaryA`. **]** |
| 32 |
|
| 33 |
**SRS_X509_SCHANNEL_02_003: [** `x509_schannel_create` shall convert the private key to binary form by calling `CryptStringToBinaryA`. **]** |
| 34 |
|
| 35 |
**SRS_X509_SCHANNEL_02_004: [** `x509_schannel_create` shall decode the private key by calling `CryptDecodeObjectEx`. **]** |
| 36 |
|
| 37 |
**SRS_X509_SCHANNEL_07_001: [** `x509_schannel_create` shall determine whether the certificate is of type RSA or ECC. **]** |
| 38 |
|
| 39 |
**SRS_X509_SCHANNEL_02_005: [** `x509_schannel_create` shall call `CryptAcquireContext`. **]** |
| 40 |
|
| 41 |
**SRS_X509_SCHANNEL_02_006: [** `x509_schannel_create` shall import the private key by calling `CryptImportKey`. **]** |
| 42 |
|
| 43 |
**SRS_X509_SCHANNEL_02_007: [** `x509_schannel_create` shall create a cerficate context by calling `CertCreateCertificateContext`. **]** |
| 44 |
|
| 45 |
**SRS_X509_SCHANNEL_02_008: [** `x509_schannel_create` shall call set the certificate private key by calling `CertSetCertificateContextProperty`. **]** |
| 46 |
|
| 47 |
**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. **]** |
| 48 |
|
| 49 |
**SRS_X509_SCHANNEL_02_010: [** Otherwise, `x509_schannel_create` shall fail and return a NULL X509_SCHANNEL_HANDLE. **]** |
| 50 |
|
| 51 |
|
| 52 |
### x509_schannel_destroy |
| 53 |
```c |
| 54 |
void x509_schannel_destroy(X509_SCHANNEL_HANDLE x509_schannel_handle) |
| 55 |
``` |
| 56 |
`x509_schannel_destroy` frees the system resources used by a `X509_SCHANNEL_HANDLE` |
| 57 |
|
| 58 |
**SRS_X509_SCHANNEL_02_011: [** If parameter `x509_schannel_handle` is NULL then `x509_schannel_destroy` shall do nothing. **]** |
| 59 |
|
| 60 |
**SRS_X509_SCHANNEL_02_012: [** Otherwise, `x509_schannel_destroy` shall free all used resources. **]** |
| 61 |
|
| 62 |
### x509_schannel_get_certificate_context |
| 63 |
```c |
| 64 |
PCCERT_CONTEXT x509_schannel_get_certificate_context(X509_SCHANNEL_HANDLE x509_schannel_handle) |
| 65 |
``` |
| 66 |
|
| 67 |
x509_schannel_get_certificate_context returns the constructed certificate context (PCCERT_CONTEXT) |
| 68 |
|
| 69 |
**SRS_X509_SCHANNEL_02_013: [** If parameter `x509_schannel_handle` is NULL then x509_schannel_get_certificate_context shall return NULL. **]** |
| 70 |
|
| 71 |
**SRS_X509_SCHANNEL_02_014: [** Otherwise, `x509_schannel_get_certificate_context` shall return a non-NULL PCCERT_CONTEXT pointer. **]** |