1 /** |
|
2 |
|
3 @page overview_WTLS WTLS |
|
4 \n |
|
5 |
|
6 @section WTLS_component_overview WTLS Certificate Management component overview |
|
7 |
|
8 The WTLS component provides support for validating WTLS certificate chains. |
|
9 WTLS certificates are used for server authentication in the @ref protocol_WTLS "WTLS protocol". |
|
10 |
|
11 WTLS certificate management is implemented as a single DLL, \c WTLSCert.DLL. This includes an implementation of the WTLS |
|
12 certificate class and its components, and an implementation of the WTLS certificate validation algorithm. |
|
13 |
|
14 Symbian OS supports only @ref WTLS_server_authentication "WTLS server authentication" (class 2), which involves parsing, |
|
15 validating and storing WTLS certificates. |
|
16 The WTLS Certificate Management component only offers support for the validation of chains composed exclusively of |
|
17 WTLS certificates. The component offers the following functionality for processing WTLS certificates: |
|
18 |
|
19 @li ability to parse a set of WTLS certificates, sent from the server, from their binary encoded form into a form in which |
|
20 they are useful, and in which client code can extract interesting information (e.g. name information) |
|
21 |
|
22 @li use of these certificates to construct a chain back to a locally stored trusted @ref root_certificate "root certificate" |
|
23 |
|
24 @li validation of this certificate chain; this includes verifying the signature and validity dates on each @ref certificate. |
|
25 |
|
26 <hr> |
|
27 |
|
28 @section WTLS_certificate WTLS certificate |
|
29 |
|
30 @section basic_data_structures Basic data structures |
|
31 |
|
32 The following classes derive from their counterparts in \c Crypto.DLL, and add only a set of constructors for construction |
|
33 from encoded binary data: |
|
34 @li \c CWTLSValidityPeriod: derived from \c CValidityPeriod |
|
35 @li \c CWTLSAlgorithmIdentifier: derived from \c CAlgorithmIdentifier |
|
36 @li \c CWTLSSigningAlgorithmIdentifier: derived from \c CSigningAlgorithmIdentifier |
|
37 @li \c CWTLSSubjectPublicKeyInfo: derived from \c CSubjectPublicKeyInfo |
|
38 @li \c CWTLSRSAPublicKey: derived from \c CRSAPublicKey |
|
39 |
|
40 Classes representing public keys are derived from the corresponding classes in \c cryptalg.h and add only a set of |
|
41 constructors for construction from encoded binary data. The WTLS Certificate Management component only offers support for |
|
42 RSA asymmetric algorithms (and RSA with SHA-1). |
|
43 |
|
44 @section name_forms Name forms |
|
45 |
|
46 The name forms/identifiers supported are: text strings (Latin-1 and Unicode), and X.500 Distinguished Names. |
|
47 The WTLS name is implemented in the \c CWTLSName class and stores the type of the underlying name (as a value for the |
|
48 \c TWTLSNameType enumeration, accessible through the \c CWTLSName::NameType() function) and the encoding of the underlying type |
|
49 (accessible as a pointer descriptor through the \c CWTLSName::NameData() function). The \c CWTLSName class also provides a function |
|
50 to do matching, \c CWTLSName::ExactMatchL(), which returns a boolean value. This function is needed for constructing/validating |
|
51 certificate chains and performs a simple byte comparison of the name forms. |
|
52 |
|
53 @section text_type Text type |
|
54 |
|
55 The \c CWTLSText class is provided to represent the text type, and can be constructed from encoded binary data. It provides |
|
56 the function, \c CWTLSText::CharacterSet(), for accessing the character set, which in turn is an integer representing the IANA designated |
|
57 number for the character set. The text can be retreived using the \c CWTLSText::Name() function. \c CWTLSText also provides the function, |
|
58 \c CWTLSText::ExactMatchL(), for matching, for which two strings that are the same, but represented in different character sets, |
|
59 should match. This differs from \c CWTLSName::ExactMatchL() for which the same two strings would not match as the bytes |
|
60 would be different. |
|
61 |
|
62 @section structured_text_type Structured text type |
|
63 |
|
64 Structured text types are represented by a subclass of \c CWTLSText called \c CWTLSStructuredText. For this type, the name |
|
65 is parsed into a set of fields. Accessors are provided for the mandatory fields: \c CWTLSStructuredText::ServiceName(), \c CWTLSStructuredText::Organization(), |
|
66 \c CWTLSStructuredText::Country(). Optional fields are represented by the \c TWTLSStructuredTextField class. This provides two accessors, |
|
67 \c TWTLSStructuredTextField::Type() and \c TWTLSStructuredTextField::Value(), to return the type of the field (this is the part of the field text on the left hand side of the |
|
68 assignment operator in the name) and its value. To access the optional fields in \c CWTLSStructuredText, functions are |
|
69 provided to return the number of fields, \c CWTLSStructuredText::Count(), and to return a particular field by its index, \c CWTLSStructuredText::FieldByIndex(). It |
|
70 is also possible to access a field value by its type using the \c CWTLSStructuredText::FieldByName() function, giving as a parameter the type of |
|
71 the desired field. This function returns a pointer because the field may not be present, in which case the return value is |
|
72 \c NULL. However, the field returned remains the property of \c CWTLSStructuredText, so calling code should not destroy it. |
|
73 |
|
74 |
|
75 @section CWTLSCertificate_class CWTLSCertificate class |
|
76 |
|
77 The \c CWTLSCertificate class is a subclass of \c CCertificate. It offers eight differing \c CWTLSCertificate::NewL()/NewLC() functions that |
|
78 allow class construction from encoded binary form, streams, or from the @ref WTLS_certificate_storage "certificate store". |
|
79 The \c CWTLSCertificate::IsEqualL() function tests whether two certificates are equal, which is not a simple as it sounds. |
|
80 For @ref X509_certificate "X.509 certificates", equality means that the issuer name and serial number fields are the same. |
|
81 This guarantees equality since a @ref CA "Certification Authority" (CA) must ensure that every certificate it issues has a |
|
82 unique serial number. But WTLS certificates do not include serial numbers, so there seems to be no definition of equality. |
|
83 The equality operator here will use a byte-for-byte comparison of the signatures on the certificates: this should not |
|
84 result in any false positives, but may give false negatives if CAs do naughty things like recertifying the same key (which |
|
85 they have been known to do). |
|
86 |
|
87 The functions \c CWTLSCertificate::IssuerName() and \c CWTLSCertificate::SubjectName() return the certificate's issuer and subject names, respectively, as |
|
88 @ref name_forms "WTLSName objects". If the certificate is an X.509 certificate, then if the name contains a Common name, |
|
89 that will be returned; otherwise, if the name contains an Organization name, that will be returned. Otherwise, an empty |
|
90 string will be returned. If the certificate is a WTLS certificate, then if the name is an X.500 @ref DN then the same rules |
|
91 will apply as for X.509 certificates. If the name is null, an empty string will be returned. If the name is of type text, |
|
92 then if the name is not a 'structured' name, the entire string will be returned; otherwise, the same procedure will be |
|
93 followed as for X.509 certificates. |
|
94 |
|
95 The \c CWTLSCertificate::ExternalizeL() function externalises the certificate to a stream. This should not be used if client code is using |
|
96 certstore. The \c CWTLSCertificate::InternalizeL() function initialises the certificate from a stream. This should not be called by client |
|
97 code; instead one of the \c CWTLSCertificate::NewL()/NewLC() static factory functions above should be used. If a client is using the |
|
98 certstore component for storage then it should use \c MCTWritableCertStore::AddL() for externalising and |
|
99 \c CWTLSCert::NewL(CCertStore& aStore, const CCertStoreEntry& aEntry) for restoring. The \c CWTLSCertificate::IsTCAL() |
|
100 function tests whether the certificate is capable of signing other certificates. Currently, this only supports structured |
|
101 text variety of WTLS certificates; other certificate types will return \c EFalse. |
|
102 |
|
103 |
|
104 |
|
105 <hr> |
|
106 |
|
107 @section WTLS_certificate_processing WTLS Certificate processing |
|
108 |
|
109 This specifies how the certificates are used for authentication: that is, how a collection of certificates is made |
|
110 into a chain terminating at a trusted root, and how that chain is then validated. |
|
111 |
|
112 The following inputs need to be supplied to the validation process: |
|
113 @li the time for which validation is to be performed |
|
114 @li a set of one or more encoded WTLS certificates sent from the server |
|
115 @li some way of indicating where to find trusted roots to complete the chain. |
|
116 |
|
117 For WTLS, the server is expected to supply an ordered collection of certificates; that is, the first certificate should be |
|
118 the server's own certificate, each subsequent certificate should certify the one immediately preceding it in the chain. |
|
119 Some checks are run on the chain in advance of validation to limit the number of requests made to the |
|
120 @ref WTLS_certificate_storage "certificate store". In particular, the chain is checked to ensure that each parent |
|
121 certificate has the authority to sign subsequent child certificates. Additionally, the chain is scanned for the earliest |
|
122 certificate in the chain that may already be declared to be trusted by the user, therefore cutting down on both retrieval |
|
123 and validation time. Finally, if no trusted certificate can be found within the given chain, a search of the local store |
|
124 is made to see whether any trusted certificates exist that can complete and validate the chain. |
|
125 |
|
126 To work around the absence of a means within the WTLS certificate data structure for a @ref CA to indicate whether the |
|
127 entity it is certifying is a CA or an @ref EE "End Entity" (EE), the maximum length of a WTLS certificate chain will be 2: |
|
128 that is, there may be no intermediate CAs. |
|
129 |
|
130 The result is a @ref CWTLSValidationResult_class object indicating the success or failure of the operation, with a reason |
|
131 for failure if appropriate and an integer indicating which certificate in the chain was bad, if appropriate. It is possible |
|
132 for client code to iterate through the certificates in the chain to retrieve and examine them. |
|
133 |
|
134 Client code uses the \c CWTLSCertificate class to do actual validation, using a set of one or more certificates supplied by a |
|
135 server and a local store of trusted root certificates. It uses two public classes, \c CWTLSCertChain and |
|
136 \c CWTLSValidationResult. |
|
137 |
|
138 @section CWTLSCertChain_class CWTLSCertChain |
|
139 |
|
140 Validation consists of constructing a chain from a set of one or more certificates supplied by the client, a set of trusted |
|
141 root certificates, and a time for which validation is to be performed. Each subsequent certificate must directly certify |
|
142 the preceding one. The chain object will attempt to construct a valid chain ending in a trusted root from the encoded |
|
143 certificates supplied by the server and the set of trusted roots. |
|
144 |
|
145 The chain supplied by the client is limited only by memory considerations. However, a check of the proposed chain is done |
|
146 to attempt to validate the shortest chain possible. For example, if the client supplied 15 certificates, but the third |
|
147 certificate is marked as trusted in the @ref WTLS_certificate_storage "certificate store", then validation will proceed |
|
148 with only the first three certificates. The remaining 12 certificates are discarded and are no longer part of the chain. |
|
149 |
|
150 Validating the chain consists in ensuring that: |
|
151 @li the issuer name for each certificate is the same as the subject name on the next certificate in the chain: this is |
|
152 really guaranteed in the construction process |
|
153 @li every certificate is within its validity period for the time specified |
|
154 @li the signature on each certificate is valid |
|
155 @li all non-self-signed CA certificates contain the appropriate values within the certificate allowing them to sign child |
|
156 certificates. In the case of @ref structured_text_type "WTLS structured text certificates", this is indicated by the |
|
157 presence of the extension field \c "T=ca" in the subject, where \c T stands for WTLS title. |
|
158 |
|
159 This class may be constructed in one of two ways: |
|
160 |
|
161 |
|
162 @li @code IMPORT_C static CWTLSCertChain* NewL(RFs& aFs, const TPtrC8& aEncodedCerts, const TUid aClient); @endcode |
|
163 Here, the first parameter is an open file server session, the second is a single descriptor containing a simple |
|
164 concatenation of one or more encoded WTLS certificates. The third parameter is a UID identifying the client for whom |
|
165 validation is being performed. With this version of the function the certstore is used to find candidate root |
|
166 certificates; only certificates in the store which are trusted by that client will be considered as valid. |
|
167 |
|
168 @li @code IMPORT_C static CWTLSCertChain* NewL(RFs& aFs, const TPtrC8& aEncodedCerts, const CArrayPtr<CWTLSCertificate>& aRootCerts); @endcode |
|
169 The only difference here is that rather than using the certstore for root certificates, the client supplies a |
|
170 collection of WTLS certificates which may be considered candidate roots for the validation process. This version should |
|
171 be used when clients do not want to use the certificate store provided (for example, an application may require that a |
|
172 certificate chain can only be completed by a certificate found on the device's WIM). Because they're not using the |
|
173 certificate store clients don't have to supply a UID. |
|
174 |
|
175 The \c CWTLSCertChain::ValidateL() function actually does the validation and takes a single parameter, which is the time for which |
|
176 validation should be performed. Clients can find the number of certificates in the chain using the \c CWTLSCertChain::Count() function, and |
|
177 retrieve individual certificates using the \c CWTLSCertChain::Cert() function. It should be noted that both of these functions return |
|
178 undefined values after the call to \c CWTLSCertChain::ValidateL() and until the completion of the associated active object. This is because |
|
179 the validation procedure potentially optimises the chain handed to it and thus the chain can change after validation. |
|
180 In summary: |
|
181 @li Before calling \c CWTLSCertChain::ValidateL(), these functions return values consistent with the certificates that have been added to |
|
182 the chain. |
|
183 @li During the execution of the active object, these return undefined values. |
|
184 @li After the completion of the active object, these functions return values consistent with the chain that was actually |
|
185 used for validation. These values may or may not be same as before the call to \c CWTLSCertChain::ValidateL(). |
|
186 |
|
187 The \c CWTLSCertChain::AppendCertsL() function can be used to append one or more encoded certificates to the certificate chain. |
|
188 |
|
189 |
|
190 @section CWTLSValidationResult_class CWTLSValidationResult |
|
191 |
|
192 The \c CWTLSValidationResult object encapsulates the result of the validation operation. The \c CWTLSValidationResult::Error() function returns |
|
193 the error status for the chain. Any errors here are considered fatal: validation has failed. The \c CWTLSValidationResult::Warnings() function |
|
194 returns an array of any warnings generated: these may or may not be fatal, depending on the context, which the client is |
|
195 expected to provide. |
|
196 |
|
197 |
|
198 Class \c TWTLSValidationStatus contains the following public data: \c iReason, and \c iCert. |
|
199 The reason for the error is given by \c iReason, while \c iCert gives the index number for the certificate that gave rise |
|
200 to the error. Some errors cannot be blamed on any single certificate, in which case the \c iCert value is meaningless. The |
|
201 same structure is used for errors and for warnings. |
|
202 |
|
203 The following errors are defined in the \c TValidationError enumeration: |
|
204 @li \c EChainHasNoRoot: it was not possible to find a trusted root to complete the chain; the \c iCert variable is |
|
205 meaningless. |
|
206 @li \c ESignatureInvalid: signature verification failed; the \c iCert variable is set to the position in the chain of the |
|
207 certificate whose signature failed to verify. |
|
208 @li \c EDateOutOfRange: the date supplied to the validation algorithm lay outside the validity period for one of the |
|
209 certificates; the \c iCert variable is set to the position in the chain of the certificate whose validity period did |
|
210 not include the supplied time. |
|
211 |
|
212 <hr> |
|
213 |
|
214 @section WTLS_certificate_storage Certificate storage |
|
215 |
|
216 Certificate management already provides a means for applications to store certificates, retrieve them from storage, and |
|
217 mark them as trusted or untrusted for various applications. It currently does this using a kind of registration scheme |
|
218 where users of certificate-based authentication supply a UID to the certificate store, and users can edit the certificates |
|
219 associated with each UID through a control panel application. When they require validation they supply the UID to the |
|
220 validation component, which uses this to select a set of those certificates in the store that may be considered trust roots |
|
221 for this application. |
|
222 |
|
223 */ |
|