Add documentation for QUIC_CREDENTIAL_CONFIG (microsoft#1753)

docs/api/QUIC_CREDENTIAL_CONFIG.md

@@ -15,50 +15,162 @@ typedef struct QUIC_CREDENTIAL_CONFIG {
         QUIC_CERTIFICATE* CertificateContext;
         QUIC_CERTIFICATE_FILE* CertificateFile;
         QUIC_CERTIFICATE_FILE_PROTECTED* CertificateFileProtected;
+        QUIC_CERTIFICATE_PKCS12* CertificatePkcs12;
     };
     const char* Principal;
     void* Reserved; // Currently unused
     QUIC_CREDENTIAL_LOAD_COMPLETE_HANDLER AsyncHandler; // Optional
+    QUIC_ALLOWED_CIPHER_SUITE_FLAGS AllowedCipherSuites;// Optional
 } QUIC_CREDENTIAL_CONFIG;
 ```
 
 # Members
 
-`Type`
+#### `Type`
 
-TODO
+Indicates which type of credential is represented.
 
-`Flags`
+`QUIC_CREDENTIAL_TYPE_NONE`
 
-TODO
+Only valid for clients. No client authentication is provided.
 
-`CertificateHash`
+`QUIC_CREDENTIAL_TYPE_CERTIFICATE_HASH`
 
-TODO
+Search the Windows Current User (Local Machine for kernel mode) My certificate store for the certificate thumbprint pointed to by the `CertificateHash` member.
+Only valid on Windows with Schannel.
 
-`CertificateHashStore`
+`QUIC_CREDENTIAL_TYPE_CERTIFICATE_HASH_STORE`
 
-TODO
+Search the Windows Current User (Local Machine for kernel mode) certificate store for the provided store name and certificate thumbprint pointed to by the `CertificateHashStore` member.
+Only valid on Windows with Schannel.
 
-`CertificateContext`
+`QUIC_CREDENTIAL_TYPE_CERTIFICATE_CONTEXT`
 
-TODO
+Provide a Windows CAPI `CERTIFICATE_CONTEXT` with the certificate to use in the `CertificateContext` member.
+Only valid on Windows in user mode.
 
-`CertificateFile`
+`QUIC_CREDENTIAL_TYPE_CERTIFICATE_FILE`
 
-TODO
+Provide file paths to a private key file in PEM format, and a certificate file in PEM or CER format, pointed to by the `CertificateFile` member.
+Only valid for OpenSSL.
 
-`CertificateFileProtected`
+`QUIC_CREDENTIAL_TYPE_CERTIFICATE_FILE_PROTECTED`
 
-TODO
+Provide file paths to a protected private key file, and a certificate file, and a password to unprotect the private key, pointed to by the `CertificateFileProtected` member.
+Only valid for OpenSSL.
 
-`Principal`
+`QUIC_CREDENTIAL_TYPE_CERTIFICATE_PKCS12`
 
-TODO
+Provide an in-memory ASN.1 blob of a PKCS12 (PFX) certificate and private, with optional private key password, pointed to by the `CertificatePkcs12` member.
+Not currently supported.
 
-`AsyncHandler`
+#### `Flags`
 
-TODO
+Any combination of the following flags which change the credential behavior.
+
+`QUIC_CREDENTIAL_FLAG_NONE`
+
+Used with server in default configuration.
+
+`QUIC_CREDENTIAL_FLAG_CLIENT`
+
+Presence of this flag indicates this is a client. Absence indicates server.
+
+`QUIC_CREDENTIAL_FLAG_LOAD_ASYNCHRONOUS`
+
+Return `QUIC_STATUS_PENDING` immediately from [ConfigurationLoadCredential](ConfigurationLoadCredential.md) and load the credentials asynchronously. Completion is indicated via the `AsyncHandler` callback.
+
+`QUIC_CREDENTIAL_FLAG_NO_CERTIFICATE_VALIDATION`
+
+Indicate to the TLS layer that no server certificate validation is to be performed. **THIS IS DANGEROUS; DO NOT USE IN PRODUCTION**
+
+`QUIC_CREDENTIAL_FLAG_ENABLE_OCSP`
+
+Enable OCSP stapling for this connection. Only valid for Schannel.
+
+`QUIC_CREDENTIAL_FLAG_INDICATE_CERTIFICATE_RECEIVED`
+
+Receive `QUIC_CONNECTION_EVENT_PEER_CERTIFICATE_RECEIVED` events when a certificate is received from the peer (client or server).
+
+`QUIC_CREDENTIAL_FLAG_DEFER_CERTIFICATE_VALIDATION`
+
+Request the TLS layer perform validation on the received certificate, and provide results to the application via `QUIC_CONNECTION_EVENT_PEER_CERTIFICATE_RECEIVED` events, and allow the application to override failed validation.
+Only supported by Schannel. Requires `QUIC_CREDENTIAL_FLAG_INDICATE_CERTIFICATE_RECEIVED` to also be set.
+
+`QUIC_CREDENTIAL_FLAG_REQUIRE_CLIENT_AUTHENTICATION`
+
+Require clients to provide authentication for the handshake to succeed.
+Not supported on client.
+
+`QUIC_CREDENTIAL_FLAG_USE_TLS_BUILTIN_CERTIFICATE_VALIDATION`
+
+Use the built-in TLS library's certificate validation instead of the platform's certificate validation.
+This is enabled by default on non-Windows systems, and only has effect on Windows when OpenSSL is used.
+
+`QUIC_CREDENTIAL_FLAG_REVOCATION_CHECK_END_CERT`
+
+Only check the leaf certificate for revocation. Only valid on Windows.
+
+`QUIC_CREDENTIAL_FLAG_REVOCATION_CHECK_CHAIN`
+
+Check every certificate in the chain for revocation. Only valid on Windows.
+
+`QUIC_CREDENTIAL_FLAG_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT`
+
+Check every certificate in the chain, except the root, for revocation. Only valid on Windows.
+
+`QUIC_CREDENTIAL_FLAG_IGNORE_NO_REVOCATION_CHECK`
+
+Ignore errors from no revocation check being performed. Only valid on Windows.
+
+`QUIC_CREDENTIAL_FLAG_IGNORE_REVOCATION_OFFLINE`
+
+Ignore revocation offline failures. Only valid on Windows.
+
+`QUIC_CREDENTIAL_FLAG_SET_ALLOWED_CIPHER_SUITES`
+
+Enables which cipher suites are available for negotiation via the `AllowedCipherSuites` member.
+
+`QUIC_CREDENTIAL_FLAGS_USE_PORTABLE_CERTIFICATES`
+
+Provide the entire certificate chain to the application as a PKCS7 binary blob in the `QUIC_CONNECTION_EVENT_PEER_CERTIFICATE_RECEIVED` event.
+Only supported by OpenSSL.
+
+#### `CertificateHash`
+
+Must **only** use with `QUIC_CREDENTIAL_TYPE_CERTIFICATE_HASH` type.
+
+#### `CertificateHashStore`
+
+Must **only** use with `QUIC_CREDENTIAL_TYPE_CERTIFICATE_HASH_STORE` type.
+
+#### `CertificateContext`
+
+Must **only** use with `QUIC_CREDENTIAL_TYPE_CERTIFICATE_CONTEXT` type.
+
+#### `CertificateFile`
+
+Must **only** use with `QUIC_CREDENTIAL_TYPE_CERTIFICATE_FILE` type.
+
+#### `CertificateFileProtected`
+
+Must **only** use with `QUIC_CREDENTIAL_TYPE_CERTIFICATE_FILE_PROTECTED` type.
+
+#### `CertificatePkcs12`
+
+Must **only** use with `QUIC_CREDENTIAL_TYPE_CERTIFICATE_PKCS12` type.
+
+#### `Principal`
+
+Principal name string to select certificate by the principal name. Only supported by Schannel.
+
+#### `AsyncHandler`
+
+Optional callback to receive completion of asynchronous credential load. Only used with `QUIC_CREDENTIAL_FLAG_LOAD_ASYNCHRONOUS` flag.
+
+#### `AllowedCipherSuites`
+
+A set of flags indicating which cipher suites are available to negotiate. Must be used with `QUIC_CREDENTIAL_FLAG_SET_ALLOWED_CIPHER_SUITES`.
 
 # Remarks