| |
This structure contains information about a secure connection that
has been established with a server.
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 sizeof(SECURITYINFO) prior to
passing the address of this structure to the function. Note that if
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 protocol that was selected
to establish the secure connection. One of the following values
will be returned:
| Constant |
Description |
| SECURITY_PROTOCOL_DEFAULT |
The default security protocol will be used when establishing
a connection. This option will always request the latest version
of the preferred security protocol and is the recommended
value. Currently the default security protocol is TLS 1.2. |
| SECURITY_PROTOCOL_SSL |
Either SSL 2.0 or SSL 3.0 should be used when establishing
a secure connection. The correct protocol is automatically
selected, based on what version of the protocol is supported by
the server. If this is the only protocol specified, TLS will be
excluded from the list of supported protocols. Both SSL 2.0
and 3.0 have been deprecated and will never be used unless
explicitly specified. It is not recommended that you enable
either of these protocols for secure connections because it will
cause most servers to reject your connection request, even if a
version of TLS is also specified. |
| SECURITY_PROTOCOL_TLS |
Either the TLS 1.0, 1.1 or 1.2 protocol should be used when
establishing a secure connection. The correct protocol is
automatically selected, based on what version of the protocol is
supported by the server. If this is the only protocol specified,
SSL will be excluded from the list of supported protocols. This
may be necessary for some servers that reject any attempt to use
the older SSL protocol and require that only TLS be used. |
| SECURITY_PROTOCOL_TLS10 |
The TLS 1.0 protocol should be used 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 should be used 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 should be used 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 is the recommended version of TLS to use
with secure connections. |
| SECURITY_PROTOCOL_SSH1 |
The Secure Shell 1.0 protocol has been selected. This
protocol has been deprecated and is no longer widely used. It
is not recommended that this protocol be used when establishing
secure connections. This protocol can only be specified when
connecting to an SSH server and is not supported with any other
application protocol. |
| SECURITY_PROTOCOL_SSH2 |
The Secure Shell 2.0 protocol has been selected. This is
the most commonly used version of the protocol. It is
recommended that this version of the protocol be used unless
the server explicitly requires the client to use an earlier
version. This protocol can only be specified when connecting to
an SSH server and is not supported with any other application
protocol. |
- dwCipher
- A numeric value which specifies the cipher that was selected
when establishing the secure connection. One of the following
values will be returned:
| Constant |
Description |
| SECURITY_CIPHER_RC2 |
The RC2 block cipher was selected. This is a variable key
length cipher which supports keys between 40 and 128 bits, in
8-bit increments. |
| 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. |
| SECURITY_CIPHER_DES |
The DES (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_AES |
The Advanced Encryption Standard cipher (also known as the
Rijndael cipher) is a fixed block size cipher which use a key
size of 128, 192 or 256 bits. This cipher is supported on
Windows XP SP3 and later versions of the operating system. |
| SECURITY_CIPHER_SKIPJACK |
The Skipjack block cipher was selected. This is a fixed key
length cipher, using 80-bit keys. |
| SECURITY_CIPHER_BLOWFISH |
The Blowfish block cipher was selected. This is a variable
key length cipher up to 448 bits, using a 64-bit block
size. |
- 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. One of the following values will be returned:
| Constant |
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. One of the following values will be
returned:
| Constant |
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. This key exchange
algorithm is only supported on Windows XP SP3 and later
versions of the operating system. |
- dwCertStatus
- A numeric value which specifies the status of the certificate
returned by the secure server. This member only has meaning for
connections using the SSL or TLS protocols. One of the following
values will be returned:
| Constant |
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. This member only has
meaning for connections using the SSL or TLS protocols.
- 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. This member only has meaning for connections using the
SSL or TLS protocols.
- 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. This member only has meaning
for connections using the SSL or TLS protocols.
- 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. This member only has meaning
for connections using the SSL or TLS protocols.
- lpszFingerprint
- A pointer to a string which
contains a sequence of hexadecimal values that uniquely identify
the server. This member is only used when a connection has
been established using the Secure Shell (SSH) protocol.
Requirements
Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cstools10.h
Unicode: Implemented as Unicode and ANSI versions.
|
|