| |
The SECURITYINFO structure contains security related information
about the connection, including the protocol, cipher suite and certificate.
typedef struct _SECURITYINFO
{
DWORD dwSize;
DWORD dwProtocol;
DWORD dwCipher;
DWORD dwCipherStrength;
DWORD dwHash;
DWORD dwHashStrength;
DWORD dwKeyExchange;
DWORD dwCertStatus;
SYSTEMTIME stCertIssued;
SYSTEMTIME stCertExpires;
LPCTSTR lpszCertIssuer;
LPCTSTR lpszCertSubject;
LPCTSTR lpszFingerprint;
} SECURITYINFO, *LPSECURITYINFO;
Members
- dwSize
- Specifies the size of the data structure. This member must
always be initialized to the size of the structure in bytes prior
to passing the address of this structure to the function. If this
this member is not initialized, an error will be returned
indicating that an invalid parameter has been passed to the
function.
- dwProtocol
- A numeric value which specifies the security protocol selected
when establishing the connection.
| Value |
Description |
| SECURITY_PROTOCOL_NONE |
The connection is not secure. This value indicates a
standard connection was established and all other structure
members will have a value of zero. |
| SECURITY_PROTOCOL_TLS10 |
The TLS 1.0 protocol was selected when establishing a
secure connection. This version is supported on all Windows
platforms, however some servers may reject connections using
version 1.0 in favor of using version 1.2. This version should
only be used for backwards compatibility with older servers that
have not been updated to use the current version of TLS. |
| SECURITY_PROTOCOL_TLS11 |
The TLS 1.1 protocol was selected when establishing a
secure connection. This version is supported on Windows 7 and
later desktop platforms, and Windows Server 2008 R2 and later
server platforms. Some servers may reject connections using
version 1.1 in favor of using version 1.2. This version should
only be used for backwards compatibility with older servers that
have not been updated to use the current version of TLS. |
| SECURITY_PROTOCOL_TLS12 |
The TLS 1.2 protocol was selected when establishing a
secure connection. This version is supported on Windows 7 and
later desktop platforms, and Windows Server 2008 R2 and later
server platforms. This version of TLS offers the broadest
compatibility with most servers. |
| SECURITY_PROTOCOL_TLS13 |
The TLS 1.3 protocol was selected when establishing a
secure connection. This is the newest version of the protocol
and is only supported on Windows 11, Windows Server 2022 and
later versions of Windows. If this version is not supported
by the operating system, TLS 1.2 will be used instead. |
- dwCipher
- A numeric value which specifies the cipher that was selected
when establishing the secure connection.
| Value |
Description |
| SECURITY_CIPHER_AES |
The Advanced Encryption Standard cipher is a fixed block
size cipher which use a key size of 128, 192 or 256 bits. |
| SECURITY_CIPHER_DES |
The Data Encryption Standard block cipher was
selected. This is a fixed key length cipher, using 56-bit
keys. |
| SECURITY_CIPHER_DES3 |
The Triple DES block cipher was selected. This cipher
encrypts the data three times using different keys, effectively
providing a 168-bit length key. |
| SECURITY_CIPHER_DESX |
A variant of the DES block cipher which XORs an extra
64-bits of the key before and after the plaintext has been
encrypted, increasing the key size to 184 bits. |
| SECURITY_CIPHER_RC4 |
The RC4 stream cipher was selected. This is a variable key
length cipher which supports keys between 40 and 128 bits, in
8-bit increments. |
| SECURITY_CIPHER_RC5 |
The RC5 block cipher was selected. This is a variable key
length cipher which supports keys up to 2040 bits, in 8-bit
increments. |
- dwCipherStrength
- A numeric value which specifies the strength (the length of the
cipher key in bits) of the cipher that was selected. Typically this
value will be 128 or 256. 40-bit and 56-bit key lengths are considered
weak encryption, and subject to brute force attacks. 128-bit and
256-bit key lengths are considered to be secure, and are the recommended
key length for secure communications.
- dwHash
- A numeric value which specifies the hash algorithm which was selected.
| Value |
Description |
| SECURITY_HASH_MD5 |
The MD5 algorithm was selected. Its use has been deprecated
and is no longer considered to be cryptographically secure. |
| SECURITY_HASH_SHA1 |
The SHA-1 algorithm was selected. Its use has been deprecated
and is no longer considered to be cryptographically secure. |
| SECURITY_HASH_SHA256 |
The SHA-256 algorithm was selected. |
| SECURITY_HASH_SHA384 |
The SHA-384 algorithm was selected. |
| SECURITY_HASH_SHA512 |
The SHA-512 algorithm was selected. |
- dwHashStrength
- A numeric value which specifies the strength (the length in
bits) of the message digest that was selected.
- dwKeyExchange
- A numeric value which specifies the key exchange algorithm which
was selected.
| Value |
Description |
| SECURITY_KEYEX_RSA |
The RSA public key algorithm was selected. |
| SECURITY_KEYEX_KEA |
The Key Exchange Algorithm (KEA) was selected. This is an
improved version of the Diffie-Hellman public key algorithm. |
| SECURITY_KEYEX_DH |
The Diffie-Hellman key exchange algorithm was selected. |
| SECURITY_KEYEX_ECDH |
The Elliptic Curve Diffie-Hellman key exchange algorithm
was selected. This is a variant of the Diffie-Hellman algorithm
which uses elliptic curve cryptography. |
- dwCertStatus
- A numeric value which specifies the status of the certificate
returned by the secure server.
| Value |
Description |
| SECURITY_CERTIFICATE_VALID |
The certificate is valid. |
| SECURITY_CERTIFICATE_NOMATCH |
The certificate is valid, but the domain name does not
match the common name in the certificate. |
| SECURITY_CERTIFICATE_EXPIRED |
The certificate is valid, but has expired. |
| SECURITY_CERTIFICATE_REVOKED |
The certificate has been revoked and is no longer
valid. |
| SECURITY_CERTIFICATE_UNTRUSTED |
The certificate or certificate authority is not trusted on
the local system. |
| SECURITY_CERTIFICATE_INVALID |
The certificate is invalid. This typically indicates that
the internal structure of the certificate has been
damaged. |
- stCertIssued
- A structure which contains the date and time that the
certificate was issued by the certificate authority. If the issue
date cannot be determined for the certificate, the SYSTEMTIME
structure members will have zero values.
- stCertExpires
- A structure which contains the date and time that the
certificate expires. If the expiration date cannot be determined for
the certificate, the SYSTEMTIME structure members will have zero
values.
- lpszCertIssuer
- A pointer to a string which contains information about the
organization that issued the certificate. This string consists of
one or more comma-separated tokens. Each token consists of an
identifier, followed by an equal sign and a value. If the
certificate issuer could not be determined, this member may be NULL.
- lpszCertSubject
- A pointer to a string which contains information about the
organization that the certificate was issued to. This string
consists of one or more comma-separated tokens. Each token consists
of an identifier, followed by an equal sign and a value. If the
certificate subject could not be determined, this member may be
NULL.
- lpszFingerprint
- A pointer to a string which contains a sequence of hexadecimal
values that uniquely identify the server. This member may be NULL.
Remarks
The size of this structure is typically determined using the
sizeof operator in C/C++ and most other languages have a similar
method for obtaining the size of a data structure or user-defined type.
It is important to note the size of this structure will be different on
32-bit and 64-bit platforms due to the difference in the length of the
structure members which are pointers.
When evaluating structure members which are string pointers, such as
lpszCertIssuer and lpszCertSubject, you should always
check to ensure their values are not NULL (zero) before attempting to
dereference them. If those values are undefined, it is not guaranteed
they will point to zero-length strings.
There are additional protocols and ciphers defined which are not
listed above because they are considered insecure and are no longer
supported. It is important to note that most servers will reject
attempts to use unsupported protocols such as SSL 3.0 and will either
abort the connection or issue an error message and then immediately
disconnect.
Requirements
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Unicode: Implemented as Unicode and ANSI versions
|
|