Checking the Security Properties of a Connection

16.1 Checking the Security Properties of a Connection

The device and the server negotiate the secure connection parameters based on mutually agreeable secure suites. After the connection has been established, the application can retrieve a SecurityInfo object and verify the integrity and server credentials of a negotiated connection. A MIDlet using an HTTPS or secure connection gets the object by calling the getSecurityInfo method on the open connection. If the MIDlet's connection is not secure enough, it can report an error and close the connection.

The application can use the SecurityInfo object to get the protocol name, protocol version, cipher suite, and certificate for a secure network connection. Figure lists the names and versions of the protocols available by calling the getProtocolName and getProtocolVersion methods of the SecurityInfo interface.

The getCipherSuite method of the SecurityInfo interface returns the name of the cipher suite used for the connection. The name is usually one of the standard ciphers listed in the CipherSuite column of the CipherSuite definitions table in Appendix C of RFC 2246 [reference 4]. Non-TLS implementations should select the cipher suite name according to the key exchange, cipher, and hash combination used to establish the connection. This will ensure that equivalent cipher suites have the same name regardless of protocol. If the getCipherSuite method returns a non-null name that is not in Appendix C of RFC 2246 [reference 4], the cipher suite's contents are specific to the device and server.

1 Server Certificate

An application calls the getServerCertificate method of the SecurityInfo object to get the server's certificate. A Certificate object contains a subject, issuer, type, version, serial number, signing algorithm, dates of valid use, and serial number.

The subject is the entity that vouches for the identity of the server; the issuer is the distinguished name of the entity that vouches for the identity of the subject. An application gets the subject from the getSubject method of the Certificate object and the issuer from the getIssuer method. The getIssuer method never returns null. The subject and issuer strings are formatted using the rules for the printable representation for X.509 distinguished names given in Section 16.1.2, "Printable Representation for X.509 Distinguished Names."

The type and version of the certificate are returned by the getType and getVersion methods of the Certificate object. The format of the version number depends on the specific type and specification, but is never null. For X.509 certificates, the value returned is X.509, and the version, per RFC 2459 [reference 7], is 2.

The application gets the name of the algorithm used to sign the certificate from the getSigAlgName method of the Certificate object. The algorithm names returned should be one of the labels defined in RFC 2459, Section 7.2 [reference 7]. For example, md5WithRSAEncryption is a valid return value.

The getSerialNumber method returns the printable form of the serial number of this Certificate or null if there is no serial number. A binary serial number should be formatted as a string using the binary-printable representation: a colon-separated list of bytes in which each byte is represented by two hex digits (capital letters for A–F). For example, "0C:56:FA:80" is in binary-printable representation.

Each X.509 certificate is valid for only a specified period of time. The getNotBefore method of the Certificate object returns the time before which the certificate may not be used. The time is the milliseconds before which the certificate is not valid; the value zero means the certificate does not have its validity restricted by time. The getNotAfter method is the time after which the certificate is not valid. The time is the milliseconds after which the certificate is not valid (the expiration date); Long.MAX_VALUE is returned if the certificate does not have its validity restricted by time. Both times must be positive.

2 Printable Representation for X.509 Distinguished Names

The distinguished name (DN) for an X.509 certificate is a semicolon-separated list of attributes. Each attribute has an object ID (represented by a label or a binary-printable representation) and a value. Figure lists common attributes and their labels. For example, "C=US;O=Any Company, Inc.;CN=www.anycompany.com" is a DN.

For string comparison purposes, the following rules define a strict printable representation that can be used for literal comparisons of distinguished names.

Any non-string value is formatted as a string using the binary-printable representation described in Section 16.1.1, "Server Certificate."