|
|
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_NONE |
No security protocol has been
selected. A secure connection has not been established with the
server. The remaining member values in this structure are not valid
and should be ignored. |
| SECURITY_PROTOCOL_SSL2 |
The Secure Sockets Layer (SSL)
version 2.0 protocol has been selected. Note that this protocol has
been deprecated and is no longer widely used. It is not recommended
that this protocol be used when establishing secure
connections. |
| SECURITY_PROTOCOL_SSL3 |
The Secure Sockets Layer (SSL)
version 3.0 protocol has been selected. This version of the
protocol, and version 1.0 of the Transport Layer Security (TLS)
protocol, are the most commonly used security protocols. |
| SECURITY_PROTOCOL_TLS1 |
The Transport Layer Security (TLS)
version 1.0 protocol has been selected. This version of the
protocol, and version 3.0 of the Secure Sockets Layer (SSL)
protocol, are the most commonly used security protocols. Note that
some servers require that the client specify TLS-1 as the only
security protocol, or they may reject the connection. |
| 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 Vista 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 40, 56 or 128. 40-bit key lengths are considered weak
encryption, and subject to brute force attacks. 56-bit key lengths
are considered to be moderately secure. 128-bit key lengths are
considered to be very secure, and is 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.
This algorithm takes a message of arbitrary length and produces a
128-bit message digest. |
| SECURITY_HASH_SHA |
The Secure Hash Algorithm (SHA)
was selected. This algorithm produces a 160-bit message
digest. |
- 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 Vista 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
- The address of a pointer to a null-terminated 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
- The address of a pointer to a null-terminated 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
- The address of a pointer to a null-terminated string which
contains a sequence of hexadecimal values that uniquely identify
the remote host. This member is only used when a connection has
been established using the Secure Shell (SSH) protocol.
Requirements
Client: Requires Windows 7, Windows Vista, Windows XP or
Windows 2000 Professional.
Server: Requires Windows Server 2008, Windows Server 2003 or
Windows 2000 Server.
Header: Include cswsock6.h.
Unicode: Implemented as Unicode and ANSI versions.
|
|