JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.
If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.
If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.
| CodeSonar® 9.2p0 | CONFIDENTIAL | CodeSecure Inc |
CodeSonar supports the use of TLS certificates for authentication.
Note that it is not possible to use certificate-based hub authentication in the presence of a proxy or reverse proxy.
CodeSonar makes use of TLS certificates for various authentication and security purposes. The certificates satisfy the requirements for TLS, X.509, and ASN.1. Certificates (and associated keys where applicable) are downloaded and uploaded in PEM encoding.
TLS certificates have several uses within CodeSonar.
| Usage | Purpose |
|---|---|
| Hub Server Certificate | The certificate that the hub will present in HTTPS sessions. The hub also has the corresponding private key, which is used to prove it is the owner (subject) of the certificate. |
| Hub Client Authentication Certificate | The certificate that the hub will use to authenticate user certificates presented for user authentication. The hub may also have the corresponding private key, in which case it will also be able to issue user certificates. |
| User Certificate | A certificate that identifies a hub user. A user with the corresponding private key can use it for certificate-based hub authentication (provided that certificate-based authentication is enabled and the user has sufficient permissions). |
Note: It is not possible to use certificate-based hub authentication in the presence of a proxy or reverse proxy. TLS client authentication is designed to prevent "man in the middle" attacks and the reverse proxy is a man in the middle.
HTTPS cannot be enabled without a hub server certificate and corresponding private key (the hub server private key). These are configured from the Configure HTTPS page or via the codesonar hub-start command, and stored on the hub. The Hub Server Certificate and keys are used to identify the hub and secure HTTPS sessions.
The hub server certificate requirements are as follows.
To avoid security warnings, the certificate must also be trusted by HTTP clients.
For best security, we recommend purchasing a hub server certificate from a trusted certificate authority.
The hub client authentication certificate is used to manage user certificate authentication. It is configured from the Configure HTTPS page or via the codesonar hub-start command, and stored on the hub.
We refer to the private key corresponding to the client authentication certificate as the client authentication private key. This key can be stored on the hub, allowing the hub to issue user certificates, but can be withheld if you prefer not to provide this functionality. User certificates are trusted if they are signed with the client authentication private key, whether or not that key is is stored on the hub.
There are three possible configuration states for hub client
authentication when HTTPS is enabled on the hub.
(When HTTPS is not enabled, hub client authentication is not
applicable.)
The client authentication certificate requirements are as follows.
To avoid security warnings, the certificate must also be trusted by HTTP clients. A self-signed client authentication certificate is normal and recommended. You may wish to explicitly configure client browsers and CodeSonar installations to trust this certificate. Otherwise, users may become accustomed to ignoring certificate warnings, largely negating the security advantages of using HTTPS.
As noted above, a self-signed client authentication certificate is normal and recommended.
If you want to configure the hub with both client authentication certificate and corresponding private key, you have three options:
If you want to configure the hub with client authentication certificate only (no private key), there is a single option:
Functionality for all these configuration cases is provided in the web GUI Configure HTTPS page.
A user may provide one or more user certificates for authentication. User certificates are managed on a per-user basis and are configured from the User Certificates page.
Note: if the hub is configured to use a certificate-based third-party authentication services, the certificates presented and authenticated through that services are not required to be configured as user authentication certificates. See Hub Authentication: Successful Authentication for details.
The user authentication certificate requirements are as follows.
The following requirements must all be met in order for a user to sign in with a user certificate.
CodeSonar provides two mechanisms for generating user certificates and keys.
The permissions required for both mechanisms are as follows.
The general form of the codesonar generate-hub-cert command is as follows.
Where the command components are as follows.
| [-auth authtype], [-hubuser username], [-hubpwfile pwfile], [-hubbearerfile bearerfile], [-hubcert certfile], [-hubkey privatekeyfile] |
Specify credentials for command
authentication and authorization. (See permission requirements above.) |
|---|---|
| [-foruser uname] |
Specifies that the user certificate Subject Common Name will be
uname.
|
| [-csr csrfile] | Specifies that temporary file csrfile should be used to store the certificate signing request. This option will only be of interest to users who don't have permission to write to the default certificate directory. |
| [-outkey outkeyfile] | Specifies that the generated private key should be saved in outkeyfile. The default location is <default_pemdir>/privkey.pem. |
| [-out outcertfile] |
Specifies that the resulting certificate should be saved in
outcertfile. The default location is
<default_pemdir>/<uname_cert_subject>.<hub_render>.pemwhere
|
| [[protocol://]host:port] |
CodeSonar will use the hub at protocol://host:port,
failing if a hub is not already running at that location.
|
| <default_pemdir> |
The default directory for an individual user's CodeSonar
certificates and keys depends on the operating system:
This directory is also used to store launch daemon tokens. |
For example, to generate a certificate for user alex on the hub located at https://hubmachine:7340:
The certificate can then be used to authenticate and authorize a CodeSonar build/analysis of project ProjectX:
When you generate a user certificate and key pair in your browser using the Generate a Certificate functionality in the User Certificates page, the browser will store the certificate and private key locally and use them for subsequent certificate-based hub authentication.
You may need to export the certificate and private key from the browser's local storage so that you can use them with other HTTPS clients, or on other machines; similarly you may need to explicitly import certificates and keys into your browser (especially existing certificates that you have uploaded using the Upload a Certificate functionality in the User Certificates page). These procedures will depend on your local operating system and your browser.
| Windows (except Firefox browser) |
Windows uses a centralized certificate store: if a browser
registers a private key with this store, all other HTTPS
clients that use the store will also be able to use that key.
(Note that Firefox does not use this store.) To view the store, use the Windows Certificate Manager.
certmgr.msc
For more information, see How to: View certificates with the MMC snap-in
[microsoft.com].
|
|
|---|---|---|
| Otherwise | Firefox | Advanced Panel - Accessibility, browsing, network, updates, and other advanced settings in Firefox |
| Chrome | Advanced Security Settings | |
| Safari | Import and export keychain items using Keychain
Access on Mac (What is Keychain Access on Mac?) |
|
For general operations on certificates and keys, use a toolkit such as OpenSSL. For example, you can use the OpenSSL x509 commandto convert a certificate file to a different format.
See also the notes on certificate revocation, below.
The CodeSonar Configure HTTPS and User Certificates pages report the following properties for stored certificates. For more information about TLS certificate specifications (and TLS in general), see the corresponding RFCs.
| Registered | The timestamp at which the certificate was registered with the hub. |
|---|---|
| Begins | The certificate is not valid before this timestamp. |
| Expires | The certificate is not valid after this timestamp. |
| Serial Number | Unique identifier for the certificate. |
| Version | Certificate format version. |
| SHA1 Thumbprint | The SHA-1 hash of the certificate. |
| Key Type | The type of the certificate's key pair. |
| Issuer location information |
In a self-signed certificate, each issuer location field will have the same contents as the corresponding subject location field. |
| Issuer Name | The Common Name (CN) of the certificate issuer. In a self-signed certificate, will be the same as Subject Name. |
| Issuer Email | The contact email address for the certificate issuer. In a self-signed certificate, will be the same as Subject Email. |
| Subject location information |
In a self-signed certificate, each subject location field will have the same contents as the corresponding issuer location field. |
| Subject Name |
The Common Name (CN) of the certificate subject. In a
self-signed certificate, will be the same as Issuer Name.
|
| Subject Email | The contact email address for the certificate subject. In a self-signed certificate, will be the same as Issuer Email. |
We say a TLS certificate C is trusted by the hub if one of the following is true.
We say a TLS certificate C is trusted by a hub client if one of the following is true.
CodeSonar does not use certificate revocation lists (CRLs). Instead, user certificates represent a whitelist-based approach to certificate authentication for users. If you determine at any point that a particular certificate is no longer appropriate for user authentication, revoke it from the User Certificates page for the corresponding user.
If your organization has existing certificate-based authentication infrastructure that includes a CRL and you wish to also apply this to the CodeSonar hub, follow the instructions below, ensuring that you revoke any existing user certificates on the hub in step 4.
Web browsers and other HTTPS clients maintain lists of trusted certificates, and are typically configured to issue warnings when a site presents a certificate that is not trusted (and doesn't have a trust chain to a trusted certificate).
If you generate a self-signed server certificate or client authentication certificate for your hub, it will not initially be trusted by HTTPS clients. You and other hub users are therefore likely to encounter these warnings until you specify that the certificate should be trusted. There are several options, summarized in approximate order of security in the following table.
| Approach | Additional Cost? | Need to Configure Exceptions? | ||
|---|---|---|---|---|
| Web Browsers | CodeSonar Installation | |||
| Don't use the functionality for generating a self-signed certificate, but instead... | ||||
| ... purchase a certificate authority certificate from a
company such as VeriSign, GlobalSign, or Thawte, and upload it to
the hub. You will probably need to use a wildcard certificate (*.example.com): authorities will not issue certificates for internal server names such as somelanmachine.example.com. |
YES | no | no | |
| ...if your organization has its own internal Certificate
Authority infrastructure, use that to generate a suitable
certificate and then upload it to the hub. [*] In this case, web browsers within your organization will likely already trust certificates issued by the internal authority: if they don't, you will need to configure them to do so. |
no | no [*] |
YES | |
| ...arrange for a third party vendor to create internal
certificates for you - essentially an outsourced version of the
previous option. Companies who offer this service typically refer
to it as intranet SSL or similar. You may prefer this option if there are no in-house resources to devote to certificate generation and management, or if you do believe that one of these companies will be able to provide better protections for your root private key than you can yourself. [**] Note that the company is not acting as a trusted authority in this case, so web browsers and other HTTPS clients will not already trust the resulting certificates. |
YES | YES [**] | YES | |
| Use the functionality for generating a self-signed certificate... | ||||
| ...and explicitly configure HTTPS clients to recognize the
certificate. |
no | YES | YES | |
| ...and let your users set up their own security exceptions
when they encounter HTTPS warnings. This is the least-preferable approach. Your users may be confused by the warning and believe they are unable to access the hub at all; conversely they may become accustomed to ignoring certificate warnings, largely negating the security advantages of using HTTPS. |
no | no | no | |
If you are using a certificate is not already trusted by web browsers on your system, or by CodeSonar, you can configure these clients to trust the certificate so that they do not issue warnings.
| Web Browser | Web browsers manage their own trusted certificate exception lists: consult browser documentation for details. Note that you will need to configure browsers on all machines that access the hub. |
|---|---|
| CodeSonar Installation |
If your local CodeSonar installation does not trust the
hub's server certificate or client authentication
certificate, you will encounter warnings when you attempt to
perform operations such as building and analyzing a project.
You can instruct the CodeSonar installation to trust the
certificate as follows.
|
If all the users at your company already have client certificates and you manage these in a centralized database, you can use these for CodeSonar hub authentication by creating and installing a CodeSonar authentication plug-in.
The general method will be as follows.
The following manual sections provide further information about various aspects of TLS certificate use in CodeSonar.
| GUI Pages | |
|---|---|
| Configure HTTPS | Configure the hub's server certificate and client authentication certificate. |
| Sign In | Sign in to a hub user account, with option to use a user certificate for authentication. |
| User Certificates | Manage the user certificates for a single hub user account. |
| Other Manual Sections | |
| The codesonar Command: generate-hub-cert | |
| Starting a Hub (see options -tls-server-certkey and -tls-client-certkey) | |
| Custom Hub Authentication Plug-Ins | |
| Hub User Accounts | |
| Hub Authentication | |
For more information about TLS certificates, see:
To report problems with this documentation, please visit https://support.codesecure.com/.